Companion plugins¶

Seven 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 -ds 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/`	`product-family-research`	seven pipeline stages + `run-all`	`0.14.2`
rosetta-archaeology	`rosetta-archaeology/`	`digital-twin-archaeology`, `inheritance-tree-render`	four phases (`survey`/`excavate`/`classify`/`preserve`) + `inheritance-tree-render` + `run-all`	`0.9.1`
engagement-codex	`engagement-codex/`	`solution-thesis-render`, `sow-render`, `spec-manifest-render`	one per skill (command name = skill name)	`0.10.2`
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.3`
engagement-rehearsal	`engagement-rehearsal/`	`persona-conversation-sim`	`rehearse`, `eval`, `run-all`	`0.1.1`
d360-distiller	`d360-distiller/`	`seed-to-skill-distillation`	`bind`, `audit`, `render`, `validate`, `run-all`	`0.1.0`
engagement-authoring	`engagement-authoring/`	`engagement-creation`, `twin-authoring`	one per skill (command name = skill name)	`0.1.0`

Slash commands match their skill name (e.g. /engagement-codex:sow-render invokes the sow-render skill). The engagement-codex / rosetta-archaeology render-* command names are kept as deprecated one-release aliases and removed next release (docs/decision-traces/plugin-skill-naming-scheme.md). rosetta-agent is a live MCP runtime router (prereqs per 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) under db/seeds/. Output is projectId='SYSTEM' / domainKey='salesforce:rosetta-core'.
rosetta-archaeology authors engagement-scoped instances (leaf KnowledgeDomain, Context Artifacts, DecisionTraces, PromotionCandidates) under db/engagements/<engagementKey>/. Output is projectId='<ENGAGEMENT-KEY>' / domainKey='salesforce:<partnerKey>:<engagementKey>'.
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) 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 pending).

All seven can be installed at the same time and do not interfere.

Distribution — the install bundle (E1-S2-WP1)¶

All seven 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.

The install bundle is closed by virtue of KMS-gating on the rosetta-design.com route, not by inclusion control. All seven 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 <plugin>-<version>.zip is a derived distribution artifact — regenerated from the extracted form via make plugin-bundle-<name> 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/<plugin>/claude-ai-skills/<skill>.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:

Repo zip (every stage / phase). Produce with cd rosetta-platform && git archive --format=zip HEAD > /tmp/rp.zip.
Prior-stage / prior-phase bundle (every step after the first). The plugin emits these; you re-upload the most recent one to continue.
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-deploy, make db-invariants, 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 — 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) and `dt-pa-007` (engagement-authoring → ADR-PA-013 pending)
`authoring/`	Operational notes for plugin authors (empirical Cowork validator constraints discovered through bisection)

Open decisions¶

Two architectural calls remain Proposed pending Vernon-Mehmet alignment:

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.
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}/<name>/<run-id>/ 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/<session-id>/).

Plugins-side compliance is a per-plugin upstream release. Tracker:

Plugin	Current version	Compliant version	Status	Notes
`rosetta-research`	0.14.2	0.9.0	Complete	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 now places `MANIFEST.md`, `STATIC-ANALYSIS-REPORT.md`, `VALIDATION-CHECKLIST.md`, and the per-stage research markdown under `outputs/plugins/rosetta-research/<run-id>/` where `<run-id>` is `<product>-stage<N>-<timestamp>` (extension) or `<product>-bootstrap-stage<N>-<timestamp>` (bootstrap). Canonical Cypher (`db/seeds/`) unchanged.
`rosetta-archaeology`	0.9.1	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/<engagementKey>/`. 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/<plugin-name>/<run-id>/ 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.

Where each plugin fits in the manifest¶

rosetta-research is the canonical authoring path operationalized by Wave 1 (E3-S1-WP1, make intake-validate). Output PRs land under the rosetta-core/proposal label and follow the content author checklist at docs/runbooks/content-author-checklist.md.
rosetta-archaeology is engagement-scoped and out of band of the canonical seeds. Engagement Cypher lives at db/engagements/<engagementKey>/ (a parallel directory to db/seeds/ introduced by the plugin) and is loaded by the same toolchain once seed-compile learns to scan that subtree — see the Phase 4 VALIDATION-CHECKLIST.md the plugin emits.

Reporting issues¶

File against this repo with the appropriate tag:

[plugin] for rosetta-research
[archaeology-plugin] for rosetta-archaeology
[<plugin-name>] for every other plugin (e.g. [engagement-codex], [rosetta-agent], [engagement-rehearsal], [d360-distiller], [engagement-authoring])

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.