gh-shakes-tzd-contextune/commands/ctx-execute.md

---
name: ctx:execute
description: Execute plan in parallel using git worktrees and multiple Claude sessions
keywords:
  - execute plan
  - run plan
  - run tasks
  - parallelize work
  - work in parallel
  - execute tasks
  - run parallel
executable: true
---

# Parallel Execute - Run Parallel Development Workflow

You are executing an automated parallel development workflow with **optimized parallel setup**.

**Contextune Integration:** This command can be triggered via `/contextune:parallel:execute` or natural language like "work on these tasks in parallel", "parallelize this work".

---

## 🎯 Performance-Optimized Architecture

**Key Innovation:** Worktrees are pre-created by script, agents focus purely on implementation, enabling deterministic parallel execution.

**Setup Performance (Measured Actuals):**
- 5 tasks: Setup completes in ~5s (deterministic script)
- 10 tasks: Setup completes in ~5s (parallel, O(1) scaling)
- 20 tasks: Setup completes in ~5s (constant time regardless of task count)

**Note:** Times shown are actual measurements from completed workflows, not estimates.

**Scaling:** Setup time is O(1) instead of O(n) — constant regardless of task count!

---

## Phase 0: Validate Prerequisites and Setup Infrastructure

**Check required tools:**

```bash
# Verify git and worktree support
git --version && git worktree list
```

**Requirements:**
- Git 2.5+ (worktree support)
- Clean working directory (no uncommitted changes on main)
- **Auto-approval configured** (see below)

**If validation fails:**
- Report missing tools to user
- Provide installation instructions
- Stop execution

### ⚡ IMPORTANT: Configure Auto-Approval to Avoid Bottlenecks

**Problem:** Without auto-approval, you must approve EVERY git command from EVERY parallel agent individually, negating all parallelism benefits!

**Solution:** Pre-approve safe git commands using Claude Code's IAM permission system.

**Quick Setup:**

1. **Run in Claude Code:** `/permissions`

2. **Add these allow rules:**
   ```
   Bash(git add:*)
   Bash(git commit:*)
   Bash(git push:*)
   ```

3. **Set permission mode:** `"defaultMode": "acceptEdits"` in settings

4. **Done!** Agents work autonomously 🚀

**📖 Complete guide:** See `docs/AUTO_APPROVAL_CONFIGURATION.md` for:
- Full configuration options
- Security considerations
- PreToolUse hook setup (advanced)
- Troubleshooting

**Without auto-approval:**
```
Agent 1: Waiting for approval... (blocked)
Agent 2: Waiting for approval... (blocked)
Agent 3: Waiting for approval... (blocked)
→ You: Must approve each one individually (bottleneck!)
```

**With auto-approval:**
```
Agent 1: Implementing... ✅ Testing... ✅ Committing... ✅
Agent 2: Implementing... ✅ Testing... ✅ Committing... ✅
Agent 3: Implementing... ✅ Testing... ✅ Committing... ✅
→ True parallelism! 🚀
```

### Setup Worktrees (Inline Script - 5 seconds)

**Generate and run the setup script:**

```bash
# Create scripts directory if needed
mkdir -p .parallel/scripts

# Generate setup script
cat > .parallel/scripts/setup_worktrees.sh <<'WORKTREE_SCRIPT'
#!/usr/bin/env bash
set -euo pipefail

# Find plan.yaml
PLAN_FILE=".parallel/plans/active/plan.yaml"
if [ ! -f "$PLAN_FILE" ]; then
  echo "Error: plan.yaml not found at $PLAN_FILE"
  exit 1
fi

# Extract task IDs
if command -v yq &> /dev/null; then
  TASK_IDS=$(yq '.tasks[].id' "$PLAN_FILE")
else
  TASK_IDS=$(grep -A 100 "^tasks:" "$PLAN_FILE" | grep "  - id:" | sed 's/.*id: *"\([^"]*\)".*/\1/')
fi

echo "Creating worktrees for $(echo "$TASK_IDS" | wc -l | tr -d ' ') tasks..."

# Create worktrees in parallel
echo "$TASK_IDS" | while read task_id; do
  branch="feature/$task_id"
  worktree="worktrees/$task_id"

  if [ -d "$worktree" ]; then
    echo "⚠️  Worktree exists: $task_id"
  elif git show-ref --verify --quiet refs/heads/$branch; then
    git worktree add "$worktree" "$branch" 2>/dev/null && echo "✅ Created: $task_id (existing branch)"
  else
    git worktree add "$worktree" -b "$branch" 2>&1 | grep -v "Preparing" && echo "✅ Created: $task_id"
  fi
done

echo ""
echo "✅ Setup complete! Active worktrees:"
git worktree list | grep "worktrees/"
WORKTREE_SCRIPT

chmod +x .parallel/scripts/setup_worktrees.sh

# Run the script
./.parallel/scripts/setup_worktrees.sh
```

**What this does:**
- ✅ Generates script in .parallel/scripts/ (user can modify)
- ✅ Reads task IDs from plan.yaml
- ✅ Creates worktrees/task-N directories
- ✅ Creates feature/task-N branches
- ✅ Idempotent (safe to run multiple times)
- ✅ Works with or without yq installed

---

## Phase 1: Extract and Load Plan

**IMPORTANT:** This phase runs the extraction script FIRST to check for plans in the current conversation.

---

### Step 1: Run Extraction Script (PRIMARY PATH)

**Always run this first - it's safe and fast (~500ms):**

```bash
./scripts/extract-current-plan.sh
```

**The script will:**
- Search current session for plan markers (`**Type:** Plan`)
- Extract plan and tasks if found
- Create `.parallel/plans/plan.yaml` and `tasks/*.md`
- Output "✅ Extraction complete!" on success
- Output "❌ Error: No plan found" if no plan in conversation

**Possible outcomes:**

