nixos-configs/home/roles/development/skills/parallel_beads.md

description

description
Orchestrate parallel bead processing with worktrees, PRs, and reviews

Parallel Beads Workflow

This skill orchestrates parallel bead processing using subagents. Each bead gets its own worktree, implementation, PR, and review.

Phase 1: Selection

1. Get ready beads: Run bd ready to list all beads with no blockers

2. Filter by plan readiness: For each ready bead, check if it's ready for batch implementation:

   • Has plan (thoughts/beads-{id}/plan.md exists): Include
   • type=bug without plan: Include (simple bugs can implement directly)
   • type=feature/task without plan: Exclude with warning

   # Check for plan existence
   ls thoughts/beads-{bead-id}/plan.md 2>/dev/null
   

3. Report skipped beads: If any beads were skipped, inform the user:

   Skipped beads (no plan):
   - {bead-id}: {title} (type: feature) - Run /beads_plan {bead-id} first
   - {bead-id}: {title} (type: task) - Run /beads_plan {bead-id} first
   

4. Present selection: Use AskUserQuestion with multiSelect: true to let the user choose which beads to work on

   • Include bead ID and title for each option
   • Only show beads that passed the plan check
   • Allow selection of multiple beads

Example:

AskUserQuestion with:
- question: "Which beads do you want to work on in parallel?"
- multiSelect: true
- options from filtered bd ready output

Phase 2: Worktree Setup

Before launching implementation subagents, create worktrees for all selected beads:

1. Get repository name:

   REPO_NAME=$(git remote get-url origin | sed 's|.*/||' | sed 's/\.git$//')
   

2. For each selected bead, create its worktree:

   BEAD_ID="[bead-id]"
   # Check if worktree already exists
   if [ -d "$HOME/wt/${REPO_NAME}/${BEAD_ID}" ]; then
     echo "Worktree already exists: ~/wt/${REPO_NAME}/${BEAD_ID}"
     # Ask user: remove and recreate, or skip this bead?
   else
     git worktree add -b "bead/${BEAD_ID}" "$HOME/wt/${REPO_NAME}/${BEAD_ID}"
   fi
   

3. Track created worktrees: Maintain a list of (bead_id, worktree_path) pairs for use in subagent instructions.

4. Report status:

   Created worktrees:
   - nixos-configs-abc → ~/wt/nixos-configs/nixos-configs-abc (branch: bead/nixos-configs-abc)
   - nixos-configs-xyz → ~/wt/nixos-configs/nixos-configs-xyz (branch: bead/nixos-configs-xyz)
   
   Skipped (existing worktree):
   - nixos-configs-123 → Ask user for resolution
   

Note: If a worktree or branch already exists, ask the user before proceeding:

• Remove existing worktree and branch, then recreate
• Skip this bead
• Use existing worktree as-is (risky - branch may have diverged)

Phase 3: Parallel Implementation

For each selected bead, launch a subagent using the Task tool. All subagents should be launched in parallel (single message with multiple Task tool calls).

Subagent Instructions Template

Each implementation subagent should receive these instructions:

Work on bead [BEAD_ID]: [BEAD_TITLE]

Worktree path: [WORKTREE_PATH]

## CRITICAL: Branch Verification (MUST DO FIRST)

