agents: single-source each agent contract as a skill preloaded via skills: #74

New issue

Closed

opened 2026-07-28 18:54:37 +00:00 by crenshawdev · 0 comments

crenshawdev commented

2026-07-28 18:54:37 +00:00

(Migrated from github.com)

What you want Cadence to do

Store each agent's contract once, as a skill, and have the agent file reference it through the skills: frontmatter field instead of restating it.

Per the subagents reference, skills listed in skills: are preloaded into the subagent's context at startup, and the full skill content is injected, not just the description. No tool call, so no compliance risk that the agent simply declines to read its own contract.

---
name: cad-verifier
effort: high
tools: Read, Bash, Grep, Glob
skills:
  - cad-verifier-contract
---
Follow the preloaded contract exactly.

Why this is worth doing on its own

It is the prerequisite two other issues are both waiting on. #63 needs it to materialize rungs without forking behaviour, and #69 needs the same mechanism to preload a shared writing contract into every agent. Landing it once means neither pays for it alone, and it means #63 arrives smaller.

It kills the cad-plan-checker-high.md shim's reason to exist. That file works around @-includes not functioning in agent bodies by reading its contract at runtime. A preloaded skill is the supported version of the same intent. Whether the shim can actually be retired here or only once #63's rungs land should be settled during the work rather than assumed now.

It is a storage change, not a behaviour change. The contract text is identical; only its location moves. That is what makes it shippable in a minor release.

What it costs

Two silent failure modes, both from #63 and both real:

A skill with disable-model-invocation: true cannot be preloaded.
A missing or disabled skill is skipped silently, with only a debug-log warning. So a typo in skills: produces an agent running with no contract at all, which looks like an agent that has decided to ignore its instructions.

The second one is the dangerous one, because the failure is invisible and the symptom is misattributed. Whatever ships needs a self-verify CONTRACTS entry asserting that every contract skill referenced by any agent actually resolves. That check is not optional garnish here; it is the thing that makes the mechanism safe to depend on.

A rung file that accumulates behaviour becomes a real variant. Not yet applicable, since rungs are #63's, but the discipline starts here: the agent file names a contract and adds nothing. If an agent file ever grows behaviour of its own, this has failed.

Scope

In: one contract skill per agent, agent files reduced to frontmatter plus a pointer, a self-verify check that every referenced contract resolves.

Out: the rigor ladder, the rung stub files, the profile enum rename, anything touching route-table.json tiers. Those are #63 and stay in v2.0.0.

Files this touches

agents/*.md, new skills/ entries (one contract per role), cadence-core/bin/self-verify.test.mjs, and agents/cad-plan-checker-high.md if the shim turns out to be retirable independently.

#63, which needs this and is narrowed by it.
#69, which needs the same mechanism for a different payload.

Extracted from #63 as part of the 1.5.0 / 2.0.0 split. This is the non-breaking half: it changes how agent contracts are stored, not anything a user configures. #63 keeps the case for the rigor ladder itself. ## What you want Cadence to do Store each agent's contract once, as a skill, and have the agent file reference it through the `skills:` frontmatter field instead of restating it. Per [the subagents reference](https://code.claude.com/docs/en/sub-agents), skills listed in `skills:` are preloaded into the subagent's context at startup, and the **full skill content** is injected, not just the description. No tool call, so no compliance risk that the agent simply declines to read its own contract. ```yaml --- name: cad-verifier effort: high tools: Read, Bash, Grep, Glob skills: - cad-verifier-contract --- Follow the preloaded contract exactly. ``` ## Why this is worth doing on its own **It is the prerequisite two other issues are both waiting on.** #63 needs it to materialize rungs without forking behaviour, and #69 needs the same mechanism to preload a shared writing contract into every agent. Landing it once means neither pays for it alone, and it means #63 arrives smaller. **It kills the `cad-plan-checker-high.md` shim's reason to exist.** That file works around `@`-includes not functioning in agent bodies by reading its contract at runtime. A preloaded skill is the supported version of the same intent. Whether the shim can actually be retired here or only once #63's rungs land should be settled during the work rather than assumed now. **It is a storage change, not a behaviour change.** The contract text is identical; only its location moves. That is what makes it shippable in a minor release. ## What it costs **Two silent failure modes, both from #63 and both real:** 1. A skill with `disable-model-invocation: true` cannot be preloaded. 2. A missing or disabled skill is skipped silently, with only a debug-log warning. So a typo in `skills:` produces an agent running with **no contract at all**, which looks like an agent that has decided to ignore its instructions. The second one is the dangerous one, because the failure is invisible and the symptom is misattributed. Whatever ships needs a self-verify CONTRACTS entry asserting that every contract skill referenced by any agent actually resolves. That check is not optional garnish here; it is the thing that makes the mechanism safe to depend on. **A rung file that accumulates behaviour becomes a real variant.** Not yet applicable, since rungs are #63's, but the discipline starts here: the agent file names a contract and adds nothing. If an agent file ever grows behaviour of its own, this has failed. ## Scope In: one contract skill per agent, agent files reduced to frontmatter plus a pointer, a self-verify check that every referenced contract resolves. Out: the rigor ladder, the rung stub files, the profile enum rename, anything touching `route-table.json` tiers. Those are #63 and stay in v2.0.0. ## Files this touches `agents/*.md`, new `skills/` entries (one contract per role), `cadence-core/bin/self-verify.test.mjs`, and `agents/cad-plan-checker-high.md` if the shim turns out to be retirable independently. ## Related - #63, which needs this and is narrowed by it. - #69, which needs the same mechanism for a different payload.