diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9f55961..fb20a34 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,9 +7,7 @@ ## Before You Start -- Read the [OVERVIEW](OVERVIEW.md) to understand what Rosetta is -- Understand the [Architecture](docs/ARCHITECTURE.md) -- Follow the [Developer Guide](DEVELOPER_GUIDE.md) +If you haven't already, read [OVERVIEW.md](OVERVIEW.md) to understand what Rosetta is. The [Architecture](docs/ARCHITECTURE.md) is useful background but not required for most contributions. For local dev setup and where things live in the repo, the [Developer Guide](DEVELOPER_GUIDE.md) is the next stop after you've read this file. ## What Contributions Are Welcome @@ -45,41 +43,22 @@ fork/clone → branch → edit → validate → push → PR See [Overall Development Flow](DEVELOPER_GUIDE.md#overall-development-flow) on how to run, test, build, review, and validate. -## Prompt Changes +## Prompt Change PRs -Rosetta is a prompt engineering system. Prompt changes have outsized impact and need extra care. +A prompt change changes how AI agents behave across every project that uses Rosetta. There's no compile error and no failing test if you break something — regressions are silent. That's why prompt PRs need evidence of behavior, not just a code-style review. -**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. +The PR must include: -Examples: +1. **A prompt brief** — goal, non-goals, constraints. +2. **Before/after behavior examples** — a prompt run on the old version, the same prompt on the new version, both outputs in the PR. +3. **Validation evidence** — what you ran to confirm the new prompt doesn't regress what the old one did. Attach to the PR description. -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 ``: - ``` +Two automated gates run on prompt PRs. Both must pass before merge: -**What to include in the PR:** +- **Static AI review** — checks the prompt file for structural problems (missing schema sections, broken frontmatter, missing required tags) before a human reviews it. +- **Scenario comparison** — runs the same scenarios against the old prompt and your new prompt, then shows the behavioral diff so the reviewer can see what actually changed. -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. +For *how* to author the prompt change itself (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 0ca03b7..e7afaeb 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -14,8 +14,30 @@ - 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, refactor, or harden prompts (agents, skills, workflows, rules, templates). Use Opus 4.6 or newer. + + Concrete invocations: + + Refactor an old prompt to R2 format: + + ```text + MUST FULLY EXECUTE `instructions/r2/core/workflows/coding-agents-prompting-flow.md` to refactor old Rosetta prompt `` as R2 prompt family in Rosetta. + ``` + + Create a new prompt: + + ```text + MUST FULLY EXECUTE `instructions/r2/core/workflows/coding-agents-prompting-flow.md` to author a new R2 Rosetta ``: + ``` + + Via Rosetta MCP (instead of file path): + + ```text + MUST ACQUIRE coding-agents-prompting-flow.md FROM KB AND FULLY EXECUTE IT to author a new R2 Rosetta ``: + ``` + + For PR submission requirements (brief, before/after, validation evidence), see [CONTRIBUTING → Prompt Change PRs](CONTRIBUTING.md#prompt-change-prs). 3. **Check your output.** - [General Review Criteria](REVIEW.md#general-review-criteria) @@ -45,7 +67,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/OVERVIEW.md b/OVERVIEW.md index 1726401..1917279 100644 --- a/OVERVIEW.md +++ b/OVERVIEW.md @@ -25,7 +25,7 @@ Design principles: **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. diff --git a/README.md b/README.md index 9819cdf..1a8e29f 100644 --- a/README.md +++ b/README.md @@ -19,43 +19,46 @@ ## 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 gives your AI coding agent your team's context — architecture, conventions, business rules — automatically, in every IDE. -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). +After installing it, you type something like *"Add password reset to the customer portal"*. Instead of a generic implementation, you get a spec + plan that already understands your codebase, with explicit approval gates before any code is written. + +Works with Claude Code, Cursor, VS Code Copilot, JetBrains, Codex, Windsurf, OpenCode, and any MCP-compatible tool. ## 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. + +Two delivery paths, same content: -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. +- **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. -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. +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) + +| IDE | Command | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------ | +| **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.md](INSTALLATION.md#plugin-based-installation) | +| **Codex** | Zip + `codex features enable codex_hooks` — see [INSTALLATION.md](INSTALLATION.md#plugin-based-installation) | + +### Option B — Connect via MCP (fallback for IDEs without a plugin) **Claude Code:** @@ -63,41 +66,66 @@ 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). -STDIO transport is available for air-gapped environments. [All IDEs and detailed setup](INSTALLATION.md). Read more in the [Quickstart](QUICKSTART.md). +### Verify and initialize -## Supported IDEs and Agents +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 +``` -Cursor | Claude Code | VS Code / GitHub Copilot | JetBrains (Copilot, Junie) | Windsurf | Codex | Antigravity | OpenCode +This generates your `docs/CONTEXT.md`, `docs/ARCHITECTURE.md`, and friends. Restart the chat after init so the new context loads. -Works with any MCP-compatible tool. +For details and troubleshooting, see [QUICKSTART.md](QUICKSTART.md) and [TROUBLESHOOTING.md](TROUBLESHOOTING.md). ## 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) | +| 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) | | 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/docs/web/_layouts/docs.html b/docs/web/_layouts/docs.html index 4efe9ba..b4524ef 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/coding-flow.md b/docs/web/docs/coding-flow.md index 544b888..7b2bafd 100644 --- a/docs/web/docs/coding-flow.md +++ b/docs/web/docs/coding-flow.md @@ -4,48 +4,15 @@ title: Coding Flow permalink: /docs/coding-flow/ --- -# Coding Flow +# Coding workflow -## Availability +When you ask Rosetta to **add, change, or fix code**, this is the workflow it runs. It produces a spec and plan first (which you approve), then the code, then tests — with explicit gates at the two points where you decide whether to continue. -OSS. This workflow lives in the core Rosetta instruction set. +> Available in: OSS core. -## TL;DR +## When to use it -Use Coding Flow for implementation work when coding is the main job, including feature work, changes, and bug fixes. -Rosetta structures that work through specs, a plan, review gates, validation, and tests. -It is the workflow Rosetta uses for adding, changing, or fixing code when coding is the main job. -It produces a plan package first, then code, review findings, validation findings, tests, and final validation evidence. -You must explicitly approve the plan before implementation starts. -You must explicitly approve the implementation before tests continue. -The workflow applies at all request sizes. What changes by size is phase scaling, not whether the workflow should be used. -Medium and large tasks add separate discovery, review, and validator work where the source marks those phases as `MEDIUM,LARGE`. -For small tasks, the source says the plan-review and implementation-review checkpoints may be combined. This page keeps that conservative: approval is still explicit and tests still do not continue without it, but the source does not define a more detailed small-task checkpoint shape than that. - -## When To Use This Workflow - -- Add, change, or fix application code. -- Implement work that needs an explicit spec and plan before coding. -- Use reviewer and validator gates to catch drift before you approve work. -- Handle code changes of any size when coding is the main job. -- Expect the workflow to scale by request size instead of switching to a different coding workflow. - -## When Not To Use This Workflow - -- Use [Requirements Documentation Authoring Flow](/rosetta/docs/requirements-authoring-flow/) when expected behavior is still unclear and you need requirements before planning code. -- Use [Code Analysis Flow](/rosetta/docs/code-analysis-flow/) when the goal is to understand existing code, not change it. -- Use [Ad-hoc Flow](/rosetta/docs/adhoc-flow/) when no fixed workflow fits the task and you need a lighter custom sequence. -- Use [Research Flow](/rosetta/docs/research-flow/) when the main deliverable is grounded investigation rather than implementation. - -## Before You Start - -- Prepare a concrete change request with scope and acceptance criteria. -- Make sure `docs/CONTEXT.md` and `docs/ARCHITECTURE.md` are current enough to guide implementation. -- Point the agent to existing requirements, API contracts, design notes, or issue links if they define non-negotiable behavior. -- Provide workflow-specific implementation context that materially changes the result, especially business rules, edge cases, auth behavior, schema and DDL constraints, config switches, and internal library references under `refsrc/`. -- For shared setup and general Rosetta customization, use [Usage Guide](/rosetta/docs/usage-guide/) instead of repeating that setup here. - -## How To Start +Say something like: ```text Add password reset support for the customer portal. I want to review the plan before implementation starts. @@ -63,13 +30,14 @@ Implement notification delivery using the existing queue abstraction. The auth r Change the billing retry logic to match the approved requirements in docs/REQUIREMENTS. Stop for approval before coding. ``` -## How Rosetta Shapes This Workflow - -Rosetta changes the user experience before any code is touched. The coding agent must load Rosetta bootstrap rules, then read project context files, then load the coding workflow. That means the session starts with context loading, classification, and planning instead of immediate edits. +Don't use it for: -Rosetta also forces explicit approvals and role separation. The workflow stays active for all request sizes, but medium and large tasks route more phases through specialized subagents for discovery, review, validation, build, and test work, so the same agent is not trusted to invent, implement, and approve in one pass. Questions are supposed to appear early when requirements, scope, or constraints are unclear. +- Understanding existing code without changing it → use [Code Analysis](/rosetta/docs/code-analysis-flow/) +- Writing requirements before the behavior is settled → use [Requirements Authoring](/rosetta/docs/requirements-authoring-flow/) +- One-off odd jobs that don't need full planning → use [Ad-hoc](/rosetta/docs/adhoc-flow/) +- Investigation rather than implementation → use [Research](/rosetta/docs/research-flow/) -Rosetta provides instructions. Coding agents act on them. Rosetta itself does not see user requests, code, or project data. +> **Quality of output depends on `docs/CONTEXT.md` and `docs/ARCHITECTURE.md`.** Rosetta reads them before planning — stale or missing context means the plan will ask more questions or miss conventions. If the change touches auth, the database schema, or external contracts, point the agent at the relevant files in your prompt. ## Workflow At A Glance diff --git a/docs/web/docs/customize.md b/docs/web/docs/customize.md new file mode 100644 index 0000000..0bd90a8 --- /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 98cb945..bf4a8a5 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 16e021b..4ee4762 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.