diff --git a/brainstorm/SKILL.md b/brainstorm/SKILL.md index b0ecec0..0fda722 100644 --- a/brainstorm/SKILL.md +++ b/brainstorm/SKILL.md @@ -272,12 +272,11 @@ codebase (compiler, type-checker, runtime, schema, API, whatever the project owns), and for each one searches the workspace for a currently-green test that ratifies it. -Dispatch carrier: - -| Field | Content | -|-------|---------| -| `spec_path` | path to the spec just written in Step 6 | -| `iteration_scope` | which sections cover the imminent first iteration (verbatim from the brainstorm session) | +Dispatch carrier — the fields `spec_path` and `iteration_scope`, +defined authoritatively under **Carrier contract** in +`agents/grounding-check.md` (note `spec_path` is an *absolute* +path). That table is the single source for those fields; it is +deliberately not restated here, so the two files cannot drift. The agent returns a `PASS` / `BLOCK` / `INFRA_ERROR` report. Orchestrator interpretation: diff --git a/brainstorm/agents/grounding-check.md b/brainstorm/agents/grounding-check.md index fc65668..53e1bc5 100644 --- a/brainstorm/agents/grounding-check.md +++ b/brainstorm/agents/grounding-check.md @@ -54,6 +54,9 @@ section, not the whole spec. ## Carrier contract — what the controller hands you +This table is the authoritative definition of the carrier fields; +the dispatching skill references it rather than restating it. + | Field | Content | |-------|---------| | `spec_path` | absolute path to the spec draft you are checking | diff --git a/docwriter/SKILL.md b/docwriter/SKILL.md index 4ab3558..a9220ff 100644 --- a/docwriter/SKILL.md +++ b/docwriter/SKILL.md @@ -59,22 +59,17 @@ agent file governs the work. ## Handoff Contract -`docwriter` consumes (from orchestrator): +`docwriter` consumes (from orchestrator) the carrier fields +`scope`, `warning_target`, and `priority_items`, defined +authoritatively under **Carrier contract** in `agents/docwriter.md`. -| Field | Content | -|-------|---------| -| `scope` | Component / package / crate / module name(s) to document, or `all` | -| `warning_target` | Specific doc-tool warnings to clear, or `all` | -| `priority_items` | Optional: items the orchestrator wants documented first | +`docwriter` produces, for the orchestrator, the fields `status`, +`files_touched`, `warnings_cleared`, and `findings`, defined +authoritatively under **Output format** (with the `status` enum in +the Status protocol) in `agents/docwriter.md`. -`docwriter` produces: - -| Field | Content | -|-------|---------| -| `status` | `DONE` / `DONE_WITH_CONCERNS` / `NEEDS_CONTEXT` / `BLOCKED` | -| `files_touched` | paths + which level (top-level / module-level / item-level) | -| `warnings_cleared` | count, plus the doc-check status | -| `findings` | items whose names or behaviour seemed confusing while documenting them (one line each, no prescriptions) | +Both contracts are single-sourced in the agent file; they are +deliberately not restated here, so the two files cannot drift. The orchestrator decides whether findings become a follow-up iteration; `docwriter` does not self-resolve. diff --git a/docwriter/agents/docwriter.md b/docwriter/agents/docwriter.md index 6e90290..3887868 100644 --- a/docwriter/agents/docwriter.md +++ b/docwriter/agents/docwriter.md @@ -57,6 +57,9 @@ Additionally: ## Carrier contract — what the controller hands you +This table is the authoritative definition of the carrier fields; +the dispatching skill references it rather than restating it. + | Field | Content | |-------|---------| | `scope` | Component / package / crate / module name(s) to document, or `all` | @@ -160,6 +163,18 @@ At most 200 words, structured: prescriptions. The orchestrator decides whether they become a follow-up. +This section (together with the Status protocol above) 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 | +|-------|---------| +| `status` | `DONE` / `DONE_WITH_CONCERNS` / `NEEDS_CONTEXT` / `BLOCKED` (see Status protocol) | +| `files_touched` | paths + which level (top-level / module-level / item-level) | +| `warnings_cleared` | count, plus the doc-check status | +| `findings` | items whose names or behaviour seemed confusing while documenting them (one line each, no prescriptions) | + ## Common Rationalisations | Excuse | Reality | diff --git a/fieldtest/SKILL.md b/fieldtest/SKILL.md index 9e5fae8..d16aba7 100644 --- a/fieldtest/SKILL.md +++ b/fieldtest/SKILL.md @@ -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` | `..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: diff --git a/fieldtest/agents/fieldtester.md b/fieldtest/agents/fieldtester.md index 3aed4f6..e68d31b 100644 --- a/fieldtest/agents/fieldtester.md +++ b/fieldtest/agents/fieldtester.md @@ -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; diff --git a/implement/SKILL.md b/implement/SKILL.md index 4622da1..817fae1 100644 --- a/implement/SKILL.md +++ b/implement/SKILL.md @@ -59,32 +59,22 @@ ON `PARTIAL` OR `BLOCKED`, THE ORCHESTRATOR-AGENT WRITES `BLOCKED.md` AT THE REP ## Per-task sub-status mechanics -The orchestrator-agent reads and follows this table verbatim -every dispatch. Sub-status values are *internal* to the -orchestrator-agent — they describe the state of an inline -role-phase, not the status of a separate subagent. The -vocabulary is preserved because it maps 1:1 to the phase -reference files (`implementer.md` / `spec-reviewer.md` / -`quality-reviewer.md`) the orchestrator-agent consults at -each role-switch. +Each dispatch, the orchestrator-agent runs an internal per-task +loop over a sub-status vocabulary — `DONE`, `DONE_WITH_CONCERNS`, +`NEEDS_CONTEXT`, `non_compliant` / `changes_requested`, `BLOCKED`, +`unclear`, and tool/infra errors — bounded by a 2-retries-per- +failure-mode re-loop limit (the 3rd attempt escalates to +`BLOCKED`). These values are *internal* to the orchestrator-agent: +they describe the state of an inline role-phase, not a separate +subagent, and are not reported upstream. -| Sub-status | Action | -|------------|--------| -| `DONE` | next phase / next task | -| `DONE_WITH_CONCERNS` | accumulate concern, next phase | -| `NEEDS_CONTEXT` (1st–2nd) | re-attempt the phase with expanded context | -| `NEEDS_CONTEXT` (3rd) | stop → `BLOCKED` to orchestrator, reason `context-exhausted` | -| `non_compliant` / `changes_requested` (1st–2nd) | switch back to implementer mindset, repair with the check's report as repair brief, then re-run the check phase | -| `non_compliant` / `changes_requested` (3rd) | stop → `BLOCKED` to orchestrator, reason `review-loop-exhausted` | -| `BLOCKED` (implementer phase) | stop → `BLOCKED` to orchestrator, reason verbatim | -| `unclear` (spec-compliance phase) | stop → `BLOCKED` to orchestrator, reason `spec-ambiguous` | -| Tool / infra error | stop → `BLOCKED` to orchestrator, reason `infra` + raw error | - -Re-loop limit: 2 retries per failure-mode per task. The 3rd -is `BLOCKED` to the orchestrator. `skip task K, continue` is -intentionally NOT a mode — tasks have implicit ordering -dependencies and the orchestrator-agent does not know the -dependency graph. +The mapping of each value to its action (and the `BLOCKED` reasons +`context-exhausted` / `review-loop-exhausted` / `spec-ambiguous` / +`infra`) is defined authoritatively under **Per-task sub-status +vocabulary** in `agents/implement-orchestrator.md` — the file the +agent actually carries at runtime in its fresh context. That table +is the single source; it is deliberately not restated here, so the +two files cannot drift. ## The Process — orchestrator side @@ -95,9 +85,9 @@ For a standard iteration: ``` Agent("implement-orchestrator", { mode: "standard", - iter_id: "", // e.g. "ct.2.3", "or.1", "23.4" + iter_id: "", plan_path: "", - task_range: [3, 8] // optional + task_range: [3, 8] }) ``` @@ -113,6 +103,13 @@ Agent("implement-orchestrator", { }) ``` +The blocks above show the call shape; each field's semantics +(including the load-bearing `iter_id` rule — it names the scratch +dir and stats filename, NOT a branch) are defined authoritatively +under **Carrier contract** in `agents/implement-orchestrator.md`. +That table is the single source for the field semantics; they are +deliberately not restated here, so the two files cannot drift. + Before dispatch: ensure the working tree is clean (`git status --porcelain` empty). The orchestrator-agent's Phase 0 will refuse to start on a dirty tree. diff --git a/implement/agents/implement-orchestrator.md b/implement/agents/implement-orchestrator.md index 886ec04..39512ef 100644 --- a/implement/agents/implement-orchestrator.md +++ b/implement/agents/implement-orchestrator.md @@ -49,7 +49,10 @@ Additionally, every dispatch: ## Carrier contract -You receive from the outer orchestrator: +You receive from the outer orchestrator the following fields. This +table is the authoritative definition of each field's semantics; +the dispatching skill shows the call shape but references this table +rather than restating the semantics. | Field | Content | |-------|---------| @@ -147,6 +150,34 @@ them as you switch roles: - Spec-compliance check reference: `spec-reviewer.md` - Quality check reference: `quality-reviewer.md` +##### Per-task sub-status vocabulary (authoritative) + +The phases below produce these sub-status values. They are +*internal* to you — they describe the state of an inline +role-phase, not the status of a separate subagent, and are not +reported upstream. This table is the authoritative definition of +the vocabulary and the re-loop rule; the per-phase prose that +follows applies it, and the dispatching skill names it but +references this table. The vocabulary maps 1:1 to the phase +reference files listed above. + +| Sub-status | Action | +|------------|--------| +| `DONE` | next phase / next task | +| `DONE_WITH_CONCERNS` | accumulate concern, next phase | +| `NEEDS_CONTEXT` (1st–2nd) | re-attempt the phase with expanded context | +| `NEEDS_CONTEXT` (3rd) | stop → `BLOCKED` to orchestrator, reason `context-exhausted` | +| `non_compliant` / `changes_requested` (1st–2nd) | switch back to implementer mindset, repair with the check's report as repair brief, then re-run the check phase | +| `non_compliant` / `changes_requested` (3rd) | stop → `BLOCKED` to orchestrator, reason `review-loop-exhausted` | +| `BLOCKED` (implementer phase) | stop → `BLOCKED` to orchestrator, reason verbatim | +| `unclear` (spec-compliance phase) | stop → `BLOCKED` to orchestrator, reason `spec-ambiguous` | +| Tool / infra error | stop → `BLOCKED` to orchestrator, reason `infra` + raw error | + +Re-loop limit: 2 retries per failure-mode per task. The 3rd is +`BLOCKED` to the orchestrator. `skip task K, continue` is +intentionally NOT a mode — tasks have implicit ordering +dependencies and you do not know the dependency graph. + #### 2.1 — Implementer phase (inline) Read `/tmp/iter-/task-K.md`. Adopt the implementer diff --git a/implement/agents/implementer.md b/implement/agents/implementer.md index ee15b36..4ee1a2a 100644 --- a/implement/agents/implementer.md +++ b/implement/agents/implementer.md @@ -51,7 +51,7 @@ whole component. | Field | Content | |-------|---------| -| `task_text_path` | Absolute path to a file (typically `/tmp/iter-/task-.md`) containing the verbatim task block extracted from the plan. Read this file as your first action. | +| `task_text_path` | Absolute path to a file (typically `/tmp/iter-/task-.md`) containing the verbatim task block extracted from the plan. Read this file as your first action. This row is the authoritative definition of `task_text_path`; `spec-reviewer` receives the same field and cross-references it. | | `scene_set` | Parent cycle, where this task fits, dependencies on earlier completed tasks | | `cross_task_context` | Shared types, file structure decisions, naming conventions agreed for the iteration | | `mode` | `standard` (plan-driven) or `mini` (debug handoff: RED test path + cause summary + minimal-fix constraint) | diff --git a/implement/agents/spec-reviewer.md b/implement/agents/spec-reviewer.md index f2aafc2..94bad67 100644 --- a/implement/agents/spec-reviewer.md +++ b/implement/agents/spec-reviewer.md @@ -61,7 +61,7 @@ your spec for this review. | Field | Content | |-------|---------| -| `task_text_path` | Absolute path (typically `/tmp/iter-/task-.md`) — same file the implementer received. Read this file as your first action. | +| `task_text_path` | The same file the implementer received — see the authoritative `task_text_path` definition in `agents/implementer.md`. Read this file as your first action. | | `diff_command` | The shell command that produces the diff to review. Default and almost-always value: `git diff HEAD` (the working tree's full unstaged diff, accumulated across all tasks of this iter so far). Earlier tasks' changes are visible in this diff because no per-task commits are made — that is intentional; focus on the files the current task block claims it touches | | `status_from_implementer` | `DONE` or `DONE_WITH_CONCERNS` — if `DONE_WITH_CONCERNS`, the concerns are quoted so you can decide if they affect spec compliance | diff --git a/planner/SKILL.md b/planner/SKILL.md index 6ea8590..4824e44 100644 --- a/planner/SKILL.md +++ b/planner/SKILL.md @@ -72,13 +72,13 @@ Read the returned file-map. Lift the relevant entries into the plan's "Files this plan creates or modifies" section; the orchestrator may add or amend entries that recon missed. -Dispatch carrier: - -| Field | Content | -|-------|---------| -| `spec_path` | path to the parent spec | -| `iteration_scope` | which sections of the spec this iteration covers | -| `focus_hint` | optional — subsystem or symbol to prioritise | +Dispatch carrier — the fields `spec_path`, `iteration_scope`, and +`focus_hint`, defined authoritatively under **Carrier contract** +in `agents/plan-recon.md` (which marks `spec_path`/`iteration_scope` +mandatory and `focus_hint` optional, and specifies the +BLOCKED-on-missing rule). That table is the single source for those +fields; it is deliberately not restated here, so the two files +cannot drift. Recon does NOT decide decomposition. Two recon dispatches per planner run is unusual but legitimate (e.g. one for the main diff --git a/planner/agents/plan-recon.md b/planner/agents/plan-recon.md index 3a2266f..60a2264 100644 --- a/planner/agents/plan-recon.md +++ b/planner/agents/plan-recon.md @@ -51,6 +51,11 @@ In addition: ## Carrier contract — what the controller hands you +This table is the authoritative definition of the carrier fields +(including which are mandatory and the BLOCKED-on-missing rule +below); the dispatching skill references it rather than restating +it. + | Field | Content | |-------|---------| | `spec_path` | Path to the spec under `paths.spec_dir` (mandatory) |