Execute Outcome

• Each agent modifies files independently
• Tests run in isolation (no interference)
• Git state stays clean (one branch per WU)
• Merge conflicts detected at integration, not during work

Setup requirements:

1. Add .worktrees/ to .gitignore (one-time setup)
2. Worktrees share the same .git directory — no duplicate clones
3. Dependencies (node_modules, .venv) must exist in worktree or be symlinked

Worktree Environment Setup

Before running /work in a worktree, ensure dependencies are available:

Python (uv/pip):

# Option A: Install in worktree (isolated, slower)
cd .worktrees/wu-BHU-141 && uv sync

# Option B: Symlink from main (shared, faster)
ln -s $(pwd)/.venv .worktrees/wu-BHU-141/.venv

Node (npm/pnpm):

# Option A: Install in worktree
cd .worktrees/wu-BHU-141 && npm install

# Option B: Symlink node_modules (careful with native deps)
ln -s $(pwd)/node_modules .worktrees/wu-BHU-141/node_modules

Recommendation: Use symlinks for speed. If a WU modifies dependencies, install fresh.

Workflow

Step 1: Fetch Outcome and Work Units

1. Fetch Outcome issue via mcp__linear-server__get_issue
2. List child issues (Work Units) via mcp__linear-server__list_issues with parentId
3. Display:

   Outcome: [title]
   
   Work Units found: N
   1. [WU-1 title] (proof: X, budget: Y)
   2. [WU-2 title] (proof: X, budget: Y)
   ...
   

Step 2: Determine Dependencies

Ask human:

Do any Work Units depend on others?

1. WU-1: [title]
2. WU-2: [title]
3. WU-3: [title]

Enter dependencies (e.g., "2→1" means WU-2 depends on WU-1):
Or type "none" if all are independent.

Build dependency graph from response.

Step 3: Plan Execution Order

Based on dependencies:

1. Topological sort to find valid order
2. Identify parallelizable groups (no interdependencies)
3. Present plan:

   Execution Plan:
   
   Batch 1 (parallel, 2 worktrees):
   - BHU-141: [title]
   - BHU-143: [title]
   
   Batch 2 (after batch 1):
   - BHU-142: [title] (depends on BHU-141)
   
   Proceed? [y/n]
   

Step 4: Execute Batches

For each batch:

If batch has 1 Work Unit:

• Execute inline using /work logic (no worktree needed)
• Commit directly to current branch

If batch has multiple Work Units (parallel):

1. Setup worktrees:

   # Get current branch name
   CURRENT_BRANCH=$(git branch --show-current)
   
   # Create worktree directory
   mkdir -p .worktrees
   
   # For each WU in batch, create worktree with feature branch
   git worktree add .worktrees/wu-BHU-141 -b wu/BHU-141 $CURRENT_BRANCH
   git worktree add .worktrees/wu-BHU-143 -b wu/BHU-143 $CURRENT_BRANCH
   

2. Launch parallel agents:

   For each Work Unit in the batch, invoke the Task tool:

   Task(
     subagent_type: "general-purpose"
     description: "Execute WU BHU-141"
     prompt: |
       Execute Work Unit BHU-141 in isolated worktree.
   
       ## Context
       - Issue ID: BHU-141
       - Worktree path: /absolute/path/to/.worktrees/wu-BHU-141
       - Base branch: wu/BHU-141
   
       ## Instructions
       1. cd to worktree: cd /absolute/path/to/.worktrees/wu-BHU-141
       2. Run /work BHU-141 workflow (fetch issue, TDD, implement, review)
       3. All file operations MUST happen in the worktree path
       4. All git commands MUST use: git -C /absolute/path/to/.worktrees/wu-BHU-141
       5. Commit format: [BHU-141] <type>: <description>
   
       ## Critical
       - NEVER modify files outside the worktree
       - Return verdict: APPROVED / NEEDS_CHANGES / BLOCKED_FOR_HUMAN
   )
   

   Launch all batch agents in parallel (single message with multiple Task calls).

3. Wait and collect:

   • Wait for all agents to complete
   • Collect results (APPROVE/NEEDS_CHANGES/BLOCKED)

