docs: rewrite Quick Start as short developer guide (CTORNDGAIN-1301) by ymakaruk-pixel · Pull Request #82 · griddynamics/rosetta

ymakaruk-pixel · 2026-05-12T09:56:18Z

Plugin-first install; MCP demoted to labeled fallback
Bootstrap rule promoted to mandatory step for MCP mode
Real example regenerated as in coding-flow.md
New Customize page with examples - needs review and testing

github-actions · 2026-05-12T09:58:34Z

Rosetta Triage Review

Summary: This PR rewrites the Quick Start page as a developer-focused Overview with a plugin-first install path, demotes MCP to a fallback, and adds a new Customize page (209 lines) covering context files, project rules, and helper MCPs — all as website documentation changes only (no code logic modified).

Findings:

Scope: Focused and coherent — 4 files changed, all in docs/web/. Adds a new Customize guide and substantially rewrites the Quick Start page.
Description: Adequately describes the 4 key changes; the author notes the Customize page "needs review and testing," which aligns with the documentation label added.
Breaking changes: None to code or APIs. The Quick Start page H1 was renamed from "Quick Start" to "Overview" — users with bookmarked anchor links to that heading may be affected.
Documentation: This PR is the documentation; no public API or code changes require additional docs.
Test coverage: No tests applicable — Jekyll docs site only.
Internal links: Several links in customize.md reference /rosetta/docs/architecture/ and /rosetta/docs/quickstart/ — the latter is unchanged in permalink (/docs/quickstart/) so it resolves correctly. Worth a local Jekyll build to confirm all relative links render properly.

Suggestions:

Run a local Jekyll build (bundle exec jekyll serve) to verify the new Customize page renders, the sidebar Customize link appears in the correct position, and all internal cross-links resolve.
Consider whether renaming the Quick Start H1 to "Overview" matches user expectations — returning users navigating by heading may find this confusing; the permalink /docs/quickstart/ is unchanged which is good.
The PR body mentions "Real example regenerated as in coding-flow.md" — confirm the example in the new quickstart.md accurately reflects the current coding workflow steps.

Automated triage by Rosetta agent

isolomatov-gd

Please double check the PR

isolomatov-gd · 2026-05-19T14:29:55Z

