---
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. **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
   - Allow selection of multiple beads

Example:
```
AskUserQuestion with:
- question: "Which beads do you want to work on in parallel?"
- multiSelect: true
- options from 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. **Implement the changes**:
   - Work in the worktree directory
   - Complete all acceptance criteria listed in the bead
   - Run any relevant tests or checks

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

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

6. **Report results**:
   - Return: PR URL, bead ID, success/failure status
   - If blocked or unable to complete, explain what's blocking progress
```

### 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)
   - Review summary
   - Any failures or blockers encountered

Example output:
```
## Parallel Beads Summary

| Bead | PR | Status | Review |
|------|-----|--------|--------|
| beads-abc | #123 | Success | Approved |
| beads-xyz | #124 | Success | Needs changes |
| beads-123 | - | Failed | Blocked by missing dependency |

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

### Next Steps
- Review PRs that need changes
- Address blockers for failed 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