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?

- 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>

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

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

Yuri and others added 12 commits May 21, 2026 13:50

docs: refine Coding workflow section for clarity and conciseness

bf48c00

docs: update contributing guidelines and developer documentation for …

6cb10fd

…clarity

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

edba16c

…ew contributors

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

249c48d

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

5e8255a

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

1f3a71f

Remove LEARNING_PATH.md

9605e3c

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 added 4 commits May 21, 2026 17:12

docs: replaced duplicates with the link to Dev Guide

bf9e1a4

docs: reverted back to SCM instead of Git

a0709ff

docs: updated Prompting section with prompting instructions and examples

000787b

docs: minor fix

fa27b8c

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: rewrite Quick Start as short developer guide (CTORNDGAIN-1301)#82

docs: rewrite Quick Start as short developer guide (CTORNDGAIN-1301)#82
ymakaruk-pixel wants to merge 16 commits into
mainfrom
CTORNDGAIN-1301-quickstart-rewrite

ymakaruk-pixel commented May 12, 2026

Uh oh!

github-actions Bot commented May 12, 2026

Uh oh!

isolomatov-gd left a comment

Uh oh!

isolomatov-gd May 19, 2026

Uh oh!

isolomatov-gd May 19, 2026

Uh oh!

isolomatov-gd May 19, 2026

Uh oh!

omaiesh May 21, 2026

Uh oh!

omaiesh May 21, 2026

Uh oh!

omaiesh May 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

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!

isolomatov-gd May 19, 2026

Choose a reason for hiding this comment

Uh oh!

isolomatov-gd May 19, 2026

Choose a reason for hiding this comment

Uh oh!

isolomatov-gd May 19, 2026

Choose a reason for hiding this comment

Uh oh!

omaiesh May 21, 2026

Choose a reason for hiding this comment

Uh oh!

omaiesh May 21, 2026

Choose a reason for hiding this comment

Uh oh!

omaiesh May 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants