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; for things that aren’t working see TROUBLESHOOTING.md.

Installation & Detection

How do I know if Rosetta is installed and configured for this repo?

1. AI coding agent loads CONTEXT.md and ARCHITECTURE.md files - if not it misses the entire context
2. AI coding agent loads workflow - if not it is taking shortcut delivering subpar results
3. AI coding agent loads hitl and orchestrator-contract - if not it will not engage user and hallucinate

If none of these are true, Rosetta is not active for this session. See INSTALLATION.md.

How do I install Rosetta for the first time?

See the Quick Start Guide for the fastest path, or INSTALLATION.md for the full setup including the fallback bootstrap rule. Once installed, 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.

Rosetta supports the current release and the one before it (N-1) so when a new release ships, the previous one keeps working while you migrate. See 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.

Plugin install or MCP install — which should I use?

Use the plugin when one is available for your IDE. Plugins bundle the bootstrap rule, skills, agents, and workflows directly into the IDE and the agent loads them locally — no live connection to a Rosetta server at request time. In practice this means:

• Faster session start, no MCP OAuth expirations dropping the agent mid-task, no dependency on the Rosetta server being reachable from your network.
• No outbound calls to an external service means no data-egress or privacy review — you’re using local static instruction files. That’s a much shorter conversation with security and compliance than authorizing a new external MCP endpoint.

Use the MCP install when no plugin path exists for your IDE — e.g. Windsurf, Antigravity, OpenCode, or JetBrains Junie. See PLUGINS.md for the IDEs that currently ship a plugin, and INSTALLATION.md for MCP setup.

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
• Guardrails, security, sensitive-data handling, and risk assessment of your current config — protections a bare agent doesn’t apply
• Less back-and-forth because the agent asks the right questions early (HITL)
• Spec-Driven Development extended with Discovery, Design, Review, and Validation phases
• More reliable results overall

For small/trivial tasks AI treats them as just small change and never executes tests nor validate results of changes. Very often small changes have side effects, which AI must figure out first. This leads to low quality unpredictable results.

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

Where do I propose changes to Rosetta itself?

See CONTRIBUTING.md and DEVELOPER_GUIDE.md.