T-AX3M-canonical-harness-model
Status: closed/done · Impact: high · Complexity: large
Replace the Claude-derived, skills-only model with a canonical, host-neutral model rich enough that no single target is privileged. It must represent the whole control-plane surface — capabilities (skills + commands), lifecycle hooks, MCP servers, tool permissions, shared context documents, and metadata — and validate markdown bodies with markdown-contract rather than frontmatter alone.
| Location | Role today |
|---|---|
plugin/lib/services/harness/model.ts | Zod model with metadata + skills + documents only; Claude frontmatter residue parked under nativeFrontmatter. No hooks/MCP/permissions/commands. |
Proposed
Section titled “Proposed”A HarnessModel whose capabilities[], hooks[], mcpServers[], permissions, documents[],
and metadata are all first-class and host-neutral. Capability bodies validate through a
markdown-contract contract. The model is the sole source of truth; every target projects from it.
Approach
Section titled “Approach”- Add host-neutral schemas:
Capability(kind: skill | command),Hook(event, matcher, action),McpServer(transport, command/url, args, env),Permission(allow/deny/ask rule sets). - Fold the old
skills/nativeFrontmatterintocapabilitieswith typed fields; drop the Claude-specific escape hatch from the canonical shape. - Add a markdown-contract contract for capability/document bodies; expose a
validateHarnessModel. - Update the
harness modelop to emit the canonical model.
Files to touch
Section titled “Files to touch”| Location | Kind | Change |
|---|---|---|
plugin/lib/services/harness/model.ts | modify | Enrich to the canonical shape. |
plugin/lib/services/harness/contract.ts | new | markdown-contract body validation. |
plugin/lib/services/harness/tests/model.test.ts | new | Schema + contract tests. |
Acceptance criteria
Section titled “Acceptance criteria”-
HarnessModelcarries capabilities, hooks, mcpServers, permissions, documents, metadata. - Capability/document bodies validate through markdown-contract.
-
sdlc harness model --output jsonemits the canonical model. - tsc + harness tests green.
Out of scope
Section titled “Out of scope”Target exporters (own tasks) and re-authoring the corpus by hand (import bootstraps it).