rosetta-agent — Rosetta agent-substrate plugin¶
A dual-runtime plugin (Claude Code + Claude Cowork) that registers
an MCP server (rosetta) exposing the
rosetta-app-server
agent-substrate /api/v1 surface as model-callable tools, plus
seven operator-driven slash commands and eight model-facing skills.
The bundled binary is an HTTPS client against
${ROSETTA_API_BASE} (default https://api.rosetta-design.com).
This is the v0.6.3 release. The plugin lives in
rosetta-platform
under util/plugins/rosetta-agent/; the bundled mcp-server binary
continues to live in
rosetta-mcp-server.
What's in v0.6.x¶
The v0.6.x line refines the v0.5.0 read/write surface: v0.6.0 added
content-honesty / provenance routing to the write-safety contract plus the
rehearsal-mode twin-apply tool (ADR-RX-017); v0.6.1 fixed MCP-server
boot on standalone binary installs (the embedded OpenAPI spec + composites
are now the default; ROSETTA_OPENAPI_PATH / ROSETTA_MCP_COMPOSITES_DIR
are override-only); v0.6.3 documents clientUid as REQUIRED at
engagement birth (app-server api 1.5.0) and the flip of the default
ROSETTA_API_BASE to https://api.rosetta-design.com. See CHANGES.md.
What's in v0.5.0¶
v0.5.0 brings the plugin up to the significantly-upgraded
rosetta-mcp-server v0.8.3 / contract 1.3.3 — the full 42-tool
read/write surface (37 wrappers + 5 composites) behind a deny-by-default
tool-policy (Epic E7 / Sprint E7-S8-WP1; ADR-RCP-009). It adds whole write
families the plugin previously could not drive — engagement twin read/write,
engagement lifecycle, engagement canvas, and the governance
three-gate — under a new write-safety posture (core/write-safety.md:
confirm-before-destructive, idempotency, enum validation, partition/access, write
provenance). Two new composites (rosetta_engagement_turn,
rosetta_engagement_canvas_slack); four new commands
(/rosetta-agent:engagement, :twin, :govern, :canvas) + four matching
skills; corrected wire contracts (slug engagementId, the
base|supplement|refine|replace|suppress overrideMode enum). See CHANGES.md.
What's in v0.4.4¶
v0.4.4 is the publication + beta-lifecycle contracts drop (Epic E7 / Sprint E7-S7). No behavioral change for runtimes that don't read the new contracts; the v0.4.3 failure/degradation surface is unchanged. The new files ship the contracts that operationalize the §11.7 GA gate ("plugin installed and active for ≥ 15 of the 20 beta participants; telemetry pipeline emitting events"): telemetry pipeline transport spec, PII redaction verification, participant install guide, cohort onboarding runbook, build pipeline + wave-relative GA trigger.
ODF resolutions this sprint: ODF-005 (PII redaction mechanism)
ratified Option A — core/telemetry.md §6 ratified in place;
ODF-004 (GA timeline pinning) in-line resolved by the build/
GA-trigger contract.
Repository layout (flat — single root, post DT-RCP-004)¶
util/plugins/rosetta-agent/
├── .claude-plugin/plugin.json ← manifest at zip root (both runtimes)
├── commands/{query,record,turn,engagement,twin,govern,canvas}.md
│ ← operator slash commands (Claude Code)
├── skills/
│ ├── agent-orchestration/SKILL.md
│ ├── context-retrieval-flows/SKILL.md
│ ├── conversation-lifecycle/SKILL.md
│ ├── decision-trace-capture/SKILL.md
│ ├── engagement-lifecycle/SKILL.md
│ ├── engagement-twin/SKILL.md
│ ├── engagement-canvas/SKILL.md
│ └── governance-lifecycle/SKILL.md
├── core/ ← shared, runtime-agnostic (26 docs)
│ ├── retrieval.md, citation.md, provenance.md, mcp-token.md,
│ ├── preflight.md, loading-state.md, prompt-injection.md,
│ ├── personas.md, telemetry.md, telemetry-pipeline.md,
│ ├── knowledge-gap.md, response-shaping.md,
│ ├── conversation-lifecycle.md, identity.md, session-lifecycle.md,
│ ├── error-handling.md, caching-and-latency.md, detection.md,
│ ├── detection-vocabulary.md, rosetta-tool-vocabulary.md,
│ ├── write-safety.md, engagement-key.md, engagement-lifecycle.md,
│ ├── engagement-twin.md, engagement-canvas.md, governance-lifecycle.md
├── references/
│ ├── cowork-runtime-notes/{detection,persona-classification,response-packaging}.md
│ ├── mcp-server-config-reference.md
│ ├── failure-simulation-harness.md, failure-degradation-matrix.md,
│ ├── pii-redaction-test-vectors.md, install-guide.md,
│ ├── beta-onboarding-runbook.md,
│ └── build-and-ga-trigger.md
├── eval/ ← eval harness (corpus, rubric, results)
├── CHANGES.md
├── README.md (this file)
└── rosetta-agent-0.6.3.zip
DT-RCP-004 (RATIFIED 2026-05-24) superseded the v0.3.6/v0.3.7
dual-adapter premise; both Claude Code and Cowork read the same
flat plugin layout. Runtime-side detection / persona-classification /
panel-rendering mechanics are described in
references/cowork-runtime-notes/; runtime implementation defers
to ODF-006 when the Cowork SDK exposes the necessary hooks.
What v0.4.4 adds (E7-S7)¶
core/telemetry-pipeline.md(NEW). Transport contract extendingcore/telemetry.md§7: endpoint + single-event-per- request batching + 5xx retry-once / 4xx no-retry / transport- error silent-degrade + delivery confirmation + load-bearing scope distinction (RCP-C-7 block-on-failure applies to the data path NEVER to telemetry; telemetry failure NEVER blocks the plugin's main flow) + PII redaction integration + operator receipt-verification procedure.references/pii-redaction-test-vectors.md(NEW). Operationalizes ODF-005 verification: 6 sections matchingcore/telemetry.md§6's six PII classes; per-class positive + negative + edge-case examples; each positive isinput → expected redacted output.references/install-guide.md(NEW). Participant-facing install documentation for the 20 beta-cohort participants: prerequisites, install steps, first-run verification, privacy/telemetry note, getting help.references/beta-onboarding-runbook.md(NEW). Operator-facing cohort management: cohort target (20; threshold ≥ 15), 5-step per-participant onboarding procedure, activity definition (default ≥ 1 Retrieval event in trailing 14 days), support escalation, cohort roster maintenance, GA-trigger interaction.references/build-and-ga-trigger.md(NEW; ODF-004 in-line resolution). Release-operator reference: bundler + versioning- RCP-C-12 distribution + 10-step release checklist + wave-relative GA trigger with four conjunctive conditions (SM-RGAS-001 Wave 1 GA + §11.7 E7-S5 + §11.7 E7-S6 + §11.7 E7-S7 all satisfied).
No SKILL cross-refs added in this sprint — core/telemetry-pipeline.md
is a runtime-side transport contract (not model-facing); the 4 SKILLs
already cross-ref core/preflight.md (E7-S4), core/error-handling.md,
and core/telemetry.md where appropriate.
Version history¶
| v0.1.0 | v0.2.0 | v0.3.0 | v0.3.5 | v0.3.6 | v0.3.7 | v0.4.0 | v0.4.1 | v0.4.2 | v0.4.3 | v0.4.4 | |
|---|---|---|---|---|---|---|---|---|---|---|---|
| MCP server | n/a | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Slash commands | /rosetta-agent:context |
(removed) | /rosetta-agent:turn, /rosetta-agent:record, /rosetta-agent:query |
(same three) | (same three) | (same three) | (same three) | (same three) | (same three) | (same three) | (same three) |
| Skills | context-retrieval |
agent-orchestration |
+ 3 more | (same four) | (same four) | (same four) | (same four) | (same four, +prompt-injection cross-ref) | (same four, +preflight cross-ref) | (same four; no new SKILL refs) | (same four; no new SKILL refs) |
| Architecture | curl wrapping HTTP | HTTPS-client binary | HTTPS-client binary | HTTPS-client binary | HTTPS-client binary | HTTPS-client binary | HTTPS-client binary | HTTPS-client binary | HTTPS-client binary | HTTPS-client binary | HTTPS-client binary |
| Home repo | rosetta-app-server | rosetta-mcp-server | rosetta-mcp-server | rosetta-platform | rosetta-platform | rosetta-platform | rosetta-platform | rosetta-platform | rosetta-platform | rosetta-platform | rosetta-platform |
| Layout | flat | flat | flat | flat | ~~dual-runtime scaffold~~ ⚠️ | ~~dual-runtime + Cowork content~~ ⚠️ | flat + core/ + references/ |
flat + 17 core docs + context-delivery contracts | flat + 18 core docs + MCP auth contracts | flat + 19 core docs + failure/degradation contracts | flat + 20 core docs + publication/beta-lifecycle contracts |
⚠️ v0.3.6 and v0.3.7 shipped a adapters/{claude-code,cowork}/ layout that did not load in Cowork — .claude-plugin/plugin.json was buried under adapters/claude-code/. DT-RCP-004 (RATIFIED 2026-05-24) superseded the dual-adapter premise; v0.4.0 returns to the flat root layout and demotes the Cowork-runtime content to references/cowork-runtime-notes/.
The slash commands wrap the MCP composite tools so operators can drive turns / governance writes / queries without the model having to compose the calls itself. The skills are model-facing — Claude loads them when deciding which tool to call.
Commands → skills¶
The seven operator-driven slash commands are terse MCP-router entry
points; their names are accepted ergonomic aliases for the model-facing
skill they route to, so the guessable-routing rule
(../NAMING.md rule 6;
docs/decision-traces/plugin-skill-naming-scheme.md)
is satisfied by this table rather than by a shared stem.
| Command | Model-facing skill |
|---|---|
/rosetta-agent:query |
context-retrieval-flows |
/rosetta-agent:turn |
conversation-lifecycle |
/rosetta-agent:record |
decision-trace-capture |
/rosetta-agent:engagement |
engagement-lifecycle |
/rosetta-agent:twin |
engagement-twin |
/rosetta-agent:canvas |
engagement-canvas |
/rosetta-agent:govern |
governance-lifecycle |
| (no command — umbrella) | agent-orchestration |
agent-orchestration is the eighth, umbrella skill: it describes how to
compose the tools across all the above and has no 1:1 command of its own.
Tool catalog¶
| Composite | What it does |
|---|---|
rosetta_turn |
One conversational turn end-to-end (idempotent create + persist + flow decide) |
rosetta_engagement_turn |
Engagement-scoped turn; binds the session to an engagement and writes turn semantics into the twin (semanticProjection) |
rosetta_record |
DecisionTrace + optional ADR application + optional QueryTrace |
rosetta_query |
Context retrieval with expand=full (inlined pattern relationships) |
rosetta_engagement_canvas_slack |
Engagement canvas as publish-ready Slack-canvas markdown (one call) |
Plus 37 read/write 1:1 wrappers (reads, engagement twin/lifecycle/canvas,
governance three-gate) behind the server's deny-by-default tool-policy — see
core/rosetta-tool-vocabulary.md for the full
catalog (reads/writes grouped, idempotency, enums, tool-policy) and
core/write-safety.md for the write discipline.
Install path¶
1. Get the MCP server binary¶
The prebuilt mcp-server archives are published on the
https://rosetta-design.com/downloads route — that is the
distribution channel for most installs. Building from source
requires collaborator access to the private rosetta-mcp-server
repository:
git clone https://github.com/vernonkeenan/rosetta-mcp-server.git # collaborators only
cd rosetta-mcp-server
make build # produces ./bin/mcp-server
The plugin's plugin.json references the binary via the
ROSETTA_MCP_BIN environment variable (defaulting to mcp-server
on $PATH). For convenience:
export ROSETTA_MCP_BIN="$(pwd)/bin/mcp-server"
2. Set environment¶
| Variable | Required | Purpose |
|---|---|---|
ROSETTA_AGENT_TOKEN |
yes | Bearer token issued for the agent-harness scope |
ROSETTA_API_BASE |
no | Upstream REST base URL (default: https://api.rosetta-design.com) |
ROSETTA_MCP_BIN |
no | Path to the mcp-server binary (default: mcp-server on $PATH) |
ROSETTA_OPENAPI_PATH |
no | Override only — the binary uses its embedded OpenAPI spec by default. Set to an on-disk spec path only when running from the rosetta-mcp-server source tree. The plugin does not set it (a relative path breaks a /usr/local/bin install). |
ROSETTA_MCP_COMPOSITES_DIR |
no | Override only — the binary uses its embedded composites by default. Same rule as ROSETTA_OPENAPI_PATH. |
The plugin manifest passes ROSETTA_AGENT_TOKEN to the binary as
ROSETTA_API_KEY. The binary holds the token in memory and adds
Authorization: Bearer … to every outbound HTTPS call to the
upstream REST API. The upstream rosetta-app-server validates each
call.
Acquisition of ROSETTA_AGENT_TOKEN: reach out to the
rosetta-app-server operator. Tokens follow the
rsk_<32+ alphanumeric> shape (ADR-GO-006). The plugin must
never echo the token in output.
3. Install the plugin¶
# from the rosetta-platform checkout
make plugin-bundle-rosetta-agent # regenerates the rosetta-agent-<version>.zip bundle
# install via Claude Code's plugin loader (path-dependent on your harness)
The Claude Code marketplace entry
(util/plugins/.claude-plugin/marketplace.json) points at
./rosetta-agent, with the manifest at the flat root
(.claude-plugin/plugin.json) per DT-RCP-004. The marketplace
loader resolves the manifest from the plugin root.
Lifecycle¶
When Claude Code launches a session with this plugin installed:
- Claude Code reads
plugin.jsonand finds themcpServers.rosettaentry. - Claude Code spawns the binary at
${ROSETTA_MCP_BIN}with the environment from the manifest. - The binary fails fast if
ROSETTA_API_KEYis unset; otherwise it loads the vendored OpenAPI spec to register tools and starts the MCP dispatcher on stdin/stdout. - Claude Code performs the MCP
initializehandshake, lists tools viatools/list, and invokes them viatools/callas the model decides. Each tool call is one HTTPS round-trip to the upstream. - On session close, Claude Code closes the binary's stdin; the
binary exits cleanly via the
Dispatcher.RunEOF path.
Versioning¶
Plugin version followed the agent-substrate info.version from the
vendored OpenAPI spec for visible correlation through v0.3.0; from
v0.3.5 onward the plugin tracks its own release cadence in
rosetta-platform. v0.2.0 was the initial release post-split from
rosetta-app-server; v0.3.0 added the slash-command + skill
catalog; v0.3.5 was the relocation patch to rosetta-platform;
v0.3.6/v0.3.7 were the dual-runtime structural relocation
(core/ + adapters/{claude-code,cowork}/), superseded by
DT-RCP-004; v0.4.0 returned to the flat root; the v0.4.x line
hardened contracts (context delivery, MCP auth,
failure/degradation, publication + beta lifecycle); v0.5.0
adopted the full v0.8.3 read/write surface under write-safety
(ADR-RCP-009); the v0.6.x line (current: v0.6.3) is described
under "What's in v0.6.x" above. Future minor bumps add composites
or refine descriptions; major bumps revisit the MCP / SKILL.md
split. See CHANGES.md.