griddynamics · ymakaruk-pixel · May 12, 2026 · May 12, 2026 · May 13, 2026 · May 14, 2026
@@ -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 `<prompt full path>` 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 <skill/agent/workflow/rule/prompt family> `<name>`: <description of what it should be>
-   ```
-
-3. Using Rosetta MCP:
-   ```
-   MUST ACQUIRE coding-agents-prompting-flow.md FROM KB AND FULLY EXECUTE IT to author a new R2 Rosetta <skill/agent/workflow/rule/prompt family> `<name>`: <description of what it should be>
-   ```
+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
 

@@ -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 `<prompt full path>` 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 <skill/agent/workflow/rule/prompt family> `<name>`: <description of what it should be>
+     ```
+
+     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 <skill/agent/workflow/rule/prompt family> `<name>`: <description of what it should be>
+     ```
+
+     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
 

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

@@ -19,85 +19,113 @@
 
 ## 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:**
 
 ```sh
 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
 

@@ -44,6 +44,7 @@
 
     <p class="docs-sidebar-cat">Guides</p>
     <a href="{{ '/docs/usage-guide/' | relative_url }}" class="docs-sidebar-link{% if page.url == '/docs/usage-guide/' %} active{% endif %}">Usage Guide</a>
+    <a href="{{ '/docs/customize/' | relative_url }}" class="docs-sidebar-link{% if page.url == '/docs/customize/' %} active{% endif %}">Customize</a>
     <a href="{{ '/docs/deployment/' | relative_url }}" class="docs-sidebar-link{% if page.url == '/docs/deployment/' %} active{% endif %}">Deployment</a>
     <a href="{{ '/docs/troubleshooting/' | relative_url }}" class="docs-sidebar-link{% if page.url == '/docs/troubleshooting/' %} active{% endif %}">Troubleshooting</a>