# Companion plugins Nine plugins ship alongside this repo. Each is bundled as a per-plugin zip here so a fresh checkout has them on hand without a separate download. The plugins emit downloadable **cumulative bundles** that mirror the rosetta-platform directory layout; the operator `unzip -d`s the bundle into their working tree and applies via PR. **Plugins & skills at a glance** | Plugin | Folder | Skills | Slash commands | Latest | | --- | --- | --- | --- | --- | | [rosetta-research](rosetta-research/) | `rosetta-research/` | `product-family-research` | seven pipeline stages + `run-all` | `0.28.1` | | [rosetta-archaeology](rosetta-archaeology/) | `rosetta-archaeology/` | `digital-twin-archaeology`, `inheritance-tree-render` | four phases (`survey`/`excavate`/`classify`/`preserve`) + `inheritance-tree-render` + `run-all` | `0.13.3` | | [engagement-codex](engagement-codex/) | `engagement-codex/` | `solution-thesis-render`, `sow-render`, `spec-manifest-render` | one per skill (command name = skill name) | `0.12.0` | | [rosetta-agent](rosetta-agent/) | `rosetta-agent/` | `agent-orchestration`, `context-retrieval-flows`, `conversation-lifecycle`, `decision-trace-capture`, `engagement-canvas`, `engagement-lifecycle`, `engagement-twin`, `governance-lifecycle` | `query`, `turn`, `record`, `canvas`, `engagement`, `govern`, `twin` | `0.6.6` | | [engagement-rehearsal](engagement-rehearsal/) | `engagement-rehearsal/` | `persona-conversation-sim` | `rehearse`, `eval`, `run-all` | `0.1.3` | | [d360-distiller](d360-distiller/) | `d360-distiller/` | `seed-to-skill-distillation` | `bind`, `audit`, `render`, `validate`, `run-all` | `0.2.0` | | [engagement-authoring](engagement-authoring/) | `engagement-authoring/` | `engagement-creation`, `twin-authoring` | one per skill (command name = skill name) | `0.2.1` | | deploy-distiller | `deploy-distiller/` | `deploy-library-distillation` | `project`, `publish`, `run-all` | `0.3.0` | | tech-note-distiller | `tech-note-distiller/` | `tech-note-distillation` | `plan`, `draft`, `validate`, `archive`, `run-all` | `0.1.0` | Slash commands match their skill name (e.g. `/engagement-codex:sow-render` invokes the `sow-render` skill). The old `render-*` command names were one-release deprecated aliases and have been removed (engagement-codex 0.11.0, rosetta-archaeology 0.10.0; `docs/decision-traces/plugin-skill-naming-scheme.md`). `rosetta-agent` is a live MCP runtime router (prereqs per [`rosetta-agent/references/install-guide.md`](rosetta-agent/references/install-guide.md)); `engagement-rehearsal` is a read-only, SIMULATED-stamped persona simulator that reuses `rosetta-agent`'s MCP server. The first two plugins are siblings of the canonical-authoring path — they emit Cypher seeds for the same target repo but operate on different parts of the metamodel. - **rosetta-research** authors canonical content (`ContextPattern`, `BusinessIntent`, `VocabularyTerm`, `SemanticEntity`, `PlatformObject`, `EngineFunction`) and submits it as a content:ingest bundle to the rosetta-app-server API, where it lands at `draft` (ADR-PL-024; `db/seeds/` left `main` at the switch release, E9-S2-WP1). - **rosetta-archaeology** authors engagement-scoped instances (leaf `KnowledgeDomain`, Context Artifacts, DecisionTraces, promotion candidates as DecisionTrace transitions) and applies them through twin:apply. Output is `projectId=''` / `domainKey='salesforce::'`. - **engagement-codex** consumes an engagement's graph state and renders the deliverable stack — a Solution Thesis (four tones), a Statement of Work, and a Spec Manifest; produces Markdown deliverables under `outputs/plugins/engagement-codex/`. - **rosetta-agent** is the agent-substrate plugin for live retrieval-grounded answers against the Rosetta Data-360 graph at `api.rosetta-design.com`. Distinct from the others: it carries an MCP server (`rosetta-mcp-server` binary, separate repo) and requires a runtime token (`agent-harness` KMS scope) per E7-S7-WP3. The plugin files install via the install bundle alongside the rest; the runtime setup is a follow-up step. - **engagement-rehearsal** is a **read-only consumer** like `engagement-codex`, but conversational rather than render: it role-plays six personas through live `rosetta_turn` conversations to propose closures for an engagement's `«TBD-N»` / `KnowledgeGap` inventory (`MODE=rehearsal`) or to mint a labeled flow/persona corpus (`MODE=eval`). It writes nothing to the graph (ADR-RX-002) and stamps every emit `SIMULATED` (ADR-RX-007); outputs land under `outputs/plugins/engagement-rehearsal/`. It registers no MCP server — live mode reuses `rosetta-agent`'s `rosetta` server. - **d360-distiller** is the seed-to-skill distillation pipeline: one skill (`seed-to-skill-distillation`) compiles task-level, happy-path builder skills from the canonical D360 seed corpus (`db/seeds/03g–10g`), or from a `rosetta-deploy` library release's `CP/`, `ADR/`, `EF/` and `BI/` files (library mode, 0.2.0), onto Salesforce's `d360_*` MCP tool surface (`bind` / `audit` / `render` / `validate` / `run-all`). Emits are compiled projections carrying a provenance colophon and a draft/UNVERIFIED banner lifted only by sandbox smoke via re-render; read-only against the graph, no own MCP server (reuses `rosetta-agent`'s `rosetta` server). `dt-pa-006` (ADR-PA-012 pending). - **engagement-authoring** is an **authoring-reference** plugin: two reference skills (`engagement-creation`, `twin-authoring`) that teach an agent how to correctly hand-construct the two engagement-scoped payloads against the `rosetta-app-server` API — the create request and the `twin.json` `TwinDocument`. It authors no files, calls no write tools, and registers no MCP server; the skill bodies are distilled mirrors of `rosetta-app-server` `docs/{engagement-creation,twin-json-authoring}-guide.md` (authoritative). It complements the archaeology/rehearsal *generators* and `rosetta-agent`'s `engagement-lifecycle` *doer* with the shared how-to-construct-it-correctly reference. `dt-pa-007` → ADR-PA-013 (Accepted 2026-09-27). - **deploy-distiller** is the graph-to-Git distillation pipeline for the `rosetta-deploy` library: one skill (`deploy-library-distillation`) runs the deterministic `deploy-projection` tool (`make deploy-projection`) over a checksummed content snapshot and writes one Markdown file per node, with YAML front matter, into the folders `rosetta-deploy`'s `rosetta.yaml` assigns (`CP/`, `ADR/`, `BI/`, `EF/`, `PO/`, `SE/`, `VT/`, the derived `sources/`, `anti-patterns/` and `indexes/`, plus `release-manifest.json`), with draft content in a visible draft lane (`project` / `publish` / `run-all`). `publish` puts the projection on a `projection/` branch of `vernonkeenan/rosetta-deploy` and opens a PR, confirm-before; it never pushes `main` and never tags. It touches no graph and registers no MCP server. `dt-pa-008` (ADR-PA-014 pending; E3-S5-WP22, WP23). - **tech-note-distiller** distills one user or practitioner document into Rosetta Tech Note drafts (`tech-note-distillation`; `plan` / `draft` / `validate` / `archive` / `run-all`). It reads the whole source, fact-checks every platform claim against official Salesforce docs (Trailhead MCP plus web search), writes `RTN-DRAFT-NN` drafts to the Tech Note template, and seals the run with a deterministic stdlib validator (embedded in a reference file and sha256-pinned), a scored rubric and a sha256 manifest. It never reserves ids, uploads or ingests: those stay human console acts. Runs on Claude Code or Claude.ai; `archive` needs Claude Code. `dt-pa-012` (no ADR; E3-S4-WP70). All nine can be installed at the same time and do not interfere. ## Deploy-edition sources (not shipped here) Two more directories hold the sources of `rosetta-deploy`'s deploy editions (E3-S5-WP25; `rosetta-deploy` `SM-RDEP-001` E3-S3-WP1 and WP2). `rosetta-deploy` copies each one into its own `plugins/` by reviewed PR and distributes it from its own marketplace. This repo does not ship them: they are listed in `deploy-edition-sources.txt`, have no entry in `.claude-plugin/marketplace.json`, no committed zip and no `make plugin-bundle-` target, and the install bundle leaves them out (operator ruling 2026-10-16). Fix a defect here; never in a copy. | Source | Skills | Slash commands | Version | | --- | --- | --- | --- | | rosetta-archaeology-deploy | `digital-twin-archaeology` | four phases (`survey`/`excavate`/`classify`/`preserve`) + `run-all` | `0.1.2` | | engagement-codex-deploy | `solution-thesis-render` | `solution-thesis-render` (command name = skill name) | `0.1.1` | - **rosetta-archaeology-deploy** runs Project Archaeology in Claude Code inside an engagement repository: a `rosetta-deploy` clone cut from a release tag, with `customer//` filled from its template. It reads the dossier in `project-docs/` and the library's files at the repository root, and writes the engagement twin under the engagement folder: `archaeology/twin.json` with its review notes, a draft per Context Artifact and DecisionTrace in `CP/` and `ADR/`, and `proposed-learnings.md` for the user to send back by hand. No connection to Rosetta. - **engagement-codex-deploy** renders the Solution Thesis in the four tones from that `archaeology/` folder into `deliverables/`, and cites the library by path and id. The customer tone still fails hard on an open gap. No SOW or Spec Manifest render: those stay with Rosetta. - Their skill names match their source plugins' skill names. That is safe because they never load beside the source plugins in a project this repo's installer writes. ## Distribution — the install bundle (E1-S2-WP1) All nine plugins ship to consumers via the **install bundle** published from this repo: - `make publish-install-bundle VERSION=vX.Y.Z` uploads `install.tar.gz` + sidecar + the tag-pinned installer script to the KMS-protected route on `rosetta-design.com` per `contracts/install-bundle.md`. - `make install-plugins` (Shape A) or `curl … | bash` (Shape B) on the consumer side fetches the bundle behind `Authorization: Bearer ${ROSETTA_API_KEY}` and unpacks into `~/.claude/plugins/` (plugin trees) and `~/.claude/rosetta/` (graph content + evidence manifest + per-release `MANIFEST.txt`). - Release runbook: `docs/runbooks/release-cut.md`. - End-user install guide: [`INSTALL.md`](../../INSTALL.md). The install bundle is closed by virtue of KMS-gating on the `rosetta-design.com` route, not by inclusion control. All nine plugins ship; access control on the route enforces RCP-C-12 for `rosetta-agent`. ## Auto-loaded inside this repo When you run `claude` from a `rosetta-platform` checkout, the plugins are auto-discovered via the `.claude/settings.json` `extraKnownMarketplaces` + `enabledPlugins` keys, which point at this directory as a project-local plugin marketplace. No install step required. First-run users get a "trust this folder?" prompt; subsequent runs are silent. The slash commands `/rosetta-research:*` (rosetta-research), `/rosetta-archaeology:*` (rosetta-archaeology), `/engagement-codex:*` (engagement-codex), and `/rosetta-agent:turn`, `/rosetta-agent:record`, `/rosetta-agent:query` (rosetta-agent — when the runtime prereqs are in place) become available automatically. The standalone skill at `../skills/architecture-discovery-coach/` is loaded the same way via the `skillsPath` setting (different mechanism, see `../skills/README.md`). For non-repo use (Cowork upload, global Claude Code install), the install bundle described above is the supported path; each plugin's per-folder README documents the manual install fallback (unzip into `~/.claude/plugins/`). ### Bundles are derived; extracted form is canonical Per ADR-PA-003, the **extracted form** of each plugin is the source of truth in this repo. The accompanying `-.zip` is a derived distribution artifact — regenerated from the extracted form via `make plugin-bundle-` when a new version is shipped. Plugin authors who edit the extracted form in this repo own the regeneration step. The install bundle (above) ships these per-plugin zips verbatim; it does not re-bundle. ### Claude.ai skill bundles (per-skill `.zip`) In addition to the per-plugin zips (for Claude Code marketplaces), each plugin's **user-facing skills** are also published as standalone, **Claude.ai-uploadable** `.zip` bundles at `util/plugins//claude-ai-skills/.zip` — *just the skill*, with its folder at the zip root, symlinks resolved to real files, dev cruft pruned, and the description trimmed to Claude.ai's ≤200-char cap. There is **no `.skill` format** — Claude.ai ingests a `.zip` (Customize → Skills → Create skill → Upload a skill). Build with `make claude-ai-skills`. The 8 `rosetta-agent` skills are excluded (they are MCP-runtime adapter routers, not standalone skills). Full convention + sources: `authoring/claude-ai-skill-bundles.md`. ## The shared upload model This section applies to the two Cowork-upload plugins, `rosetta-research` and `rosetta-archaeology`. Both are read-only against your repo. The session you run them in only sees what you upload: 1. **Repo zip** (every stage / phase). Produce with `cd rosetta-platform && git archive --format=zip HEAD > /tmp/rp.zip`. 2. **Prior-stage / prior-phase bundle** (every step after the first). The plugin emits these; you re-upload the most recent one to continue. 3. **Domain references** (archaeology only): the Project Archaeology Manual and the engagement discovery dossier. Each stage / phase returns ONE cumulative zip containing every artifact produced so far. The internal layout mirrors the target repo paths so `unzip -d ~/path/to/rosetta-platform/` drops files exactly where they belong. ## Constitutional alignment The plugins operate within the rosetta-platform invariants (`CLAUDE.md`): - **C-2 / ADR-PL-001** — Cypher is canonical. Every seed file the plugins emit is `.cypher`; markdown projections are derived. - **C-4 / ADR-PL-004** — Make is the operational surface. Plugins produce artifacts; the user runs `make seed-diff`, `make intake-validate`, `make engagement-load`, etc. against the unzipped output. - **C-5 / metamodel §5** — Five-field identity on every inheritable graph write. - **C-6** — `ProvenanceEvent` on every schema mutation. - **C-7 / ADR-PL-016** — Producer-only contract; plugins never reference `rosetta-app-server`. Plugins will not invoke `make`, `cypher-shell`, `mysql`, `docker`, or any command on your environment. Pushing to Neo4j and merging to `main` is always an operator action. ## Plugin-author governance The PA-* ADR series and plugin-authoring notes co-located here constrain how Cowork plugins produce content for this repo. They are distinct from the platform-level PL-* series under ../../docs/adrs/, which governs this repo's own code, schema, and infrastructure. | Path | Contents | | --- | --- | | `adrs/` | ADR-PA-001 through ADR-PA-011, and ADR-PA-013 (ADR-PA-012 is reserved for `d360-distiller`, implementation-gated) — plugin-author architectural decisions (read-only contract, output paths, identity contract, MATCH-not-MERGE discipline, lifecycleState transitions, Makefile integration, runtime-output paths, render layout, engagement-twin dual sink, and the **`engagement-rehearsal` read-only + SIMULATED simulator contracts** — ADR-PA-011, Accepted 2026-06-14, promoted from `dt-pa-005`, E3-S5-WP19). ADR-PA-012 (`d360-distiller`) and ADR-PA-013 (`engagement-authoring`) are pending promotion from `dt-pa-006` / `dt-pa-007`. | | `decision-traces/` | Methodology DTs `DT-PA-001…003` (in `methodology-decisions.md`) + standalone `dt-pa-004` (engagement-twin dual sink → ADR-PA-010) and `dt-pa-005` (engagement-rehearsal plugin → ADR-PA-011, **RATIFIED 2026-06-14**), plus `dt-pa-006` (d360-distiller → ADR-PA-012 pending), `dt-pa-007` (engagement-authoring → ADR-PA-013 pending), `dt-pa-008` (deploy-distiller → ADR-PA-014 on ratification) and `dt-pa-009` (`rosetta-research` reads `rosetta-ugc` dataset releases instead of `docs/evidence/document-inventory.csv`; **RATIFIED 2026-10-08**, no ADR; superseded in part for `--kb` runs by `rosetta-meta` DT-RX-063, recorded in `docs/decision-traces/e3-s4-wp66-kb-list-replaces-pin-pr.md`), `dt-pa-010` (product-docs runs author BusinessIntents; every ContextPattern ADDRESSES one; **RATIFIED 2026-10-29**, no ADR) `dt-pa-011` (`rosetta-research` reference profile `reference/d360-mcp-kb`: practice plus a deterministic catalog; **RATIFIED 2026-10-30**, no ADR) and `dt-pa-012` (tech-note-distiller: document-to-Tech-Note distillation; OPEN, built on its recommended resolution, no ADR) | | `authoring/` | Operational notes for plugin authors (empirical Cowork validator constraints discovered through bisection) | ### Open decisions Two architectural calls remain **Proposed** pending Vernon-Mehmet alignment: 1. ADR-PA-007 — Makefile integration for `db/engagements/`. Three options on the table; recommended is Option 3 (parallel `db-engagement-load` target). Resolution unblocks the plugin's `VALIDATION-CHECKLIST.md` from flagging the question on every run. 2. DT-PA-003 — Inline-property vs child-node storage for `alternativesConsidered` and `provenanceSources`. Recommended child-node storage; would require a migration on `rosetta-research` v0.3.2's existing inline-array conventions. The other ten ADR-PA-* and the two methodology DTs (DT-PA-001 / DT-PA-002) are **Accepted** — they ratify decisions already implemented in shipped plugin code (`rosetta-research` v0.3.2, `rosetta-archaeology` v0.1.6) and the NTO-01 dry-run. ### Migration to ADR-PA-008 ADR-PA-008 establishes that plugin/skill runtime outputs land at `outputs/{plugins,skills}///` in the repo root, gitignored, never auto-promoted. Skills-side compliance is **complete** at ratifying-PR merge (the architecture-discovery-coach SKILL.md directs deliverables to `outputs/skills/architecture-discovery-coach//`). Plugins-side compliance is a per-plugin upstream release. Tracker: | Plugin | Current version | Compliant version | Status | Notes | | --- | --- | --- | --- | --- | | `rosetta-research` | 0.28.1 | 0.9.0 | **Complete** | v0.28.1 has Stage 7 publish the run's HTML review page for Curation > Runs (platform MySQL 055, app-server API 1.45.0). v0.28.0 writes the replacement runs' contract fixes into every profile (platform E3-S4-WP69): documented names exempt from the paraphrase gate, the five graph-wide unique properties checked at Stage 3 and Stage 7, the builder's evidence-reference limit and `SPLIT=yes`, SemanticEntity `entityType`, and thin-pattern consolidation. v0.27.1 folds the d360-mcp-kb replacement run's rulings into the reference profile (dt-pa-011 status log). v0.27.0 adds `--profile=reference/d360-mcp-kb` (dt-pa-011), which authors up to 60 practice patterns plus a deterministic catalog of the release's documented Data 360 objects. v0.26.0 reads a knowledge base's release list with `--kb` (rosetta-meta DT-RX-063). v0.23.0 reads Tech Notes as members of the pinned releases (rosetta-meta DT-RX-055; `rtn-core` retired). v0.22.0 reports one stable, revisioned seven-stage lifecycle through the app-server and completes it only from a real committed ingestion event. Compliance shipped in v0.9.0 alongside the per-node `evidenceSources` contract, Stage 6 corpus utilization report, and corpus-doc hygiene pass. Bundle's internal layout places `MANIFEST.md`, `STATIC-ANALYSIS-REPORT.md`, `VALIDATION-CHECKLIST.md`, and the per-stage research markdown under `outputs/plugins/rosetta-research//`. Canonical graph content remains off `main`. | | `rosetta-archaeology` | 0.13.3 | 0.2.0 | **Complete** | Compliance shipped in v0.2.0. Bundle's internal layout now places `MANIFEST.md`, `VALIDATION-CHECKLIST.md`, `EVAL-INVOCATION-CHECKLIST.md`, and the four phase research notes (`survey-brief.md`, `excavation-inventory.md`, `classification-readiness-verdict.md`, `preservation-promotion-analysis.md`) under `outputs/plugins/rosetta-archaeology//`. Canonical engagement Cypher (`db/engagements/`) and Site Package (`site-packages/`, including `partner-validation/PARTNER-CERTIFICATION-REQUEST.md` per Manual Ch. 15) unchanged. | Compliance criteria per plugin: bundle's internal layout for non-canonical files (manifests, validation checklists, partner certification requests, eval invocation scripts, run logs) moves to `outputs/plugins///` paths inside the bundle. Canonical content (engagement Cypher, site packages) stays at its existing canonical destination per ADR-PA-002. When a compliant plugin release lands here, its row drops from **TODO** to **Complete** and the row's "Compliant version" field records the actual version that brought compliance. ### Durable run closeout ADR-PA-008's 2026-10-19 amendment adds an optional platform-side archive adapter without changing any plugin bundle or execution path. The registered producer IDs are `rosetta-research`, `rosetta-archaeology`, `engagement-codex`, `rosetta-agent`, `engagement-rehearsal`, `d360-distiller`, `engagement-authoring`, `deploy-distiller` and `tech-note-distiller` (the last registered in `rosetta-artifacts` by its first archive PR). After a stable run handoff, an operator may invoke `make artifacts-checkpoint` or `make artifacts-closeout` as documented in `docs/runbooks/run-artifact-archive.md`. The producer closeout uses `archive-closeout-template.md` and returns an exact archive commit, checkpoint path, checkpoint SHA-256 and inventory SHA-256 together with independent execution, structural, semantic, human-review, delivery and archive states. A reference-only plugin or a plugin that produced no run does not fabricate archive output. The adapter is not a semantic validator or ingestion lane. A remotely verified or sealed run may still be interrupted, failed, semantically defective, unreviewed and not submitted. ## Where each plugin fits in the manifest - **rosetta-research** submits its content:ingest bundle to the ingestion API (dry run first, then a commit on the operator's confirmed target); the content lands at `draft` and SME review in the console moves it (ADR-PL-024, in effect since the switch release, E9-S2-WP1). There are no content PRs. - **rosetta-archaeology** is engagement-scoped. Its `twin.json` is applied through twin:apply; nothing is committed to the repo, and `make engagement-load` is retired (the seed-era path is the baseline tag `v0.27.0`). ## Reporting issues File against this repo with the appropriate tag: - `[plugin]` for `rosetta-research` - `[archaeology-plugin]` for `rosetta-archaeology` - `[]` for every other plugin (e.g. `[engagement-codex]`, `[rosetta-agent]`, `[engagement-rehearsal]`, `[d360-distiller]`, `[engagement-authoring]`, `[deploy-distiller]`, `[tech-note-distiller]`) Include the plugin version (visible in the zip filename and in `.claude-plugin/plugin.json`), the stage / phase you were running, and the upload manifest the plugin reported.