Skip to content

engagement-authoring

The engagement authoring-reference plugin — the 7th sibling. It carries two reference skills that teach an agent how to correctly hand-construct the two engagement-scoped payloads against the rosetta-app-server API, before writing them:

  • engagement-creation — starting a new engagement (POST /api/v1/engagements / rosetta_create_engagement).
  • twin-authoring — authoring the twin.json TwinDocument (POST /api/v1/engagements/{uid}/twin:apply / rosetta_apply_engagement_twin).

The two are ordered: create the engagement first, then apply the twin into it (twin:apply 404s on a missing engagement).

What it is (and is NOT)

  • Reference, not doer. Both skills are advisory knowledge. They author no files, call no write tools, and register no MCP server. The actual writes are the caller's — via rosetta-agent's MCP surface (rosetta_create_engagement, rosetta_apply_engagement_twin) or a direct REST call.
  • Distilled mirrors of the app-server docs. The authoritative sources are in rosetta-app-server: docs/engagement-creation-guide.md, docs/twin-json-authoring-guide.md, and the files they cite (api/rosetta-v1.yaml, config/digital-twin/node-types.yaml, internal/digitaltwin/twin.go, internal/handlers/engagements.go, queries/v1/engagement_create.cypher). When the API changes, the app-server docs move first; these skills are re-synced from them.
  • Companion to the generators and the doer. rosetta-archaeology and engagement-rehearsal generate twin documents; rosetta-agent's engagement-lifecycle skill performs the engagement create over MCP. This plugin is the shared how-to-construct-it-correctly reference for all of them and for hand-authors.

Command → skill routing

Each command name equals the skill it drives (1:1 capability) — the house naming rule:

Command Skill Covers
/engagement-authoring:engagement-creation engagement-creation The create dual-write, required clientUid, the engagementUid/engagementId naming trap, account/authorization defaults, the auto creator lead grant, status vs derived stage, the 201/403/409/422 map
/engagement-authoring:twin-authoring twin-authoring The TwinDocument: 11 writable labels, inheritable-vs-non-inheritable identity, five-field identity, natural keys, required props + closed enums, edge-endpoint resolution incl. REFINES_PATTERN MATCH-only, DecisionTrace inline children, baseRevision, the 422/409 failure codes

Both skills also auto-load on their description triggers (creating an engagement / authoring a twin.json) without an explicit command.

Posture

  • Read/reference-only. No write tool is invoked from either skill; each says so explicitly. No mcpServers block — the plugin needs no server (it only documents the caller's write calls).
  • Self-contained. The skill bodies embed the full guidance so the plugin is useful in a Cowork/Claude session with no rosetta checkout present.

Governance

Authorized by dt-pa-007 (Proposed — pending Vernon ratification → ADR-PA-013, next free). This is a plugin-author decision (a reference consumer of the already-shipped app-server API surface, no cross-repo contract change) → the ADR-PA lane, not ADR-RX.