refactor: single-source carrier/handoff contracts across skills

Apply the debug-skill pattern (commits 6410732..de42974) to the
remaining skills: the agent file is the single source for each
interface field's semantics; the SKILL.md copy is reduced to field
names plus a pointer, marking the agent's contract table
authoritative. Because SKILL.md loads into orchestrator context and
agents/*.md into the subagent's fresh system prompt with no
transclusion, duplicated field tables drift apart over time.

- brainstorm: carrier (spec_path/iteration_scope) -> grounding-check;
  the absolute-path requirement now lives only in the agent.
- planner: carrier (spec_path/iteration_scope/focus_hint) ->
  plan-recon, including the mandatory/optional markers and the
  BLOCKED-on-missing rule SKILL.md had omitted.
- fieldtest: carrier + produced fields -> fieldtester; the skill-level
  `status` roll-up (clean/friction_found/bugs_found/infra_blocked),
  which is not part of the agent's run-status protocol, stays defined
  in SKILL.md only.
- docwriter: carrier + produced fields -> docwriter agent.
- implement: carrier (iter_id scratch-dir/stats/not-a-branch
  semantics) -> implement-orchestrator; per-task sub-status vocabulary
  moved into the orchestrator-agent (it runs the loop in a fresh
  context and could not read SKILL.md at runtime, yet referenced "the
  sub-status table" by name); task_text_path single-sourced in
  implementer with spec-reviewer cross-referencing.

audit was already the reference implementation (pointers, no restated
contracts) and is unchanged.

closes #2

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-30 11:10:10 +02:00
parent de42974056
commit 0b969838c0
12 changed files with 131 additions and 72 deletions
+14 -15
View File
@@ -101,23 +101,22 @@ stay readable.
## Handoff Contract
`fieldtest` consumes (from orchestrator at cycle close):
`fieldtest` consumes (from orchestrator at cycle close) the carrier
fields `cycle_id`, `cycle_scope`, `axis_hints`, and `commit_range`,
defined authoritatively under **Carrier contract** in
`agents/fieldtester.md` (which also specifies the empty-`axis_hints`
fallback).
| Field | Content |
|-------|---------|
| `cycle_id` | e.g. `cycle-22` |
| `cycle_scope` | 1-3 sentences naming what shipped |
| `axis_hints` | bullet list, one per cycle axis the test should probe |
| `commit_range` | `<prev-cycle-close>..HEAD` |
`fieldtest` produces, for the orchestrator, the fields `spec_path`,
`examples_added`, and `findings`, defined authoritatively under
**Output format** in `agents/fieldtester.md` — single-sourced in
the agent file, deliberately not restated here so the two files
cannot drift.
`fieldtest` produces:
| Field | Content |
|-------|---------|
| `spec_path` | spec file under `paths.spec_dir` with a `fieldtest-` prefix |
| `examples_added` | list of fixture paths committed |
| `findings` | list, each with class (`bug` / `friction` / `spec_gap` / `working`) + recommendation |
| `status` | `clean` / `friction_found` / `bugs_found` / `infra_blocked` |
It additionally reports one skill-level `status` roll-up — one of
`clean` / `friction_found` / `bugs_found` / `infra_blocked`. This
field is owned here (it is not part of the agent's per-run status
protocol), so it is defined in this file only.
The orchestrator drives downstream:
+15
View File
@@ -57,6 +57,10 @@ ratified. This is part of the public-interface story.
## Carrier contract — what the controller hands you
This table is the authoritative definition of the carrier fields
(including the empty-`axis_hints` fallback below); the dispatching
skill references it rather than restating it.
| Field | Content |
|-------|---------|
| `cycle_id` | e.g. `cycle-22` |
@@ -252,6 +256,17 @@ The full text of the spec is in the spec file in the working
tree; do NOT reproduce it in the report. The orchestrator
reads the file before committing.
This section is the authoritative definition of what the role
produces; the dispatching skill references it rather than
restating it. Named for the orchestrator handoff, the produced
fields are:
| Field | Content |
|-------|---------|
| `spec_path` | spec file under `paths.spec_dir` with a `fieldtest-` prefix |
| `examples_added` | list of fixture paths committed |
| `findings` | list, each with class (`bug` / `friction` / `spec_gap` / `working`) + recommendation |
## What you DO NOT ship
- Bug fixes. You record bugs; `debug` writes the RED test;