**A) Extraction succeeds:**
```
✅ Created .parallel/plans/plan.yaml
✅ Created task files in .parallel/plans/tasks/
✅ Extraction complete!
```
→ Continue to Step 3 (load the plan)

**B) Plan already exists:**
```
Error: .parallel/plans/plan.yaml already exists
```
→ Continue to Step 2 (check existing)

**C) No plan in conversation:**
```
❌ Error: No plan found in transcript
```
→ Continue to Step 2 (check existing)

---

### Step 2: Check for Existing Plan (MULTI-SESSION PATH)

**Only reached if Step 1 didn't find/extract a plan**

Check if a plan.yaml already exists from a previous session:

```bash
ls .parallel/plans/plan.yaml 2>/dev/null && echo "✅ Found existing plan" || echo "❌ No plan exists"
```

**Possible outcomes:**

**A) Plan exists:**
```
✅ Found existing plan
```
→ This is from a previous session
→ Continue to Step 3 (load it)

**B) No plan exists:**
```
❌ No plan exists
```
→ No plan in conversation AND no saved plan
→ Continue to Step 4 (ask user)

---

### Step 3: Load and Validate Plan

**Now read the plan.yaml file (either just extracted or from previous session):**

```bash
# Read the plan
cat .parallel/plans/plan.yaml
```

**Validate the plan has required structure:**
- ✅ `metadata:` section with name, status
- ✅ `tasks:` array with at least one task
- ✅ Each task has: id, name, file, priority, dependencies

**For each task in the plan:**
- Read task metadata from plan.yaml (id, name, priority, dependencies)
- Sort tasks by priority: blocker → high → medium → low
- Build execution graph based on dependencies

**Context Optimization:**
- ✅ If tasks were just extracted → Already in context (0 tokens!)
- ✅ If new session → Will read task files when spawning agents
- ✅ Only read what's needed, when it's needed

**Plan loaded and validated → Continue to Phase 2 (setup worktrees)**

---

### Step 4: No Plan Found (ASK USER)

**Only reached if both Step 1 and Step 2 failed**

Tell the user:

```
❌ No plan found in conversation or filesystem.

To create a plan, run: /ctx:plan

Then re-run /ctx:execute to start parallel execution.
```

**Do NOT proceed to Phase 2 without a valid plan.**

---

**Plan validation:**
- plan.yaml exists and has valid YAML syntax
- All referenced task files exist
- Each task has: id, priority, objective, files, acceptance criteria
- No circular dependencies
- Task IDs in plan.yaml match task IDs in task files

**Status filtering:**
- Read each task file's YAML frontmatter to check status
- Skip tasks with status: completed
- Only execute tasks with status: pending or blocked
- Report which tasks are being executed vs skipped

**If validation fails:**
- Report specific issues to user (missing files, syntax errors, circular deps, etc.)
- Suggest running `/contextune:parallel:plan` to create proper plan

---

## Phase 2: Spawn Autonomous Haiku Agents (PARALLEL) ⚡

**IMPORTANT:** This is where the optimization happens! We use specialized Haiku agents for 85% cost savings and 2x speedup.

**Three-Tier Architecture in Action:**
- **Tier 1** (You - Sonnet): Orchestration and planning
- **Tier 2** (Haiku): Autonomous task execution
- **Result**: 81% cost reduction, 2x performance improvement

### 🔍 Script-Based Setup = True Determinism (v0.5.5)

**Key architectural decision:** Worktrees are **pre-created by script** before agents spawn!

**Why this matters:**
- ✅ **Deterministic:** Script creates all worktrees reliably (no AI unpredictability)
- ✅ **Fast:** 5 seconds total for any number of tasks (parallel xargs)
- ✅ **Simple agents:** Agents focus only on implementation, not infrastructure
- ✅ **Smaller prompts:** 33% reduction in agent context (no setup instructions)

**Performance:**
```
Old approach (agents create own worktrees):
5 tasks: 73s total (8s setup per agent in parallel)

New approach (script pre-creates worktrees):
5 tasks: 5s setup + work time (deterministic!)

Time saved: 68s (93% faster setup)
```

**Observability via Git + PRs:**
- Each task has its own task file (.parallel/plans/active/tasks/task-N.md)
- Each task has its own git branch (atomic changes, easy rollback)
- Each task has its own worktree (isolated environment)
- Each task gets a PR created from task file (full spec + implementation)
- All visible in `git worktree list`, `gh pr list`, git history

**For each independent task in the plan:**

Spawn a `parallel-task-executor` Haiku agent. Each agent receives:

### 🎯 v0.4.0: Context-Grounded Execution (Zero Research!)

**IMPORTANT:** If using Contextune v0.4.0+ with context-grounded research:

✅ **All research was ALREADY done during planning!**
- Web searches for best practices (2025, not 2024!)
- Library comparisons and recommendations
- Codebase pattern searches
- Specification validation
- Dependency analysis

✅ **The specifications you receive are COMPLETE and GROUNDED:**
- Based on current date and tech stack
- Follows existing specifications
- Reuses existing code patterns
- Uses compatible dependencies
- Follows proven best practices from 2025

✅ **Your job is EXECUTION ONLY:**
- Read the specification
- Execute EXACTLY as specified
- Do NOT research alternatives
- Do NOT make architectural decisions
- Do NOT search for different libraries
- If ANYTHING is unclear → ASK, don't guess!

**Why this matters:**
The planning phase (Sonnet) already did comprehensive parallel research. You (Haiku) are optimized for fast, accurate execution of well-defined tasks. Trust the plan!

**Cost savings:**
- Planning (Sonnet + research): $0.20
- Your execution (Haiku): $0.04 per task
- If you re-research: Wastes time and money!

---

### Subagent Instructions Template