1. **Navigate to worktree**:
   ```bash
   cd [WORKTREE_PATH]

2. Verify branch (MANDATORY before ANY modifications):

   CURRENT_BRANCH=$(git branch --show-current)
   echo "Current branch: $CURRENT_BRANCH"
   pwd
   

   ABORT CONDITIONS - If ANY of these are true, STOP IMMEDIATELY:

   • Branch is main or master
   • Branch does not match bead/[BEAD_ID]

   If you detect any abort condition:

   ABORTING: Branch verification failed.
   Expected branch: bead/[BEAD_ID]
   Actual branch: [CURRENT_BRANCH]
   Working directory: [pwd output]
   
   DO NOT PROCEED. Report this error to the orchestrator.
   

After Verification Passes

3. Review the bead requirements:

   • Run bd show [BEAD_ID] to understand the acceptance criteria
   • Note any external issue references (GitHub issues, Linear tickets, etc.)

4. Extract validation criteria:

   • Check for a plan: thoughts/beads-[BEAD_ID]/plan.md
   • If plan exists:
     • Read the plan and find the "Automated Verification" section
     • Extract each verification command (lines starting with - [ ] followed by a command)
     • Example: - [ ] Tests pass: \make test`→ extractmake test`
   • If no plan exists, use best-effort validation:
     • Check if Makefile exists → try make test and make lint
     • Check if flake.nix exists → try nix flake check
     • Check if package.json exists → try npm test
     • If none found, note "No validation criteria found"

5. Implement the changes:

   • Work in the worktree directory
   • Complete all acceptance criteria listed in the bead

   After implementation, run validation:

   • Execute each validation command from step 4
   • Track results in this format:

     VALIDATION_RESULTS:
     - make test: PASS
     - make lint: FAIL (exit code 1: src/foo.ts:23 - missing semicolon)
     - nix flake check: SKIP (command not found)
     

   • If any validation fails:
     • Continue with PR creation (don't block)
     • Document failures in bead notes: bd update [BEAD_ID] --notes="Validation failures: [list]"

6. Commit and push:

   • Stage all changes: git add -A
   • Create a descriptive commit message
   • Push the branch: git push -u origin bead/[BEAD_ID]

7. Create a PR:

   • Detect hosting provider from origin URL: git remote get-url origin
   • If URL contains github.com, use gh; otherwise use tea (Gitea/Forgejo)
   • PR title: "[BEAD_ID] [BEAD_TITLE]"
   • PR body must include:
     • Reference to bead ID: "Implements bead: [BEAD_ID]"
     • Any external issue references from the bead (e.g., "Closes #123")
     • Summary of changes
   • For GitHub (gh):

     gh pr create --title "[BEAD_ID] [BEAD_TITLE]" --body "$(cat <<'EOF'
     ## Summary
     [Brief description of changes]
     
     ## Bead Reference
     Implements bead: [BEAD_ID]
     
     ## External Issues
     [Any linked issues from the bead]
     
     ## Changes
     - [List of changes made]
     
     ## Validation
     [Include validation results from step 4]
     
     | Check | Status | Details |
     |-------|--------|---------|
     | make test | PASS | |
     | make lint | FAIL | src/foo.ts:23 - missing semicolon |
     | nix flake check | SKIP | command not found |
     EOF
     )"
     

   • For Gitea (tea):

     tea pr create --head bead/[BEAD_ID] --base main \
       --title "[BEAD_ID] [BEAD_TITLE]" \
       --description "## Summary
     [Brief description of changes]
     
     ## Bead Reference
     Implements bead: [BEAD_ID]
     
     ## External Issues
     [Any linked issues from the bead]
     
     ## Changes
     - [List of changes made]
     
     ## Validation
     [Include validation results from step 4]
     
     | Check | Status | Details |
     |-------|--------|---------|
     | make test | PASS | |
     | make lint | FAIL | src/foo.ts:23 - missing semicolon |
     | nix flake check | SKIP | command not found |"
     

8. Update bead status:

   • Mark the bead as "in_review": bd update [BEAD_ID] --status=in_review
   • Add the PR URL to the bead notes: `bd update [BEAD_ID] --notes="$(bd show [BEAD_ID] --json | jq -r '.notes')

PR: [PR_URL]"`

9. Report results:
   • Return:
     • PR URL
     • Bead ID
     • Implementation status (success/failure/blocked)
     • Validation summary: X passed, Y failed, Z skipped
     • List of any validation failures with details
   • If blocked or unable to complete, explain what's blocking progress
   • If validation failed, include the specific failures so the main agent can summarize them for the user

### Launching Subagents

