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

   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