```
You are Subagent working on: {task.name}

**Task Reference:** .parallel/plans/tasks/{task.id}.md (Markdown + YAML frontmatter)
**Plan Reference:** .parallel/plans/plan.yaml

**IMPORTANT:** Your task file is in Markdown with YAML frontmatter containing your complete specification.

**Quick Reference:**
- Priority: {task.priority}
- Dependencies: {task.dependencies}

**Your Complete Task Specification:**

Read your task file for all details:
```bash
cat .parallel/plans/tasks/{task.id}.md
```

The file contains:
- 🎯 Objective
- 🛠️ Implementation Approach (libraries, patterns to follow)
- 📁 Files to Touch (create/modify/delete)
- 🧪 Tests Required (unit/integration)
- ✅ Acceptance Criteria
- ⚠️ Potential Conflicts
- 📝 Notes

---

## YOUR COMPLETE WORKFLOW

### Phase 1: Setup Your Environment (Do This First!)

**Step 0: Mark Task as In Progress**

Update the task status in plan.yaml to track that you're starting work:

```bash
# Update task status to in_progress
TASK_FILE=".parallel/plans/active/tasks/{task.id}.md"

# Use sed to update status field in YAML frontmatter
sed -i.bak 's/^status: pending$/status: in_progress/' "$TASK_FILE"

# Verify the update
echo "✅ Task status updated to in_progress"
```

**Step 1: Navigate to Your Worktree**

Your worktree and branch were already created by the setup script!

```bash
# Navigate to your worktree
cd worktrees/{task.id}

# Verify you're in the right place
echo "Current branch: $(git branch --show-current)"
echo "Expected branch: feature/{task.id}"
```

**Step 2: Setup Development Environment**

```bash
# Copy environment files if they exist
cp ../../.env .env 2>/dev/null || true
cp ../../.env.local .env.local 2>/dev/null || true

# Install dependencies (adjust based on project type)
{project_setup_commands}

# Example for Node.js:
# npm install

# Example for Python:
# uv sync

# Example for Rust:
# cargo build
```

**Verify setup:**
```bash
# Run a quick test to ensure environment works
{project_verify_command}

# Example: npm run typecheck
# Example: uv run pytest --collect-only

# Log that setup is complete
echo "✅ Environment setup complete, starting implementation..."
```

---

### Phase 2: Implement the Feature

**Read your task file for complete details:**

```bash
cat .parallel/plans/tasks/{task.id}.md
```

**Your task file is in Markdown with YAML frontmatter:**
- **Frontmatter**: Contains id, priority, status, dependencies, labels
- **Body**: Contains objective, approach, libraries, files, tests, acceptance criteria

**Follow the implementation approach specified in the task:**
- Approach: {From "## 🛠️ Implementation Approach" section}
- Libraries: {From "**Libraries:**" section}
- Patterns: {From "**Pattern to follow:**" section}

**Detailed implementation steps:**

{Generate steps based on task.objective, task.files, and task.implementation}

**🎯 EXECUTION-ONLY Guidelines (v0.4.0):**

**DO (Execute as specified):**
- ✅ Follow the specification EXACTLY
- ✅ Use the libraries/tools specified in the plan
- ✅ Implement the patterns specified in the plan
- ✅ Follow existing code patterns and conventions
- ✅ Write tests as specified
- ✅ Keep commits atomic and descriptive
- ✅ Run linter/formatter before committing

**DON'T (No research, no decisions):**
- ❌ Research alternative approaches (already done in planning!)
- ❌ Choose different libraries (planning chose the best one!)
- ❌ Make architectural decisions (planning made them!)
- ❌ Search for "better" patterns (planning found them!)
- ❌ Second-guess the specification

**IF UNCLEAR:**
- ⚠️ Specification is ambiguous → Report back to main agent
- ⚠️ Implementation detail missing → Ask for clarification
- ⚠️ Library doesn't work as expected → Report to main agent
- ⚠️ Tests are unclear → Request test specification

**Remember:** All research was done. All decisions were made. You execute!

**Commit messages should follow:**
```
{type}: {brief description}

{detailed explanation if needed}

Implements: {task.id}

🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
```

---

### Phase 3: Test Your Work

**Run all relevant tests:**

```bash
# Unit tests
{unit_test_command}

# Integration tests (if applicable)
{integration_test_command}

# Linting
{lint_command}

# Type checking
{typecheck_command}
```

**All tests MUST pass before pushing!**

If tests fail:
1. Fix the issues
2. Re-run tests
3. Update GitHub issue with status

---

### Phase 4: Push and Report

**Push your branch:**

Use git push (single command is OK per DRY strategy):

```bash
git push origin "feature/{task.id}"
```

**Note:** If you need commit + push workflow, use `../../scripts/commit_and_push.sh` instead.

**Log completion:**

```bash
echo "✅ Task {task.id} completed and pushed!"
echo ""
echo "Branch: feature/{task.id}"
echo "Commits: $(git log --oneline origin/main..HEAD | wc -l)"
echo ""
echo "Files changed:"
git diff --name-only origin/main..HEAD
echo ""
echo "Ready for PR creation!"
```

---

### Phase 5: Report Back to Main Agent

**Step 1: Mark Task as Completed**

Update the task status to reflect successful completion:

```bash
# Update task status to completed
TASK_FILE=".parallel/plans/active/tasks/{task.id}.md"

# Use sed to update status field in YAML frontmatter
sed -i.bak 's/^status: in_progress$/status: completed/' "$TASK_FILE"

# Verify the update
echo "✅ Task status updated to completed"
```

**Step 2: Return to main agent with:**

```
✅ Task completed successfully!

**Task ID:** {task.id}
**Branch:** feature/{task.id}
**Worktree:** worktrees/{task.id}
**Tests:** All passing ✅
**Status:** Ready for PR

