@build - Execute Workstream
Execute a single workstream following TDD discipline with automatic guard.
Invocation (BEADS-001)
Accepts both formats:
- •
@build 00-001-01— WS-ID (PP-FFF-SS), resolve beads_id from.beads-sdp-mapping.jsonl - •
@build sdp-xxx— Beads task ID directly
Beads Integration (when enabled)
When Beads is enabled (bd installed, .beads/ exists):
- •Resolve ID: ws_id → beads_id via mapping (if ws_id given)
- •Before work:
bd update {beads_id} --status in_progress - •Execute: TDD cycle
- •On success:
bd close {beads_id} --reason "WS completed" --suggest-next - •On failure:
bd update {beads_id} --status blocked - •Before commit:
bd sync
When Beads NOT enabled: Skip Beads steps. Use ws_id only.
SDP repo: Beads always enabled (see .cursorrules).
Quick Reference
| Step | Action | Gate |
|---|---|---|
| 0 | Resolve beads_id | ws_id → mapping or use beads_id |
| 1 | Beads IN_PROGRESS | bd update {beads_id} --status in_progress |
| 2 | Activate guard | sdp guard activate {ws_id} |
| 3 | Read WS spec | AC present and clear |
| 4 | TDD cycle | @tdd for each AC |
| 5 | Quality check | sdp quality check passes |
| 6 | Beads CLOSED/blocked | bd close or bd update --status blocked |
| 7 | Beads sync + Complete | bd sync then commit |
Workflow
Step 0: Resolve Task ID
bash
# Input: ws_id (00-001-01) OR beads_id (sdp-xxx)
# If ws_id: beads_id = grep mapping for sdp_id
# If beads_id: ws_id = grep mapping for beads_id (reverse lookup)
# Guard needs ws_id; Beads needs beads_id
beads_id=$(grep -m1 "\"sdp_id\": \"{WS-ID}\"" .beads-sdp-mapping.jsonl 2>/dev/null | grep -o '"beads_id": "[^"]*"' | cut -d'"' -f4)
ws_id=$(grep -m1 "\"beads_id\": \"{beads_id}\"" .beads-sdp-mapping.jsonl 2>/dev/null | grep -o '"sdp_id": "[^"]*"' | cut -d'"' -f4)
Step 1: Beads IN_PROGRESS (when Beads enabled)
bash
[ -n "$beads_id" ] && bd update "$beads_id" --status in_progress
Step 2: Activate Guard
bash
sdp guard activate {WS-ID}
Gate: Must succeed. If fails, WS not ready.
Step 3: Read Workstream
bash
Read("docs/workstreams/backlog/{WS-ID}-*.md")
Extract:
- •Goal and Acceptance Criteria
- •Input/Output files
- •Steps to execute
Step 4: TDD Cycle
For each AC, call internal TDD skill:
code
@tdd "AC1: {description}"
Cycle: Red → Green → Refactor
Step 5: Quality Check
bash
sdp quality check --module {module}
Must pass:
- •Coverage ≥80%
- •mypy --strict
- •ruff (no errors)
- •Files <200 LOC
Step 6: Beads CLOSED or blocked
On success:
bash
[ -n "$beads_id" ] && bd close "$beads_id" --reason "WS completed" --suggest-next
On failure (quality check fails, TDD fails):
bash
[ -n "$beads_id" ] && bd update "$beads_id" --status blocked
Step 7: Complete
bash
# When Beads enabled: sync before commit
[ -d .beads ] && bd sync
sdp guard complete {WS-ID}
git add .
git commit -m "feat({scope}): {WS-ID} - {title}"
Quality Gates
Errors
| Error | Cause | Fix |
|---|---|---|
| No active WS | Guard not activated | sdp guard activate |
| File not in scope | Editing wrong file | Check WS scope |
| Coverage <80% | Missing tests | Add tests |
See Also
- •BEADS-001 Phase 2.3 — Beads @build spec
- •WorkstreamExecutor — Python implementation
- •Full Build Spec
- •TDD Skill
- •Guard Skill