rosetta

What is Rosetta

https://github.com/user-attachments/assets/6df6e217-3e5c-4691-84ed-7440701a87de

AI coding agents are great — until you try to use them across a real team. Everyone builds their own prompts and instructions, knowledge stays in silos, and the agent — not knowing your architecture or constraints — guesses from a few open files and confidently does the wrong thing.

That's why we built Rosetta — open-source engineering governance and context for AI coding agents. It's not another proprietary agent; it works with the tools you already use (Claude Code, Cursor, Copilot, Codex, and other MCP-compatible agents) and loads your team's shared engineering instructions into every session. Everything is versioned in Git and can run inside your perimeter.

Teach agents how to think, not what to do. The model already knows Python and React; what it lacks is your engineering discipline. That's what Rosetta encodes.

[!NOTE] If you are effectively using your current setup, writing your own skills, and managing AI using your own processes, you probably don't need Rosetta.

User Guide

Rosetta-guided work follows five phases — Prepare → Research → Plan → Act → Validate — with approval gates at the key decision points.

Read more in the User Guide.

Quick Start

Overall Process: Install (plugin preferred) → Initialize workspace → Configure workspace ecosystem (tools, MCPs) → Proceed with Coding, Modernization, Analysis, etc.

Please follow Quick Start Guide which will walk you through the process.

Very detailed information on installation and configuration in all available modes is in Installation Guide.

Skills

Reusable units of work the AI loads on demand. Workflows pick them for you, and most can also be called by name.

Let Rosetta decide

1. rosetta: You want Rosetta to handle it itself. Classifies your request, picks the matching workflow, and runs it end to end.

Understand what exists

1. load-project-context: Gives the AI your project's business context, architecture, and past decisions before any work starts.
2. codemap: Gives the AI a structural map of the repo to navigate by. Uses your LSP or code-graph tooling when available.
3. discovery: Evidence-backed picture of what exists today, including whether this was already attempted and done wrong.
4. reverse-engineering: Recovers domain rules and intent from code into business specs.
5. research: Researches any question grounded in your project, with real sources. Compares options and validates its own conclusions.

Decide what to build

1. requirements-authoring: Precise and atomic requirement units: EARS acceptance criteria, rationale, alternatives, dependencies, traceability. You combine them into stories or features.
2. requirements-use: Plans and builds from approved requirements. Every task, test, and result traces back to a requirement ID.
3. design: Deep architecture decisions with defended rejections, plus domain playbooks: distributed systems, multi-tenancy, payments, regulated data, migrations.
4. tech-specs: Produces target-state interfaces, API contracts, data models, and security considerations. Forces the AI to read the real code, grounding its assumptions.
5. planning: An ordered graph of AI sessions for automated execution, each with its own scope, checklist, and handoff.
6. backlog: Turns a thin ticket into a buildable one: gaps found, questions posed, facts written back. Also produces a WBS for people.
7. reasoning: Breaks a hard problem down, identifies roles, boundaries, events, models. Works via Tree-of-Thoughts, expanding every alternative to its conclusion before committing.

Build it

1. coding: Simple, minimal, in-scope changes following KISS/SOLID/DRY. Systematic dependency-ordered validation: database, API, web, mobile. Covers IaC.
2. testing: Isolated and idempotent at 80%+ coverage, external calls mocked only. Scenario tests start from a sequence diagram: what depends on what, what is shared setup, then the test.
3. debugging: OODA. Root cause with evidence before any fix, one hypothesis at a time, prevention recommended. Three failed fixes means a design problem.
4. security: Threat modeling plus code, dependency, IaC, container, cloud, and API review. Secrets gated before ingestion, active testing only where authorized. Output is remediation tasks.
5. natural-writing: Strips AI giveaways: hype words, em-dashes, rhetorical questions, fake engagement. For docs, emails, posts, release notes.

Test automation and QA

1. qa-knowledge: QA engineering end to end: sources into requirements, gap analysis, Given-When-Then specs, TMS export, runnable API and UI tests, failure triage. Every case is implemented or recorded as a gap, never dropped.
2. qa-structure: Canonical paths, slugs, and state files for QA runs. Each session in its own folder, so parallel runs never collide and a long flow knows which phase is done.
3. data-collection: Read-only pull from issue tracker, test management, wiki, and the codebase. A ticket gets recorded, not acted on. Gaps and permission walls recorded, never guessed.

Delegate the work

1. orchestration: Sizes the work, builds and briefs a subagent team, and gates every result through fresh eyes instead of self-review. Large plans run with phases, steps, and tasks.
2. subagent-directives: Requested automatically by the orchestrator for every subagent: stay in scope, stop and report when blocked rather than improvise, prove each claim with links and line ranges.
3. large-workspace-handling: Use when a repository is too big to handle at once. Splits into non-overlapping scopes, one subagent each, then a second wave verifies the work.
4. coding-agents-farm: Runs Claude, Codex, Copilot, Gemini and others in parallel on isolated git worktrees, for throughput or cross-model validation. Burns money fast, so it is gated behind explicit consent.

Keep the session on track

1. hitl: Makes the AI work together with you. Approval gates at specs, implementation, and closing, with review in small batches. A clear affirmative counts.
2. questioning: A few high-impact questions before work starts, each one decision, with why it matters and a recommended answer. Anything researchable it answers itself.
3. self-organization: Keeps work organized as it grows: splits oversized tasks and files, clears stale content, flags when a session should restart. Announces before it reorganizes.

Stay safe

1. sensitive-data: Secrets, keys, PII, PHI, and payment data never get read, printed, logged, or committed. Masked on sight, and the same care applies to the code it writes.
2. dangerous-actions: Before anything irreversible: blast radius first, safer alternatives offered, explicit approval required. Higher environments are off limits.
3. risk-assessment: Checks what the AI can actually reach, such as databases, cloud accounts, and production servers. Rates the risk and blocks outright when it is critical.

Recover when it goes wrong

1. deviation: Stops the moment work no longer matches what you asked, or the AI cannot stand behind its own solution. Escalates instead of pressing on.
2. self-learning: After a failure or a wrong result, stops and finds the cause, then records a reusable rule in the repo's memory so it does not repeat.
3. post-mortem: Diagnoses why a session went wrong across your prompt, workspace docs, local config, Rosetta instructions, and tooling. Can file a sanitized issue when Rosetta is at fault.

Extend

1. harness: Builds what the AI needs to run and check your system: command-line and MCP actions, dev containers, skills, subagents, workflows, hooks, and unattended automation. Encoded once, proved on every run.
2. coding-agents-prompt-authoring: Write, review, harden, and port your own skills, subagents, workflows, and rules, including between different IDEs and agents.