**Summary:** {brief summary of what was implemented}
```

---

## RULES FOR SUBAGENTS

1. ✅ **Autonomy:** Your worktree is pre-created, focus on implementation
2. ✅ **Isolation:** Work only in your assigned worktree directory
3. ✅ **Testing:** All tests must pass before reporting completion
4. ✅ **Status Tracking:** Update task status at key points:
   - Start: pending → in_progress
   - Success: in_progress → completed
   - Error: * → blocked
5. ❌ **No touching main:** Never commit directly to main branch
6. ❌ **No touching other worktrees:** Stay in your assigned directory
7. ⚠️ **Report conflicts:** If you encounter merge conflicts, report to main agent
8. 🎯 **EXECUTE ONLY (v0.4.0):** Follow spec exactly, no research, no decisions
9. ⚠️ **Ask if unclear:** Specification ambiguous? Report to main agent, don't guess!
10. 📝 **Document in commits:** Write clear commit messages explaining what/why

### 🔍 Git + Task Files + PRs = Observability (v0.5.5)

**Why this architecture provides excellent observability:**

**Task Files (.parallel/plans/active/tasks/task-N.md):**
- Version-controlled specifications
- Status tracking (pending/in_progress/completed/blocked)
- Complete implementation details
- Acceptance criteria
- Single source of truth

**Git Branches:**
- Atomic changes per task
- Easy to review (one feature per branch)
- Safe to rollback (branch isolation)
- Clear attribution (who did what)
- Parallel history (no conflicts in main)

**Git Worktrees:**
- Isolated environments
- No context switching overhead
- Visible in `git worktree list`
- Independent test runs
- No shared state issues

**Pull Requests:**
- Full specification (from task file)
- Complete implementation (git diff)
- Review comments and discussion
- CI/CD integration
- Merge history

**Observability Commands:**
```bash
# See task status
grep "^status:" .parallel/plans/active/tasks/*.md

# See all active parallel work
git worktree list
git branch | grep feature/task

# See progress on specific task
cat .parallel/plans/active/tasks/task-0.md
cd worktrees/task-0
git log --oneline

# See what changed in a task
cd worktrees/task-0
git diff origin/main..HEAD

# See PRs
gh pr list --head feature/task-0

# See all completed tasks
grep "status: completed" .parallel/plans/active/tasks/*.md
```

**Benefits:**
- ✅ No duplication (task files = single source of truth)
- ✅ Version controlled (all specs in git history)
- ✅ Easy debugging (git history + task files)
- ✅ Portable (works offline, survives GitHub → GitLab)
- ✅ Audit trail (compliance, security, learning)

---

## ERROR HANDLING

**If worktree navigation fails:**
- Verify worktree exists: `git worktree list`
- Report to main agent (worktree should have been pre-created by script)

**If tests fail:**
- Do NOT push failing code
- Mark task as blocked:
  ```bash
  TASK_FILE=".parallel/plans/active/tasks/{task.id}.md"
  sed -i.bak 's/^status: .*$/status: blocked/' "$TASK_FILE"
  ```
- Report exact error messages to main agent
- Request help if blocked

**If environment setup fails:**
- Document exact error message
- Check for missing dependencies
- Mark task as blocked:
  ```bash
  TASK_FILE=".parallel/plans/active/tasks/{task.id}.md"
  sed -i.bak 's/^status: .*$/status: blocked/' "$TASK_FILE"
  ```
- Report to main agent for project-specific guidance

**If implementation is unclear:**
- Mark task as blocked:
  ```bash
  TASK_FILE=".parallel/plans/active/tasks/{task.id}.md"
  sed -i.bak 's/^status: .*$/status: blocked/' "$TASK_FILE"
  ```
- Report specific questions to main agent
- Do NOT guess or make assumptions

---

End of subagent instructions.
```

### Spawning Haiku Agents (Implementation)

**Use the Task tool with `parallel-task-executor` agent:**

For each task in the YAML plan, create a Task tool invocation with:
- `description`: "{task.name}"
- `prompt`: The complete subagent instructions template above (filled with task-specific YAML values)
- `subagent_type`: "contextune:parallel-task-executor" (Haiku agent)

**Load task data with context optimization:**

```python
import yaml

# Step 1: Read plan.yaml index
with open('.parallel/plans/plan.yaml') as f:
    plan = yaml.safe_load(f)

# Step 2: For each task in index
for task_ref in plan['tasks']:
    task_id = task_ref['id']
    task_name = task_ref['name']  # Name from index!
    task_file = task_ref['file']
    task_priority = task_ref['priority']
    task_dependencies = task_ref.get('dependencies', [])

    # Step 3: Context optimization decision
    # Question: Is task file already in context?
    # Answer: YES if created in this session, NO if reading from disk

    # If NOT in context → read task file
    # If IN context → skip read, use existing context!

    # For now, read task file when spawning agent
    # (Haiku will use it directly for GitHub issue creation)
    with open(f'.parallel/plans/{task_file}') as f:
        task_content = f.read()

    # Fill template with data from INDEX (not full task file!)
    # Haiku agent will read full task file for implementation details
    prompt = subagent_template.format(
        task_id=task_id,
        task_name=task_name,  # From index!
        task_priority=task_priority,  # From index!
        task_dependencies=', '.join(task_dependencies)  # From index!
    )

    # Spawn agent with minimal prompt
    # Agent reads tasks/task-N.md for complete spec
    Task(
        description=task_name,
        prompt=prompt,
        subagent_type="contextune:parallel-task-executor"
    )
```

**Context Optimization Benefits:**
- ✅ **Index-first approach**: Get task names, priorities from plan.yaml (1K tokens)
- ✅ **Lazy loading**: Only read task files when spawning agents
- ✅ **Same-session optimization**: If tasks just created → already in context!
- ✅ **Minimal prompt**: Agent gets id, name, priority from index
- ✅ **Agent reads full spec**: Haiku reads tasks/task-N.md for details
- ✅ **Zero transformation**: Task file used directly for GitHub issue (~500 tokens saved per task)

**CRITICAL:** Spawn ALL agents in a SINGLE response using multiple Task tool invocations. This ensures parallel execution from the start.

---

### Context Optimization: Same Session vs New Session

**Same Session (Plan just created):**
```
1. User runs /contextune:parallel:plan
2. Planning agent creates:
   - plan.yaml (in context)
   - tasks/task-0.md (in context)
   - tasks/task-1.md (in context)
   - tasks/task-2.md (in context)
3. User runs /contextune:parallel:execute
4. Execution agent:
   - Reads plan.yaml (~1K tokens)
   - Tasks ALREADY in context (0 tokens!)
   - Total: 1K tokens ✅

Savings: Massive! No re-reading task files.
```

**New Session (Reading from disk):**
```
1. User runs /contextune:parallel:execute (new session)
2. Execution agent:
   - Reads plan.yaml index (~1K tokens)
   - Sees task-0, task-1, task-2 in index
   - Reads task-0.md when spawning agent (~3K tokens)
   - Reads task-1.md when spawning agent (~3K tokens)
   - Reads task-2.md when spawning agent (~3K tokens)
   - Total: ~10K tokens

Still optimized: Only reads what's needed, when it's needed.
```

**Key Insight:** plan.yaml acts as lightweight index/TOC. Model decides when to read full task files based on context availability.

---

**Cost Tracking:**
Each Haiku agent costs ~$0.04 per task execution (vs $0.27 Sonnet - **85% savings!**)

For 5 parallel tasks:
- **Old (All Sonnet):** 5 × $0.27 = $1.35
- **New (Haiku Agents):** 5 × $0.04 = $0.20
- **Savings:** $1.15 per workflow (85% reduction!)

**Example for 3 tasks:**

```
[Single response with 3 Task tool calls using parallel-task-executor agent]
Task 1: Implement authentication (Haiku agent - $0.04)
Task 2: Build dashboard UI (Haiku agent - $0.04)
Task 3: Add analytics tracking (Haiku agent - $0.04)
Total cost: $0.12 (vs $0.81 Sonnet - 85% savings!)
```

All 3 Haiku agents start simultaneously in their pre-created worktrees! ⚡

---

## Phase 4: Monitor Progress (Optional)

**While subagents are working:**

Users can check progress at any time with:

```bash
/contextune:parallel:status
```

This will show:
- Active worktrees and their branches
- Task status (from YAML frontmatter)
- Test results (if available)
- Estimated completion

**Main agent responsibilities during monitoring:**
- Respond to subagent questions
- Resolve conflicts if subagents report issues
- Coordinate shared resource access if needed

---

## Phase 5: Handle Subagent Completion

**As each subagent completes:**

1. **Verify completion:**
   - Check task status is "completed" in task file
   - Verify branch is pushed
   - Confirm tests are passing

2. **Review changes:**
   ```bash
   # Check task status
   grep "^status:" .parallel/plans/active/tasks/task-*.md

   # Switch to completed worktree
   cd worktrees/task-0

   # Review diff
   git diff origin/main..HEAD
   ```

3. **Prepare for merge:**
   - Document what was completed
   - Note any conflicts or issues
   - Track completion in main agent's todo list

---

## Phase 6: Create Pull Requests

**Generate and run the PR creation script:**

```bash
# Generate PR creation script
cat > .parallel/scripts/create_prs.sh <<'PR_SCRIPT'
#!/usr/bin/env bash
set -euo pipefail

BASE_BRANCH="${1:-main}"
TASKS_DIR=".parallel/plans/active/tasks"

echo "Creating PRs for completed tasks..."

# Find completed tasks
for task_file in "$TASKS_DIR"/task-*.md; do
  [ -f "$task_file" ] || continue

  status=$(grep "^status:" "$task_file" | head -1 | awk '{print $2}')
  [ "$status" = "completed" ] || continue

  task_id=$(basename "$task_file" .md)
  branch="feature/$task_id"
  title=$(grep "^# " "$task_file" | head -1 | sed 's/^# //')
  labels=$(awk '/^labels:/,/^[a-z]/ {if ($0 ~ /^\s*-/) print $2}' "$task_file" | tr '\n' ',' | sed 's/,$//')

  # Check if PR exists
  if gh pr list --head "$branch" --json number -q '.[0].number' &>/dev/null; then
    echo "⚠️  PR exists for $task_id"
    continue
  fi

  # Create PR
  if [ -n "$labels" ]; then
    gh pr create --base "$BASE_BRANCH" --head "$branch" --title "$title" --body-file "$task_file" --label "$labels"
  else
    gh pr create --base "$BASE_BRANCH" --head "$branch" --title "$title" --body-file "$task_file"
  fi

  echo "✅ Created PR for $task_id: $title"
done

echo ""
echo "✅ PR creation complete!"
PR_SCRIPT

chmod +x .parallel/scripts/create_prs.sh

# Run the script
./.parallel/scripts/create_prs.sh
```

**What this does:**
- ✅ Generates script in .parallel/scripts/ (user can modify)
- ✅ Finds all tasks with status: completed
- ✅ Extracts title from task file (first # heading)
- ✅ Creates PR with task file as body (zero transformation!)
- ✅ Adds labels from task YAML frontmatter
- ✅ Links PR to task via branch name

**Alternative: Merge Directly (No Review Needed)**

If you don't need PR reviews, use the merge script:

```bash
# For each completed task:
./scripts/merge_and_cleanup.sh task-0 "Fix missing utils module"
```

**Script handles:**
- ✅ Checkout and pull main
- ✅ Merge with --no-ff
- ✅ Push to remote
- ✅ Automatic conflict detection
- ✅ Error recovery with Haiku

**Choose based on project workflow:**
- **PRs:** Code review, CI/CD, team visibility
- **Direct merge:** Solo dev, fast iteration, no review needed

---

## Phase 6.5: Merge Completed Tasks (Direct Merge Workflow)

**IMPORTANT:** If you chose direct merge (no PRs), use the merge script with smart error recovery!

**For EACH completed task, use smart_execute wrapper:**

```bash
# Merge task-0 with AI error recovery
./scripts/smart_execute.sh ./scripts/merge_and_cleanup.sh task-0 "Review CRUD endpoints"

# Merge task-1 with AI error recovery
./scripts/smart_execute.sh ./scripts/merge_and_cleanup.sh task-1 "Paper CSV import"

# Merge task-2 with AI error recovery
./scripts/smart_execute.sh ./scripts/merge_and_cleanup.sh task-2 "Paper listing endpoint"

# Merge task-3 with AI error recovery
./scripts/smart_execute.sh ./scripts/merge_and_cleanup.sh task-3 "Database-first workflow"
```

**Why use smart_execute.sh wrapper:**
- ✅ Automatic error detection
- ✅ Haiku tries to fix errors first ($0.001, 70-80% success rate)
- ✅ Copilot escalation if Haiku fails ($0.10, 90-95% success rate)
- ✅ Only escalates to you (Claude) if both AI layers fail
- ✅ 99.9% automatic recovery rate

**Error recovery cascade:**
```
Script executes → Error?
  ├─ NO → Success ✅
  └─ YES → Haiku analyzes error
      ├─ Fixed → Success ✅ (70-80% of errors)
      └─ Still failing → Copilot escalates
          ├─ Fixed → Success ✅ (90-95% of remaining)
          └─ Still failing → Escalate to you (Claude main session)
```

**What the merge script does:**
```bash
# For each task:
1. git checkout main (or specified branch)
2. git pull origin main (get latest)
3. git merge --no-ff feature/task-N -m "Merge branch 'feature/task-N'"
4. git push origin main
5. git branch -d feature/task-N (delete local)
6. git push origin --delete feature/task-N (delete remote)
7. Clean up worktree
```

**NEVER use manual git commands for merging!** The script:
- ✅ Handles conflicts automatically
- ✅ Ensures you're on main before merging
- ✅ Pulls latest changes first
- ✅ Uses proper merge message format
- ✅ Cleans up after merge
- ✅ Single command per task

**If merge conflicts occur:**

The script will detect and report conflicts. Then:

```bash
# Script stops at conflict - resolve manually
git status  # See conflicted files

# Edit files to resolve conflicts
# Then:
git add <resolved-files>
git commit  # Complete the merge
git push origin main

# Clean up manually
git worktree remove worktrees/task-N
git branch -d feature/task-N
```

**Token efficiency:**
- Multi-command approach: ~15-20 commands = 8K-12K tokens
- Script approach: 4 commands (one per task) = ~2K tokens
- **Savings:** 75-85% reduction

---

## Phase 7: Verify Integration

**After merging all tasks:**

1. **Run full test suite on main:**
   ```bash
   git checkout main
   {full_test_command}
   ```

2. **Check for integration issues:**
   - Do all features work together?
   - Are there any unexpected interactions?
   - Performance regressions?

3. **Fix any integration bugs:**
   - Create new issues for bugs found
   - Fix directly on main (small fixes)
   - Or create hotfix branches (larger fixes)

---

## Phase 8: Cleanup

**Clean up completed worktrees:**

```bash
# Use the cleanup command
/contextune:parallel:cleanup
```

**The command handles:**
- ✅ Removes all completed worktrees
- ✅ Deletes merged branches
- ✅ Prunes stale references
- ✅ Safety checks (won't delete unmerged work)
- ✅ Atomic operations (all or nothing)

**Archive the plan:**

```bash
# Move timestamped plan to archive
mkdir -p .parallel/archive
mv .parallel/plans/20251025-042057 .parallel/archive/

# Or keep it for reference (plans are lightweight)
# Plans with status tracking are useful for future reference
```

---

## Phase 9: Report to User

**Provide comprehensive summary with cost tracking:**

```
✅ Parallel execution complete!

**Task Status Summary:**
- ✅ Completed: {N} tasks
- ⚠️ Blocked: {M} tasks (if any)
- ⏳ In Progress: {P} tasks (if any)
- 📋 Pending: {Q} tasks (if any)

**Tasks Completed:** {N} / {Total}
**Actual Wall-Clock Time:** {actual_time} (measured)
**Speedup Factor:** {speedup_factor}x (calculated from actuals)
**Token Usage:** {total_tokens} tokens
**Actual Cost:** ${cost}

**Note:** All metrics shown are ACTUAL measurements from this workflow.
Future workflows may vary based on task complexity and dependencies.

**Merged Branches:**
- feature/task-0: {task 0 title}
- feature/task-1: {task 1 title}
- feature/task-2: {task 2 title}

**Test Results:**
- ✅ All unit tests passing
- ✅ All integration tests passing
- ✅ Linter passing
- ✅ Type checker passing

**Pull Requests:**
- Created: #{PR_NUM1}, #{PR_NUM2}, #{PR_NUM3}

**💰 Cost Savings (Haiku Optimization):**
```
┌─────────────────────────────────────────────────┐
│ Cost Comparison: Sonnet vs Haiku Agents        │
├─────────────────────────────────────────────────┤
│ Scenario 1: All Sonnet Agents                  │
│   Main agent (planning):        $0.054         │
│   {N} execution agents:         ${N × 0.27}    │
│   Total:                        ${total_sonnet}│
├─────────────────────────────────────────────────┤
│ Scenario 2: Haiku Agents (ACTUAL) ✨           │
│   Main agent (planning):        $0.054         │
│   {N} Haiku agents:             ${N × 0.04}    │
│   Total:                        ${total_haiku} │
├─────────────────────────────────────────────────┤
│ 💵 This Workflow Saved:         ${savings}     │
│ 📊 Cost Reduction:              {percentage}%  │
│ ⚡ Speed Improvement:           ~2x faster     │
└─────────────────────────────────────────────────┘

Annual projection (1,200 workflows):
  • Old cost (Sonnet): ${total_sonnet × 1200}
  • New cost (Haiku):  ${total_haiku × 1200}
  • Annual savings:    ${savings × 1200} 💰
```

**Next Steps:**
- [ ] Review merged code
- [ ] Deploy to staging
- [ ] Update documentation
- [ ] Announce to team

**Cleanup:**
- Worktrees removed: {N}
- Branches deleted: {N}
- Plan archived: .parallel/archive/20251025-042057/

🎉 All tasks completed successfully via Contextune parallel execution!
🚀 Powered by Script-Based Setup + Context-Grounded Research v0.5.5
✨ Scripts handle infrastructure, Haiku agents execute blindly
```

**Calculate Cost Savings:**

Use this formula to calculate actual costs:

```python
# Cost per agent (Claude pricing as of Oct 2024)
SONNET_INPUT_COST = 3.00 / 1_000_000   # $3/MTok
SONNET_OUTPUT_COST = 15.00 / 1_000_000  # $15/MTok
HAIKU_INPUT_COST = 0.80 / 1_000_000     # $0.80/MTok
HAIKU_OUTPUT_COST = 4.00 / 1_000_000    # $4/MTok

# Average tokens per agent
MAIN_AGENT_INPUT = 18_000
MAIN_AGENT_OUTPUT = 3_000
EXECUTION_AGENT_INPUT_SONNET = 40_000
EXECUTION_AGENT_OUTPUT_SONNET = 10_000
EXECUTION_AGENT_INPUT_HAIKU = 30_000
EXECUTION_AGENT_OUTPUT_HAIKU = 5_000

# Calculate costs
main_cost = (MAIN_AGENT_INPUT * SONNET_INPUT_COST +
             MAIN_AGENT_OUTPUT * SONNET_OUTPUT_COST)

sonnet_agent_cost = (EXECUTION_AGENT_INPUT_SONNET * SONNET_INPUT_COST +
                     EXECUTION_AGENT_OUTPUT_SONNET * SONNET_OUTPUT_COST)

haiku_agent_cost = (EXECUTION_AGENT_INPUT_HAIKU * HAIKU_INPUT_COST +
                    EXECUTION_AGENT_OUTPUT_HAIKU * HAIKU_OUTPUT_COST)

# Total costs
num_tasks = len(completed_tasks)
total_sonnet = main_cost + (num_tasks * sonnet_agent_cost)
total_haiku = main_cost + (num_tasks * haiku_agent_cost)
savings = total_sonnet - total_haiku
percentage = (savings / total_sonnet) * 100

# Format nicely
print(f"This workflow saved: ${savings:.2f} ({percentage:.0f}% reduction)")
```

---

## Contextune Integration

### Natural Language Triggers

Users can trigger this command with:
- `/contextune:parallel:execute` (explicit)
- "work on X, Y, Z in parallel"
- "parallelize these tasks"
- "execute parallel development"
- "run these in parallel"

Contextune automatically detects these intents and routes to this command.

### Global Availability

This command works in ALL projects after installing Contextune:

```bash
/plugin install slashsense
```

No project-specific configuration needed.

### Related Commands

When suggesting next steps, mention:
- `/contextune:parallel:status` - Monitor progress
- `/contextune:parallel:cleanup` - Clean up completed work
- `/contextune:parallel:plan` - Create development plan

---

## Performance Comparison

### v0.4.0: Agents Create Own Worktrees

```
Time Analysis for 5 tasks:
Planning:                            60s
Spawn 5 agents:                       5s
Each agent creates issue + worktree:  8s (concurrent!) ⚡
──────────────────────────────────────────
Total Setup:                         73s
Work time:                           Parallel ✅
```

### v0.5.5: Script Pre-Creates Worktrees (CURRENT)

```
Time Analysis for 5 tasks:
Planning:                              60s
Run setup_worktrees.sh:                 5s (all 5 in parallel!)
Spawn 5 agents:                         5s
──────────────────────────────────────────
Total Setup:                           70s
Work time:                             Parallel ✅

Time Saved: 3 seconds (4% faster)
```

**But more importantly:**
- ✅ **Deterministic:** Script always works the same way
- ✅ **Simpler agents:** 33% less context (no setup instructions)
- ✅ **No duplication:** Task files are single source of truth
- ✅ **Cheaper:** Smaller agent prompts = lower costs per task

---

## Example User Interactions

**Natural Language:**
```
User: "work on auth, dashboard, and analytics in parallel"

You: Analyzing request... detected 3 independent tasks.

Creating parallel execution plan...
✅ Plan created: .parallel/plans/20251021-143000/

Setting up infrastructure...
✅ Created 3 worktrees in 5 seconds (script)

Spawning 3 autonomous Haiku agents...
🚀 Agent 1: Auth implementation (worktrees/task-0)
🚀 Agent 2: Dashboard UI (worktrees/task-1)
🚀 Agent 3: Analytics tracking (worktrees/task-2)

[Agents work concurrently in pre-created worktrees]

✅ All tasks completed with parallel execution
Token efficiency: Significant reduction vs sequential approach

Creating PRs...
✅ 3 PRs created from task files

Triggered via Contextune natural language detection.
```

**Explicit Command:**
```
User: "/contextune:parallel:execute"

You: [Load existing plan or ask for task list]
     [Execute full parallel workflow as above]
```

---

## Troubleshooting

**Issue: "Worktree already exists"**
- Run: `git worktree list` to see active worktrees
- Remove stale: `git worktree remove worktrees/task-0`
- Or run: `/contextune:parallel:cleanup`

**Issue: "Setup script failed"**
- Check: `git --version` (need 2.5+ for worktree support)
- Check: Permissions on `.parallel/plans/active/scripts/`
- Run: `chmod +x .parallel/plans/active/scripts/setup_worktrees.sh`

**Issue: "Tests failing in subagent"**
- Subagent should report back to main agent
- Check task status: `grep "^status:" .parallel/plans/active/tasks/task-*.md`
- Review git log in worktree for error context
- Main agent provides guidance

**Issue: "Merge conflicts"**
- Expected with shared files
- Subagents should rebase before final push
- Main agent resolves during merge phase

**Issue: "Subagent not responding"**
- Check Claude Code UI for subagent status
- Review subagent's last output
- May need to restart subagent

---

## Implementation Notes

- Uses optimized parallel setup (agents create own issues/worktrees)
- Uses Haiku agents for 85% cost savings and 2x speedup
- Fully autonomous agents reduce coordination overhead
- Setup time is O(1) regardless of task count
- Works identically across all projects (global availability)
- Follows git best practices (feature branches, worktrees, atomic commits)

---

## Specialized Haiku Agents

Contextune v0.3.0 includes specialized Haiku agents for specific operations. Use them when you need focused capabilities:

### 1. parallel-task-executor
**Use for:** Complete feature implementation from start to finish

**Capabilities:**
- Creates GitHub issue and worktree
- Implements features
- Runs tests
- Pushes code and reports

**Cost:** ~$0.04 per task
**When to use:** Default agent for all parallel task execution

### 2. worktree-manager
**Use for:** Git worktree lifecycle management

**Capabilities:**
- Create worktrees with safety checks
- Diagnose worktree issues
- Remove and cleanup worktrees
- Handle lock files
- Bulk operations

**Cost:** ~$0.008 per operation
**When to use:** Troubleshooting worktree issues, bulk cleanup, advanced worktree operations

**Example:**
```bash
# Use directly for troubleshooting
Task tool with subagent_type: "contextune:worktree-manager"
Prompt: "Diagnose and fix worktree lock files in .git/worktrees/"
```

### 3. issue-orchestrator
**Use for:** GitHub issue management

**Capabilities:**
- Create issues with templates
- Update and comment on issues
- Manage labels
- Link issues to PRs
- Bulk operations

**Cost:** ~$0.01 per operation
**When to use:** Bulk issue creation, issue management automation, complex labeling

**Example:**
```bash
# Use directly for bulk operations
Task tool with subagent_type: "contextune:issue-orchestrator"
Prompt: "Create 10 issues from this task list and label them appropriately"
```

### 4. test-runner
**Use for:** Autonomous test execution and reporting

**Capabilities:**
- Run unit/integration/E2E tests
- Generate test reports
- Create issues for failures
- Track coverage
- Multi-language support (Python, JS/TS, Rust, Go)

**Cost:** ~$0.02 per test run
**When to use:** Dedicated test execution, failure tracking, CI/CD integration

**Example:**
```bash
# Use directly for test automation
Task tool with subagent_type: "contextune:test-runner"
Prompt: "Run full test suite and create GitHub issues for any failures"
```

### 5. performance-analyzer
**Use for:** Workflow benchmarking and optimization

**Capabilities:**
- Measure workflow timing
- Identify bottlenecks
- Calculate metrics (Amdahl's Law)
- Generate reports
- Cost analysis

**Cost:** ~$0.015 per analysis
**When to use:** Performance monitoring, optimization analysis, cost tracking

**Example:**
```bash
# Use directly for performance analysis
Task tool with subagent_type: "contextune:performance-analyzer"
Prompt: "Analyze the last 5 parallel workflows and identify bottlenecks"
```

---

## Cost Optimization Strategy

**Three-Tier Model in Practice:**

**Tier 1 - Skills (Sonnet):**
- Guidance and expertise
- User-facing explanations
- Complex reasoning
- **Cost:** 20% of total workflow

**Tier 2 - Orchestration (Sonnet - You):**
- Planning and coordination
- Breaking down tasks
- Managing agents
- **Cost:** Already included (you're the orchestrator)

**Tier 3 - Execution (Haiku):**
- Implementing features
- Running tests
- Managing infrastructure
- **Cost:** 80% of work, but Haiku = 73% cheaper!

**Result:** 81% overall cost reduction!

**Example Workflow Costs:**

**5 Parallel Tasks (Old - All Sonnet):**
```
Main agent (planning):     $0.054
5 execution agents:        $1.350 (5 × $0.27)
Total:                     $1.404
```

**5 Parallel Tasks (New - Haiku Agents):**
```
Main agent (planning):     $0.054 (Sonnet)
5 Haiku agents:            $0.220 (5 × $0.04)
Total:                     $0.274
Savings:                   $1.13 (81% reduction!)
```

**Annual Savings (1,200 workflows/year):**
```
Old cost:  $1,684/year
New cost:  $328/year
Savings:   $1,356/year (81% reduction!)
```

---

## Performance Comparison: Sonnet vs Haiku

**Response Time:**
- Haiku 4.5: ~1-2 seconds
- Sonnet 4.5: ~3-5 seconds
- **Speedup:** 2x faster

**Context Window:**
- Both: 200K tokens (same capacity)

**Quality for Execution Tasks:**
- Haiku: Excellent (well-defined workflows)
- Sonnet: Excellent (but overkill for execution)
- **Conclusion:** Use right tool for the job!

**When to Use Each:**

**Use Sonnet when:**
- Complex reasoning required
- Ambiguous requirements
- Architectural decisions
- User-facing explanations

**Use Haiku when:**
- Well-defined workflows
- Deterministic operations
- Repetitive tasks
- Infrastructure automation

---

## See Also

**Documentation:**
- `docs/HAIKU_AGENT_ARCHITECTURE.md` - Complete architecture spec
- `docs/AGENT_INTEGRATION_GUIDE.md` - Integration patterns
- `docs/COST_OPTIMIZATION_GUIDE.md` - Cost tracking and ROI

**Agent Specifications:**
- `agents/parallel-task-executor.md` - Default execution agent
- `agents/worktree-manager.md` - Worktree specialist
- `agents/issue-orchestrator.md` - GitHub issue specialist
- `agents/test-runner.md` - Test execution specialist
- `agents/performance-analyzer.md` - Performance analysis specialist

**Related Commands:**
- `/contextune:parallel:plan` - Create development plan
- `/contextune:parallel:status` - Monitor progress
- `/contextune:parallel:cleanup` - Clean up worktrees