Skip to content

docs: restructure README around the user journey #238

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
omaiesh wants to merge 13 commits into
base: main
Choose a base branch
from
Open

docs: restructure README around the user journey #238

Changes from 1 commit
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
01cf34c
docs: restructure README around the user journey
omaiesh Aug 9, 2026
6031816
docs: rewrite README as a shorter, problem-led face
omaiesh Aug 11, 2026
0fdab6d
docs: drop CONFIGURATION.md from this PR
omaiesh Aug 11, 2026
20cfc30
docs: collapse the Documentation section and complete its table
omaiesh Aug 11, 2026
da00fcc
Merge origin/main into docs/readme-user-journey-216
omaiesh Aug 13, 2026
f6599e8
Merge remote-tracking branch 'origin/main' into docs/readme-user-jour…
omaiesh Aug 17, 2026
9f07e29
docs: add skills, workflows, examples, and recommendations to README
omaiesh Aug 17, 2026
95d2292
docs: restructure Set up your repository, trim Documentation table, r…
omaiesh Aug 19, 2026
a589b6c
docs: adopt reviewer-requested structure, ground workflow skills in s…
omaiesh Aug 23, 2026
39ab595
docs: flatten workflow categories, reorder entries, minor skill copy …
omaiesh Aug 23, 2026
0958f09
docs: revert intro to problem-led framing, ground Skills callout in d…
omaiesh Aug 24, 2026
6ea8a30
docs: describe workflow logic in the All-In-One tables
omaiesh Aug 26, 2026
c77e9cd
Merge origin/main into docs/readme-user-journey-216
omaiesh Aug 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
docs: describe workflow logic in the All-In-One tables 
Replace the per-workflow 4.x sections with scenario tables grouped by
intent, so a reader picks a workflow by what they want to do.

Rewrite the "What it does" column for all 13 workflows: each entry now
states the workflow's operating logic and its essential engineering
activities — human approval gates, independent agent review, subagent
delegation — instead of listing phases in order. Wording is grounded in
the phase definitions under instructions/r3/core/workflows/.

Condense the intro to a single positioning sentence and drop the separate
Skills section, since workflows are the entry point.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
  • Loading branch information
@omaiesh @claude
omaiesh and claude committed Aug 26, 2026
commit 6ea8a3086b3f9f6ecda38049cd9c6617447bb1d0
157 changes: 32 additions & 125 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,7 @@
</p>
</div>

AI coding agents are great — until you try to use them across a real team. Everyone builds their own prompts and instructions, knowledge stays in silos, and the agent — not knowing your architecture or constraints — guesses from a few open files and confidently does the wrong thing.

That's why we built Rosetta — open-source engineering governance and context for AI coding agents. It's not another proprietary agent; it works with the tools you already use (Claude Code, Cursor, Copilot, Codex, and other MCP-compatible agents) and loads your team's shared engineering instructions into every session. Everything is versioned in Git and can run inside your perimeter.
Rosetta is open-source engineering governance and context for AI coding agents: it loads your team's shared instructions, architecture and constraints into every session of the tools you already use (Claude Code, Cursor, Copilot, Codex, and other MCP-compatible agents), so the agent works from your standards instead of guessing from a few open files.

**Teach agents how to think, not what to do.** The model already knows Python and React; what it lacks is your engineering discipline. That's what Rosetta encodes.

Expand Down Expand Up @@ -47,139 +45,48 @@ Connect the agent to your other tools, such as a code graph or test runner. Add

Those are implemented to fully cover entire area of work as All-In-One. If full workflow is not needed you can ask or use skills directly.

### 4.1 Help Workflow

Finds the right workflow for your request and hands off directly into it.

Use it when you do not know what Rosetta can do, or which workflow fits.

**Skills:** [`/natural-writing`](instructions/r3/core/skills/natural-writing/SKILL.md), [`/reasoning`](instructions/r3/core/skills/reasoning/SKILL.md)

