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

   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