executing-sequential-phase

What this skill does

# Executing Sequential Phase

## Overview

**Sequential phases use natural git-spice stacking in the main worktree.**

Each task creates a branch with `gs branch create`, which automatically stacks on the current HEAD. No manual stacking operations needed.

**Critical distinction:** Sequential tasks BUILD ON each other. They need integration, not isolation.

## When to Use

Use this skill when `execute` command encounters a phase marked "Sequential" in plan.md:
- ✅ Tasks must run in order (dependencies)
- ✅ Execute in existing `{runid}-main` worktree
- ✅ Trust natural stacking (no manual `gs upstack onto`)
- ✅ Stay on task branches (don't switch to base between tasks)

**Sequential phases never use worktrees.** They share one workspace where tasks build cumulatively.

## Multi-Repo Support

### Receiving Multi-Repo Context

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

### Sequential Execution Across Repos

In multi-repo mode, sequential tasks may span repos:

```
Phase 1 (sequential):
- Task 1.1: repo=shared-lib  # Shared types first
- Task 1.2: repo=backend     # Backend uses shared types
- Task 1.3: repo=frontend    # Frontend uses shared types
```

For each task, switch to that task's repo context.

### Per-Repo Worktrees

In multi-repo sequential phases:
- Each repo has its own main worktree: `{repo}/.worktrees/{runId}-main/`
- Tasks execute in their repo's worktree
- Switching tasks = switching repos (if different)

### Per-Repo Setup Commands

Read setup commands from each task's repo:

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

### Per-Repo Constitution

Pass correct constitution to subagents:

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

### Per-Repo Stacking

Sequential tasks across repos create per-repo stacks:

```
Execution order:
1. Task 1.1 (shared-lib) → creates branch in shared-lib
2. Task 1.2 (backend) → creates branch in backend
3. Task 1.3 (backend) → stacks on 1.2 in backend
4. Task 1.4 (frontend) → creates branch in frontend

Result:
- shared-lib stack: task-1-1
- backend stack: task-1-2 → task-1-3
- frontend stack: task-1-4
```

Each repo maintains its own linear stack. Cannot stack across repos.

### Single-Repo Mode (Unchanged)

All existing behavior preserved:
- Single main worktree at `.worktrees/{runId}-main/`
- Single CLAUDE.md for setup commands
- Single constitution at `@docs/constitutions/current/`
- Single linear stack of branches

## The Natural Stacking Principle

```
SEQUENTIAL PHASE = MAIN WORKTREE + NATURAL STACKING
```

**What natural stacking means:**
1. Start on base branch (or previous task's branch)
2. Create new branch with `gs branch create` → automatically stacks on current
3. Stay on that branch when done
4. Next task creates from there → automatically stacks on previous

**No manual commands needed.** The workflow IS the stacking.

## The Process

**Announce:** "I'm using executing-sequential-phase to execute {N} tasks sequentially in Phase {phase-id}."

### Step 0: Verify Orchestrator Location

**MANDATORY: Verify orchestrator is in correct location before any operations:**

**Single-repo mode:**
```bash
REPO_ROOT=$(git rev-parse --show-toplevel)
CURRENT=$(pwd)

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"
```

**Multi-repo mode:**
```bash
# Orchestrator runs from WORKSPACE_ROOT (parent of all repos)
CURRENT=$(pwd)

if [ "$CURRENT" != "$WORKSPACE_ROOT" ]; then
  echo "❌ Error: Orchestrator must run from workspace root"
  echo "Current: $CURRENT"
  echo "Expected: $WORKSPACE_ROOT"
  echo ""
  echo "Return to workspace: cd $WORKSPACE_ROOT"
  exit 1
fi

echo "✅ Orchestrator location verified: Workspace root ($WORKSPACE_MODE mode)"
```

**Why critical:**
- Orchestrator delegates work but never changes directory
- Single-repo: All operations use `git -C .worktrees/path` or `bash -c "cd path && cmd"`
- Multi-repo: All operations use `git -C {repo}/.worktrees/path` or `bash -c "cd {repo}/path && cmd"`
- This assertion catches upstream drift immediately

### Step 1: Verify Setup and Base Branch

**First, verify we're on the correct base branch for this phase:**

**Single-repo mode:**
```bash
# Get current branch in main worktree
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 "⚠️  WARNING: Phase {phase-id} starting from unexpected branch"
  echo "   Current: $CURRENT_BRANCH"
  echo "   Expected: $EXPECTED_BASE"
  echo ""
  echo "This means the previous phase ended on the wrong branch."
  echo "Possible causes:"
  echo "- Code review or quality checks switched branches"
  echo "- User manually checked out different branch"
  echo "- Resume from interrupted execution"
  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"
```

**Multi-repo mode:**

In multi-repo, base branch verification is per-repo. For each repo that has tasks in this phase:

```bash
# For each repo with tasks in this phase
for REPO in ${REPOS_IN_PHASE[@]}; do
  WORKTREE_PATH="${WORKSPACE_ROOT}/${REPO}/.worktrees/${RUN_ID}-main"

  # Check if this repo's worktree exists
  if [ ! -d "$WORKTREE_PATH" ]; then
    echo "Creating main worktree for repo: ${REPO}"
    bash <<EOF
    cd ${WORKSPACE_ROOT}/${REPO}
    git worktree add .worktrees/${RUN_ID}-main -b ${RUN_ID}-main
EOF
  fi

  # Verify branch (or create if first task in this repo)
  CURRENT_BRANCH=$(git -C "$WORKTREE_PATH" branch --show-current)
  echo "✅ Repo ${REPO} on branch: $CURRENT_BRANCH"
done
```

**Then check and install dependencies (orchestrator never cd's):**

**Single-repo mode:**
```bash
# Check if dependencies installed in main worktree
if [ ! -d .worktrees/{runid}-main/node_modules ]; then
  echo "Installing dependencies in main worktree..."
  bash <<'EOF'
  cd .worktrees/{runid}-main
  {install-command}
  {postinstall-command}
  EOF
fi
```

**Multi-repo mode:**

Setup commands are read from each task's repo CLAUDE.md. Install dependencies before executing each task:

```bash
# For each task, install dependencies in that repo's worktree
TASK_REPO="${task.repo}"
WORKTREE_PATH="${WORKSPACE_ROOT}/${TASK_REPO}/.worktrees/${RUN_ID}-main"

# Read setup commands from task's repo CLAUDE.md
if [ "$WORKSPACE_MODE" = "multi-repo" ]; then
  CLAUDE_MD_PATH="${WORKSPACE_ROOT}/${TASK_REPO}/CLAUDE.md"
else
  CLAUDE_MD_PATH="CLAUDE.md"
fi

INSTALL_CMD=$(grep -A1 "**install**:" ${CLAUDE_MD_PATH} | tail -1 | sed 's/`//g' | xargs)
POSTINSTALL_CMD=$(grep -A1 "**postinstall**:" ${CLAUDE_MD_PATH} | tail -1 | sed 's/`//g' | xargs)

# Check if dependencies installed in repo's worktree
if [ ! -d "${WORKTREE_PATH}/node_modules" ]; then
  echo "Installing dependencies in ${TASK_REPO} worktree..."
  bash <<EOF
  cd ${WORKTREE_PATH}
  ${INSTALL_CMD}
  ${POSTINSTALL_CMD}
EOF
fi
```

**Why heredoc:** Orchestrator stays in main repo/workspace root. Heredoc creates subshell that exits after commands.

**Why main worktree:** Sequential tasks share main worktree per repo. All sequential phases share this worktree within each repo.

**Red flag:** "Create phase-specific worktree" - NO. Sequential = shared worktree (per repo).

### Step 1.5: Extract Phase Context (Before Dispatching)

**Before spawn