diff --git a/.gitignore b/.gitignore index 722abf2c..c06303a7 100644 --- a/.gitignore +++ b/.gitignore @@ -54,6 +54,7 @@ logs/ *.swo *~ .cursor/mcp.json +.claude/settings.local.json # OS .DS_Store diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9f559618..dfe0d8f5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,9 +21,7 @@ - **Feature requests** — open an issue describing the problem and your proposed solution - **Feedback** — positive or negative, both matter. Tell us what works well, what frustrates you, what confuses you. File an issue or start a discussion. -Not sure where your idea fits? Open an issue first. - -## Fast Path to Your First PR +## How to Contribute 1. Pick a small, scoped issue (or open one with your proposal) 2. Make focused edits. One concern per PR. @@ -32,54 +30,14 @@ Not sure where your idea fits? Open an issue first. That's it. Small PRs get reviewed faster and merged sooner. -## Contributing Workflow - -``` -fork/clone → branch → edit → validate → push → PR -``` - -- Branch from `main`. Use descriptive branch names. -- Commit messages: short summary line, body if needed. No special format enforced. -- Run local validation before pushing. -- Open a PR against `main`. Fill in the PR template. - -See [Overall Development Flow](DEVELOPER_GUIDE.md#overall-development-flow) on how to run, test, build, review, and validate. - -## Prompt Changes - -Rosetta is a prompt engineering system. Prompt changes have outsized impact and need extra care. - -**Use the prompting flow.** The [`coding-agents-prompting-flow`](USAGE_GUIDE.md#workflows) with `coding-agents-prompt-authoring` skill helps you author, design, refactor, harden, and modernize prompt families (agents, skills, workflows, workflow phases, rules). It understands Rosetta internals. Use it with Opus 4.6 model. - -Examples: - -1. Refactoring old rosetta prompt to new: - ``` - MUST FULLY EXECUTE `instructions/r2/core/workflows/coding-agents-prompting-flow.md` to refactor old Rosetta prompt `` as R2 prompt family in Rosetta. - ``` - -2. Creating a new prompt: - ``` - MUST FULLY EXECUTE `instructions/r2/core/workflows/coding-agents-prompting-flow.md` to author a new R2 Rosetta ``: - ``` - -3. Using Rosetta MCP: - ``` - MUST ACQUIRE coding-agents-prompting-flow.md FROM KB AND FULLY EXECUTE IT to author a new R2 Rosetta ``: - ``` - -**What to include in the PR:** - -1. A prompt brief: goal, non-goals, constraints -2. Before/after behavior examples -3. Validation evidence (attach to PR description) +See [Overall Development Flow](DEVELOPER_GUIDE.md#overall-development-flow) for the full sequence: setup, development, testing, validation, and PR submission. -**Automated review pipelines will run on your PR:** +## Changing Prompts -- **Static AI review** validates prompt changes for structure, quality, correctness, and governance -- **Scenario comparison** runs scenarios with old and new prompts, then validates the behavioral difference +Prompt changes have outsized impact and need extra care. +A prompt change modifies how AI agents behave across every project that uses Rosetta. -Both must pass before merge. +For details on the prompt change (which workflow to use, which model, concrete invocations), see [Developer Guide → step 2 of Overall Development Flow](DEVELOPER_GUIDE.md#overall-development-flow). ## AI-Assisted Contributions diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index 0ca03b77..05e683f9 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -14,8 +14,39 @@ - See [Contributing Workflow](CONTRIBUTING.md#contributing-workflow) for git-related info 2. **Develop Rosetta using claude code / codex / cursor** or **Use the prompting flow.** - - Development: existing rules will kick in, we use HTTP MCP, everything is preconfigured using claude standards. The repo's `.mcp.json` pre-configures Claude Code to connect to the **dev** MCP endpoint (`rosetta-dev.example.com/mcp`) — this is intentional so contributors see their in-progress instruction changes reflected immediately. End users connect to the production endpoint instead. - - Prompting: use the [`coding-agents-prompting-flow` (description + examples)](CONTRIBUTING.md#prompt-changes) to author, refactor, or harden prompts. + - **Development:** existing rules kick in, HTTP MCP is preconfigured. The repo's `.mcp.json` pre-configures Claude Code to connect to the **dev** MCP endpoint (`rosetta-dev.example.com/mcp`) — this is intentional so contributors see their in-progress instruction changes reflected immediately. End users connect to the production endpoint instead. + - **Prompting:** use the [`coding-agents-prompting-flow`](USAGE_GUIDE.md#workflows) with the `coding-agents-prompt-authoring` skill to author, design, refactor, harden, and modernize prompt families (agents, skills, workflows, workflow phases, rules). It understands Rosetta internals. Use it with Opus 4.6 model. + + Examples: + +1. Refactoring old rosetta prompt to new: + ``` + MUST FULLY EXECUTE `instructions/r2/core/workflows/coding-agents-prompting-flow.md` to refactor old Rosetta prompt `` as R2 prompt family in Rosetta. + ``` + +2. Creating a new prompt: + ``` + MUST FULLY EXECUTE `instructions/r2/core/workflows/coding-agents-prompting-flow.md` to author a new R2 Rosetta ``: + ``` + +3. Using Rosetta MCP: + ``` + MUST ACQUIRE coding-agents-prompting-flow.md FROM KB AND FULLY EXECUTE IT to author a new R2 Rosetta ``: + ``` + +**What to include in the PR:** + +1. A prompt brief: goal, non-goals, constraints +2. Before/after behavior examples +3. Validation evidence (attach to PR description) + +**Automated review pipelines will run on your PR:** + +- **Static AI review** validates prompt changes for structure, quality, correctness, and governance +- **Scenario comparison** runs scenarios with old and new prompts, then validates the behavioral difference + +Both must pass before merge. + 3. **Check your output.** - [General Review Criteria](REVIEW.md#general-review-criteria) @@ -45,7 +76,7 @@ - All: update documentation, including web site 7. **Pipelines.** - - [Automated pipelines](CONTRIBUTING.md#prompt-changes) will execute + - [Automated pipelines](CONTRIBUTING.md#prompt-change-prs) will execute - Static AI review and scenario comparison - Both must pass diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 00000000..1ffba96b --- /dev/null +++ b/FAQ.md @@ -0,0 +1,117 @@ +# FAQ + +**Who is this for?** Anyone evaluating, installing, or using Rosetta who has a quick question that isn't a bug or setup issue. +**When should I read this?** Before opening an issue — most meta-questions are answered here. For setup problems see [INSTALLATION.md](INSTALLATION.md); for things that aren't working see [TROUBLESHOOTING.md](TROUBLESHOOTING.md). + +--- + +## Installation & Detection + +**How do I know if Rosetta is installed and configured for this repo?** + +Four signals, in order of reliability: + +1. After you send your first prompt in a new chat session, the agent's reply opens with `I have loaded context using Rosetta: ...`. This is the definitive sign — Rosetta successfully bootstrapped for the session. (Subsequent prompts in the same session reuse the loaded context and won't repeat the line.) +2. The MCP server shows as connected in your IDE's MCP settings (Rosetta endpoint reachable). See [INSTALLATION.md](INSTALLATION.md) for setup or [TROUBLESHOOTING.md](TROUBLESHOOTING.md#connection--authentication) if it's disconnected. +3. A bootstrap rule file exists in the repo (e.g. `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/`, or your IDE's instruction file) and contains the Rosetta bootstrap block. This is the fallback when MCP isn't available. +4. The Rosetta entry exists in your IDE's configuration. The [Uninstalling section in INSTALLATION.md](INSTALLATION.md#uninstalling) lists exactly where Rosetta lives for each IDE and mode — invert it to check for presence: + - **Plugin:** run `claude plugin list` (Claude Code), check installed Copilot agents (VS Code), or look for extracted plugin files in the repo (Codex) + - **MCP:** run `claude mcp list` / `codex mcp list`, or open your IDE's MCP config file (Cursor, VS Code, Windsurf, JetBrains, Antigravity, OpenCode) and look for a `Rosetta` entry + - **Offline:** confirm an `instructions/` directory exists in the repo + +If none of these are true, Rosetta is not active for this session. See [INSTALLATION.md](INSTALLATION.md). + +**How do I install Rosetta for the first time?** + +See the [Get Started section in README.md](README.md#get-started) for the fastest path, or [INSTALLATION.md](INSTALLATION.md) for the full setup including the fallback bootstrap rule. Once installed, [QUICKSTART.md](QUICKSTART.md) walks you through your first session. + +**Which Rosetta release should I use?** + +**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).) + +Rosetta uses release-based versioning so new instructions can be developed without breaking agents on stable releases, and rollback is always possible. See [OVERVIEW.md](OVERVIEW.md) for the rationale. + +**How do I upgrade from R1 to R2?** + +Open a new chat in your IDE and type: `Initialize this repository using Rosetta (upgrade R1 to R2)`. Rosetta will detect the existing R1 layout and migrate it. + +--- + +## Token Usage & Performance + +**Does an AI agent consume more tokens with Rosetta?** + +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 +- 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. + +**Why does the first message in a session take longer?** + +Rosetta runs prep steps once per session: it loads context, classifies the request, picks a workflow, and reads relevant project files (`CONTEXT.md`, `ARCHITECTURE.md`, etc.). Subsequent messages reuse this context and are fast. + +--- + +## Behavior & Modes + +**Does Rosetta work in plan mode, Auto mode, or `danger-full-access`?** + +Yes. Rosetta runs in every mode. Permission modes and Auto mode only change what the agent is *allowed* to do without asking — they do not turn off Rosetta's prep steps, workflows, or HITL gates. The only way to opt out of HITL is to explicitly tell the agent `fully autonomous` or `no HITL`. + +**Can I skip the prep steps for a trivial one-line change?** + +No. Prep steps are a blocking gate and run once per session. They are lightweight (load context, classify request, pick workflow) and are designed so even trivial tasks get the right routing. The savings from skipping are tiny; the cost of skipping and getting the wrong answer is high. + +**How do I opt out of HITL (human-in-the-loop) for a single task?** + +Include the literal phrase `fully autonomous` or `no HITL` in your request. This is the only accepted opt-out; ambiguous phrasing won't disable HITL by design. Use sparingly — HITL exists to catch ambiguous intent and risky actions. + +**The agent stopped following Rosetta mid-session. What happened?** + +Most likely an expired MCP OAuth token. See [TROUBLESHOOTING.md](TROUBLESHOOTING.md#agent-not-using-rosetta) — re-authenticate through your IDE's MCP settings. + +--- + +## Concepts + +**How does Rosetta compare to other AI agent tools (superpowers, GSD, etc.)?** + +Most similar tools focus on one meta-flow — usually coding. Rosetta covers ~12 SDLC workflows: coding, test generation, AQA, modernization, research, code analysis, requirements authoring, external library onboarding, workspace init, prompt authoring, and more. See [USAGE_GUIDE.md](USAGE_GUIDE.md) for the full list. + +Rosetta also adds guardrails, HITL approval gates, sensitive-data handling, and risk assessment that apply across all workflows. + +If you already have a sophisticated harness for the one workflow you care about, you may not need Rosetta. If you want a broad, consistent foundation across many engineering activities, that's where Rosetta fits. + +**What's the difference between a skill, workflow, agent, and rule?** + +- **Rule** — always-on policy the agent must follow (e.g. guardrails, HITL questioning, file naming). Loaded at the start of every session. +- **Skill** — a focused capability the agent invokes for a specific need (e.g. `load-context`, `questioning`, `tech-specs`). Invoked on demand. +- **Workflow** — an end-to-end multi-phase process for a class of request (e.g. coding, modernization, research). One per top-level request. +- **Agent / subagent** — a specialized role spawned by the orchestrator to do delegated work in isolation (e.g. reviewer, researcher, engineer). + +See [OVERVIEW.md](OVERVIEW.md) for the full picture. + +**Where do I put project-specific overrides?** + +In `gain.json` at the repo root. It defines SDLC setup and locations of Rosetta files and wins in any conflict with default Rosetta conventions. See [bootstrap-rosetta-files](https://github.com/griddynamics/rosetta/blob/main/instructions/r2/core/rules/bootstrap-rosetta-files.md?plain=1) for the canonical file list. + +**What files does Rosetta create in my repo?** + +The headline ones are `docs/CONTEXT.md` and `docs/ARCHITECTURE.md`. The full set (including `TODO.md`, `ASSUMPTIONS.md`, `TECHSTACK.md`, `DEPENDENCIES.md`, `CODEMAP.md`, `IMPLEMENTATION.md`, `MEMORY.md`, and the `plans/` and `refsrc/` directories) is documented in the `bootstrap-rosetta-files` rule. + +--- + +## Contributing & Support + +**Where do I report bugs or request features?** + +Open an [issue](https://github.com/griddynamics/rosetta/issues). + +**Where do I propose changes to Rosetta itself?** + +See [CONTRIBUTING.md](CONTRIBUTING.md) and [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md). diff --git a/INSTALLATION.md b/INSTALLATION.md index ab49bb68..0697e6be 100644 --- a/INSTALLATION.md +++ b/INSTALLATION.md @@ -1,7 +1,7 @@ # Installation **Who is this for?** Complete setup reference for all installation modes. -**When should I read this?** When you need the full picture: HTTP, STDIO, plugins, offline, or environment variables. For the fastest path, see [QUICKSTART.md](QUICKSTART.md). +**When should I read this?** When you need the full picture: plugins, HTTP, STDIO, offline, or environment variables. For the fastest path, see the [Get Started section in README.md](README.md#get-started). > [!CAUTION] > You must receive a prior approval from your manager and company to use it. @@ -13,18 +13,22 @@ ## Choose Your Mode -| | HTTP | STDIO | Plugin | Offline | -| ------------------ | --------------------------- | --------------------------------------- | -------------------------------------------- | ------------------------------------------- | -| Setup | Single URL, OAuth automatic | Env vars, API key per user | IDE-specific install or extract zip | Download zip, copy files | -| Local dependencies | None | Python 3.12+, uvx | None | None | -| Auth | OAuth via browser | API key from Rosetta Server | None | None | -| Network | Requires internet | Requires internet | Download only | No network needed (with local models) | -| Best for | Most users | Custom configs, controlled environments | Claude Code, VS Code Copilot, Codex | Air-gapped or highly regulated environments | +| | Plugin | HTTP | STDIO | Offline | +| ------------------ | ------------------------------------------------- | ------------------------------------ | --------------------------------------- | ------------------------------------------- | +| Setup | IDE-specific install or extract zip | Single URL, OAuth automatic | Env vars, API key per user | Download zip, copy files | +| Local dependencies | None | None | Python 3.12+, uvx | None | +| Auth | None | OAuth via browser | API key from Rosetta Server | None | +| Network | Download only | Requires internet | Requires internet | No network needed (with local models) | +| Best for | Claude Code, VS Code Copilot, Codex | Most users | Custom configs, controlled environments | Air-gapped or highly regulated environments | ## Step 1: Install Pick one mode and follow its section. +### Plugin-Based Installation (recommended) + +See [PLUGINS.md](PLUGINS.md) to install Rosetta in your IDE (Claude Code, Cursor, VS Code Copilot, JetBrains Copilot, Codex). + ### HTTP Transport One URL, no local dependencies, OAuth handles authentication automatically. @@ -411,46 +415,6 @@ Required for STDIO transport. Optional otherwise. Do not set `VERSION`. It uses a server-controlled default for managed upgrades. See [Architecture — Tradeoffs](docs/ARCHITECTURE.md#tradeoffs) for rationale. -### Plugin-Based Installation (pre-release) - -Rosetta publishes plugins for supported IDEs. Each plugin installs the full Rosetta instruction set locally. - -Read more about plugin contents and capabilities in [PLUGINS.md](PLUGINS.md). - -#### Claude Code - -```sh -claude plugin marketplace add griddynamics/rosetta -claude plugin install rosetta@rosetta -``` - -Updating after installation: - -```sh -claude plugin marketplace update rosetta -claude plugin update rosetta@rosetta -``` - -#### VS Code / GitHub Copilot - -Install `rosetta` via VS Code Copilot Plugins (not VS Code extensions). - -#### JetBrains / GitHub Copilot - -1. Download `core-copilot-*.zip` from the [latest release](https://github.com/griddynamics/rosetta/releases/latest) -2. Create a `.github` folder in your repository and extract the archive contents into it -3. Delete files not needed for JetBrains: `.github/.mcp.json`, `.github/hooks.json`, `.github/templates`, `.github/rules/bootstrap.md` -4. Copy the contents of `.github/rules/plugin-files-mode.md` into `.github/copilot-instructions.md` and append before the closing `` tag: `Rosetta plugin root: ".github", get_context_instructions: must read fully all five "cat .github/rules/bootstrap-*.md" files all lines. You MUST FOLLOW ALL instructions and then MUST select workflow and execute it. All workflows are stored in ".github/rules/.md".` -5. Enable in JetBrains GitHub Copilot settings: Agent Mode, Custom Agent, Coding Agent, Subagent, Skills - -#### Codex - -Download `core-codex-*.zip` from the [latest release](https://github.com/griddynamics/rosetta/releases/latest), extract on top of the repository, and enable hooks: - -```sh -codex features enable hooks -``` - ### Offline Installation (No MCP) For environments without network access to Rosetta Server. @@ -533,7 +497,7 @@ The agent runs an eight-phase workflow (see [Usage Guide — Init Workspace](USA ### Workspace Files Created -After initialization, Rosetta maintains these files in your repository. Read more about their purpose in [Architecture — Workspace Files](docs/ARCHITECTURE.md#workspace-files). +After initialization, Rosetta maintains the following files in your repository. Read more about their purpose in [Architecture — Workspace Files](docs/ARCHITECTURE.md#workspace-files). **Committed to SCM:** diff --git a/OVERVIEW.md b/OVERVIEW.md index 17264016..6a09f5ad 100644 --- a/OVERVIEW.md +++ b/OVERVIEW.md @@ -1,6 +1,6 @@ # Overview -**Who is this for?** Engineers, leads, and architects who want to understand how Rosetta works before contributing or evaluating it. +**Who is this for?** Engineers and leads who want to understand how Rosetta works before contributing or evaluating it. **When should I read this?** After the [README](README.md), before diving into [Architecture](docs/ARCHITECTURE.md) or [Contributing](CONTRIBUTING.md). @@ -13,19 +13,19 @@ ## Core Mental Model -Rosetta is a **meta-prompting, context engineering, and centralized instructions management** for AI coding agents. It provides structured context - rules, skills, workflows, and sub-agents - guiding AI systems to operate with a deep understanding of system architecture, domain constraints, and engineering standards. Rosetta also accelerates project onboarding by reverse-engineering architecture and domain context, improving the reliability and consistency of AI-generated code. +Rosetta gives your AI coding agent the right instructions for each request — the rules, skills, workflows, and subagents it needs — so the agent knows your architecture, conventions, and engineering standards. On a new project, Rosetta can read the code first and extract that context into files the agent uses on every later request, so it doesn't have to re-learn the project each time. Design principles: **Agent-agnostic.** Works across Cursor, Claude Code, VS Code, Windsurf, JetBrains (Copilot, Junie), GitHub Copilot, Codex, Antigravity, OpenCode, and any MCP-compatible IDE. Adopts agent-specific features where available, simulates them where not. -**Progressive disclosure.** Instructions load in stages (bootstrap, classification, workflow-specific, sub-instructions) to [prevent context overflow](docs/ARCHITECTURE.md#context-overflow-prevention). The agent gets only what it needs for the current task. +**Stage-by-stage loading.** Instructions load in stages — universal policies first, then the workflow for your specific request, then anything else as needed. The agent never gets the full instruction set; it gets only what the current task needs. This [prevents context overflow](docs/ARCHITECTURE.md#context-overflow-prevention). -**Classification-first.** Every request is auto-classified into a [workflow type](USAGE_GUIDE.md#workflows) before any work begins. Classification drives which instructions, skills, and rules load. Provided workflows are used as templates. +**Classification-first.** Every request is auto-classified into a [workflow type](USAGE_GUIDE.md#workflows) before any work begins. The classification drives which instructions, skills, and rules load. **Release-based versioning.** Instructions are organized by release (r1, r2, r3). New instructions can be developed without breaking agents on stable versions. Rollback is always possible. See [Architecture — Tradeoffs](docs/ARCHITECTURE.md#tradeoffs) for rationale. -**Rules-as-code.** AI behavior is authored, versioned, reviewed, and approved through standard engineering workflows. Same rigor as application code. See [Contributing — Prompt Changes](CONTRIBUTING.md#prompt-changes) for the authoring process. +**Rules-as-code.** AI behavior is authored, versioned, reviewed, and approved through standard engineering workflows. Same rigor as application code. See [Developer Guide — Overall Development Flow](DEVELOPER_GUIDE.md#overall-development-flow) for the authoring process, and [Contributing — Prompt Change PRs](CONTRIBUTING.md#prompt-change-prs) for PR requirements. **Security by design.** No source code transfer. Air-gap capable. Runs inside the organization's perimeter. See [Context — Design Philosophy](docs/CONTEXT.md#design-philosophy) for the full set. @@ -33,27 +33,9 @@ Design principles: **Batteries included.** Ships proven defaults from real-world projects. Makes the right thing the easy thing. -## Key Concepts +## Terminology -These terms are defined here and referenced everywhere else. - - -| Term | Definition | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | -| **Bootstrap** | Critical universal policies (core, execution, hitl, guardrails) loaded at agent startup. | -| **Classification** | Auto-detection of request type (coding, testing, research, init, etc.) that routes to a specific workflow. | -| **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. | -| **Template** | Parameterized prompt with variables and validated placeholders. | -| **Release** | Versioned instruction set (r1, r2, r3). Enables safe evolution, rollback, and A/B testing. | -| **Guardrails** | Safety measures: scope limits, data protection, transparency rules, approval gates, risk assessment. | -| **HITL** | Human-in-the-loop. Approval gates at critical decision points (specs, plans, risky actions). | -| **Meta-prompting** | Rosetta MCP consults the AI agent on what should be done and how using meta-prompts. | -| **Rosetta** | MCP and CLI of Instruction and Knowledge Management System. | -| **Prompt** | Skill, Rule, Workflow, Command, Subagent, Agent, Template, or any generic prompt. **Rosetta prompt** prompt for Rosetta. | -| **Shells** | Small prompt proxies with proper fronmatters created during onboarding so that coding agents are aware of skill, agents, commands. | +See [TERMINOLOGY.md](TERMINOLOGY.md) for definitions of bootstrap, classification, workflow, skill, rule, subagent, template, release, guardrails, HITL, meta-prompting, prompt, and shells. ## How Rosetta Fits into Your Workflow @@ -62,9 +44,9 @@ Your IDE and coding agent ask Rosetta for instructions on each request. **Request types.** Twelve workflow types cover the SDLC: coding, requirements documentation authoring, automated QA, test generation, research, initialization, modernization, external library onboarding, code analysis, coding agents prompting, help, and ad-hoc. See the [Usage Guide — Workflows](USAGE_GUIDE.md#workflows) for details on each. -**Standard pattern (P-RPA).** Every workflow follows Prepare, Research, Plan, Act. Each phase can involve subagents, skills, and HITL approval gates. +**Four-phase pattern.** Every workflow has four phases: Prepare, Research, Plan, Act. Each phase can use subagents, skills, and HITL approval gates. -**Prepare** is executed once during repository initialization and maintained automatically by AI. It reverse-engineers business context, architecture, tech stack, and coding patterns into workspace files that every subsequent workflow uses. See [Usage Guide — Init Workspace](USAGE_GUIDE.md#workflows) for the full phase breakdown. +**Prepare** runs once when you first initialize the repository. The agent reads your code and extracts your business context, architecture, tech stack, and conventions into workspace files. Every later workflow uses those files. See [Usage Guide — Init Workspace](USAGE_GUIDE.md#workflows) for the full phase breakdown. **Scaling by size:** @@ -81,13 +63,18 @@ Read more about the [bootstrap flow](docs/ARCHITECTURE.md#bootstrap-flow) in the ↓ 2. Bootstrap Agent receives universal policies and guardrails ↓ -3. Classify Request type auto-detected from your input + [Users describe what they need] ↓ -4. Load Workflow-specific instructions, skills, and rules load progressively +3. Classify Rosetta classifies users request (coding, research, init, etc.) ↓ -5. Execute Plan, approve (HITL gate), execute with subagents, validate, loop +4. Load The matching workflow, skills, and guardrails load progressively ↓ -6. Evolve New releases developed safely; rollback if needed +5. Execute The workflow runs its four phases: + • Prepare — load context (CONTEXT.md, ARCHITECTURE.md), guardrails + • Research — investigate code, requirements, prior decisions + • Plan — produce reviewable spec and plan (HITL approval gate) + • Act — implement with subagents, validate, loop + ``` ## Three-Layer Architecture @@ -98,7 +85,7 @@ Instructions are organized in three layers that merge at runtime: - **Organization** — your company's conventions and policies - **Project** — local repo docs and configs -Layers at the same resource path get [bundled together](docs/ARCHITECTURE.md#bundler). This is layered customization, not multi-tenancy. See [Architecture](docs/ARCHITECTURE.md) for component details and data flow. +When the same file path exists in multiple layers, Rosetta merges them at runtime. It's customization by layer, not separate tenants. See [Architecture](docs/ARCHITECTURE.md) for component details and data flow. ## What Rosetta Does Not Do diff --git a/PLUGINS.md b/PLUGINS.md index cfeeb0ba..47fc5ccd 100644 --- a/PLUGINS.md +++ b/PLUGINS.md @@ -1,43 +1,56 @@ +# Plugins + +Rosetta plugins bundle the bootstrap rule, skills, agents, workflows, and other instructions directly into your IDE. The agent loads them locally — no live connection to Rosetta is needed at request time. + +Two install modes per IDE: + +- **Marketplace** — managed install from a plugin marketplace. Easier; preferred when available. +- **Standalone** — manual zip extraction into your repo. For IDEs without a marketplace path, or environments that block external marketplaces. + > [!CAUTION] -> You must receive a prior approval from your manager and company to use it. +> You must receive prior approval from your manager and company to use Rosetta. > [!WARNING] -> Use **Sonnet 4.6**, **GPT-5.3-codex-medium**, **gemini-3.1-pro** or better models. Avoid Auto model selection. +> Use **Sonnet 4.6**, **GPT-5.3-codex-medium**, **gemini-3.1-pro**, or better. Avoid Auto. ->[!NOTE] -> This is pre-release, but it already works. +> [!NOTE] +> Plugins are pre-release. They install and run; report bugs at . -## Claude Code Full Plugin Installation +## Claude Code ```sh - claude plugin marketplace add griddynamics/rosetta claude plugin install rosetta@rosetta - ``` -## Cursor Standalone +To update later: + +```sh +claude plugin marketplace update rosetta +claude plugin update rosetta@rosetta +``` -1. Download `core-cursor-standalone-*.zip` from the [latest release](https://github.com/griddynamics/rosetta/releases/latest) -2. Extract the archive contents directly into the repository. -3. Verify you can see a file `.cursor/agents/architect.md`. Ensure there are no `.cursor/.cursor` folders. +## Cursor -## Cursor Team Marketplace +### Marketplace (recommended) -If you have respective edition of Cursor you can add it as plugin to your corporate marketplace. See https://cursor.com/docs/plugins#team-marketplaces +If you have a Cursor edition that supports plugins, add `https://github.com/griddynamics/rosetta` to your team marketplace. See for the setup steps on the Cursor side. -You can also install plugin to claude code and it will appear in Cursor :) +Cursor also sees plugins installed via Claude Code. If you've already installed via `claude plugin install`, do **not** install again in Cursor — the same content would be duplicated in Cursor's context. -`https://github.com/griddynamics/rosetta` provides marketplace and plugin for Cursor. +### Standalone -> [!WARNING] -> Cursor sees and uses all claude code plugins, so you should not install plugins to claude code and cursor, just install to claude code. Otherwise everything will be duplicated in Cursor context! +1. Download `core-cursor-standalone-*.zip` from the [latest release](https://github.com/griddynamics/rosetta/releases/latest). +2. Extract the archive contents into your repository. +3. Verify `.cursor/agents/architect.md` exists. Ensure there is no nested `.cursor/.cursor/` folder. -## VS Code Github Copilot +## VS Code (GitHub Copilot) -Add marketplace to `chat.plugins.marketplaces` in settings using using local files path: `https://github.com/griddynamics/rosetta`. +### Marketplace (recommended) -Go to agent customizations screen (settings gear icon in Copilot chat plane), click `Browse Marketplaces`, click `install` for `rosetta`. +1. In VS Code settings, add `https://github.com/griddynamics/rosetta` to `chat.plugins.marketplaces`. +2. Open the Copilot chat panel, click the settings gear icon to open agent customizations. +3. Click **Browse Marketplaces**, then **install** for `rosetta`. Add marketplaces to VS Code @@ -45,75 +58,26 @@ Go to agent customizations screen (settings gear icon in Copilot chat plane), cl Install plugins -## Github Copilot Standalone (JetBrains and VS Code) - -1. Download `core-copilot-standalone-*.zip` from the [latest release](https://github.com/griddynamics/rosetta/releases/latest) -2. Extract the archive contents directly into the repository, if `.github/copilot-instructions.md` you will have to merge contents: first from Rosetta, then the original content. -3. Verify you can see a file `.github/agents/architect.agent.md`. Ensure there are no `.github/.github` folders. - -## Codex plugins (standalone only) - -Codex plugins only allow to pass hooks, MCPs and skills as of now (Apr 2026). - -Download `core-codex-*.zip` from the [latest release](https://github.com/griddynamics/rosetta/releases/latest), extract on top of the repository, and enable hooks: - -```sh -codex features enable hooks -``` - -## Next Steps - -### Onboarding Repository (One-Time Initialization) - -``` -Initialize this repository using Rosetta -``` - -The agent will analyze your tech stack, generate documentation (TECHSTACK.md, CODEMAP.md, DEPENDENCIES.md, ARCHITECTURE.md, CONTEXT.md), and ask clarifying questions. Read more about [workspace files](INSTALLATION.md#workspace-files-created) and [all workflows](USAGE_GUIDE.md#workflows). - -> [!NOTE] -> **Prefer medium models:** High reasoning and Opus models consume too much token on reasoning. -> **Composite workspaces:** init each repository separately, then init at the workspace level with "This is composite workspace" appended. -> **Dead code or existing specs:** mention their location in the prompt to save time. - -### Coding Workflow +### Standalone -**WHAT**: Majority of tasks are actually coding tasks, including unit tests. Just ask exactly what is required. +See [GitHub Copilot Standalone](#github-copilot-standalone-jetbrains-and-vs-code) below — same procedure for VS Code and JetBrains. -``` -/coding-flow Implement side bar on the home page, ... -``` +## GitHub Copilot Standalone (JetBrains and VS Code) -``` -/coding-flow Identify and implement fix, ... -``` +Use this when the marketplace path isn't available — JetBrains Copilot (no marketplace), or VS Code environments that block external marketplaces. -### Business and Technical Requirements +1. Download `core-copilot-standalone-*.zip` from the [latest release](https://github.com/griddynamics/rosetta/releases/latest). +2. Extract the archive contents into your repository. If `.github/copilot-instructions.md` already exists, merge contents — Rosetta first, then the original content. +3. Verify `.github/agents/architect.agent.md` exists. Ensure there is no nested `.github/.github/` folder. -**WHY**: Requirements - is the source of truth for code and tests. Going requirements first is the most effective. In brownfield start with extracting. +## Codex -``` -/requirements-authoring-flow extract detailed business and technical requirements from community of ... using subagents. Additionally, ... . Once done spawn subagent to validate and repeat an entire loop until there are no issues detected. -``` +Codex plugins currently support hooks, MCPs, and skills only (as of April 2026). -``` -/requirements-authoring-flow extract high-level business and technical requirements at end-point level for controllers according to glob ... using subagents. Additionally, ... . Once done spawn subagent to validate and repeat an entire loop until there are no issues detected. -``` +1. Download `core-codex-*.zip` from the [latest release](https://github.com/griddynamics/rosetta/releases/latest). +2. Extract the archive contents into your repository. +3. Enable hooks: -### Modernization - -**FIRST**: Document modernization goals in CONTEXT.md, document target services technical aspects in ARCHITECTURE.md, document where source code should be created, keep refsrc populated with reference code source (old code, new code, reusable libraries, configuration and documentation files, and similar). - -**NOTE**: All phases are must. All phases to be implemented one-by-one with proper review. Phase 3: Pre-Modernization Test Coverage is a must (and must include both unit and integration/e2e tests). - -``` -/modernization-flow Perform modernization phase 1 to reuse library refsrc/... using subagents. -``` - -``` -/modernization-flow Perform modernization phase 2 to analyze service module ... using subagents. Target microservice name is ... . -``` - -``` -/modernization-flow Perform modernization phase 8 for target service to analyze service module ... using subagents. Must use `coding-flow.md` to actually implement and as the main flow. Once done spawn subagent to validate and repeat an entire loop until there are no issues detected. -``` + ```sh + codex features enable hooks + ``` diff --git a/QUICKSTART.md b/QUICKSTART.md index caf12517..a5b2d832 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -1,233 +1,104 @@ -# Quick Start +# Quick Start — your first session with Rosetta -**Who is this for?** New users setting up Rosetta for the first time. -**When should I read this?** When you want to go from zero to a working setup. +**Who is this for?** You've just installed Rosetta and want to do your first real task. +**When should I read this?** Right after install. For install steps, see [README](README.md) (Get Started section) or [PLUGINS.md](PLUGINS.md). For troubleshooting setup itself, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md). --- -## Step 1: Connect Rosetta MCP +## 1. Open the right folder -> [!CAUTION] -> You must receive a prior approval from your manager and company to use it. +Open the **actual project repo** in your IDE — not the parent folder that contains it. Rosetta initializes whatever folder Claude is running in, so opening a parent directory scatters Rosetta files into the wrong place. -> [!WARNING] -> Use **Sonnet 4.6**, **GPT-5.3-codex-medium**, **gemini-3.1-pro** or better models. Avoid Auto model selection. +Quick check: in the IDE's terminal, run `pwd`. The output should be your project root (where your `package.json`, `pom.xml`, `pyproject.toml`, etc. lives), not its parent. -> [!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. - -Rosetta uses HTTP MCP transport with OAuth. Pick your IDE and add the configuration. - -
-Cursor - -Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project): - -```json -{ - "mcpServers": { - "Rosetta": { - "url": "https://mcp.rosetta.griddynamics.net/mcp" - } - } -} -``` - -
- -
-Claude Code +## 2. Start Claude and verify Rosetta loaded ```sh -claude mcp add --transport http Rosetta https://mcp.rosetta.griddynamics.net/mcp +claude ``` -Authenticate inside a claude session with `/mcp`, select Rosetta, Authenticate, and complete the OAuth flow. - -
- -
-Codex +Inside the session, type: -```sh -codex mcp add Rosetta --url https://mcp.rosetta.griddynamics.net/mcp -codex mcp login Rosetta ``` - -
- -
-VS Code / GitHub Copilot - -Add to `.vscode/mcp.json` or `~/.mcp.json`: - -```json -{ - "servers": { - "Rosetta": { - "url": "https://mcp.rosetta.griddynamics.net/mcp" - } - } -} -``` - -
- -
-GitHub Copilot (JetBrains) - -`Settings` > `Tools` > `GitHub Copilot` > `MCP Settings`. Add to `~/.config/github-copilot/intellij/mcp.json`: - -```json -{ - "servers": { - "Rosetta": { - "url": "https://mcp.rosetta.griddynamics.net/mcp" - } - } -} +What can you do, Rosetta? ``` -Restart IDE after changes. - -
+You should see a list of workflows (`coding-flow`, `init-workspace-flow`, `code-analysis-flow`, etc.) and high-value skills: -
-JetBrains Junie +Rosetta proper response Rosetta proper response -`Settings` > `Tools` > `Junie` > `MCP Settings` > `+ Add` > `As JSON`: +If the response is generic Claude output with no Rosetta-specific mentions, the plugin or MCP didn't load — see [TROUBLESHOOTING.md](TROUBLESHOOTING.md). -```json -{ - "mcpServers": { - "Rosetta": { - "url": "https://mcp.rosetta.griddynamics.net/mcp" - } - } -} -``` +The first time a Rosetta skill is invoked, Claude asks for permission. Pick option **2** ("Yes, and don't ask again…") so future calls don't keep interrupting. -
+> **Model matters.** Use Sonnet 4.6, GPT-5.3-codex-medium, gemini-3.1-pro, or better. Avoid Auto — weaker models silently skip Rosetta's tools. Use `/model` to check or change in Claude Code. -
-Windsurf +## 3. Initialize the repository -Add to your Windsurf MCP config: +Once per repo: -```json -{ - "mcpServers": { - "Rosetta": { - "url": "https://mcp.rosetta.griddynamics.net/mcp" - } - } -} ``` - -
- -
-Antigravity - -Add to your Antigravity MCP config: - -```json -{ - "mcpServers": { - "Rosetta": { - "serverUrl": "https://mcp.rosetta.griddynamics.net/mcp" - } - } -} +Initialize this repository using Rosetta ``` -
+Rosetta scans your tech stack and generates a baseline set of workspace docs (`docs/CONTEXT.md`, `docs/ARCHITECTURE.md`, `docs/TECHSTACK.md`, `docs/CODEMAP.md`, `docs/DEPENDENCIES.md`, plus state files under `agents/`). It will ask you a series of decisions before writing anything. -
-OpenCode +**The init decision prompts:** -Add to `opencode.json`: +- **Doc depth** — the most consequential. + - **Lightweight** — concise core docs. Right for small or single-service apps and most pet projects. + - **Full** — adds patterns extraction, deeper diagrams, NFRs. Pick this for large codebases you'll evolve over months. + - **Minimal** — only `CONTEXT.md`, `ARCHITECTURE.md`, `IMPLEMENTATION.md`. Don't pick to save time — future workflows need `TECHSTACK.md` and `DEPENDENCIES.md` and will re-ask the same questions every task without them. +- **Patterns**, **Status**, **Target state** — the "Recommended" option is usually correct. Override only with specific reason. -```json -{ - "mcp": { - "Rosetta": { - "type": "http", - "url": "https://mcp.rosetta.griddynamics.net/mcp", - "enabled": true - } - } -} -``` +After decisions, Rosetta asks **clarifying questions about your project** (purpose, users, architecture choices, conventions). Answer them carefully — these populate `CONTEXT.md` and `ARCHITECTURE.md`, which every future workflow reads on every task. Vague answers here mean Rosetta asks them again on every coding task. -
- -Any MCP client that supports HTTP transport can connect using the endpoint URL. Complete the OAuth flow when prompted. - -STDIO transport is available for air-gapped environments. See [INSTALLATION.md](INSTALLATION.md). - -## Step 2: Verify +> **Composite workspaces:** init each repository separately, then init at the workspace level with "This is composite workspace" appended. +> **Dead code or existing specs:** mention their location in the prompt to save Rosetta time. -Ask the agent: +When init finishes, **exit and restart Claude** — context files only load at session start: +```sh +/exit +claude ``` -What can you do, Rosetta? -``` - -It should use Rosetta MCP to retrieve agents, guardrails, and instructions: -Rosetta proper response Rosetta proper response - -## Step 3: Initialize (once per repository) +## 4. Run your first task -Ask the agent: +In the new session, describe what you want in plain language: ``` -Initialize this repository using Rosetta +Add password reset functionality. I want to review the plan before any code is written. ``` -The agent will analyze your tech stack, generate documentation (TECHSTACK.md, CODEMAP.md, DEPENDENCIES.md, ARCHITECTURE.md, CONTEXT.md), and ask clarifying questions. Read more about [workspace files](INSTALLATION.md#workspace-files-created) and [all workflows](USAGE_GUIDE.md#workflows). - -> [!NOTE] -> **Prefer medium models:** High reasoning and Opus models consume too much token on reasoning. -> **Composite workspaces:** init each repository separately, then init at the workspace level with "This is composite workspace" appended. -> **Dead code or existing specs:** mention their location in the prompt to save time. - -## Common Issues - -- **OAuth prompt does not appear:** restart your IDE and retry the connection. Read more in [Troubleshooting — Connection & Authentication](TROUBLESHOOTING.md#connection--authentication). -- **Agent ignores Rosetta tools:** confirm the MCP server shows as connected in your IDE's MCP settings. Add a [bootstrap rule](INSTALLATION.md) if the agent still skips Rosetta. Read more in [Troubleshooting — Agent Not Using Rosetta](TROUBLESHOOTING.md#agent-not-using-rosetta). -- **Slow or empty responses:** check your network can reach your Rosetta MCP host. See [TROUBLESHOOTING.md](TROUBLESHOOTING.md#slow-or-empty-responses). - -## Step 4: Add Bootstrap Rule (optional) +Rosetta routes to the coding workflow. You'll see: -If something does not work. +1. **Discovery** — a `discoverer` subagent reads `CONTEXT.md` / `ARCHITECTURE.md`, scans the relevant files, gathers constraints. +2. **Tech plan** — an `architect` writes `-SPECS.md` (the what) and `-PLAN.md` (the how) under `plans//`. +3. **Review plan** — a `reviewer` subagent inspects the spec + plan against your request. +4. **Your approval gate** — Rosetta stops and waits. Reply with `Yes, I reviewed the plan` to proceed, or push back if something's wrong. +5. **Implementation** — the `engineer` subagent writes only the approved scope. Build must pass; tests come later. +6. **Code review + validation** — `reviewer` + `validator` inspect the diff. +7. **Your second approval gate** — `Yes, I approve the implementation` to continue. +8. **Tests** — the engineer writes and runs tests, reviewer checks coverage. -Download [bootstrap.md](https://github.com/griddynamics/rosetta/blob/main/instructions/r2/core/rules/bootstrap.md?plain=1) and add it to your IDE's instruction file (keep entire contents, including YAML frontmatter): +Two explicit gates. You can always reject and iterate. Small tasks may collapse the phases and combine the gates — approval is still always explicit. See [USAGE_GUIDE.md](USAGE_GUIDE.md#workflows) for the full phase breakdown of every workflow. -| IDE | Destination | -| -------------------------- | --------------------------------- | -| Cursor | `.cursor/rules/bootstrap.mdc` | -| Claude Code | `.claude/claude.md` | -| VS Code / GitHub Copilot | `.github/copilot-instructions.md` | -| GitHub Copilot (JetBrains) | `.github/copilot-instructions.md` | -| JetBrains Junie | `.junie/guidelines.md` | -| Windsurf | `.windsurf/rules/bootstrap.md` | -| Antigravity | `.agent/rules/bootstrap.md` | -| OpenCode/Cursor | `AGENTS.md` | +## 5. Common first-hour gotchas -## Next Steps +- **"Agent ignores Rosetta tools."** Check `/mcp` status (MCP mode) or `claude plugin list` (plugin mode). If MCP shows disconnected, re-authenticate. If the plugin is missing, reinstall via [PLUGINS.md](PLUGINS.md). +- **Generic output, no workflow phases visible.** Wrong model — switch off Auto and use Sonnet 4.6 / Opus / GPT-5.3-codex-medium. +- **Init ran but the docs landed in the wrong folder.** You initialized from a parent directory (see Step 1). `cd` into the correct repo, delete the misplaced `docs/`, and re-run init. +- **Rosetta keeps asking the same questions on every task.** Your `CONTEXT.md` and `ARCHITECTURE.md` are too thin. Fill them in — recurring questions are gaps in those files. +- **You skipped the restart after init.** New `CONTEXT.md` / `ARCHITECTURE.md` won't load mid-session. Always `/exit` + `claude` after init. -- [Usage Guide](USAGE_GUIDE.md) — how to use Rosetta flows -- [Overview](OVERVIEW.md) — mental model and terminology -- [Deployment Guide](DEPLOYMENT_GUIDE.md) — org-wide deployment -- [Contributing](CONTRIBUTING.md) — make your first contribution -- [Architecture](docs/ARCHITECTURE.md) — system internals +Full diagnostics: [TROUBLESHOOTING.md](TROUBLESHOOTING.md). -## Video Tutorials +## Where to next -- [Install Using MCP](https://vimeo.com/1174124251/f38e017d8d?fl=ml&fe=ec) — step-by-step setup -- [Install without MCP](https://vimeo.com/1174124213/c50179147c?fl=ml&fe=ec) — air-gapped environments -- [Initialize with Antigravity](https://vimeo.com/1174124165/8f5fbd7775?fl=ml&fe=ec) — project initialization -- [Subagents and Workflows in Claude Code](https://vimeo.com/1174124272/96056d5cc5?fl=ml&fe=ec) — advanced configuration +- [USAGE_GUIDE.md](USAGE_GUIDE.md) — every workflow and skill in detail +- [OVERVIEW.md](OVERVIEW.md) — mental model and terminology +- [PLUGINS.md](PLUGINS.md) — per-IDE plugin install +- [INSTALLATION.md](INSTALLATION.md) — MCP / STDIO / offline, env vars +- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) — symptom-first diagnosis +- [CONTRIBUTING.md](CONTRIBUTING.md) — making your first Rosetta contribution diff --git a/README.md b/README.md index e12f14fc..27ae2a12 100644 --- a/README.md +++ b/README.md @@ -19,49 +19,55 @@ ## What is Rosetta -Rosetta is a meta-prompting, context engineering, and centralized knowledge management for AI coding agents. It provides structured context - rules, skills, workflows, and sub-agents - guiding AI systems to operate with a deep understanding of system architecture, domain constraints, and engineering standards. Rosetta also accelerates project onboarding by reverse-engineering architecture and domain context, improving the reliability and consistency of AI-generated code. +Rosetta is an open-source instruction-management system for AI coding agents. It plugs into your IDE and delivers the rules, skills, workflows, guardrails, and project conventions your agent needs on each request. -Every AI interaction follows four phases: **Prepare** (load guardrails and context), **Research** (search the knowledge base), **Plan** (produce a reviewable plan), **Act** (execute with full context). Read more in the [Usage Guide](USAGE_GUIDE.md#workflows). +Rosetta gives your AI coding agent your team's context — architecture, conventions, business rules — automatically, in every IDE. -## Supported IDEs and Agents +After installing it, you type something like *"Add password reset to the customer portal"*. Instead of a generic implementation, the agent: -Cursor | Claude Code | VS Code / GitHub Copilot | JetBrains (Copilot, Junie) | Windsurf | Codex | Antigravity | OpenCode | Gemini CLI +1. Drafts a **spec** at `plans/password-reset/password-reset-SPECS.md` — components touched, contracts, acceptance criteria — informed by your existing `CONTEXT.md`, `ARCHITECTURE.md`, and conventions +2. Drafts a **plan** at `plans/password-reset/password-reset-PLAN.md` — phased tasks, subagent delegation, HITL checkpoints +3. Stops at each **approval gate** and waits for explicit confirmation, e.g. `"Yes, I reviewed the plan"` before implementation, `"Yes, I approve the implementation"` before finalizing -Works with any MCP-compatible tool. +Works with Claude Code, Cursor, VS Code Copilot, JetBrains, Codex, Windsurf, OpenCode, and any MCP-compatible tool. + +## Who is Rosetta for + +Mid-level, senior engineers and team-leads working in a multi-user environment with enterprise codebases. Team size doesn't matter — 1 person or 10+. What matters is that the codebase is large enough that one person can't hold all of it, and you ship to real environments where mistakes have real consequences. + +You've used AI coding agents but haven't built your own harness of skills, workflows, and guardrails around them. You want to ship product, not maintain your own prompts. ## Why use it -- **Context engineering, not prompt hacking.** Agents receive your conventions, architecture, and business rules automatically — structured, versioned, and ready before the first line of code. See [how it fits your workflow](OVERVIEW.md#how-rosetta-fits-into-your-workflow). -- **Write once, run everywhere.** Agent-agnostic design adapts to any IDE and any tech stack. No per-tool maintenance. -- **Guardrails built in.** Approval gates, risk assessment, and data protection ensure consistent AI behavior across teams. See [how Rosetta protects you](USAGE_GUIDE.md#how-rosetta-protects-you). -- **Cross-project intelligence** *(opt-in).* Publish business and technical context from every project into a shared knowledge base. Agents see the system, not just one repo — trace flows across services, catch breaking API changes before they ship, and assess blast radius of any change across the portfolio. -- **One-command onboarding.** New repo, new developer — productive immediately with best practices baked in. -- **Instructions as code.** Prompts version-controlled with release management — single source of truth for all teams. +- **Plan first, code after approval.** Before any code is written, Rosetta produces a spec + plan you explicitly approve. Same goes before tests run. No autonomous runaway. +- **One config, every IDE.** Add one MCP endpoint (or install the plugin) — same conventions and guardrails apply in Claude Code, Cursor, Copilot, JetBrains, and the rest. +- **Conventions enforced automatically.** Your `CONTEXT.md`, `ARCHITECTURE.md`, and project rules load into every relevant request. The agent stops fabricating patterns and starts following yours. +- **Designed not to see your code.** Rosetta serves instructions only — source code never reaches it. See [How it works](#how-it-works) below for the architectural controls. + +*Need cross-repo intelligence (trace flows across services, catch breaking API changes early)? See [Cross-Project Context](USAGE_GUIDE.md#cross-project-context) — opt-in via your Rosetta server.* ## How it works -Your IDE connects to the Rosetta MCP server. The server exposes guardrails and common best practices, and provides a menu of available instructions — workflows and coding conventions. The coding agent selects only what it needs for the current task; Rosetta delivers just those, keeping the agent's context lean. By design, no source code or project data reaches Rosetta. +Rosetta provides a menu of instructions — workflows, guardrails, project conventions. Your AI agent picks only what the current task needs, loads it, and runs. Rosetta never sees your source code or project data. -Rosetta is designed to not see your source code. It only serves knowledge and instructions to the agent. The agent loads only what it needs per request (progressive disclosure) and follows your organization's workflows. +Two delivery paths, same content: -Rosetta is engineered to prevent the unintentional transmission of sensitive data through the following architectural controls: -- **Deterministic Instruction Serving**: Instructions are delivered as MCP resources in a strictly deterministic manner. By eliminating the need for semantic search, coding agents are never required to transmit source code or sensitive context to Rosetta to retrieve instructions. -- **Read-Only Default State**: "Write" mode is disabled and hidden by default. Enabling write capabilities requires an explicit, intentional configuration at deployment, ensuring that data persistence remains entirely outside of the end-user's control. -- **Schema-Strict Input Validation**: All MCP tool inputs undergo rigorous validation against predefined schemas. This ensures the system rejects any unexpected payloads or "over-sharing" of data that does not match the required parameters. +- **Plugin (preferred — most clients prefer this).** Bundles instructions directly into your IDE or repo. No live connection to Rosetta needed at request time. Available for Claude Code, VS Code Copilot, JetBrains, Codex. +- **MCP server (fallback).** Your IDE connects to Rosetta over HTTP and pulls instructions on demand. Works with any MCP-compatible IDE. + +For architectural controls and the threat model, see [SECURITY.md](SECURITY.md). ## Get Started -**Cursor** — add to `~/.cursor/mcp.json` or `.cursor/mcp.json`: +> **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. -```json -{ - "mcpServers": { - "Rosetta": { - "url": "https://mcp.rosetta.griddynamics.net/mcp" - } - } -} -``` +### Option A — Install the plugin (recommended) + +A plugin bundles Rosetta's bootstrap rule, skills, agents, and workflows directly into your IDE. No MCP wiring, no manual bootstrap file. + +See [PLUGINS.md](PLUGINS.md) to install Rosetta in your IDE (Claude Code, Cursor, VS Code Copilot, JetBrains Copilot, Codex). + +### Option B — Connect via MCP (fallback for IDEs without a plugin) **Claude Code:** @@ -69,35 +75,78 @@ Rosetta is engineered to prevent the unintentional transmission of sensitive dat claude mcp add --transport http Rosetta https://mcp.rosetta.griddynamics.net/mcp ``` +Then run `claude`, type `/mcp` → Rosetta → **Authenticate**. + +**Cursor / Windsurf** — `~/.cursor/mcp.json`: + +```json +{ "mcpServers": { "Rosetta": { "url": "https://mcp.rosetta.griddynamics.net/mcp" } } } +``` + +**VS Code / Copilot** — `.vscode/mcp.json`: + +```json +{ "servers": { "Rosetta": { "url": "https://mcp.rosetta.griddynamics.net/mcp" } } } +``` + **Codex:** ```sh -codex mcp add Rosetta --url https://mcp.rosetta.griddynamics.net/mcp -codex mcp login Rosetta +codex mcp add Rosetta --url https://mcp.rosetta.griddynamics.net/mcp && codex mcp login Rosetta ``` -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). + +### Verify and initialize + +In your IDE, ask: + +```text +What can you do, Rosetta? +``` + +You should see Rosetta's workflow list. Then, once per repo: + +```text +Initialize this repository using Rosetta +``` + +This generates your `docs/CONTEXT.md`, `docs/ARCHITECTURE.md`, and associated files. Restart the chat after init so the new context loads. + +For details and troubleshooting, see [QUICKSTART.md](QUICKSTART.md) and [TROUBLESHOOTING.md](TROUBLESHOOTING.md). + +## Where to go next + +Pick a path based on your role: -STDIO transport is available for air-gapped environments. [All IDEs and detailed setup](INSTALLATION.md). Read more in the [Quickstart](QUICKSTART.md). +- **Engineer using Rosetta day-to-day** → [QUICKSTART.md](QUICKSTART.md) (first session), then [USAGE_GUIDE.md](USAGE_GUIDE.md) (workflows you'll use), then [FAQ.md](FAQ.md) when stuck. +- **Lead evaluating Rosetta for your team** → [OVERVIEW.md](OVERVIEW.md) (mental model and what Rosetta does *not* do), [SECURITY.md](SECURITY.md) (privacy and threat model), [CONTEXT.md](docs/CONTEXT.md) (business case), and [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md) if you're self-hosting infrastructure. +- **Contributor** → [LEARNING_PATH.md](LEARNING_PATH.md) (what to read in what order), then [CONTRIBUTING.md](CONTRIBUTING.md) (PR workflow). ## Documentation | I want to... | Read | |---|---| | Understand what Rosetta is and how to think about it | [OVERVIEW.md](OVERVIEW.md) | -| Set up Rosetta | [QUICKSTART.md](QUICKSTART.md) | -| Learn how to use Rosetta flows | [USAGE_GUIDE.md](USAGE_GUIDE.md) | +| Read the business case (why Rosetta exists, value per role) | [CONTEXT.md](docs/CONTEXT.md) | +| Onboard as a new contributor (what to read in what order) | [LEARNING_PATH.md](LEARNING_PATH.md) | +| Look up a Rosetta-specific term | [TERMINOLOGY.md](TERMINOLOGY.md) | +| See the full setup guide (all IDEs, troubleshooting) | [QUICKSTART.md](QUICKSTART.md) | +| Learn how to use Rosetta workflows | [USAGE_GUIDE.md](USAGE_GUIDE.md) | | Deploy Rosetta for my organization | [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md) | | Understand the system architecture | [ARCHITECTURE.md](docs/ARCHITECTURE.md) | | Navigate the codebase | [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md) | | Contribute a change | [CONTRIBUTING.md](CONTRIBUTING.md) | +| Get answers to common questions | [FAQ.md](FAQ.md) | | Debug a problem | [TROUBLESHOOTING.md](TROUBLESHOOTING.md) | +| Read the security policy | [SECURITY.md](SECURITY.md) | | See release history | [CHANGELOG.md](CHANGELOG.md) | -| Security Policy | [SECURITY.md](SECURITY.md) | ## Contributing -Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for workflow and expectations. +Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for workflow and expectations. ## Community diff --git a/REVIEW.md b/REVIEW.md index e2b03a8f..5740a945 100644 --- a/REVIEW.md +++ b/REVIEW.md @@ -73,7 +73,7 @@ Instructions (skills, agents, workflows, rules, templates) define how AI agents - **Precise wording.** No vague qualifiers ("approximately", "generally", "might"). Measurable and specific. - **Explicit over implicit.** State requirements directly. Do not assume the agent will infer intent. - **Imperative form.** "Do X", not "You should consider doing X". Target each rule line below 8 words. -- **Use common and domain terms.** Avoid jargon unless defined in [OVERVIEW.md — Key Concepts](OVERVIEW.md#key-concepts). Consistent terminology across all instructions. +- **Use common and domain terms.** Avoid jargon unless defined in [TERMINOLOGY.md](TERMINOLOGY.md). Consistent terminology across all instructions. - **No AI slop.** No filler, no em-dashes, no marketing language. If it sounds like a LinkedIn post, rewrite. - **No non-operational content.** Remove history, rationale annotations, origin labels, change notes. Instructions describe current state. - **Structured over prose.** Prefer lists, tables, and short sections over paragraphs. diff --git a/TERMINOLOGY.md b/TERMINOLOGY.md new file mode 100644 index 00000000..3d6659f3 --- /dev/null +++ b/TERMINOLOGY.md @@ -0,0 +1,22 @@ +# Terminology + +**Who is this for?** Anyone reading or contributing to Rosetta docs who needs the definition of a Rosetta-specific term. +**When should I read this?** As a lookup — these terms appear throughout the rest of the docs. + +| Term | Definition | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | +| **Bootstrap** | Critical universal policies (core, execution, hitl, guardrails) loaded at agent startup. | +| **Classification** | Auto-detection of request type (coding, testing, research, init, etc.) that routes to a specific workflow. | +| **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. | +| **Template** | Parameterized prompt with variables and validated placeholders. | +| **Release** | Versioned instruction set (r1, r2, r3). Enables safe evolution, rollback, and A/B testing. | +| **Guardrails** | Safety measures: scope limits, data protection, transparency rules, approval gates, risk assessment. | +| **Hook** | Agent-side automation triggered by specific events (file modification, tool calls, dangerous actions). Enforces guardrails or injects context. Configured in the IDE (e.g. Claude Code `settings.json`). | +| **HITL** | Human-in-the-loop. Approval gates at critical decision points (specs, plans, risky actions). | +| **Meta-prompting** | Rosetta MCP consults the AI agent on what should be done and how using meta-prompts. | +| **Rosetta** | MCP and CLI of Instruction and Knowledge Management System. | +| **Prompt** | Skill, Rule, Workflow, Command, Subagent, Agent, Template, or any generic prompt. **Rosetta prompt** prompt for Rosetta. | +| **Shells** | Small prompt proxies with proper fronmatters created during onboarding so that coding agents are aware of skill, agents, commands. | diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index edad479b..50cc4bc0 100644 --- a/TROUBLESHOOTING.md +++ b/TROUBLESHOOTING.md @@ -1,7 +1,7 @@ # Troubleshooting **Who is this for?** Anyone blocked while using or developing Rosetta. -**When should I read this?** When something isn't working and you need a quick fix. +**When should I read this?** When something isn't working and you need a quick fix. For meta-questions ("how does X work", "does Rosetta do Y"), see [FAQ.md](FAQ.md) first. --- @@ -96,6 +96,8 @@ Common causes: unsupported file format, oversized documents, malformed markdown. ## Still Stuck? +- [FAQ.md](FAQ.md) — common questions about behavior, token usage, and concepts +- [Discord](https://discord.gg/QzZ2cWg36g) - [Open an issue](https://github.com/griddynamics/rosetta/issues) - [rosetta-support@griddynamics.com](mailto:rosetta-support@griddynamics.com) - [Website](https://griddynamics.github.io/rosetta/) diff --git a/USAGE_GUIDE.md b/USAGE_GUIDE.md index 908de1f4..82e135c4 100644 --- a/USAGE_GUIDE.md +++ b/USAGE_GUIDE.md @@ -1,6 +1,6 @@ # Usage Guide -**Who is this for?** Engineers, leads, and architects using Rosetta in their daily work. +**Who is this for?** Engineers and leads using Rosetta in their daily work. **When should I read this?** After [QUICKSTART.md](QUICKSTART.md). When you want to understand what Rosetta offers and how to use each flow. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index fdd51c8b..eb2e6181 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -4,7 +4,7 @@ **When should I read this?** After [OVERVIEW.md](../OVERVIEW.md). Before touching MCP tools, CLI publishing, instruction content, or folder structure. -For terminology (workflow, skill, rule, subagent, bootstrap, etc.), see [OVERVIEW.md — Key Concepts](../OVERVIEW.md#key-concepts). +For terminology (workflow, skill, rule, subagent, bootstrap, etc.), see [TERMINOLOGY.md](../TERMINOLOGY.md). --- @@ -407,7 +407,7 @@ Instructions live in `/instructions/r2/` in the instructions repository, using a **Layered customization.** Core provides the universal foundation. Organization folders extend or override it. Files at the same VFS resource path get **bundled together** by the Bundler. `INSTRUCTION_ROOT_FILTER` controls which layers are included (e.g., `CORE,GRID`). -**Component relationships.** Workflows invoke subagents. Subagents use skills. All reference rules. Templates live inside skills. Guardrails are rules. See [Overview — Key Concepts](../OVERVIEW.md#key-concepts) for definitions. +**Component relationships.** Workflows invoke subagents. Subagents use skills. All reference rules. Templates live inside skills. Guardrails are rules. See [TERMINOLOGY.md](../TERMINOLOGY.md) for definitions. **Naming.** Lowercase, dash-separated, globally unique filenames. Entry points: `SKILL.md` for skills, `.md` for agents, workflows, and rules. diff --git a/docs/web/_layouts/docs.html b/docs/web/_layouts/docs.html index 17b8dfc4..342c0a2e 100644 --- a/docs/web/_layouts/docs.html +++ b/docs/web/_layouts/docs.html @@ -44,6 +44,7 @@

