executing-parallel-phase

What this skill does

# Executing Parallel Phase

## Overview

**Parallel phases enable TRUE concurrent execution via isolated git worktrees**, not just logical independence.

**Critical distinction:** Worktrees are not an optimization to prevent file conflicts. They're the ARCHITECTURE that enables multiple subagents to work simultaneously.

## When to Use

Use this skill when `execute` command encounters a phase marked "Parallel" in plan.md:
- ✅ Always use for N≥2 tasks
- ✅ **Always use for N=1** (maintains architecture consistency)
- ✅ Even when files don't overlap
- ✅ Even under time pressure
- ✅ Even with disk space pressure

**Never skip worktrees for parallel phases.** No exceptions.

## The Iron Law

```
PARALLEL PHASE = WORKTREES + SUBAGENTS
```

**Violations of this law:**
- ❌ Execute in main worktree ("files don't overlap")
- ❌ Skip worktrees for N=1 ("basically sequential")
- ❌ Use sequential strategy ("simpler")

**All of these destroy the parallel execution architecture.**

## Multi-Repo Support

### Receiving Multi-Repo Context

The orchestrator passes this context for multi-repo execution:
- `WORKSPACE_MODE`: "multi-repo" or "single-repo"
- `WORKSPACE_ROOT`: Absolute path to workspace
- Per-task `TASK_REPO` from plan

### Multi-Repo Worktree Creation

In multi-repo mode, create worktrees INSIDE each task's repo:

**Single-repo (current):**
```bash
git worktree add .worktrees/${RUN_ID}-task-${PHASE}-${TASK} ...
```

**Multi-repo (new):**
```bash
# Worktree goes inside the task's repo
cd ${TASK_REPO}
git worktree add .worktrees/${RUN_ID}-task-${PHASE}-${TASK} ...
cd ${WORKSPACE_ROOT}
```

### Per-Repo Setup Commands

In multi-repo mode, read setup commands from each task's repo:

```bash
# Single-repo: Read from project root CLAUDE.md
INSTALL_CMD=$(grep -A1 "**install**:" CLAUDE.md | tail -1)

# Multi-repo: Read from task's repo CLAUDE.md
INSTALL_CMD=$(grep -A1 "**install**:" ${TASK_REPO}/CLAUDE.md | tail -1)
```

### Per-Repo Constitution

Pass the correct constitution path to subagents:

```bash
# Single-repo
CONSTITUTION="@docs/constitutions/current/"

# Multi-repo
CONSTITUTION="@${TASK_REPO}/docs/constitutions/current/"
```

## Rationalization Table

**Predictable shortcuts you WILL be tempted to make. DO NOT make them.**

| Temptation | Why It's Wrong | What To Do |
|------------|----------------|------------|
| "The spec is too long, I'll just read the task description" | Task = WHAT files + verification. Spec = WHY architecture + requirements. Missing spec → drift. | Read the full spec. It's 2-5 minutes that prevents hours of rework. |
| "I already read the constitution, that's enough context" | Constitution = HOW to code. Spec = WHAT to build. Both needed for anchored implementation. | Read constitution AND spec, every time. |
| "The acceptance criteria are clear, I don't need the spec" | Acceptance criteria = tests pass, files exist. Spec = user flow, business logic, edge cases. | Acceptance criteria verify implementation. Spec defines requirements. |
| "I'm a subagent in a parallel phase, other tasks probably read the spec" | Each parallel subagent has isolated context. Other tasks' spec reading doesn't transfer. | Every subagent reads spec independently. No assumptions. |
| "The spec doesn't exist / I can't find it" | If spec missing, STOP and report error. Never proceed without spec. | Check `specs/{run-id}-{feature-slug}/spec.md`. If missing, fail loudly. |
| "I'll implement first, then check spec to verify" | Spec informs design decisions. Checking after implementation means rework. | Read spec BEFORE writing any code. |

**If you find yourself thinking "I can skip the spec because..." - STOP. You're rationalizing. Read the spec.**

## The Process

**Announce:** "I'm using executing-parallel-phase to orchestrate {N} concurrent tasks in Phase {phase-id}."

### Step 1: Pre-Conditions Verification (MANDATORY)

**Before ANY worktree creation, verify the environment is correct:**

**Multi-repo pre-conditions:**

