docs(tdd): wire sibling skills to the new entry path

The tdd skill referenced its neighbours (implement, brainstorm,
debug) but none referenced it back. Close the loop so the new
executable-spec-first entry path is reachable and consistent from
every skill that describes a relationship it now belongs to:

- implement: mini-mode trigger + dispatch example now cover a
  RED-first handoff from `debug` OR `tdd` (was debug-only); the
  orchestrator's task template and Phase-3 skip note generalised.
  This was real drift — mini-mode is no longer debug-exclusive.
- planner: skip rule gains the `tdd` case (it skips brainstorm
  AND planner — the RED executable-spec is the plan).
- brainstorm: `tdd` added to the permitted-skip list as the
  profile-gated alternative entry path, plus a cross-ref marking
  brainstorm as the bounce-back target when behaviour stops being
  test-specifiable.
- boss: pipeline diagram, Step-3 routing prose, and cross-refs.
  A test-specifiable feature issue is dispatched to `tdd`
  autonomously, the same way a bug issue goes to `debug`; this is
  NOT a new-cycle bounce-back (the test is the spec). The
  bounce-back fires only reactively, when tdd surfaces a genuine
  design fork.
- debug: reciprocal sibling note + cross-ref (new behaviour is
  tdd's job; debug is for regressions of existing behaviour).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-01 16:56:56 +02:00
parent 873e6e8f88
commit 137ec21e26
6 changed files with 54 additions and 10 deletions
+19 -1
View File
@@ -93,6 +93,8 @@ brainstorm → planner → implement → audit → fieldtest
+ +
debug (bug-triggered) debug (bug-triggered)
+ +
tdd → implement (mini) (test-specifiable feature, if profile enables it)
+
docwriter (post-stability) docwriter (post-stability)
``` ```
@@ -105,6 +107,21 @@ does `brainstorm` get dispatched. If a spec exists but no plan:
`audit`. If the iteration is a bug-fix: `debug`. Read each `audit`. If the iteration is a bug-fix: `debug`. Read each
skill's `SKILL.md` trigger section if unsure. skill's `SKILL.md` trigger section if unsure.
If the project profile enables the `tdd` phase and the picked
item is a **test-specifiable feature issue** — its body pins one
observable behaviour and the existing-cycle/new-cycle question
does not apply (it is a backlog issue, not a top-level work
container needing a fresh spec) — dispatch `tdd` autonomously,
the same way a bug issue is dispatched to `debug`. `tdd` is its
sibling: it authors a RED executable-spec and hands the GREEN
side to `implement` mini-mode. This is **not** a new-cycle
bounce-back (the test is the spec; no `brainstorm` is dispatched
to begin). The bounce-back fires only reactively: if `tdd`
reports the behaviour is not test-specifiable (a genuine design
fork), that escalation routes to `brainstorm` and — being a new
cycle that needs a fresh spec — is a bounce-back to the user per
§"Direction freedom" trigger 4.
If the working tree is mid-flight (uncommitted changes left over If the working tree is mid-flight (uncommitted changes left over
from a previous session): inspect first, then resume the right from a previous session): inspect first, then resume the right
step. Do not restart from scratch. step. Do not restart from scratch.
@@ -299,4 +316,5 @@ actionable ask, not a wrap-up summary.
record-reality discipline for the only autonomous glossary writer. record-reality discipline for the only autonomous glossary writer.
- **Downstream skills dispatched:** `../brainstorm`, - **Downstream skills dispatched:** `../brainstorm`,
`../planner`, `../implement`, `../audit`, `../fieldtest`, `../planner`, `../implement`, `../audit`, `../fieldtest`,
`../debug`, `../docwriter`. `../debug`, `../tdd` (test-specifiable feature, profile-gated;
autonomously dispatchable like `../debug`), `../docwriter`.
+12
View File
@@ -31,6 +31,12 @@ Triggers:
**Skipping is permitted only** for: **Skipping is permitted only** for:
- A bug-fix iteration (use `debug` directly). - A bug-fix iteration (use `debug` directly).
- A test-specifiable feature, on a project whose profile
enables the `tdd` phase (use `tdd` directly — the RED
executable-spec is the spec, no prose spec needed). The
boundary is the design line: the moment one honest minimal
assertion cannot pin the behaviour without choosing between
plausible designs, `tdd` bounces back here.
- A tidy iteration (use `audit` directly). - A tidy iteration (use `audit` directly).
- A trivial mechanical edit (per the project's CLAUDE.md - A trivial mechanical edit (per the project's CLAUDE.md
"trivial mechanical edits" carve-out). "trivial mechanical edits" carve-out).
@@ -408,6 +414,12 @@ Hand off carries:
- **Output target:** `../planner/SKILL.md` — only valid next - **Output target:** `../planner/SKILL.md` — only valid next
skill. skill.
- **Alternative entry path / bounce-back source:**
`../tdd/SKILL.md` — on profiles that enable it, a
test-specifiable feature enters through `tdd` instead of
here; `tdd` bounces the work back to `brainstorm` the moment
the behaviour stops being test-specifiable (a genuine design
fork). Such a bounce-back arrives as a normal cycle request.
- **Agent dispatched:** `agents/grounding-check.md` - **Agent dispatched:** `agents/grounding-check.md`
dispatched in Step 7.5 as a hard-gate. The agent reads the dispatched in Step 7.5 as a hard-gate. The agent reads the
spec with fresh context and reports PASS / BLOCK / spec with fresh context and reports PASS / BLOCK /
+10
View File
@@ -40,6 +40,12 @@ Trigger this skill on:
change, not a fix. Ad-hoc judgement that a bug is "too small change, not a fix. Ad-hoc judgement that a bug is "too small
for TDD" is the exact failure mode this skill exists to prevent. for TDD" is the exact failure mode this skill exists to prevent.
`debug` is for a regression of *existing* behaviour. New
test-specifiable behaviour is its sibling `tdd`'s job (same
two-stage RED→GREEN shape, triggered by a feature description
rather than an observed misbehaviour) — route there instead,
on profiles that enable it.
## The Iron Law ## The Iron Law
``` ```
@@ -93,3 +99,7 @@ separate one.
GREEN side after the orchestrator has decided whether to GREEN side after the orchestrator has decided whether to
commit the RED test separately or as part of the final fix commit the RED test separately or as part of the final fix
commit. commit.
- **Sibling RED-first skill:** `../tdd/SKILL.md` — same
two-stage RED→GREEN handoff to `implement` mini-mode, but
triggered by a new test-specifiable behaviour rather than an
observed bug.
+6 -6
View File
@@ -35,8 +35,8 @@ orchestrator-agent every dispatch.
Triggers: Triggers:
- A plan exists under `paths.plan_dir` (standard mode). - A plan exists under `paths.plan_dir` (standard mode).
- A `debug` skill has produced a RED test + cause and is - A `debug` skill (RED test + cause) or a `tdd` skill (RED
handing off for the GREEN side (mini mode). executable-spec) has handed off for the GREEN side (mini mode).
**Never skipped** when there is code to ship. Trivial **Never skipped** when there is code to ship. Trivial
mechanical edits (one-line typo fix, schema rename across N mechanical edits (one-line typo fix, schema rename across N
@@ -91,15 +91,15 @@ Agent("implement-orchestrator", {
}) })
``` ```
For a debug-handoff (mini mode): For a RED-first handoff from `debug` or `tdd` (mini mode):
``` ```
Agent("implement-orchestrator", { Agent("implement-orchestrator", {
mode: "mini", mode: "mini",
iter_id: "bugfix-<short-symptom>", iter_id: "bugfix-<short-symptom>", # tdd: "feat-<short-behaviour>"
red_test_path: "<absolute path>", red_test_path: "<absolute path>",
cause_summary: "<1-2 sentences from debugger>", cause_summary: "<1-2 sentences from debugger>", # tdd: spec_summary, the desired-behaviour line
constraint: "minimal fix, no surrounding cleanup" constraint: "minimal fix, no surrounding cleanup" # tdd: "minimal feature, no surrounding scope"
}) })
``` ```
+3 -3
View File
@@ -125,7 +125,7 @@ ON `PARTIAL` OR `BLOCKED`, WRITE `BLOCKED.md` AT THE REPO ROOT BEFORE RETURNING.
``` ```
Make this RED test pass: <red_test_path> Make this RED test pass: <red_test_path>
Cause (from debugger): Context (from debugger cause, or tdd spec_summary):
<cause_summary> <cause_summary>
Constraint: <constraint> Constraint: <constraint>
@@ -258,8 +258,8 @@ E2E fixtures. Write them into the working tree alongside the
rest of the iter's changes; the orchestrator will commit rest of the iter's changes; the orchestrator will commit
them together. them together.
(Mini mode: skip Phase 3 — the RED test from `debug` IS the (Mini mode: skip Phase 3 — the RED test handed off from `debug`
coverage.) or `tdd` IS the coverage.)
### Phase 4 — On PARTIAL/BLOCKED, write BLOCKED.md ### Phase 4 — On PARTIAL/BLOCKED, write BLOCKED.md
+4
View File
@@ -36,6 +36,10 @@ May be skipped when:
- The work is a bug fix where the RED test from `debug` IS - The work is a bug fix where the RED test from `debug` IS
the plan (handoff goes straight to `implement` mini-mode). the plan (handoff goes straight to `implement` mini-mode).
- The work is a test-specifiable feature routed through `tdd`,
where the RED executable-spec IS the plan (handoff goes
straight to `implement` mini-mode). `tdd` skips both
`brainstorm` and `planner`.
- The work is a trivial mechanical edit (per the project's - The work is a trivial mechanical edit (per the project's
CLAUDE.md "trivial mechanical edits" carve-out). CLAUDE.md "trivial mechanical edits" carve-out).