Guides

Usage Guide + Customize Deployment Troubleshooting diff --git a/docs/web/docs/customize.md b/docs/web/docs/customize.md new file mode 100644 index 00000000..0bd90a8c --- /dev/null +++ b/docs/web/docs/customize.md @@ -0,0 +1,209 @@ +--- +layout: docs +title: Customize +permalink: /docs/customize/ +--- + +# Customize Rosetta for your project + +Rosetta works out of the box. These three things make it work *better* — adapted to how your team actually writes code. + +All three are optional. They stack in impact: invest in #1 first, add #2 and #3 only when you hit the specific need. + +--- + +## 1. Improve your context files + +**The single highest-leverage customization.** Every Rosetta workflow reads `docs/CONTEXT.md` and `docs/ARCHITECTURE.md` before doing anything. The more these files cover, the fewer questions Rosetta asks and the better the output. + +### What they are + +These files are created automatically when you run "Initialize this repository using Rosetta". After init, you edit them by hand to fill the gaps. + +| File | What goes in it | +| --------------------- | ---------------------------------------------------------------------------------------------------------------- | +| `docs/CONTEXT.md` | **The why.** Business purpose, user types, key workflows, domain constraints, what success looks like. | +| `docs/ARCHITECTURE.md`| **The how.** System components, data flow, deployment topology, integration points, key design decisions. | +| `docs/TECHSTACK.md` | **The what.** Languages, frameworks, libraries, tools, plus *why* each was chosen (helps Rosetta avoid wrong replacements). | + +### When to do it + +- Rosetta keeps asking the same questions across different tasks +- Output keeps missing a convention your team takes for granted +- A new engineer joins and you wish they could read one file to understand the project — that file should be CONTEXT.md +- You're about to start a non-trivial feature and want to front-load the context + +### Example: thin vs fleshed-out CONTEXT.md + +**Thin (what init often produces if your repo lacks signals):** + +```markdown +# Context + +This project is a REST API for managing customer orders. +Built with Node.js and PostgreSQL. +``` + +→ Rosetta will ask about auth, payment integration, multi-tenancy, error format, +idempotency, and 5 other things before it can plan any feature. + +**Fleshed out:** + +```markdown +# Context + +## Purpose +B2B order management API used by 40 enterprise customers. Handles +order intake, fulfillment routing, and invoice generation. Replaces +a legacy SAP module. + +## Key constraints +- Multi-tenant: every table has `tenant_id`, every query MUST filter on it +- Idempotency required on all POSTs — clients retry aggressively +- Invoices are immutable once issued (audit requirement) +- All money is stored as integer cents, never floats + +## Integration points +- Auth: Okta SSO + service-to-service JWT (see ARCHITECTURE.md) +- Payments: Stripe Connect (we never touch card data) +- Fulfillment: outbound webhooks to 3 warehouse partners + +## What "done" looks like +- Endpoint has OpenAPI spec, 80%+ test coverage, idempotency key support, + tenant filter, structured error response `{ error: { code, message } }` +``` + +→ Rosetta now plans a feature with idempotency, tenant filtering, and the +correct error shape on the first pass. No follow-up questions. + +### Tip: spot when yours needs work + +After a few Rosetta sessions, look at the questions Rosetta asked. Every +recurring question is a CONTEXT.md or ARCHITECTURE.md gap. + +--- + +## 2. Add project-specific rules + +**For hard rules you want enforced every time.** Drop a markdown file alongside Rosetta — no Rosetta files modified. Rosetta loads your project rules on top of its own. + +### When to do it + +- "Always use pnpm, never npm/yarn" +- "All new endpoints must use the standard error middleware" +- "No `console.log` — use the structured logger from `lib/log.ts`" +- "Tests must use Vitest, not Jest" +- "All React components must be functional with hooks; no class components" + +If you find yourself correcting Rosetta the same way twice, that's a rule. + +### Where to put rules + +| IDE | Path (any `.md` file works) | +| -------------------------------- | ------------------------------ | +| Cursor | `.cursor/rules/*.mdc` | +| Claude Code | `.claude/rules/*.md` | +| Windsurf | `.windsurf/rules/*.md` | +| JetBrains (Junie + AI Assistant) | `.aiassistant/rules/agents.md` | +| Antigravity | `.agent/rules/*.md` | +| OpenCode | `.opencode/agent/*.md` | +| VS Code / GitHub Copilot | `.github/copilot-instructions.md` | + +### Example: an API conventions rule + +Save as `.claude/rules/api-conventions.md` (or the equivalent path for your IDE): + +```markdown +# API conventions + +Apply when adding, modifying, or reviewing any HTTP endpoint. + +## Required for every endpoint + +1. **Tenant filter.** Every query MUST include `WHERE tenant_id = $1`. + Reject if missing — no exceptions. +2. **Idempotency.** POSTs must accept `Idempotency-Key` header and dedupe + via the `idempotency_keys` table. +3. **Error shape.** Errors return `{ error: { code: string, message: string } }`. + Codes from `lib/errors/codes.ts`. Never leak raw DB or stack messages. +4. **Validation.** Use Zod schemas in `schemas/`. No inline validation. +5. **Tests.** At least one happy path + one tenant-isolation test + (verify cross-tenant request returns 404, not 403). + +## Forbidden + +- `console.log` — use `logger` from `lib/log.ts` +- Raw SQL string concatenation — use parameterized queries or the query builder +- Returning DB rows directly — always map through a DTO in `dto/` +``` + +→ Rosetta now applies all of this automatically. You stop catching the same +mistakes in review. + +### Tips + +- **One file per topic.** `api-conventions.md`, `testing.md`, `logging.md` — easier to skim than one mega-file. +- **State the trigger.** Start with "Apply when…" so Rosetta knows when the rule activates. +- **Show, don't tell.** Bad/good code snippets beat prose explanations. + +--- + +## 3. Add helper MCPs + +**To give Rosetta capabilities beyond your codebase.** MCPs are tools your AI agent can call — Rosetta is one of them, but you can add more. + +### When to do it + +- Rosetta hallucinates library APIs → add a docs MCP (Context7) +- You need the agent to test a web page → add a browser MCP (Playwright / Chrome DevTools) +- Agent needs to read your DB schema or run queries → add a database MCP +- You want it to look up Jira tickets or Figma designs → add the matching MCP + +### The top 3 + +Add these to the same IDE config file where you added Rosetta. + +**Context7** — up-to-date library/framework docs. Best ROI of any MCP. + +```json +{ + "mcpServers": { + "Rosetta": { "url": "https://mcp.rosetta.griddynamics.net/mcp" }, + "Context7": { "url": "https://mcp.context7.com/mcp" } + } +} +``` + +**Playwright MCP** — drive a real browser, fill forms, click elements, scrape pages. + +```json +{ "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp@latest"] } } +``` + +**Chrome DevTools MCP** — full Chrome control: console, network tab, snapshots. + +```json +{ "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp"] } } +``` + +Full list with use cases: [Usage Guide → Recommended MCP Servers](/rosetta/docs/usage-guide/#recommended-mcp-servers). + +--- + +## How they stack + +| Layer | Effort | Impact | Best for | +| ---------------- | ------------- | -------- | --------------------------------------------- | +| Context files | 30–60 min | Huge | Every project. Do this first. | +| Project rules | 5–10 min each | High | Recurring corrections, team conventions. | +| Helper MCPs | 1 min each | Variable | Specific capabilities Rosetta is missing. | + +Start with #1. Add a rule the first time you correct Rosetta twice. Add an MCP the first time Rosetta says "I'd need to check the docs for that." + +--- + +## Going deeper + +- [Quick Start](/rosetta/docs/quickstart/) — installation and basics +- [Usage Guide](/rosetta/docs/usage-guide/) — every workflow, skill, and agent +- [Architecture](/rosetta/docs/architecture/) — how Rosetta loads and applies these layers under the hood diff --git a/docs/web/docs/index.md b/docs/web/docs/index.md index 98cb9450..bf4a8a5c 100644 --- a/docs/web/docs/index.md +++ b/docs/web/docs/index.md @@ -45,6 +45,11 @@ Rosetta is a meta-prompting, context engineering, and centralized instructions m

