feat(skills): Enforce worktree/branch workflow in parallel_beads

home/roles/development/skills/beads_batch_research_plan.md

@@ -1,317 +0,0 @@
----
-description: Batch research and planning for multiple beads with interactive question review
-model: opus
----
-
-# Beads Batch Research+Plan
-
-This skill automates the common workflow of:
-1. Running /beads_research in parallel for multiple beads
-2. Presenting open questions interactively for user input (bead-by-bead)
-3. Running /beads_plan for all researched beads (plus any spawned from splits)
-
-## When to Use
-
-- You have multiple beads ready for work
-- You want to research and plan them efficiently before implementation
-- You prefer to batch your question-answering rather than context-switching between skills
-
-## Phase 1: Selection
-
-1. **Get ready beads**: Run `bd ready --limit=20` to list beads with no blockers
-
-2. **Filter already-researched beads**:
-   For each ready bead, check if it already has research:
-   ```bash
-   ls thoughts/beads-{bead-id}/research.md 2>/dev/null
-   ```
-
-   Categorize beads:
-   - **Needs research**: No `research.md` exists
-   - **Has research, needs plan**: `research.md` exists but no `plan.md`
-   - **Already planned**: Both `research.md` and `plan.md` exist
-
-3. **Present selection**:
-   ```
-   Ready beads available for batch research+plan:
-
-   NEEDS RESEARCH:
-   - {bead-id}: {title} (type: {type})
-   - ...
-
-   HAS RESEARCH (plan only):
-   - {bead-id}: {title} (type: {type})
-   - ...
-
-   ALREADY PLANNED (skip):
-   - {bead-id}: {title}
-
-   Which beads would you like to process?
-   ```
-
-4. **Use AskUserQuestion** with `multiSelect: true`:
-   - Include bead ID and title for each option
-   - Separate options by category
-   - Allow selection across categories
-
-## Phase 2: Parallel Research
-
-For each selected bead that NEEDS RESEARCH, launch a research subagent.
-
-### Subagent Instructions Template
-
-```
-Research bead [BEAD_ID]: [BEAD_TITLE]
-
-1. **Load bead context**:
-   ```bash
-   bd show [BEAD_ID]
-   ```
-
-2. **Create artifact directory**:
-   ```bash
-   mkdir -p thoughts/beads-[BEAD_ID]
-   ```
-
-3. **Conduct research** following beads_research.md patterns:
-   - Analyze and decompose the research question
-   - Spawn parallel sub-agent tasks (codebase-locator, codebase-analyzer, etc.)
-   - Synthesize findings
-
-4. **Write research document** to `thoughts/beads-[BEAD_ID]/research.md`:
-   - Include frontmatter with metadata
-   - Document findings with file:line references
-   - **CRITICAL**: Include "## Open Questions" section listing any unresolved items
-
-5. **Return summary**:
-   - Research status (complete/partial)
-   - Number of open questions
-   - Key findings summary (2-3 bullet points)
-   - List of open questions verbatim
-```
-
-### Launching Subagents
-
-Use `subagent_type: "opus"` for research subagents (matches beads_research model setting).
-
-Launch ALL research subagents in a single message for parallel execution:
-```
-<Task calls for each selected bead needing research - all in one message>
-```
-
-### Collecting Results
-
-Wait for ALL research subagents to complete. Collect:
-- Bead ID
-- Research status
-- Open questions list
-- Any errors encountered
-
-## Phase 3: Interactive Question Review
-
-Present each bead's open questions sequentially for user input.
-
-### For Each Bead (in order):
-
-1. **Present research summary**:
-   ```
-   ## Bead {N}/{total}: {bead-id} - {title}
-
-   Research complete. Key findings:
-   - {finding 1}
-   - {finding 2}
-
-   Open questions requiring your input:
-   1. {question 1}
-   2. {question 2}
-
-   Additionally:
-   - Should this bead be split into multiple beads? (y/n)
-   - If split, describe the split:
-   ```
-
-2. **Collect user responses**:
-   - Answers to open questions
-   - Split decision (yes/no)
-   - If split: new bead titles and how to divide the work
-
-3. **Handle splits**:
-   If user indicates a split:
-   ```bash
-   # Create new beads for split work
-   bd create --title="{split title 1}" --type={type} --priority={priority} \
-     --description="{description based on user input}"
-
-   # Update original bead if scope narrowed
-   bd update {original-bead-id} --description="{updated description}"
-   ```
-
-   Track new bead IDs for inclusion in planning phase.
-
-4. **Update research document**:
-   Append user answers to `thoughts/beads-{id}/research.md`:
-   ```markdown
-   ## User Clarifications [{timestamp}]
-
-   Q: {question 1}
-   A: {user answer 1}
-
-   Q: {question 2}
-   A: {user answer 2}
-
-   ## Bead Splits
-   {If split: description of split and new bead IDs}
-   ```
-
-### Progress Tracking
-
-After each bead's questions are answered, confirm before moving to next:
-```
-Questions answered for {bead-id}. {N-1} beads remaining.
-Continue to next bead? (y/n)
-```
-
-### Beads with No Questions
-
-If a bead's research had no open questions:
-```
-## Bead {N}/{total}: {bead-id} - {title}
-
-Research complete with no open questions.
-
-Key findings:
-- {finding 1}
-- {finding 2}
-
-Should this bead be split? (y/n)
-```
-
-## Phase 4: Parallel Planning
-
-After all questions answered, launch planning subagents for all beads.
-
-### Beads to Plan
-
-Include:
-- Original beads that were researched
-- Beads that had existing research (from selection phase)
-- New beads spawned from splits
-
-### Subagent Instructions Template
-
-```
-Create implementation plan for bead [BEAD_ID]: [BEAD_TITLE]
-
-1. **Load context**:
-   ```bash
-   bd show [BEAD_ID]
-   ```
-
-2. **Read research** (it exists and has user clarifications):
-   Read `thoughts/beads-[BEAD_ID]/research.md` FULLY
-
-3. **Create plan** following beads_plan.md patterns:
-   - Context gathering via sub-agents
-   - Design approach based on research findings and user clarifications
-   - **Skip interactive questions** - they were already answered in research review
-
-4. **Write plan** to `thoughts/beads-[BEAD_ID]/plan.md`:
-   - Full plan structure with phases
-   - Success criteria (automated and manual)
-   - References to research document
-
-5. **Update bead**:
-   ```bash
-   bd update [BEAD_ID] --notes="Plan created: thoughts/beads-[BEAD_ID]/plan.md"
-   ```
-
-6. **Return summary**:
-   - Plan status (complete/failed)
-   - Number of phases
-   - Estimated complexity (small/medium/large)
-   - Any issues encountered
-```
-
-### Launching Subagents
-
-Use `subagent_type: "opus"` for planning subagents (matches beads_plan model setting).
-
-Launch ALL planning subagents in a single message:
-```
-<Task calls for each bead to plan - all in one message>
-```
-
-### Handling Beads Without Research
-
-For beads that had existing research but user didn't review questions:
-- Planning subagent reads existing research
-- If research has unresolved open questions, subagent should flag this in its return
-
-## Phase 5: Summary
-
-After all planning completes, present final summary.
-
-### Summary Format
-
-```
-## Batch Research+Plan Complete
-
-### Successfully Processed:
-| Bead | Title | Research | Plan | Phases | Complexity |
-|------|-------|----------|------|--------|------------|
-| {id} | {title} | Complete | Complete | 3 | medium |
-| {id} | {title} | Complete | Complete | 2 | small |
-
-### New Beads (from splits):
-| Bead | Title | Parent | Status |
-|------|-------|--------|--------|
-| {new-id} | {title} | {parent-id} | Planned |
-
-### Failed:
-| Bead | Title | Phase Failed | Error |
-|------|-------|--------------|-------|
-| {id} | {title} | Research | Timeout |
-
-### Next Steps:
-1. Review plans at `thoughts/beads-{id}/plan.md`
-2. Run `/parallel_beads` to implement all planned beads
-3. Or run `/beads_implement {id}` for individual implementation
-
-### Artifacts Created:
-- Research: thoughts/beads-{id}/research.md (x{N} files)
-- Plans: thoughts/beads-{id}/plan.md (x{N} files)
-```
-
-## Error Handling
-
-### Research Subagent Failure
-- Log the failure with bead ID and error
-- Continue with other beads
-- Exclude failed beads from question review and planning
-- Report in final summary
-
-### Planning Subagent Failure
-- Log the failure with bead ID and error
-- Research still valid - can retry planning manually
-- Report in final summary
-
-### User Cancellation During Question Review
-- Save progress to bead notes
-- Report which beads were completed
-- User can resume with remaining beads in new session
-
-### Split Bead Creation Failure
-- Report error but continue with original bead
-- User can manually create split beads later
-
-## Resource Limits
-
-- Maximum concurrent research subagents: 5
-- Maximum concurrent planning subagents: 5
-- If more beads selected, process in batches
-
-## Notes
-
-- This skill is designed for the "research+plan before implementation" workflow
-- Pairs well with `/parallel_beads` for subsequent implementation
-- Run `/reconcile_beads` after implementation PRs merge

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**:
+Worktree path: [WORKTREE_PATH]
-   - 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**:
+## 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:
 
 ```
 <Task calls for each selected bead - all in one message>
 ```
 
+**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