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

1. **Create worktree**:
   - Branch name: `bead/[BEAD_ID]`
   - Worktree path: `~/wt/[REPO_NAME]/[BEAD_ID]`
   - Command: `git worktree add -b bead/[BEAD_ID] ~/wt/[REPO_NAME]/[BEAD_ID]`

2. **Review the bead requirements**:
   - Run `bd show [BEAD_ID]` to understand the acceptance criteria
   - Note any external issue references (GitHub issues, Linear tickets, etc.)

3. **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`
   - 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"

4. **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 3
   - 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]"`

5. **Commit and push**:
   - Stage all changes: `git add -A`
   - Create a descriptive commit message
   - Push the branch: `git push -u origin bead/[BEAD_ID]`

6. **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
     [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`):
     ```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
     [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 |"
     ```

7. **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]"`

8. **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

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

Collect results from all subagents before proceeding.

## Phase 3: 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 4: 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

- **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
- **Worktree conflicts**: If a worktree already exists, ask the user if they want to remove it or skip that bead

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