For each bead, substitute into the template:
- `[BEAD_ID]` - the bead ID
- `[BEAD_TITLE]` - the bead title
- `[WORKTREE_PATH]` - the worktree path created in Phase 2

Use `subagent_type: "general-purpose"` for implementation subagents. Launch all selected beads' subagents in a single message for parallel execution:

<Task calls for each selected bead - all in one message>

**Important**: The worktree paths were created in Phase 2. Use the exact paths that were created, e.g.:
- `~/wt/nixos-configs/nixos-configs-abc`
- `~/wt/nixos-configs/nixos-configs-xyz`

Collect results from all subagents before proceeding.

## Phase 4: Parallel Review

After all implementation subagents complete, launch review subagents for each PR.

### Review Subagent Instructions Template

Review PR for bead [BEAD_ID]

1. Detect hosting provider: Run git remote get-url origin - if it contains github.com use gh, otherwise use tea

2. Read the PR:

   • For GitHub: gh pr view [PR_NUMBER] --json title,body,additions,deletions,files
   • For Gitea: tea pr view [PR_NUMBER]
   • View the diff: git diff main...bead/[BEAD_ID]

3. Review against acceptance criteria:

   • Run bd show [BEAD_ID] to get the acceptance criteria
   • Verify each criterion is addressed

4. Leave review comments:

   • For GitHub: gh pr review [PR_NUMBER] --comment --body "[COMMENTS]"
   • For Gitea: tea pr review [PR_NUMBER] --comment "[COMMENTS]"
   • Include:
     • Acceptance criteria checklist (which are met, which might be missing)
     • Code quality observations
     • Suggestions for improvement

5. Return summary:

   • Overall assessment (ready to merge / needs changes)
   • Key findings

Launch all review subagents in parallel.

## Phase 5: Cleanup and Summary

After reviews complete:

1. **Clean up worktrees**:
   ```bash
   git worktree remove ~/wt/[REPO_NAME]/[BEAD_ID] --force

Do this for each bead's worktree.

2. Provide final summary: Present a table or list with:

   • Bead ID
   • PR URL
   • Status (success / failed / blocked)
   • Validation summary (X/Y passed)
   • Review summary
   • Any failures or blockers encountered

   If any validation failures occurred, list them in a "Validation Failures" section so the user can address them.

Example output:

## Parallel Beads Summary

| Bead | PR | Bead Status | Validation | Review |
|------|-----|-------------|------------|--------|
| beads-abc | #123 | in_review | 3/3 passed | Approved |
| beads-xyz | #124 | in_review | 2/3 passed | Needs changes |
| beads-123 | - | open (failed) | - | Blocked by missing dependency |

### Validation Failures
- beads-xyz: `make lint` failed - src/foo.ts:23 missing semicolon

### Failures/Blockers
- beads-123: Could not complete because [reason]

### Next Steps
- Fix validation failures before merging
- Review PRs that need changes
- Address blockers for failed beads
- Run `/reconcile_beads` after PRs are merged to close beads

Error Handling

• Worktree creation failures (Phase 2):

  • If git worktree add fails (branch exists, path exists), prompt user:
    • Remove existing and retry
    • Skip this bead
    • Use existing (with warning about potential divergence)
  • Do NOT proceed to subagent launch until worktree is confirmed

• Branch verification failures (subagent reports):

  • If subagent reports it's on main or master, do NOT retry
  • Mark bead as failed with reason "Branch verification failed"
  • Continue with other beads but flag this as a critical issue
  • Investigation required: the worktree may have been corrupted or not created properly

• Subagent failures: If a subagent fails or times out, note it in the summary but continue with other beads

• PR creation failures: Report the error but continue with reviews of successful PRs

Resource Limits

• Consider limiting concurrent subagents to 3-5 to avoid overwhelming system resources
• If user selects more beads than the limit, process them in batches

Notes

• This workflow integrates with the beads system (bd commands)
• Worktrees are created in ~/wt/[REPO_NAME]/ by convention
• Each bead gets its own isolated branch and worktree
• PRs automatically reference the bead ID for traceability