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

---
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

   ```bash
   # 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**:
   ```bash
   REPO_NAME=$(git remote get-url origin | sed 's|.*/||' | sed 's/\.git$//')
   ```

2. **For each selected bead**, create its worktree:
   ```bash
   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):
   ```bash
   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\`` → extract `make test`
     - Note any "Per CONTRIBUTING.md:" requirements for additional validation
     - Also read the "Manual Verification" section from the plan if present
     - Save manual verification items for inclusion in the PR description (they won't be executed)
   - 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`
     - **Check for CONTRIBUTING.md** → read and extract testing/linting requirements
       - Track which requirements can be automated vs need manual review
       - Automated: commands that can be run (e.g., "run `make test`")
       - Manual: qualitative checks (e.g., "ensure documentation is updated")
     - 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 (not applicable - no flake.nix)
     - cargo test: ERROR (command not found)
     ```

   **Status definitions:**
   - **PASS**: Check executed successfully with no issues
   - **FAIL**: Check executed but found issues that need attention
   - **SKIP**: Check not applicable to this project (e.g., no Makefile for `make test`)
   - **ERROR**: Check could not execute (missing tool, permission error, 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`):
     ```bash
     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 Steps Completed

     ### Automated Checks
     | Check | Status | Details |
     |-------|--------|---------|
     | make test | PASS | |
     | make lint | FAIL | src/foo.ts:23 - missing semicolon |
     | nix flake check | SKIP | not applicable - no flake.nix |
     | cargo test | ERROR | command not found |

     ### Manual Verification Required
     [If plan has Manual Verification items, list them as unchecked boxes:]
     - [ ] Verify UI changes match design mockups
     - [ ] Test on mobile viewport sizes
     [If no manual verification items: "None specified in plan."]

     ### CONTRIBUTING.md Compliance
     [If CONTRIBUTING.md requirements were extracted:]
     - [x] Tests pass (verified via `make test`)
     - [ ] Documentation updated (needs manual review)
     [If no CONTRIBUTING.md: "No contribution guidelines found."]
     EOF
     )"
     ```
   - For Gitea (`tea`):
     ```bash
     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 Steps Completed

     ### Automated Checks
     | Check | Status | Details |
     |-------|--------|---------|
     | make test | PASS | |
     | make lint | FAIL | src/foo.ts:23 - missing semicolon |
     | nix flake check | SKIP | not applicable - no flake.nix |
     | cargo test | ERROR | command not found |

     ### Manual Verification Required
     [If plan has Manual Verification items, list them as unchecked boxes:]
     - [ ] Verify UI changes match design mockups
     - [ ] Test on mobile viewport sizes
     [If no manual verification items: None specified in plan.]

     ### CONTRIBUTING.md Compliance
     [If CONTRIBUTING.md requirements were extracted:]
     - [x] Tests pass (verified via make test)
     - [ ] Documentation updated (needs manual review)
     [If no CONTRIBUTING.md: No contribution guidelines 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, W errors`
     - List of any validation failures or errors 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