# 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.6** 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`; **v0.6.4** removed
three phantom tools from the docs; **v0.6.5** documents the
`rosetta-mcp-server` v0.11.0 surface (46 tools): every governance tool needs a
platform admin's key, reads included; the keyed node tools
(`rosetta_get_digital_twin_node_by_key`, `rosetta_update_digital_twin_node_by_key`)
and who may write which node; `rosetta_ingest_content`, which is dry runs
only against production until the DT-RX-036 switch; and the turn-persist rules
since api 1.10.0 (`rosetta_persist_conversation_turn` with an `engagementId`
needs a grant on that engagement, every gap needs `gapType` and `description`,
and a collision with another lane's DecisionTrace is a 409 before anything is
persisted); **v0.6.6** drops the docs' pointers to the repo's `db/seeds/`,
`db/engagements/` and evidence CSV, which leave the platform repo's `main` at the
DT-RX-036 switch (ADR-PL-024). 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.6.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
  extending `core/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 matching `core/telemetry.md` §6's
  six PII classes; per-class positive + negative + edge-case
  examples; each positive is `input → 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. Its `semanticProjection` is not written in server v0.11.0 (the persist step lacks `engagementId`); see `core/conversation-lifecycle.md` §11 |
| `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 **41 read/write 1:1 wrappers** (reads, engagement twin/lifecycle/canvas,
digital-twin node CRUD, governance three-gate, content ingest) 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.

Every key sees the same tools; the upstream server decides what a key may do.
Governance tools (reads included), canonical node writes, node creates and
`rosetta_ingest_content` need a **platform admin's key** and answer 403
otherwise (`core/rosetta-tool-vocabulary.md` §7.1).

## 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:

```bash
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:

```bash
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

```bash
# 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:

1. Claude Code reads `plugin.json` and finds the `mcpServers.rosetta`
   entry.
2. Claude Code spawns the binary at `${ROSETTA_MCP_BIN}` with the
   environment from the manifest.
3. The binary fails fast if `ROSETTA_API_KEY` is unset; otherwise it
   loads the vendored OpenAPI spec to register tools and starts the
   MCP dispatcher on stdin/stdout.
4. Claude Code performs the MCP `initialize` handshake, lists tools
   via `tools/list`, and invokes them via `tools/call` as the model
   decides. Each tool call is one HTTPS round-trip to the upstream.
5. On session close, Claude Code closes the binary's stdin; the
   binary exits cleanly via the `Dispatcher.Run` EOF 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.6`) 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`.