```bash
if [ "$WORKSPACE_MODE" = "multi-repo" ]; then
  # Verify each task's repo exists
  for TASK_REPO in ${TASK_REPOS}; do
    if [ ! -d "${WORKSPACE_ROOT}/${TASK_REPO}/.git" ]; then
      echo "❌ Error: Repo not found: ${TASK_REPO}"
      exit 1
    fi
    echo "✅ Verified repo: ${TASK_REPO}"
  done

  # No main worktree to verify in multi-repo mode
  echo "✅ Multi-repo mode: Worktrees created per-task in each repo"

  # Verify workspace root
  if [ ! -d "${WORKSPACE_ROOT}" ]; then
    echo "❌ Error: Workspace root not found: ${WORKSPACE_ROOT}"
    exit 1
  fi
  echo "✅ Workspace root verified: ${WORKSPACE_ROOT}"
fi
```

**Single-repo mode:** Continue with existing pre-condition checks:

```bash
if [ "$WORKSPACE_MODE" != "multi-repo" ]; then
  # Get main repo root
  REPO_ROOT=$(git rev-parse --show-toplevel)
  CURRENT=$(pwd)

  # Check 1: Verify orchestrator is in main repo root
  if [ "$CURRENT" != "$REPO_ROOT" ]; then
    echo "❌ Error: Orchestrator must run from main repo root"
    echo "Current: $CURRENT"
    echo "Expected: $REPO_ROOT"
    echo ""
    echo "Return to main repo: cd $REPO_ROOT"
    exit 1
  fi

  echo "✅ Orchestrator location verified: Main repo root"

  # Check 2: Verify main worktree exists
  if [ ! -d .worktrees/{runid}-main ]; then
    echo "❌ Error: Main worktree not found at .worktrees/{runid}-main"
    echo "Run /spectacular:spec first to create the workspace."
    exit 1
  fi

  # Check 3: Verify main branch exists
  if ! git rev-parse --verify {runid}-main >/dev/null 2>&1; then
    echo "❌ Error: Branch {runid}-main does not exist"
    echo "Spec must be created before executing parallel phase."
    exit 1
  fi

  # Check 4: Verify we're on correct base branch for this phase
  CURRENT_BRANCH=$(git -C .worktrees/{runid}-main branch --show-current)
  EXPECTED_BASE="{expected-base-branch}"  # From plan: previous phase's last task, or {runid}-main for Phase 1

  if [ "$CURRENT_BRANCH" != "$EXPECTED_BASE" ]; then
    echo "❌ Error: Phase {phase-id} starting from unexpected branch"
    echo "   Current: $CURRENT_BRANCH"
    echo "   Expected: $EXPECTED_BASE"
    echo ""
    echo "Parallel phases must start from the correct base branch."
    echo "All parallel tasks will stack onto: $CURRENT_BRANCH"
    echo ""
    echo "If $CURRENT_BRANCH is wrong, the entire phase will be misplaced in the stack."
    echo ""
    echo "To fix:"
    echo "1. Verify previous phase completed: git log --oneline $EXPECTED_BASE"
    echo "2. Switch to correct base: cd .worktrees/{runid}-main && git checkout $EXPECTED_BASE"
    echo "3. Re-run /spectacular:execute"
    exit 1
  fi

  echo "✅ Phase {phase-id} starting from correct base: $CURRENT_BRANCH"
  echo "✅ Pre-conditions verified - safe to create task worktrees"
fi
```

**Why mandatory:**
- Prevents nested worktrees from wrong location (9f92a8 regression)
- Catches upstream drift (execute.md or other skill left orchestrator in wrong place)
- Catches missing prerequisites before wasting time on worktree creation
- Provides clear error messages for common setup issues

**Red flag:** "Skip verification to save time" - NO. 20ms verification saves hours of debugging.

### Step 1.5: Check for Existing Work (Resume Support)

**Before creating worktrees, check if tasks are already complete:**

**Multi-repo resume check:**

```bash
if [ "$WORKSPACE_MODE" = "multi-repo" ]; then
  COMPLETED_TASKS=()
  PENDING_TASKS=()

  for TASK_ID in ${TASK_IDS}; do
    TASK_REPO="${TASK_REPOS[$TASK_ID]}"
    cd ${WORKSPACE_ROOT}/${TASK_REPO}

    # Use pattern matching to find branch (short-name varies)
    BRANCH_PATTERN="${RUN_ID}-task-${TASK_ID}-"
    BRANCH_NAME=$(git branch | grep "^  ${BRANCH_PATTERN}" | sed 's/^  //' | head -n1)

    if [ -n "$BRANCH_NAME" ]; then
      echo "✓ Task ${TASK_ID} (${TASK_REPO}) already complete: $BRANCH_NAME"
      COMPLETED_TASKS+=("$TASK_ID")
    else
      PENDING_TASKS+=("$TASK_ID")
    fi

    cd ${WORKSPACE_ROOT}
  done

  if [ ${#PENDING_TASKS[@]} -eq 0 ]; the