[Help Workflow Details](https://griddynamics.github.io/rosetta/docs/help-flow/)

### 4.2 Coding Workflow

Orchestrates subagents and executes: discovery, design, specifications, hitl, implementation, review, unit/integration/e2e testing, final manual validation by AI.

Covers E2E and gives a fully implemented and tested solution. Intended for medium to large tasks.

**Skills:** [`/requirements-use`](instructions/r3/core/skills/requirements-use/SKILL.md), [`/tech-specs`](instructions/r3/core/skills/tech-specs/SKILL.md), [`/planning`](instructions/r3/core/skills/planning/SKILL.md), [`/coding`](instructions/r3/core/skills/coding/SKILL.md), [`/testing`](instructions/r3/core/skills/testing/SKILL.md)

[Coding Workflow Details](https://griddynamics.github.io/rosetta/docs/coding-flow/)

### 4.3 Code Analysis Workflow

Reverse-engineers a codebase into architecture documentation. Every claim traces to real code.

Use it to understand a system before you plan, refactor, or migrate it.

**Skills:** [`/requirements-authoring`](instructions/r3/core/skills/requirements-authoring/SKILL.md), [`/reverse-engineering`](instructions/r3/core/skills/reverse-engineering/SKILL.md), [`/reasoning`](instructions/r3/core/skills/reasoning/SKILL.md), [`/large-workspace-handling`](instructions/r3/core/skills/large-workspace-handling/SKILL.md), [`/questioning`](instructions/r3/core/skills/questioning/SKILL.md)

[Code Analysis Workflow Details](https://griddynamics.github.io/rosetta/docs/code-analysis-flow/)

### 4.4 Ad-hoc Workflow

Builds a custom plan from reusable building blocks, then executes it with tracking.

Use it for small or unusual tasks that do not fit any other workflow.

**Skills:** [`/planning`](instructions/r3/core/skills/planning/SKILL.md), [`/reasoning`](instructions/r3/core/skills/reasoning/SKILL.md), [`/tech-specs`](instructions/r3/core/skills/tech-specs/SKILL.md)

[Ad-hoc Workflow Details](https://griddynamics.github.io/rosetta/docs/adhoc-flow/)

### 4.5 Test Case Generation Workflow

Turns a ticket into a requirements document and a set of manual test cases.

Use it when you need designed test scenarios with traceability, before any automation code exists.

**Skills:** [`/data-collection`](instructions/r3/core/skills/data-collection/SKILL.md), [`/qa-knowledge`](instructions/r3/core/skills/qa-knowledge/SKILL.md), [`/hitl`](instructions/r3/core/skills/hitl/SKILL.md), [`/coding`](instructions/r3/core/skills/coding/SKILL.md)

[Test Case Generation Workflow Details](https://griddynamics.github.io/rosetta/docs/testgen-flow/)

### 4.6 API AQA Workflow

Turns API contracts and test cases into working, corrected, automated tests. Gated by your approval.

Use it to automate backend API tests from OpenAPI specs or request/response cases.

**Skills:** [`/data-collection`](instructions/r3/core/skills/data-collection/SKILL.md), [`/qa-knowledge`](instructions/r3/core/skills/qa-knowledge/SKILL.md), [`/qa-structure`](instructions/r3/core/skills/qa-structure/SKILL.md), [`/reverse-engineering`](instructions/r3/core/skills/reverse-engineering/SKILL.md), [`/coding`](instructions/r3/core/skills/coding/SKILL.md), [`/testing`](instructions/r3/core/skills/testing/SKILL.md), [`/debugging`](instructions/r3/core/skills/debugging/SKILL.md)

[API AQA Workflow Details](https://griddynamics.github.io/rosetta/docs/api-aqa-flow/)

### 4.7 UI AQA Workflow

Turns a test case into a working automated UI test. Follows your repo's existing page objects.

Use it to automate browser or end-to-end tests, or to fix a failing one.

**Skills:** [`/data-collection`](instructions/r3/core/skills/data-collection/SKILL.md), [`/qa-knowledge`](instructions/r3/core/skills/qa-knowledge/SKILL.md), [`/qa-structure`](instructions/r3/core/skills/qa-structure/SKILL.md), [`/reverse-engineering`](instructions/r3/core/skills/reverse-engineering/SKILL.md), [`/coding`](instructions/r3/core/skills/coding/SKILL.md), [`/testing`](instructions/r3/core/skills/testing/SKILL.md), [`/debugging`](instructions/r3/core/skills/debugging/SKILL.md)

[UI AQA Workflow Details](https://griddynamics.github.io/rosetta/docs/ui-aqa-flow/)

### 4.8 Requirements Authoring Workflow

Drafts and validates requirements as small, atomic units. Each unit needs your approval.

Use it when behavior is unclear or high-impact, or when you need traceability.

**Skills:** [`/hitl`](instructions/r3/core/skills/hitl/SKILL.md), [`/requirements-authoring`](instructions/r3/core/skills/requirements-authoring/SKILL.md), [`/reverse-engineering`](instructions/r3/core/skills/reverse-engineering/SKILL.md)

[Requirements Authoring Workflow Details](https://griddynamics.github.io/rosetta/docs/requirements-authoring-flow/)

### 4.9 Research Workflow

Drafts a research prompt for your approval, then runs it and documents the answer.

Use it for deep investigation or a technology comparison before you choose an approach.

**Skills:** [`/reasoning`](instructions/r3/core/skills/reasoning/SKILL.md), [`/research`](instructions/r3/core/skills/research/SKILL.md)

[Research Workflow Details](https://griddynamics.github.io/rosetta/docs/research-flow/)

### 4.10 Modernization Workflow

Migrates or upgrades a system through sequential, spec-first phases. Each phase needs your approval.

Use it for a real migration: a language conversion, a framework upgrade, or a persistence change.

**Skills:** [`/hitl`](instructions/r3/core/skills/hitl/SKILL.md), [`/load-project-context`](instructions/r3/core/skills/load-project-context/SKILL.md), [`/orchestration`](instructions/r3/core/skills/orchestration/SKILL.md)

[Modernization Workflow Details](https://griddynamics.github.io/rosetta/docs/modernization-flow/)

### 4.11 External Library Onboarding Workflow

Packages an external library into reference material and a short learning guide.

Use it when your project depends on an internal SDK or external client, without source access.

**Skills:** [`/hitl`](instructions/r3/core/skills/hitl/SKILL.md), [`/load-project-context`](instructions/r3/core/skills/load-project-context/SKILL.md), [`/orchestration`](instructions/r3/core/skills/orchestration/SKILL.md)

[External Library Onboarding Workflow Details](https://griddynamics.github.io/rosetta/docs/external-lib-flow/)

### 4.12 Security Workflow
### Build & change

Runs an authorized security review and prepares remediation inputs. It never fixes code itself.
| I want to… | Scenario | Command | What it does |
| ------------------------------------- | ----------------------------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Write a feature, fix a bug, add tests | [Write or change code](user-guide/scenarios/coding.md) | `/coding-flow` | Scales to the size of the change: specs and architecture options before code, implementation and tests by subagents, independent agent review and real validation, your approval at every gate. |
| Define what to build first | [Author requirements](user-guide/scenarios/requirements.md) | `/requirements-authoring-flow` | Captures intent, proposes a MECE outline, then drafts requirements as atomic units, each agent-reviewed and approved by you before it enters the traceable final set. |
| Handle a small or unusual task | [Ad-hoc task](user-guide/scenarios/adhoc-task.md) | `/adhoc-flow` | Composes a bespoke plan from reusable building blocks instead of a fixed sequence, reviews it with you before execution, then runs it with tracking and a closing summary. |

Use it for an authorized review of an application, a repository, or an AI system.
### Test & QA

**Skills:** [`/hitl`](instructions/r3/core/skills/hitl/SKILL.md), [`/security`](instructions/r3/core/skills/security/SKILL.md), [`/risk-assessment`](instructions/r3/core/skills/risk-assessment/SKILL.md), [`/dangerous-actions`](instructions/r3/core/skills/dangerous-actions/SKILL.md), [`/sensitive-data`](instructions/r3/core/skills/sensitive-data/SKILL.md), [`/subagent-directives`](instructions/r3/core/skills/subagent-directives/SKILL.md)
| I want to… | Scenario | Command | What it does |
| ------------------------------- | ------------------------------------------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Design test cases from a ticket | [Generate test cases](user-guide/scenarios/generate-test-cases.md) | `/testgen-flow` | Rebuilds a requirements baseline from ticket and wiki sources, turns gaps and contradictions into questions for you, then derives traceable test cases and exports them to your TMS. |
| Automate a UI test | [Automate UI tests](user-guide/scenarios/automate-ui-tests.md) | `/ui-aqa-flow` | Grounds tests in your existing page objects and conventions, agrees ambiguous selectors with you, then implements, runs, diagnoses failures and corrects until the suite passes. |
| Automate an API test | [Automate API tests](user-guide/scenarios/automate-api-tests.md) | `/api-aqa-flow` | Reads the API spec against your test cases, clarifies gaps before any code is written, then specifies, implements, executes and corrects tests until they pass. |

[Security Workflow Details](https://griddynamics.github.io/rosetta/docs/security-flow/)
### Understand

### 4.13 Coding Agents Prompting Workflow
| I want to… | Scenario | Command | What it does |
| ------------------------------- | ---------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Understand an existing codebase | [Analyze a codebase](user-guide/scenarios/analyze-a-codebase.md) | `/code-analysis-flow` | Reverse-engineers behaviour into documents where every claim links back to code, splits large codebases across parallel agents, raises unknowns as questions and proposes no changes. |
| Investigate or compare options | [Research a question](user-guide/scenarios/research.md) | `/research-flow` | Meta-prompting: your question becomes a research prompt you approve, executed in an isolated subagent and returned as a documented answer with grounded references. |

Authors or adapts prompts for AI agents: skills, subagents, workflows, and rules.
### Transform

Use it to create, refactor, review, or port a prompt to another agent.
| I want to… | Scenario | Command | What it does |
| --------------------------- | -------------------------------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Migrate or upgrade a system | [Modernize / migrate](user-guide/scenarios/modernize.md) | `/modernization-flow` | Recovers specs from the old code and maps dependencies before any target decision, then implements in small approved batches, preserving behaviour and test coverage. |
| Teach the agent a library | [Onboard a library](user-guide/scenarios/onboard-a-library.md) | `/external-lib-flow` | Packages a private library into a compressed, searchable reference plus a short learning guide, wires it into your project docs, and verifies the agent can actually use it. |

**Skills:** [`/coding-agents-prompt-authoring`](instructions/r3/core/skills/coding-agents-prompt-authoring/SKILL.md)
### Govern quality

[Coding Agents Prompting Workflow Details](https://griddynamics.github.io/rosetta/docs/coding-agents-prompting-flow/)
| I want to… | Scenario | Command | What it does |
| ----------------------------- | -------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Run a security review | [Review security](user-guide/scenarios/security-review.md) | `/security-flow` | Works only inside the scope you authorize: deterministic gates and threat-model-driven inspection, evidence behind every finding, independent review, then a sanitized report with remediation inputs. |
| Author or adapt agent prompts | [Author agent prompts](user-guide/scenarios/author-agent-prompts.md) | `/coding-agents-prompting-flow` | Extracts intent into an approved brief and blueprint, drafts each prompt through a hardening loop, then simulates realistic runs and validates against intent before anything is saved. |

## Skills
### Not sure?

40+ built-in disciplines run behind the scenes, covering everyday engineering work like [`coding`](instructions/r3/core/skills/coding/SKILL.md), [`qa-knowledge`](instructions/r3/core/skills/qa-knowledge/SKILL.md), and [`testing`](instructions/r3/core/skills/testing/SKILL.md). Browse the full set [here](instructions/r3/core/skills).
| I want to… | Scenario | Command | What it does |
| ----------------------- | -------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Find the right workflow | [Get help](user-guide/scenarios/get-help.md) | `/help-flow` | Lists what your installation actually offers, matches your request to a capability, explains how to use it, and hands off into that workflow in the same session. |

## Documentation

Expand Down