4. Integrate completed work:

   # For each successful WU, merge its branch
   git merge wu/BHU-141 --no-edit
   git merge wu/BHU-143 --no-edit
   

5. Cleanup worktrees:

   git worktree remove .worktrees/wu-BHU-141
   git worktree remove .worktrees/wu-BHU-143
   git branch -d wu/BHU-141
   git branch -d wu/BHU-143
   

Between batches:

• Report progress
• Ensure all merges from previous batch are complete
• If any Work Unit failed, ask human:

  BHU-141 failed review. Options:
  1. Retry BHU-141
  2. Skip BHU-141, continue with others (cleanup its worktree)
  3. Stop execution (cleanup all worktrees)
  

Step 5: Handle Merge Conflicts

After parallel batch completion, merges may conflict:

1. Detect conflict:

   git merge wu/BHU-141 --no-edit
   # If exit code != 0 and output contains "CONFLICT"
   

2. On conflict, report to human:

   Merge conflict integrating BHU-141.
   
   Conflicting files:
   - src/models/land.py
   - src/services/valuation.py
   
   Options:
   1. I'll resolve manually (pause execution)
   2. Abort BHU-141, keep other WUs
   3. Stop execution entirely
   

3. If human resolves:

   • Wait for human to run git add . && git commit
   • Verify merge complete: git status shows clean state
   • Continue with next merge or batch

4. Conflict prevention tips:

   • Work Units touching same files should be sequential, not parallel
   • During dependency mapping (Step 2), ask: "Do any WUs modify the same files?"

Step 6: Handle Blocked Items

If a Work Unit is BLOCKED_FOR_HUMAN:

1. Pause batch execution
2. Report the blocking issue
3. Keep worktree intact (human may need to inspect)
4. Wait for human decision
5. Resume or abort based on decision

Step 7: Update Outcome

After all Work Units complete:

1. Update Outcome issue status checklist:

   ## Status
   - [x] Work Units defined
   - [x] Work Units complete
   - [ ] Success metric verified
   

2. Report to human:

   ## Outcome Execution Complete
   
   Outcome: [title]
   
   Work Units: N/N complete
   - [x] WU-1: [title] - APPROVED
   - [x] WU-2: [title] - APPROVED
   - [x] WU-3: [title] - APPROVED
   
   Total lines changed: X
   Total decisions logged: Y
   
   Next: Verify success metric.
   

Error Handling

Cleanup on Abort

If execution is aborted (by human or error), always cleanup:

# List all worktrees created for this outcome
git worktree list | grep ".worktrees/wu-"

# Remove each worktree
git worktree remove .worktrees/wu-BHU-141 --force
git worktree remove .worktrees/wu-BHU-143 --force

# Delete orphan branches
git branch -D wu/BHU-141 wu/BHU-143

# Remove worktrees directory if empty
rmdir .worktrees 2>/dev/null || true

Never leave worktrees behind — they consume disk space and cause confusion.

Execution Modes

Sequential (safe):

/execute-outcome BHU-139 --sequential

Runs all Work Units one by one, no parallelism.

Parallel (fast):

/execute-outcome BHU-139 --parallel

Maximum parallelism based on dependency graph.

Default: Ask about dependencies, then optimize.

Progress Tracking

During execution, maintain state:

Outcome: BHU-139
Started: 2026-01-21 12:30
Base branch: feature/land-valuation

Batch 1/2 (parallel):
  Worktrees: .worktrees/wu-BHU-141, .worktrees/wu-BHU-143
  - [x] BHU-141: APPROVED → merged ✓
  - [x] BHU-143: APPROVED → merged ✓
  Worktrees cleaned up ✓

Batch 2/2 (sequential):
  - [~] BHU-142: IN PROGRESS...

Active worktrees: 0
Elapsed: 7 min

Worktree Status Commands

To inspect state during execution:

# List all worktrees
git worktree list

# Check branch status in a worktree
git -C .worktrees/wu-BHU-141 status

# View commits made in worktree
git -C .worktrees/wu-BHU-141 log --oneline -5