From 16f6dfcec78c19b32022d747dfa48247fcb07d14 Mon Sep 17 00:00:00 2001 From: John Ogle Date: Wed, 14 Jan 2026 13:54:23 -0800 Subject: [PATCH] feat(skills): Enforce worktree/branch workflow in parallel_beads --- .../development/skills/parallel_beads.md | 119 +++++++++++++++--- 1 file changed, 103 insertions(+), 16 deletions(-) diff --git a/home/roles/development/skills/parallel_beads.md b/home/roles/development/skills/parallel_beads.md index ab043e1..b431f67 100644 --- a/home/roles/development/skills/parallel_beads.md +++ b/home/roles/development/skills/parallel_beads.md @@ -42,7 +42,46 @@ AskUserQuestion with: - options from filtered bd ready output ``` -## Phase 2: Parallel Implementation +## 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). @@ -53,16 +92,43 @@ 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]` +Worktree path: [WORKTREE_PATH] -2. **Review the bead requirements**: +## 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.) -3. **Extract validation criteria**: +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 @@ -74,12 +140,12 @@ Work on bead [BEAD_ID]: [BEAD_TITLE] - Check if `package.json` exists → try `npm test` - If none found, note "No validation criteria found" -4. **Implement the changes**: +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 3 + - Execute each validation command from step 4 - Track results in this format: ``` VALIDATION_RESULTS: @@ -91,12 +157,12 @@ Work on bead [BEAD_ID]: [BEAD_TITLE] - Continue with PR creation (don't block) - Document failures in bead notes: `bd update [BEAD_ID] --notes="Validation failures: [list]"` -5. **Commit and push**: +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]` -6. **Create a PR**: +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]" @@ -156,13 +222,13 @@ Work on bead [BEAD_ID]: [BEAD_TITLE] | nix flake check | SKIP | command not found |" ``` -7. **Update bead status**: +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]"` -8. **Report results**: +9. **Report results**: - Return: - PR URL - Bead ID @@ -175,15 +241,24 @@ PR: [PR_URL]"` ### 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: ``` ``` +**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 3: Parallel Review +## Phase 4: Parallel Review After all implementation subagents complete, launch review subagents for each PR. @@ -218,7 +293,7 @@ Review PR for bead [BEAD_ID] Launch all review subagents in parallel. -## Phase 4: Cleanup and Summary +## Phase 5: Cleanup and Summary After reviews complete: @@ -264,9 +339,21 @@ Example output: ## 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 -- **Worktree conflicts**: If a worktree already exists, ask the user if they want to remove it or skip that bead ## Resource Limits