Menu
Decomposes assigned BDD scenarios into bd sub-issues for TDD execution, keeping the outer loop proof intact
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Adversarial review gate for scenario-based BC work; sole emitter of work_done for assign_scenarios and bugfix-with-scenarios dispatches
Routes inbound lead messages to the correct BC subagent after sufficiency gating; the sole entry point for all BC inbox processing
Determines whether an inbound lead message is sufficient to act on, or whether a clarify response is required before dispatch
Merges the work branch into the BC's main and pushes so the work_id commit is reachable from origin/main before any work_done emission
Situational mechanics for the turn-limited PO<->Architect BC-decomposition collaboration. Load this when you are actively running a decomposition exchange with the PO (or, as the PO, with the Architect) and need the round cap, the extension protocol, and the ship-from-here rule. Per PDR-014.
Executes a bd-decomposed implementation plan sub-issue by sub-issue with context isolation and mandatory TDD per behavior
| name | writing-plans-bdd |
| description | Decomposes assigned BDD scenarios into bd sub-issues for TDD execution, keeping the outer loop proof intact |
When the router dispatches assign_scenarios or request_bugfix (with scenarios) work to the implementer, the implementer must plan before coding. The plan is not a document — no plan document, no markdown file, no checklist. The plan lives in beads as sub-issues of the work's lead bead.
This ensures:
Before creating any sub-issue, run bd show <work_id> and read the
existing decomposition. The plan step is idempotent: re-entering it
(after a context reset, a reopened sub-issue, a clarify round-trip, or a
re-dispatch) must RECONCILE the existing plan, never blindly re-decompose.
Decide per behavior the assigned scenario(s) require:
bd close --reason "<reason>" naming the surviving plan.
Never leave two sub-issues decomposing one behavior.Definition — "already planned": a RED ("write the failing test for
<behavior>") AND its GREEN ("implement <behavior>") already exist under
this work_id, matched on the behavior the title names. If both legs are
present and consistent, the behavior is planned; do not create a second pair.
For each discrete behavior that must be built to make the assigned scenario(s) pass, create two bd sub-issues of the lead bead:
RED sub-issue — "write the failing test for <behavior>"
test(red): <behavior> and the test suite confirms the test fails for
the right reason.GREEN sub-issue — "implement <behavior>"
feat(green): <behavior> and the test is passing.Then add a dependency so the GREEN sub-issue cannot start until the RED sub-issue is closed:
bd dep add <green_id> <red_id>
This dependency DAG is the enforcement point for test-first order. The router
reads it via bd ready to know which sub-issues are unblocked and can be
dispatched.
Naming convention:
The assigned Gherkin scenario(s) are the BDD outer loop — they pin what
work_done proves. Decomposition must not change what that proof is.
Concretely: you may decompose into as many RED/GREEN sub-issue pairs as needed, but every sub-issue must exist in service of making the assigned scenario(s) pass. You may NOT:
features/ that were not assigned.When behavior B depends on behavior A (e.g. B builds on an abstraction A
introduces), encode that as bd dep edges in addition to the RED/GREEN edges:
# A's GREEN must be closed before B's RED can start
bd dep add <B_red_id> <A_green_id>
This forms an explicit DAG. The router dispatches any sub-issue with no open
blockers (bd ready) — independent RED sub-issues at the same layer are
dispatched in parallel to bc-implementer subagents. Dependent sub-issues
wait until all their blockers are closed.
bd Commands# ADOPT EXISTING — never create blind. Read the current plan first.
bd show <work_id>
# No sub-issues → decompose below.
# Complete RED/GREEN pair for the behavior already present → adopt it, create nothing.
# Partial/duplicate → reconcile in place (add the missing leg, or
# `bd close <straggler> --reason "duplicate of <surviving_id>"`).
# Create the RED sub-issue
bd create "write the failing test for <behavior>" --parent <work_id>
# → prints <red_id>
# Create the GREEN sub-issue
bd create "implement <behavior>" --parent <work_id>
# → prints <green_id>
# Add RED→GREEN dependency: GREEN waits for RED
bd dep add <green_id> <red_id>
# For cross-behavior deps: B's RED waits for A's GREEN
bd dep add <B_red_id> <A_green_id>
# Mark claimed and in-progress as you work each behavior
bd update <sub_id> --claim
bd update <sub_id> --status in_progress
# Close when complete (RED: failing test committed; GREEN: impl + passing)
bd close <sub_id>
# Check what's ready (no open blockers) — used by the router dispatch loop
bd ready
bd dep add establishes the parent-child relationship so bd show <work_id>
surfaces the full decomposition tree with dependency edges.
digraph bdd_plan {
rankdir=TB;
assign [label="Receive assign_scenarios\nor bugfix w/ scenarios", shape=box];
read [label="Read scenario(s) carefully", shape=box];
show [label="bd show <work_id>", shape=box];
exists [label="Plan already exists?", shape=diamond];
decomp [label="Decompose into behaviors\n(RED + GREEN sub-issues per behavior,\nbd dep edges for order)", shape=box];
recon [label="Adopt / reconcile in place\n(complete a partial pair,\nclose duplicate stragglers)", shape=box];
ready [label="bd ready\n→ dispatch all unblocked sub-issues\nIN PARALLEL to bc-implementer", shape=box];
loop [label="Each bc-implementer: TDD inner loop\ntest(red) commit → feat(green) commit", shape=box];
gate [label="Gate: all dispatched sub-issues closed?\ntest(red) precedes feat(green)?", shape=diamond];
outer [label="Run assigned Gherkin\nscenario(s) — must pass", shape=diamond];
review [label="Hand off to bc-reviewer", shape=box];
assign -> read -> show -> exists;
exists -> decomp [label="no: decompose"];
exists -> recon [label="yes: adopt/reconcile"];
decomp -> ready;
recon -> ready;
ready -> loop -> gate;
gate -> ready [label="no: wait for layer"];
gate -> outer [label="DAG drained"];
outer -> review [label="pass"];
outer -> ready [label="fail: reopen sub-issue"];
}
bd dep add <green> <red>.TodoWrite, inline checklists, or scratch notes for tracking. If it's work, it's a bead.bd ready) are dispatched together, in parallel, by the router. Dependent sub-issues wait for all their blockers to close before being dispatched.bd show <work_id> before creating any sub-issue. A re-entered plan step RECONCILES the existing plan (adopt a complete pair, complete a partial one, close duplicate stragglers); it does NOT duplicate. Two sub-issues decomposing one behavior is a defect the work-done-gate blocks on.A well-sized sub-issue takes one TDD inner loop (one RED-GREEN-REFACTOR cycle, possibly a few tests). If a sub-issue's description contains "and" or spans multiple components, split it.
If you cannot decompose the work without reinterpreting an assigned scenario, that is a signal the scenario may be ambiguous. File a clarify to the lead before proceeding.