Usage Guide

Workflows, skills, agents, customization, and best practices.

+ +

Guides

+

Customize

+

Adapt Rosetta to your project: context files, project rules, helper MCPs — with examples.

+

Guides

Deployment

diff --git a/docs/web/docs/quickstart.md b/docs/web/docs/quickstart.md index 16e021be..4ee47624 100644 --- a/docs/web/docs/quickstart.md +++ b/docs/web/docs/quickstart.md @@ -4,235 +4,196 @@ title: Quick Start permalink: /docs/quickstart/ --- -# Quick Start +# Overview -**Who is this for?** New users setting up Rosetta for the first time. +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. + +> **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. --- -## Step 1: Connect Rosetta MCP +## 1. Install -> [!WARNING] -> You must receive a prior approval from your manager and company to use it. +Two options. **Pick A if your IDE supports a plugin** — it's the recommended path. Otherwise use B. -> [!WARNING] -> Use **Sonnet 4.6**, **GPT-5.3-codex-medium**, **gemini-3.1-pro** or better models. Avoid Auto model selection. +### Option A — Plugin (recommended) -> [!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. +A plugin bundles Rosetta's bootstrap rule, skills, agents, and workflows directly into your IDE. No MCP wiring, no manual bootstrap file. -Rosetta uses HTTP MCP transport with OAuth. Pick your IDE and add the configuration. +| IDE | Install | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| **Claude Code** | `claude plugin marketplace add griddynamics/rosetta` then `claude plugin install core@rosetta` | +| **VS Code / GitHub Copilot** | Install `core-copilot` via VS Code Copilot Plugins | +| **JetBrains / Copilot** | Zip + manual config — see [Installation](/rosetta/docs/installation/#plugin-based-installation) | +| **Codex** | Zip + `codex features enable codex_hooks` — see [Installation](/rosetta/docs/installation/#plugin-based-installation) | -
-Cursor +> Plugins are the recommended install path — clients prefer them over MCP, and the install bundles everything you need (bootstrap rule, skills, agents, workflows). If a plugin isn't available for your IDE yet, use Option B. -Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project): +Done with Option A → skip to **[Verify](#2-verify)**. -```json -{ - "mcpServers": { - "Rosetta": { - "url": "https://mcp.rosetta.griddynamics.net/mcp" - } - } -} -``` +### Option B — MCP + bootstrap (fallback) -
+Use this when your IDE doesn't have a plugin yet, or your environment requires it. -
+**B.1 — Connect Rosetta MCP** + +
Claude Code ```sh claude mcp add --transport http Rosetta https://mcp.rosetta.griddynamics.net/mcp ``` -Authenticate inside a claude session with `/mcp`, select Rosetta, Authenticate, and complete the OAuth flow. - +Then start `claude` and, inside the session, type `/mcp` → select **Rosetta** → **Authenticate** to complete OAuth.
-Codex - -```sh -codex mcp add Rosetta --url https://mcp.rosetta.griddynamics.net/mcp -codex mcp login Rosetta -``` +Cursor / Windsurf -
- -
-VS Code / GitHub Copilot - -Add to `.vscode/mcp.json` or `~/.mcp.json`: +`~/.cursor/mcp.json` (or project-local `.cursor/mcp.json`): ```json -{ - "servers": { - "Rosetta": { - "url": "https://mcp.rosetta.griddynamics.net/mcp" - } - } -} +{ "mcpServers": { "Rosetta": { "url": "https://mcp.rosetta.griddynamics.net/mcp" } } } ``` -
-GitHub Copilot (JetBrains) +VS Code / GitHub Copilot -`Settings` > `Tools` > `GitHub Copilot` > `MCP Settings`. Add to `~/.config/github-copilot/intellij/mcp.json`: +`.vscode/mcp.json` or `~/.mcp.json`: ```json -{ - "servers": { - "Rosetta": { - "url": "https://mcp.rosetta.griddynamics.net/mcp" - } - } -} +{ "servers": { "Rosetta": { "url": "https://mcp.rosetta.griddynamics.net/mcp" } } } ``` - -Restart IDE after changes. -
-JetBrains Junie - -`Settings` > `Tools` > `Junie` > `MCP Settings` > `+ Add` > `As JSON`: +Codex / JetBrains / Antigravity / OpenCode -```json -{ - "mcpServers": { - "Rosetta": { - "url": "https://mcp.rosetta.griddynamics.net/mcp" - } - } -} +```sh +# Codex +codex mcp add Rosetta --url https://mcp.rosetta.griddynamics.net/mcp && codex mcp login Rosetta ``` +JetBrains Junie: `Settings → Tools → Junie → MCP Settings → + Add → As JSON`, use the Cursor JSON above. +GitHub Copilot (JetBrains): `Settings → Tools → GitHub Copilot → MCP Settings`, edit `~/.config/github-copilot/intellij/mcp.json` with the VS Code JSON above. +Antigravity / OpenCode: see [Installation](/rosetta/docs/installation/).
-
-Windsurf +> For the full list of IDEs, see [Installation](/rosetta/docs/installation/). -Add to your Windsurf MCP config: +**B.2 — Add the bootstrap rule (mandatory for MCP mode)** -```json -{ - "mcpServers": { - "Rosetta": { - "url": "https://mcp.rosetta.griddynamics.net/mcp" - } - } -} -``` +MCP alone doesn't reliably trigger Rosetta on every request. You must drop a small markdown file (`bootstrap.md`) into your IDE's instructions so the agent calls Rosetta before doing anything. -
+Download [bootstrap.md](https://github.com/griddynamics/rosetta/blob/main/instructions/r2/core/rules/bootstrap.md?plain=1) and place it at the path for your IDE: -
-Antigravity +| IDE | Path | +| ------------------------------ | --------------------------------- | +| Cursor | `.cursor/rules/bootstrap.mdc` | +| Claude Code | `.claude/claude.md` | +| VS Code / Copilot (any) | `.github/copilot-instructions.md` | +| JetBrains Junie | `.junie/guidelines.md` | +| Windsurf | `.windsurf/rules/bootstrap.md` | +| Antigravity | `.agent/rules/bootstrap.md` | +| OpenCode | `AGENTS.md` | -Add to your Antigravity MCP config: +Keep the file's YAML frontmatter intact. -```json -{ - "mcpServers": { - "Rosetta": { - "serverUrl": "https://mcp.rosetta.griddynamics.net/mcp" - } - } -} -``` +## 2. Verify -
+``` +What can you do, Rosetta? +``` -
-OpenCode +The agent should list Rosetta's workflows and capabilities. If it doesn't, jump to [Setup issues](#setup-issues). -Add to `opencode.json`: +## 3. Initialize your repo -```json -{ - "mcp": { - "Rosetta": { - "type": "http", - "url": "https://mcp.rosetta.griddynamics.net/mcp", - "enabled": true - } - } -} +``` +Initialize this repository using Rosetta ``` -
+Rosetta scans your stack, generates `docs/TECHSTACK.md`, `docs/CODEMAP.md`, `docs/DEPENDENCIES.md`, `docs/CONTEXT.md`, `docs/ARCHITECTURE.md`, and asks you to fill the gaps. **Restart your chat session afterward** so the new context loads. -Any MCP client that supports HTTP transport can connect using the endpoint URL. Complete the OAuth flow when prompted. +Run once per repo. For composite workspaces, init each repo first, then run init at workspace level with "This is composite workspace" appended. -STDIO transport is available for air-gapped environments. See [Installation](/rosetta/docs/installation/). +--- -## Step 2: Verify +## A real example -Ask the agent: +> *A **workflow** is what Rosetta runs to do the work — coding, init, requirements, etc. Rosetta picks the workflow from your request automatically.* ``` -What can you do, Rosetta? +You: "Add password reset support to the customer portal. + I want to review the plan first." + +Rosetta loads the coding workflow: + + • Discovery – discoverer subagent gathers affected code, + dependencies, constraints + • Tech plan – architect writes -SPECS.md (the what) + and -PLAN.md (the how) in the feature + plan folder (e.g. plans/PASSWORD-RESET/) + • Review plan – reviewer inspects them against your request + → Your approval – say "Yes, I reviewed the plan" + • Implementation – engineer codes only the approved scope; + build must pass (tests are separate) + • Review code – reviewer inspects the diff against the specs + • Validation – validator checks spec coverage and gaps + → Your approval – say "Yes, I approve the implementation" + • Tests – engineer writes and runs isolated tests + • Review tests – reviewer checks coverage and scenarios + • Final validation – end-to-end dependency check ``` -It should use Rosetta MCP to retrieve agents, guardrails, and instructions. +Phases scale by task size: small tasks handle discovery, reviews, and validation inline, and may combine the two approval gates into one. Approval is still always explicit. See [Coding Flow](/rosetta/docs/coding-flow/) for the full canonical phase list with scaling rules. -## Step 3: Initialize (once per repository) +## Common requests -Ask the agent: +Plain language. Rosetta picks the workflow. -``` -Initialize this repository using Rosetta -``` +| Say this | What runs | +| ----------------------------------------------------- | ---------------------- | +| "Add / fix / change \" | Coding workflow | +| "Initialize this repository" | Init workflow | +| "Explain how \ works" | Code analysis | +| "Define requirements for \" | Requirements authoring | +| "Ad-hoc: \" | Composed flow | +| "What can you do, Rosetta?" / "What workflows exist?" | Self-help | -The agent will analyze your tech stack, generate documentation (TECHSTACK.md, CODEMAP.md, DEPENDENCIES.md, ARCHITECTURE.md, CONTEXT.md), and ask clarifying questions. Read more about [workspace files](/rosetta/docs/installation/#workspace-files-created) and [all workflows](/rosetta/docs/usage-guide/#workflows). +Pro workflows (Research, Modernization, Test Generation, Automated QA, External Library, Prompting) need the enterprise edition — see [Usage Guide](/rosetta/docs/usage-guide/#workflows). -> [!NOTE] -> **Prefer medium models:** High reasoning and Opus models consume too much token on reasoning. -> **Composite workspaces:** init each repository separately, then init at the workspace level with "This is composite workspace" appended. -> **Dead code or existing specs:** mention their location in the prompt to save time. +## Setup issues -## Step 4: Add Bootstrap Rule (optional) +| Symptom | Fix | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| OAuth prompt never appears | Restart IDE. In Claude Code, run `claude`, then in-session: `/mcp` → Rosetta → Authenticate. | +| Agent ignores Rosetta tools | **MCP mode:** confirm `bootstrap.md` is in place (Step B.2) and the MCP server shows connected. **Plugin mode:** confirm plugin installed via `claude plugin list`. | +| Agent worked, then stopped | OAuth token expired. Re-authenticate. Tools still appear but instructions stop loading. | +| Inconsistent / shallow output | Wrong model. Switch off Auto and use Sonnet 4.6 / GPT-5.3-codex-medium / gemini-3.1-pro. | +| Slow or empty replies | Check network reaches `mcp.rosetta.griddynamics.net`. First-time init on large repos is slow — that's expected. | -If something does not work. +Full diagnostics: [Troubleshooting](/rosetta/docs/troubleshooting/). -Download [bootstrap.md](https://github.com/griddynamics/rosetta/blob/main/instructions/r2/core/rules/bootstrap.md?plain=1) and add it to your IDE's instruction file (keep entire contents, including YAML frontmatter): +## Customize (optional) -| IDE | Destination | -| -------------------------- | --------------------------------- | -| Cursor | `.cursor/rules/bootstrap.mdc` | -| Claude Code | `.claude/claude.md` | -| VS Code / GitHub Copilot | `.github/copilot-instructions.md` | -| GitHub Copilot (JetBrains) | `.github/copilot-instructions.md` | -| JetBrains Junie | `.junie/guidelines.md` | -| Windsurf | `.windsurf/rules/bootstrap.md` | -| Antigravity | `.agent/rules/bootstrap.md` | -| OpenCode | `AGENTS.md` | +Three ways to make Rosetta work better for your project, ordered by impact: improve your context files, add project-specific rules, and add helper MCPs. None are required — start with the first when Rosetta begins asking the same questions repeatedly. -## Common Issues +See [Customize](/rosetta/docs/customize/) for the full how-to with real example rule files and configs. -- **OAuth prompt does not appear:** restart your IDE and retry the connection. Read more in [Troubleshooting — Connection & Authentication](/rosetta/docs/troubleshooting/#connection--authentication). -- **Agent ignores Rosetta tools:** confirm the MCP server shows as connected in your IDE's MCP settings. Add a [bootstrap rule](/rosetta/docs/installation/) if the agent still skips Rosetta. Read more in [Troubleshooting — Agent Not Using Rosetta](/rosetta/docs/troubleshooting/#agent-not-using-rosetta). -- **Slow or empty responses:** check your network can reach your Rosetta MCP host. See [Troubleshooting](/rosetta/docs/troubleshooting/#slow-or-empty-responses). +--- -## Next Steps +## Going deeper -- [Usage Guide](/rosetta/docs/usage-guide/) — how to use Rosetta flows -- [Overview](/rosetta/docs/overview/) — mental model and terminology -- [Deployment](/rosetta/docs/deployment/) — org-wide deployment -- [Contributing](/rosetta/docs/contributing/) — make your first contribution -- [Architecture](/rosetta/docs/architecture/) — system internals +- [Usage Guide](/rosetta/docs/usage-guide/) — every workflow, skill, and agent in detail +- [Architecture](/rosetta/docs/architecture/) — how Rosetta works under the hood +- [Installation](/rosetta/docs/installation/) — STDIO, plugins, air-gapped, env vars +- [Deployment](/rosetta/docs/deployment/) — running Rosetta org-wide +- [Contributing](/rosetta/docs/contributing/) — submit a PR -## Video Tutorials +Stuck? [Discord](https://discord.gg/QzZ2cWg36g) · [Issues](https://github.com/griddynamics/rosetta/issues) · rosetta-support@griddynamics.com -- [Install Using MCP](https://vimeo.com/1174124251/f38e017d8d?fl=ml&fe=ec) — step-by-step setup -- [Install without MCP](https://vimeo.com/1174124213/c50179147c?fl=ml&fe=ec) — air-gapped environments -- [Initialize with Antigravity](https://vimeo.com/1174124165/8f5fbd7775?fl=ml&fe=ec) — project initialization -- [Subagents and Workflows in Claude Code](https://vimeo.com/1174124272/96056d5cc5?fl=ml&fe=ec) — advanced configuration +> Rosetta is designed to never see your data or IP — it provides a "menu" of instructions to your agent, not the other way around. Get manager/company approval before using it on real codebases.