菜单
Implement TRD with beads project management — persistent bead hierarchy, dependency-aware execution via br/bv, and cross-session resumability (Codex skill for /ensemble:implement-trd-beads)
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | ensemble-implement-trd-beads |
| description | Implement TRD with beads project management — persistent bead hierarchy, dependency-aware execution via br/bv, and cross-session resumability (Codex skill for /ensemble:implement-trd-beads) |
| user-invocable | true |
| argument-hint | [trd-path] [--plan] [--execute] [--status] [--reset-task TRD-XXX] [max parallel N] |
| model | gpt-5.1-codex |
This Codex skill mirrors the Ensemble slash command /ensemble:implement-trd-beads.
Follow the workflow below, adapt to the current repository, and keep outputs structured.
Parse a TRD and create a beads hierarchy (epic -> stories -> tasks) before any implementation begins. Drive execution order through bv --robot-next (with br ready fallback) rather than TRD re-parsing. Record all state transitions in br beads so the implementation is resumable across sessions without access to local state files.
This command wraps the implement-trd-enhanced execution model with a full beads project management layer powered by br (beads_rust) and bv (beads_viewer). It transforms TRD-structured work into a persistent, queryable beads hierarchy and drives execution order through bv --robot-next — enabling cross-session resumability, graph-aware triage, and parallel execution planning.
Key behaviors:
1. Handle Special Arguments Process --status and --reset-task arguments for early exit paths
'=== TEAM STATUS: <TRD_SLUG> ==='
'Tasks in_progress (building): <N>' -- list task IDs and assigned builder
'Tasks in_review: <N>' -- list task IDs and reviewer
'Tasks in_qa: <N>' -- list task IDs and QA agent
For each task with rejection count > 0: show 'Task <ID>: <N> rejections'
'Tasks completed: <M> / <Total>'
'================================='
Filter for title containing [trd:<TRD_SLUG>:task:<TASK_ID>]
2. Tool Availability Check Verify br is installed and functional, detect bv availability
3. Git-Town and Working Directory Verification Verify git-town installed and working directory is clean
4. TRD Selection and Validation Locate, validate, and detect format of the target TRD file
5. Design Readiness Gate Verification Check if the TRD passed the Design Readiness Gate from create-trd v3.0.0
6. Resume Detection Check for existing beads scaffold to enable cross-session resume
a. sub_state == 'in_progress' with assigned: comment -> re-delegate to same builder (or new one if original failed)
b. sub_state == 'in_review' -> delegate directly to reviewer with context from builder comment
c. sub_state == 'in_qa' -> delegate directly to QA with context from reviewer comment
d. sub_state == 'in_progress' with verdict:rejected in previous comment -> re-delegate to builder with rejection context
'=== RESUMING TEAM EXECUTION: <TRD_SLUG> ==='
'Tasks in_progress (building): <N>'
'Tasks in_review: <N>'
'Tasks in_qa: <N>'
'Tasks completed: <M>'
'Team config: lead=<agent>, builders=<list>, reviewer=<agent or none>, QA=<agent or none>'
'=== Resuming lead loop... ==='
7. TRD Staleness Gate Check TRD freshness before committing to a feature branch. Skip on resume. Algorithm defined in packages/development/skills/staleness-gate/SKILL.md.
8. Feature Branch Creation Create or switch to feature branch for TRD implementation
9. Strategy Detection Determine implementation strategy from arguments, TRD content, or auto-detection
10. Team Configuration Detection Determine team mode using precedence order: (1) TRD ## Team Configuration section, (2) command YAML team: section, (3) no team (single-agent). Sets TEAM_MODE, TEAM_CONFIG_SOURCE, TEAM_ROLES, REVIEWER_ENABLED, and QA_ENABLED for all subsequent steps. AC: FR-TD-1, FR-TD-2, FR-TD-6, FR-TD-7, FR-TD-8, AC-TD-1, AC-TD-2, AC-TD-3, FR-5.1, FR-5.2, FR-5.3, FR-5.4, FR-5.5, FR-5.6, NFR-1.3, NFR-4.2
Print 'NOTE: This TRD has <N> tasks across <M> domains. Consider running /ensemble:configure-team <trd-path> to auto-configure team roles.'
- Verify team.roles array exists
- Verify 'lead' and 'builder' roles are present in team.roles
- Verify agent: and agents: fields are mutually exclusive per role
- Verify owns: list is non-empty for each role
- Read name: field (required; must be one of: lead | builder | reviewer | qa)
- Read agent: (singular string) OR agents: (list of strings) — these are mutually exclusive
- Normalize: if agent: was used, convert to agents: [agent_name] so all downstream code uses agents: uniformly
- Read owns: list (required)
- Store as TEAM_ROLES[name] = {agents: [...], owns: [...]}
1. Scan packages/*/agents/*.yaml using glob pattern when running from repo source
2. For each file: extract basename, strip .yaml extension -> agent name
3. Include every available Task agent name exposed by the runtime (for installed plugins this may be ensemble-full:<agent>)
4. Also scan .claude/router-rules.json if it exists: extract any custom agent names defined there
5. Deduplicate into KNOWN_AGENTS set (sorted alphabetically for deterministic output)
For each agent name in role.agents:
If agent_name NOT in KNOWN_AGENTS:
Print: "ERROR: Agent '<agent_name>' referenced in team role '<role_name>' not found in ensemble registry."
Print: "Known agents: <sorted comma-separated KNOWN_AGENTS list>"
Print: "Check packages/*/agents/*.yaml for available agents."
HALT
11. Marketplace Preflight Check Before execution begins, check for marketplace capability gaps that may affect team config quality. Presents suggestions for missing agents/skills and installs approved plugins. Re-reads team config from TRD after installation if agents referenced in TRD team config are now available. AC: FR-11.1 through FR-11.6, AC-8.1 through AC-8.6
12. Traceability Validation Gate Run validate-requirements as an automatic preflight gate before scaffolding begins. Checks that PRD requirements have TRD task coverage, that [satisfies] annotations reference real REQ-NNN IDs, and that every user-facing task has a paired -TEST task. Errors (orphaned annotations) halt execution; warnings are printed but do not halt. Skipped if TRD has no [satisfies] annotations (legacy TRD without traceability).
If PRD_REQUIREMENTS is empty AND PRD file is non-empty: print 'WARNING: PRD parsed but no REQ-NNN headings found — PRD may use a different format. Skipping validation.' Skip remaining validation steps and proceed to Scaffold.
If TRD_TASKS is empty AND TRD is non-empty: print 'WARNING: TRD parsed but no [satisfies] annotations found — TRD may use a different format. Skipping validation.' Skip remaining validation steps and proceed to Scaffold.
1. TRD Parsing and Scaffold Specialist Boundary Parse TRD into structured phases and tasks; reserve scaffold work for beads-scaffold-specialist semantics
2. Idempotency Cache Cache existing beads to enable partial scaffold resume via title-prefix matching
3. Root Epic Creation Create the top-level epic bead for the TRD
4. Story Bead Creation Create one story bead per TRD phase under the root epic
5. Task Bead Creation Create one task bead per TRD task under its phase story with full description from TRD actions
6. Synthesized Test Bead Creation for Nested Test Sub-items Promote nested test sub-items (test checklist items lacking their own TRD-NNN-TEST id) into first-class, dependency-wired test beads so they are tracked and implemented
7. Dependency Encoding Wire explicit TRD dependencies and inter-phase sequential gates
br dep add <blocked_bead_id> <blocker_bead_id> (blocker blocks blocked). If the exact edge already exists, skip as no-op. Warn and skip any edge whose blockerId or blockedId cannot be resolved to a bead id.br dep add <blocked_bead_id> <blocker_bead_id> and add metadata comment '<edge.metadata>' to the blocked bead. If br reports a cycle or contradictory direction, print the exact edge and ask user to choose one of: retry (rerun the same br dep add after user manually fixes graph state), skip (record a skipped-edge comment and continue), reverse (swap blocker_bead_id and blocked_bead_id, show the reversed command, require explicit confirmation, then run once), abort (HALT immediately). Never auto-resolve or continue without a user choice.8. BV Execution Planning Run bv robot-plan and robot-triage for graph-aware execution planning
9. Scaffold Summary and BV Analysis Print scaffolding summary with BV analysis output
10. Wheel Instructions Output Print execution instructions for multi-agent parallel implementation. AC: FR-WI-1, FR-WI-2, FR-WI-3, FR-WI-4, AC-WI-1, AC-WI-2
br list --status=open # Sanity check that br works
/ensemble:implement-trd-beads --execute
# Or drive manually: bv --robot-next (repeat until epic is complete)
# Reads br ready beads, assigns to agents, runs pipeline,
# merges completed branches, and closes beads automatically.
br list --status=in_progress # Live bead status
br get <bead-id> # Inspect a specific bead
git town propose # Propose PR for feature branch
1. Execution Loop Poll bv robot-next (or br ready) and execute tasks until epic is complete. AC: FR-GD-1, FR-GD-2, FR-GD-3, AC-TD-3, AC-BC-1
- Use the existing v2.1.0 Execute loop (all steps 1-6 unchanged)
- Skip all team-specific steps (reviewer delegation, QA delegation, rejection loop, parallel builders)
- Quality Gate phase: run full scope (current behavior)
- Continue to LOOP below
- Replace the standard execution loop with the Lead Orchestration Loop below (TRD-013, AC: FR-LL-1, AC-LL-1)
- Reviewer delegation: enabled (TRD-016)
- QA delegation: enabled if QA_ENABLED=true (TRD-017)
- Parallel builder slots: active (TRD-025)
- Quality Gate phase: reduced scope if QA_ENABLED=true (TRD-031)
- Note: Scaffold phase is IDENTICAL in both modes (no team awareness in scaffold)
- Note: Completion phase is IDENTICAL in both modes
- Note: v2.1.0 beads without status: comments are treated as in_progress (builder stage) — safe default for backward compat (TRD-038)
- RETURN (team loop handles all remaining execution; skip LOOP below)
LEAD ORCHESTRATION LOOP (TEAM_MODE=true):
Variables: active_builders = {} (bead_id -> builder_agent)
LOOP:
1. br sync --flush-only (ensure JSONL current)
2. Check in-flight tasks (tasks with br native status=in_progress that have sub-states in_review or in_qa):
- Run: br list --status=in_progress --json, filter by TRD slug
- For each in-progress bead: call get_sub_state(bead_id)
- If sub_state == 'in_review': proceed to Reviewer Delegation step (TRD-016)
- If sub_state == 'in_qa': proceed to QA Delegation step (TRD-017)
- If sub_state == 'in_progress': task is with builder (normal)
3. Count available slots: available_slots = max_parallel - len(active_builders)
(default max_parallel=1, increased by 'max parallel N' argument)
4. If available_slots > 0:
- Get next tasks: if EXECUTE_ONLY=true or BV_AVAILABLE, run bv --robot-next --format toon (returns top unblocked task; bv is guaranteed available when EXECUTE_ONLY=true)
Else (EXECUTE_ONLY=false AND not BV_AVAILABLE): run br ready, filter by [trd:<TRD_SLUG>:task:] prefix
- Phase-strict selection: bv --robot-next / br ready return BEAD records titled [trd:<TRD_SLUG>:task:<TRD-NNN>]. Extract the TRD-NNN id from each ready bead's title to form READY_TRD_IDS, and form CLOSED_TRD_IDS = the TRD-NNN ids of all currently-closed task beads (the same set used by phase-status). Run: node "$TRD_CLI" next-task "<TRD_FILE_PATH>" --ready "<comma-joined READY_TRD_IDS>" --closed "<comma-joined CLOSED_TRD_IDS>" --max <available_slots or 1>. If ok is false or the process exits non-zero: print the error and HALT (do NOT dispatch on undefined selection). The returned selected[] are TRD-NNN ids; map each back to its bead id via TRD_TO_BEAD_MAP and dispatch ONLY those beads. This deterministically enforces the phase boundary (later-phase tasks filtered when PR_FORMAT=true); do NOT hand-filter.
- For each task (up to available_slots):
a. (TRD-021) Architecture Review: check task description for keywords:
'architecture', 'design', 'system', 'cross-cutting', 'multi-component', 'orchestrat'
If ANY keyword found:
- Lead performs brief architectural review (read TRD context, consider phase impact)
- Generate guidance notes (key design decisions, patterns to use, pitfalls to avoid)
- Record: br comment add <bead_id> 'architecture-review lead:<agent> guidance:<url_encoded_summary>'
- Include guidance in builder prompt: 'Architecture guidance from lead: <guidance_notes>'
If NO keywords: skip architecture review, proceed normally
b. (TRD-020) Lead Skip Decision: evaluate task characteristics before delegating to builder:
- If task description contains ONLY documentation/comments (no code changes expected):
SKIP_REVIEW=true, SKIP_QA=true
- If REVIEWER_ENABLED=false: SKIP_REVIEW=true (per TRD-023)
- If QA_ENABLED=false: SKIP_QA=true (per TRD-023)
- Lead can also skip based on judgment (low-risk configuration, etc.)
Record skip decisions:
- If SKIP_REVIEW: br comment add <bead_id> 'status:skip-review lead:<agent> reason:<rationale>'
- If SKIP_QA: br comment add <bead_id> 'status:skip-qa lead:<agent> reason:<rationale>'
Transition directly:
- Both review and QA skipped: validate_transition(bead_id, 'closed') directly after builder
- Only review skipped: validate_transition(bead_id, 'in_qa') -> QA delegation after builder
- No skips: normal flow (in_progress -> in_review -> in_qa -> closed)
AC: FR-LL-6, FR-LL-7, FR-LL-10, AC-LL-3, AC-LL-4, AC-LL-5, AC-LL-6
c. (TRD-022) Sibling Task Context: collect completed sibling tasks in same phase:
- Query br list --status=closed --json filtered by TRD slug, then restrict to task ids in PHASE_TASK_IDS[N] (task beads carry no phase/pr title segment — do NOT filter by a [trd:<TRD_SLUG>:phase:<N>] prefix, which never matches)
- For each closed task in this phase: read br comment list, find last implementation summary
- Limit to 5 most recently closed siblings
- If sibling context found, add to builder prompt:
'Previously completed tasks in this phase:'
'[TRD-XXX]: <implementation_summary_first_200_chars>'
'[TRD-YYY]: <implementation_summary_first_200_chars>'
- If no siblings completed yet: omit this section from prompt
AC: FR-LL-9
d. Select builder from TEAM_ROLES.builder.agents using keyword matching (TRD-014)
e. validate_transition(bead_id, 'in_progress') -- write status comment
f. Delegate to builder via Task(subagent_type=<builder>, prompt=<builder_prompt>) (TRD-015)
g. active_builders[bead_id] = builder
--- Parallel Builder Execution (TRD-025) ---
When available_slots > 1 AND multiple tasks are ready, apply parallel dispatch:
TRD-025-1. Set BUILDER_SLOTS = max_parallel (default 1, overridden by 'max parallel N' argument)
TRD-025-2. Query available tasks for parallel dispatch:
- If EXECUTE_ONLY=true or BV_AVAILABLE: run bv --robot-plan --format toon to get parallel execution tracks
Extract up to BUILDER_SLOTS tasks from the top-priority track(s)
- Else (EXECUTE_ONLY=false AND not BV_AVAILABLE): run br ready, filter by [trd:<TRD_SLUG>:task:] prefix, take up to BUILDER_SLOTS entries
- Candidate task list: CANDIDATE_TASKS = up to BUILDER_SLOTS ready tasks
TRD-025-3. File conflict detection: prevent assigning tasks with overlapping file targets
- For each task in CANDIDATE_TASKS:
a. Extract target file paths from the bead description
(look for 'File:', file path patterns like src/*, and file mentions in action items)
b. Build FILE_MAP: task_id -> [file_path, ...]
- Build SEEN_FILES = {} (file_path -> first task_id that claims it)
- Iterate CANDIDATE_TASKS in order:
For each task: check if ANY of its file paths are already in SEEN_FILES
- If NO overlap: add task to CONFLICT_FREE set, add its files to SEEN_FILES
- If overlap found: discard this task (keep first occurrence); log discarded task_id
- CONFLICT_FREE = ordered list of tasks with no file overlaps (up to BUILDER_SLOTS)
TRD-025-4. Launch concurrent Task() delegations for CONFLICT_FREE task set:
Phase A — Pre-flight (sequential, per task):
For each task in CONFLICT_FREE: run steps 4a-4e (architecture review, skip decision,
sibling context, builder selection, validate_transition) to prepare builder prompt.
Phase B — Concurrent dispatch:
Issue all Task() calls (step 4f) for CONFLICT_FREE simultaneously (parallel invocation).
Each builder works independently on its assigned task.
Phase C — Post-dispatch bookkeeping (sequential, per task):
For each dispatched task: run step 4g (active_builders[bead_id] = builder).
TRD-025-5. Wait for all parallel builders to complete:
- Block until ALL concurrent Task() delegations from TRD-025-4 return results
- Collect structured builder summaries (files_changed, implementation_description, etc.)
TRD-025-6. Process each builder result sequentially (after all parallel builders finish):
- For each completed builder result in CONFLICT_FREE order:
a. On builder success: run Reviewer Delegation step (step 3a) for this task
b. On reviewer approval: run QA Delegation step (step 3b) for this task
c. On any rejection: run Rejection Loop (step 3c) for this task
(Review and QA remain sequential per task even when builders ran in parallel)
- Remove each completed task from active_builders after its full pipeline finishes
--- Sequential Commit Ordering (TRD-026) ---
When parallel builders complete and their full pipelines (review+QA) pass, the lead serializes git commit operations:
TRD-026-1. Maintain COMMIT_QUEUE = ordered list of tasks whose pipelines completed successfully (in completion order).
TRD-026-2. For each task in COMMIT_QUEUE (process one at a time):
a. Run: git diff --name-only HEAD to see current staged changes
b. If no file conflicts with prior commits in this batch: commit immediately
- git commit with message referencing task ID and bead ID
- br comment add <bead_id> 'commit-order:<N> commit:<sha>'
- N = position in COMMIT_QUEUE (1-indexed)
c. If file conflict detected (same file modified by prior commit):
- One retry: builder re-applies its changes on top of the current HEAD
- If retry succeeds: commit normally, record commit-order:<N>
- If retry fails: br update <bead_id> --status=open; br comment add <bead_id> 'status:open commit-conflict-unresolved: returned to open'; continue to next task in COMMIT_QUEUE
TRD-026-3. After all commits: br sync --flush-only
--- Parallel Builder Failure Isolation (TRD-027) ---
If one builder fails (Task() returns error or structured failure summary) during parallel execution:
TRD-027-1. Reset that task: br update <bead_id> --status=open
TRD-027-2. Record failure (pure audit record — no state prefix): br comment add <bead_id> 'verdict:failed builder:<agent_type> reason:<error_summary>'
Note: NO status: prefix — this is a failure audit comment, not a state transition. validate_transition is NOT called.
The bead is already open (reset in step 1); a status: prefix would mislead get_sub_state() on the next loop iteration.
TRD-027-3. Other parallel builders continue unaffected (do not interrupt them).
TRD-027-4. The failed task enters the debug loop (Execute step 5: Debug Loop) on the NEXT loop iteration OR is eligible for re-assignment to another builder.
TRD-027-5. Lead tracks builder slot count: when a builder fails, its slot is freed immediately (active_builders count decremented).
TRD-027-6. Lead refills available slots on the next loop iteration by querying bv --robot-next / br ready again.
5. Check loop exit:
- If no tasks returned by bv/br AND no active_builders AND no in-flight tasks: break to Completion
- If no tasks returned but tasks exist in_review or in_qa: wait (check in-flight tasks next iteration)
6. br sync --flush-only
7. Continue LOOP
2. Task Claim and Specialist Selection Claim task in beads before delegating to specialist agent
-> fall back to backend-developer (first in list)
3. Task Delegation Build prompt and delegate to selected specialist, require closing summary comment
- Include ONLY: task description from bead, TRD section for this task, architecture guidance (if any), sibling context (if any from TRD-022)
- Do NOT include: full TRD content, other phase tasks, conversation history, previous builder outputs
- Include the file path(s) the task targets so the builder can Read them directly
- Include the test file path(s) the task should create/modify
- If the bead description contains a 'Sub-items' or 'Embedded tests' section: list every one of those items verbatim in the builder prompt and instruct: 'You MUST implement EVERY checklist sub-item listed, including all embedded tests. The task is not complete until every sub-item — especially each test — is implemented and passing. Do not skip tests that lack their own task id.'
- Each builder subagent starts with clean context — this is intentional for quality
'IMPORTANT: Do NOT close this bead (do not run br close). When done, return a structured summary:'
' - files_changed: [list of modified files with paths]'
' - implementation_description: [what was implemented]'
' - test_results: [pass/fail with details]'
' - issues_encountered: [list of problems, empty if none]'
' - recommendations: [follow-up suggestions, empty if none]'
a. Extract files_changed from builder's structured summary
b. Run: br comment add <bead_id> 'status:in_review builder:<agent> files:<comma-joined-files_changed>'
c. validate_transition(bead_id, 'in_review') -- see Execute step 9 (State Machine Transition Validator)
d. Proceed to Reviewer Delegation (TRD-016, Execute step 3a)
a. br comment add <bead_id> 'Implementation failed: <error_summary>. Builder: <agent>.'
b. Enter debug loop (Execute step 5)
3a. Reviewer Delegation and Verdict Handling (TEAM_MODE=true only) Delegate to reviewer after builder submits, parse verdict, route accordingly. AC: FR-CR-1, FR-CR-2, FR-CR-3, FR-CR-4, FR-CR-5, FR-CR-6, FR-LL-3, FR-SM-5, AC-SM-3
'If REJECTED: provide specific feedback with file, line, issue, and suggestion.'
3b. QA Delegation and Verdict Handling (TEAM_MODE=true only) Delegate to QA agent after reviewer approves and task is in_qa state, parse verdict, route accordingly. AC: FR-QA-1, FR-QA-2, FR-QA-3, FR-QA-4, FR-QA-5, FR-QA-6, FR-LL-4, FR-SM-6, AC-SM-1
'IMPORTANT: For each PRD AC listed in Validates PRD ACs:, provide explicit verdict (PROVEN/NOT_PROVEN) with evidence.'
build PROVEN_ACS list of AC-NNN-M IDs with verdict=PROVEN
Extract REQ_ID from TASK_TRACEABILITY[TASK_ID].satisfies_req_id
If test task: 'status:closed qa:<agent> verdict:passed req-satisfied:<REQ_ID> ac-proven:<PROVEN_ACS comma-joined>'
If impl task: 'status:closed qa:<agent> verdict:passed' (existing behavior)
br comment add <ROOT_EPIC_ID> 'req-verified:<REQ_ID> by:<TASK_ID> qa:<QA_AGENT> ac-proven:<PROVEN_ACS comma-joined>'
- Include: QA rejection reason, failed acceptance criteria, test failure details
- Builder re-implements, then goes back through reviewer -> QA
3c. Rejection Loop with Builder Re-Delegation (TEAM_MODE=true only) Triggered by reviewer REJECTED (from step 3a) or QA REJECTED (from step 3b). Collects full rejection context, enforces MAX_REJECTIONS cap, and re-delegates to the original builder or escalates to lead. AC: FR-LL-5, AC-SM-3, AC-SM-4
rejection_count: <count of lines containing verdict:rejected>,
latest_reason: <url_decoded reason from most recent verdict:rejected comment>,
previous_attempts: <summaries of builder implementation from prior builder comments>,
reviewer_feedback: <specific reviewer issues if rejection source is reviewer (step 3a)>,
qa_feedback: <specific QA issues including failed ACs and test failures if rejection source is QA (step 3b)>
}
- Identify original builder from the bead's assigned: metadata in the first status:in_progress comment
(Run: br comment list <bead_id>, scan forward for first 'status:in_progress assigned:<agent>' comment)
- Re-delegate to SAME original builder:
Generate a normalized executable workstream TRD from multiple source TRDs (Codex skill for /ensemble:create-workstream-trd)
Approval-gated Beads graph refinement before execution (Codex skill for /ensemble:refine-beads)
Create Foreman-native structured Technical Requirements Document from PRD — omits adversarial review phase, outputs parser-compatible tables (Codex skill for /ensemble:create-trd-foreman)
Create Technical Requirements Document from PRD with architecture design and adversarial review (Codex skill for /ensemble:create-trd)
Create comprehensive Product Requirements Document with structured elicitation and adversarial review (Codex skill for /ensemble:create-prd)
Pre-implementation cross-artifact consistency sweep — checks PRD↔TRD↔beads alignment before coding begins (Codex skill for /ensemble:analyze-requirements)