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).

Which lane (0.2.0, platform E9-S1-WP2). twin:apply takes engagement content; canonical, engagement-less content goes to content:ingest (POST /api/v1/domains/{domainKey}/content:ingest). twin-authoring § 9b tells them apart and lists what has no lane yet. They are the only lanes: from the DT-RX-036 switch (E9-S2-WP1; ADR-PL-024) nothing is authored in the platform repo's db/engagements/ or db/seeds/, and make prod-migrate is schema-only. Before the DT-RX-036 switch no plugin's ingestion target submits to a shared or production app-server, and no one calls rosetta_ingest_content through the hosted connector to commit.

Edges and gate fields (0.2.1, platform E9-S1-WP17). twin-authoring § 4.2 is the twin:apply edge allowlist, keyed by triple, with the four triples the archaeology lane adds; an edge off the list and a gate-owned DecisionTrace field (gateStatus, completenessScore, coherenceScore, decisionPoint) are refused once the E9-S2 switch is on, and an unchanged echo of a twin read still applies (app-server twin-apply-archaeology-lane.md Q-F-1, Q-L-1).

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 (RATIFIED 2026-09-25 by Vernon Keenan), promoted to ADR-PA-013 (Accepted 2026-09-27). 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.

This page as Markdown — for pasting into Claude or another assistant · llms.txt