@@ -0,0 +1,5 @@
+{


Remove this from commit

isolomatov-gd · 2026-05-19T14:31:30Z

 ---

-# Coding Flow
+# Coding workflow


I think we cut too much from coding-flow.
Why did we rename Flow -> workflow ?

isolomatov-gd · 2026-05-19T14:32:10Z

 baseSchema: docs/schemas/rule.md
 ---

 <bootstrap_rosetta_files compact="NEVER" optimize="NEVER" summarize="AS-IS">


Why this file was modified?

omaiesh · 2026-05-21T13:57:16Z

 ## Still Stuck?

+- [FAQ.md](FAQ.md) — common questions about behavior, token usage, and concepts
+- [Discord](https://discord.gg/QzZ2cWg36g)


Remove this link

omaiesh · 2026-05-21T14:03:51Z

+| **Workflow**       | Multi-phase pipeline coordinating subagents for a specific request type. Defines phases, steps, and approval gates. Alias **Command**       |
+| **Skill**          | Reusable unit of work loaded into agents on demand. Skills define *how* to accomplish a specific task.                                      |
+| **Rule**           | Persistent constraint applied globally or by path pattern. Defines best practices, guardrails, guidelines.                                  |
+| **Subagent**       | Delegated specialist with fresh context and its own system prompt. Alias: **Agent**. Examples: orchestrator, planner, executor, and others. |


we don't have orchestrator as a subagent. let's choose one from the list.
This might lead users to think that Rosetta is acting as an orchestrator.

omaiesh · 2026-05-21T14:06:52Z

-Complete the OAuth flow when prompted. Then ask: *"Initialize this repository using Rosetta"*
+Other IDEs and STDIO transport: see [INSTALLATION.md](INSTALLATION.md). Any MCP-compatible tool can connect using the same endpoint.
+
+**Then add the bootstrap rule (MCP mode only).** Some IDEs don't reliably invoke MCP tools on their own. Download [bootstrap.md](https://github.com/griddynamics/rosetta/blob/main/instructions/r2/core/rules/bootstrap.md?plain=1) and place it where your IDE looks for instructions (e.g. `.claude/claude.md`, `.cursor/rules/bootstrap.mdc`, `.github/copilot-instructions.md`). Full path table in [QUICKSTART.md](QUICKSTART.md).


Can we changed 'r2' in url on some the summary value of the current version? I would like to avoid changed it every time

- Plugin-first install; MCP demoted to labeled fallback - Bootstrap rule promoted to mandatory step for MCP mode - Real example regenerated against canonical coding-flow.md - New Customize page with worked examples (CONTEXT.md, rules, MCPs) - Sidebar + docs index updated to include Customize Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Cross-checked against docs/web/docs/coding-flow.md per Igor's review request: - Phase names: "Specs + plan" → "Tech plan"; "Plan review" → "Review plan"; "Code review" → "Review code"; "Tests review" → "Review tests" - Artifact names use <FEATURE>-SPECS.md / <FEATURE>-PLAN.md placeholder with plans/PASSWORD-RESET/ as the concrete example - Prompt updated to "Add password reset support to the customer portal. I want to review the plan first." (matches canonical "How To Start" style) - Added scaling footnote: small tasks handle some phases inline and may combine the two HITL gates; approval still always explicit - Linked to /docs/coding-flow/ for canonical phase reference Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

- What is Rosetta: cut meta-prompting/four-phase jargon; replaced with plain definition + concrete usage example + IDE list inline. - Why use it: 6 slogan-led bullets to 4 benefit-led bullets; demoted cross-project intelligence to a small italic callout. - How it works: cut duplicate privacy paragraphs and 3 security control bullets (kept in SECURITY.md); added plugin/MCP delivery split with plugin recommended (clients prefer plugins). - Get Started: plugin-first install (Option A) with MCP fallback (Option B); added model-choice warning and mandatory bootstrap rule step for MCP mode; merged verify and initialize. - Cut redundant "Supported IDEs and Agents" section; "any MCP- compatible tool" folded into Option B. - Documentation table: row labels cleaned up for verb consistency and reordered (security before changelog). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…clarity

- Updated OVERVIEW.md to link to TERMINOLOGY.md - Enhanced PLUGINS.md with clearer installation instructions and warnings. - fix QUICKSTART.md for first-time users, emphasizing project initialization and common issues. - Added FAQ.md to address common questions and installation issues. - Revised REVIEW.md to ensure consistent terminology referencing TERMINOLOGY.md. - Improved TROUBLESHOOTING.md with additional guidance and links to FAQ.md. - Clarified architecture details in ARCHITECTURE.md and updated references to terminology. - Adjusted bootstrap rules in instructions to reflect Git instead of SCM for file exclusions.

…ew contributors

Local Claude Code IDE config shouldn't be committed; gitignoring it alongside the existing .cursor/mcp.json pattern. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

- Add user request step between Bootstrap and Classify in lifecycle diagram - Expand Execute step with four-phase bullets (Prepare/Research/Plan/Act) - Remove Evolve step from per-session lifecycle (it is a release-level concern) - Fix CONTEXT.md links in README.md to point to docs/CONTEXT.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…llation files and so on. Followed on comments made in github

isolomatov-gd · 2026-05-27T13:08:46Z

+
+### Where to put rules
+
+| IDE                              | Path (any `.md` file works)    |


isolomatov-gd

Pls see the rest of the comments + verify all contents

isolomatov-gd · 2026-05-27T13:11:17Z

+**Playwright MCP** — drive a real browser, fill forms, click elements, scrape pages.
+
+```json
+{ "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp@latest"] } }


Suggested change

{ "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp@latest"] } }

"playwright": { "command": "npx", "args": ["-y", "@playwright/mcp@latest"] }

isolomatov-gd · 2026-05-27T13:11:55Z

+{
+  "mcpServers": {
+    "Rosetta": { "url": "https://mcp.rosetta.griddynamics.net/mcp" },
+    "Context7": { "url": "https://mcp.context7.com/mcp" }
+  }
+}


Suggested change

{

"mcpServers": {

"Rosetta": { "url": "https://mcp.rosetta.griddynamics.net/mcp" },

"Context7": { "url": "https://mcp.context7.com/mcp" }

}

}

"Context7": { "url": "https://mcp.context7.com/mcp" }

isolomatov-gd · 2026-05-27T13:12:43Z

+**Chrome DevTools MCP** — full Chrome control: console, network tab, snapshots.
+
+```json
+{ "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp"] } }


Suggested change

{ "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp"] } }

"chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp"] }

isolomatov-gd · 2026-05-27T13:13:54Z

+Rosetta gives your AI coding agent your team's context, standards, and guardrails — across any IDE.

-**When should I read this?** When you want to go from zero to a working setup.
+You install Rosetta in your IDE, ask the agent "Initialize this repository using Rosetta", and it produces a plan + code + tests with the conventions of your codebase, not generic ones.


Suggested change

