ensemble-implement-trd-beads

Ensemble Command: /ensemble:implement-trd-beads

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-plan (with br ready fallback when bv is unavailable) 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-plan — enabling cross-session resumability, graph-aware triage, and parallel execution planning.

Key behaviors:

• Scaffold: epic -> stories -> tasks created in br before first line of code
• Idempotency: existing scaffolds detected via title-prefix matching; partial scaffolds resumed safely
• Execution: bv --robot-plan determines what to run next, extracting up to max_parallel tasks for parallel execution (fallback: br ready when bv unavailable)
• Quality gates: phase completion triggers test delegation; results recorded as br comments
• Sync: br sync --flush-only exports JSONL before every bv call
• Wheel instructions: printed every run with NTM spawn commands for multi-agent flywheel
• Graceful degradation: bv features skipped if bv unavailable; br required
• No .trd-state/ files: beads + JSONL are the single source of truth

Workflow

Phase 1: Preflight

1. Handle Special Arguments Process --status and --reset-task arguments for early exit paths

• If $ARGUMENTS contains '--plan' AND $ARGUMENTS contains '--execute': print 'ERROR: --plan and --execute are mutually exclusive.' and EXIT
• Parse $ARGUMENTS for .md paths. Initialize COMBINED_WORKSTREAM_MODE=false before branching. If two or more TRD paths are present without '--workstream' or '--legacy-multi': print 'ERROR: Multiple TRDs passed directly. Direct multi-TRD execution is deprecated because it can lose fidelity across parser/runtime merge boundaries. Run /ensemble:create-workstream-trd ... then /ensemble:implement-trd-beads , or rerun with --workstream to generate first.' and HALT before any br/git/scaffold side effects. If two or more TRD paths are present with '--workstream': resolve TRD_CLI and run node "$TRD_CLI" create-workstream-trd <TRD_PATHS...>; parse {ok,path}. If ok is false or JSON malformed, print errors and HALT. Replace TRD path list with the generated single workstream TRD path and continue normal single-TRD behavior. If two or more TRD paths are present with '--legacy-multi': set COMBINED_WORKSTREAM_MODE=true, set SOURCE_TRD_PATHS to the ordered path list, print 'DEPRECATED: direct multi-TRD mode; prefer /ensemble:create-workstream-trd then implement the generated workstream TRD', and list every source TRD. If exactly one TRD path is present: keep COMBINED_WORKSTREAM_MODE=false and preserve existing single-TRD behavior exactly. If zero TRD paths are present: keep COMBINED_WORKSTREAM_MODE=false and defer to normal single-TRD selection in Preflight step 4.
• If $ARGUMENTS contains '--plan': set PLAN_ONLY=true (scaffold phase runs, Execute phase is skipped — print wheel instructions and exit after scaffold completes)
• If $ARGUMENTS contains '--execute': set EXECUTE_ONLY=true (scaffold phase is skipped — resume detection runs, Execute phase runs against existing beads)
• If $ARGUMENTS contains '--use-current-branch': set USE_CURRENT_BRANCH_REQUESTED=true; if $ARGUMENTS also contains '--branch=': print 'ERROR: --use-current-branch and --branch= are mutually exclusive.' and HALT before any git side effects. If flag absent: set USE_CURRENT_BRANCH_REQUESTED=false. If $ARGUMENTS contains '--branch=': extract the branch name after '=' and store it as BRANCH_REQUESTED; if --use-current-branch is also present this is already caught and HALTed above.
• If $ARGUMENTS contains '--status' AND TEAM_MODE=true: (TRD-029, AC: FR-IT-8, AC-BC-2)
• 1. Derive TRD_SLUG from filename (same derivation as normal Preflight step 4)
• 1. Run: br list --status=in_progress --json, filter by [trd:<TRD_SLUG>:task:] prefix
• 1. For each in-progress task: call get_sub_state(bead_id) to get sub-state
• 1. Group and print:

•    '=== 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>'
  

•    '================================='
  

• 1. EXIT
• If $ARGUMENTS contains '--status' AND COMBINED_WORKSTREAM_MODE=true: capture all issues with explicit file redirection, e.g. ISSUES_JSON=$(mktemp); br list --all --limit 0 --json > "$ISSUES_JSON". If the user supplied --workstream , run node "$TRD_CLI" workstream-status --issues-json "$ISSUES_JSON" --workstream ; otherwise omit --workstream and print all detected workstreams. Parse {ok,workstreams,trds,blocked,ready,parallelSafeStreams}; if ok is false, process exits non-zero, or JSON is malformed, print the error and HALT. Print release train progress, each TRD epic progress, blocked items, ready items, and parallel-safe streams; EXIT
• If $ARGUMENTS contains '--status' AND TEAM_MODE=false: derive TRD_SLUG, then call trd_progress() (Execute phase order 10) to print the TRD-scoped progress summary, EXIT
• If $ARGUMENTS contains '--reset-task' AND TEAM_MODE=true: (TRD-030, AC: FR-IT-9, AC-BC-3)
• 1. Extract TASK_ID from argument
• 1. Find bead: br list --status=open --json OR br list --status=in_progress --json

•  Filter for title containing [trd:<TRD_SLUG>:task:<TASK_ID>]
  

• 1. Reset br native status: br update <bead_id> --status=open
• 1. Add reset comment: br comment add <bead_id> 'status:open reset:manual reason:--reset-task'
• 1. Run: br sync --flush-only
• 1. Print: 'Reset task <TASK_ID> (bead: <bead_id>) to open. Team sub-state cleared.'
• 1. EXIT
• If $ARGUMENTS contains '--reset-task' AND TEAM_MODE=false: extract TASK_ID, run br list --status=open --json, filter JSON for entry with title containing [trd:<TRD_SLUG>:task:<TASK_ID>], run br update <BEAD_ID> --status=open, EXIT