You install Rosetta in your IDE, ask the agent "Initialize this repository using Rosetta", and it produces a plan + code + tests with the conventions of your codebase, not generic ones.

You install Rosetta in your IDE, ask the agent "Initialize this repository using Rosetta", and during coding workflows it produces a plan + code + tests with the conventions of your codebase, not generic ones.

isolomatov-gd · 2026-05-27T13:15:02Z

-**When should I read this?** When you want to go from zero to a working setup.
+You install Rosetta in your IDE, ask the agent "Initialize this repository using Rosetta", and it produces a plan + code + tests with the conventions of your codebase, not generic ones.
+
+> **Use a strong model.** Sonnet 4.6, GPT-5.3-codex-medium, gemini-3.1-pro, or better. Avoid Auto. Weaker models silently skip Rosetta's tools.


Suggested change

> **Use a strong model.** Sonnet 4.6, GPT-5.3-codex-medium, gemini-3.1-pro, or better. Avoid Auto. Weaker models silently skip Rosetta's tools.

> [!WARNING]

> You must receive a prior approval from your manager and company to use it.

> [!WARNING]

> Use **Sonnet 4.6**, **GPT-5.3-codex-medium**, **gemini-3.1-pro** or better models. Avoid Auto model selection.

> [!NOTE]

> Rosetta is designed to never use or see data or IP.

> Instead it uses inversion of control, by providing a "menu" to AI coding agents.

isolomatov-gd · 2026-05-27T14:05:56Z

+
+**R2** is the current stable release — use it for production work.
+
+**R3** is in active development and not for production use yet. (Internal contributors testing R3 do so by switching to the `V3` branch — see [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md).)


R3/V3 branch and so on - remove, this is not for users of rosetta

isolomatov-gd · 2026-05-27T14:06:47Z

+Use the **plugin** when one is available for your IDE. Plugins bundle the bootstrap rule, skills, agents, and workflows directly into the IDE and the agent loads them locally — no live connection to a Rosetta server at request time. In practice this means:
+
+- Faster session start, no MCP OAuth expirations dropping the agent mid-task, no dependency on the Rosetta server being reachable from your network.
+- No outbound calls to an external service means no data-egress or privacy review — you're installing static instruction files into the repo. That's a much shorter conversation with security and compliance than authorizing a new external MCP endpoint.


Suggested change

- No outbound calls to an external service means no data-egress or privacy review — you're installing static instruction files into the repo. That's a much shorter conversation with security and compliance than authorizing a new external MCP endpoint.

- No outbound calls to an external service means no data-egress or privacy review — you're using local static instruction files. That's a much shorter conversation with security and compliance than authorizing a new external MCP endpoint.

isolomatov-gd · 2026-05-27T14:08:15Z

+
+Yes, but with a purpose. Rosetta loads bootstrap rules, the workflow for your request type, and any skills needed for the task — typically a few thousand extra tokens up front. In return you get:
+
+- Fewer wrong-path executions that would burn far more tokens being undone


Guardrails, Security, Sensitive Data handling, current config risk assessment, reliable results.

isolomatov-gd · 2026-05-27T14:10:21Z

+
+- Fewer wrong-path executions that would burn far more tokens being undone
+- Less back-and-forth because the agent asks the right questions early (HITL)
+- Reusable plans, specs, and memory that compound across sessions


Suggested change

- Reusable plans, specs, and memory that compound across sessions

- Spec-Driven Development extended with Discovery, Design, Review, and Validation phases

- Reusable agent memory that allows AI to learn on current repo

isolomatov-gd · 2026-05-27T14:13:08Z

+- Less back-and-forth because the agent asks the right questions early (HITL)
+- Reusable plans, specs, and memory that compound across sessions
+
+For small/trivial tasks the overhead can feel high relative to the task. For medium/large tasks the overhead is small relative to total work and the reliability gain usually pays for itself. <!-- TODO: link to any published benchmarks if available -->


Suggested change

For small/trivial tasks the overhead can feel high relative to the task. For medium/large tasks the overhead is small relative to total work and the reliability gain usually pays for itself. 

For small/trivial tasks AI treats them as just small change and never executes tests nor validate results of changes. Very often small changes have side effects, which AI must figure out first. This leads to low quality unpredictable results.

isolomatov-gd

Pls see the rest of the comments + verify all contents

ymakaruk-pixel requested review from ElizaVetaFomka and YevheniiaLementova as code owners May 12, 2026 09:56

github-actions Bot added the documentation Improvements or additions to documentation label May 12, 2026

ymakaruk-pixel force-pushed the CTORNDGAIN-1301-quickstart-rewrite branch 4 times, most recently from edc35b6 to 665c208 Compare May 18, 2026 12:52

ymakaruk-pixel requested a review from isolomatov-gd as a code owner May 18, 2026 12:52

isolomatov-gd requested changes May 19, 2026

View reviewed changes

ymakaruk-pixel force-pushed the CTORNDGAIN-1301-quickstart-rewrite branch from 5fe0a19 to b141495 Compare May 21, 2026 11:01

omaiesh reviewed May 21, 2026

View reviewed changes

Yuri and others added 17 commits May 26, 2026 16:03

docs: refine Coding workflow section for clarity and conciseness

ae0e68f

docs: update contributing guidelines and developer documentation for …

db2b838

…clarity

docs: enhance FAQ, Overview, and Usage Guide; add Learning Path for n…

3529e41

…ew contributors

chore: untrack .claude/settings.local.json and add to .gitignore

f3927b6

Local Claude Code IDE config shouldn't be committed; gitignoring it alongside the existing .cursor/mcp.json pattern. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Revert changes to docs/web/docs/coding-flow.md

4f4ad88

Revert changes to instructions/r2/core/rules/bootstrap-rosetta-files.md

2cdac8b

Remove LEARNING_PATH.md

a4d91eb

docs: replaced duplicates with the link to Dev Guide

535646d

docs: reverted back to SCM instead of Git

fddf2d3

docs: updated Prompting section with prompting instructions and examples

16fc203

docs: minor fix

a1235a4

docs: removed duplicates by keeping installation infomration in insta…

1e53b1f

…llation files and so on. Followed on comments made in github

ymakaruk-pixel force-pushed the CTORNDGAIN-1301-quickstart-rewrite branch from 78fe427 to 1e53b1f Compare May 26, 2026 13:41

docs: updated README to clarify Rosetta's purpose and functionality

c9335e3

isolomatov-gd reviewed May 27, 2026

View reviewed changes

isolomatov-gd requested changes May 27, 2026

View reviewed changes

	{ "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp@latest"] } }
	"playwright": { "command": "npx", "args": ["-y", "@playwright/mcp@latest"] }

	{ "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp"] } }
	"chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp"] }

	You install Rosetta in your IDE, ask the agent "Initialize this repository using Rosetta", and it produces a plan + code + tests with the conventions of your codebase, not generic ones.
	You install Rosetta in your IDE, ask the agent "Initialize this repository using Rosetta", and during coding workflows it produces a plan + code + tests with the conventions of your codebase, not generic ones.

-> **Use a strong model.** Sonnet 4.6, GPT-5.3-codex-medium, gemini-3.1-pro, or better. Avoid Auto. Weaker models silently skip Rosetta's tools.
+> [!WARNING]
+> You must receive a prior approval from your manager and company to use it.
+> [!WARNING]
+> Use **Sonnet 4.6**, **GPT-5.3-codex-medium**, **gemini-3.1-pro** or better models. Avoid Auto model selection.
+> [!NOTE]
+> Rosetta is designed to never use or see data or IP.
+> Instead it uses inversion of control, by providing a "menu" to AI coding agents.


		R2 is the current stable release — use it for production work.

		R3 is in active development and not for production use yet. (Internal contributors testing R3 do so by switching to the `V3` branch — see [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md).)

	- No outbound calls to an external service means no data-egress or privacy review — you're installing static instruction files into the repo. That's a much shorter conversation with security and compliance than authorizing a new external MCP endpoint.
	- No outbound calls to an external service means no data-egress or privacy review — you're using local static instruction files. That's a much shorter conversation with security and compliance than authorizing a new external MCP endpoint.


		Yes, but with a purpose. Rosetta loads bootstrap rules, the workflow for your request type, and any skills needed for the task — typically a few thousand extra tokens up front. In return you get:

		- Fewer wrong-path executions that would burn far more tokens being undone

	- Reusable plans, specs, and memory that compound across sessions
	- Spec-Driven Development extended with Discovery, Design, Review, and Validation phases
	- Reusable agent memory that allows AI to learn on current repo

	For small/trivial tasks the overhead can feel high relative to the task. For medium/large tasks the overhead is small relative to total work and the reliability gain usually pays for itself. <!-- TODO: link to any published benchmarks if available -->
	For small/trivial tasks AI treats them as just small change and never executes tests nor validate results of changes. Very often small changes have side effects, which AI must figure out first. This leads to low quality unpredictable results.

Conversation

ymakaruk-pixel commented May 12, 2026

Uh oh!

github-actions Bot commented May 12, 2026

Rosetta Triage Review

Uh oh!

isolomatov-gd left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

isolomatov-gd left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

isolomatov-gd left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants