Understanding Cross-Phase Stacking

Overview

Phases automatically build on each other's completed work. Understanding how phases chain together is essential for correct execution.

This is a reference skill - read it to understand cross-phase dependencies, not to execute a workflow.

When to Use

Use this skill when:

Starting a new phase (need to understand what base to build from)
Debugging stack relationships across phase boundaries
Verifying phases are chaining correctly
Understanding why parallel worktrees use specific base branches

Mental model check: If you're thinking "create worktrees from {runid}-main branch", you need this skill.

The Cross-Phase Inheritance Principle

MAIN WORKTREE CURRENT BRANCH = LATEST COMPLETED WORK

Key insight:

Sequential phases leave main worktree on their last task's branch
Parallel phases leave main worktree on their last stacked branch
Next phase (sequential or parallel) inherits from current branch, not original base

This creates automatic linear chaining across all phases.

Example: Sequential → Parallel → Sequential

Phase 1 (Sequential) - Database Setup

# Working in: .worktrees/{runid}-main
# Starting from: {runid}-main (base branch)

# Task 1: Database schema
gs branch create {runid}-task-1-1-database-schema
# Creates branch, commits work
# Main worktree now on: {runid}-task-1-1-database-schema ← KEY STATE

Phase 1 result:

Branch created: {runid}-task-1-1-database-schema
Main worktree current branch: {runid}-task-1-1-database-schema
This branch becomes Phase 2's base

Phase 2 (Parallel) - Three Feature Implementations

# Base detection (CRITICAL):
BASE_BRANCH=$(git -C .worktrees/{runid}-main branch --show-current)
# Returns: {runid}-task-1-1-database-schema ← Inherits from Phase 1

# Create parallel worktrees FROM Phase 1's completed branch
git worktree add .worktrees/{runid}-task-2-1 --detach "$BASE_BRANCH"
git worktree add .worktrees/{runid}-task-2-2 --detach "$BASE_BRANCH"
git worktree add .worktrees/{runid}-task-2-3 --detach "$BASE_BRANCH"

# All 3 parallel tasks build on Phase 1's database schema

After parallel tasks complete and stack:

# In main worktree (.worktrees/{runid}-main):
# Branch 1: {runid}-task-2-1-user-service → tracked
# Branch 2: {runid}-task-2-2-product-service → tracked, upstacked onto Branch 1
# Branch 3: {runid}-task-2-3-order-service → tracked, upstacked onto Branch 2

# Main worktree now on: {runid}-task-2-3-order-service ← KEY STATE

Phase 2 result:

Linear stack: database-schema → user-service → product-service → order-service
Main worktree current branch: {runid}-task-2-3-order-service
This branch becomes Phase 3's base

Phase 3 (Sequential) - Integration Tests

# Working in: .worktrees/{runid}-main (reused from Phase 1)
# Current branch: {runid}-task-2-3-order-service (from Phase 2)

# Task 1: Integration tests
gs branch create {runid}-task-3-1-integration-tests
# Automatically stacks on Phase 2's last task via natural stacking

Phase 3 result:

Linear chain: Phase 1 → Phase 2 tasks → Phase 3
Complete stack shows all work in order

Verification Between Phases

Before starting parallel phase (check inheritance):

# Verify base branch before creating worktrees
BASE_BRANCH=$(git -C .worktrees/{runid}-main branch --show-current)
echo "Starting parallel phase from: $BASE_BRANCH"
# Should show previous phase's completed branch, NOT {runid}-main

Before starting sequential phase (check current state):

# Verify starting point
CURRENT_BRANCH=$(git -C .worktrees/{runid}-main branch --show-current)
echo "Starting sequential phase from: $CURRENT_BRANCH"
# Should show previous phase's last stacked branch

After phase completes (verify stack):

cd .worktrees/{runid}-main
gs log short
# Should show linear chain including all previous phases

Key Principles

Main worktree tracks progress
- Current branch = latest completed work
- Not static - changes as phases complete
Parallel phases inherit from current
- Use git -C .worktrees/{runid}-main branch --show-current as base
- NOT {runid}-main (that's the original starting point)
Parallel stacking preserves continuity
- Last stacked branch becomes next phase's base
- Checkout last branch after stacking completes
Sequential phases extend naturally
- gs branch create stacks on current HEAD
- No manual base specification needed
No manual intervention needed
- Cross-phase chaining is automatic
- Following per-phase patterns creates correct chain

Common Mistake: Creating From Wrong Base

❌ Wrong: Creating parallel worktrees from original base

# DON'T DO THIS:
git worktree add .worktrees/{runid}-task-2-1 --detach {runid}-main

Why wrong: Ignores Phase 1's completed work. Phase 2 won't have database schema from Phase 1.

Result: Broken dependency chain. Phase 2 builds on stale base instead of Phase 1's changes.

✅ Correct: Creating parallel worktrees from current branch

# DO THIS:
BASE_BRANCH=$(git -C .worktrees/{runid}-main branch --show-current)
git worktree add .worktrees/{runid}-task-2-1 --detach "$BASE_BRANCH"

Why correct: Inherits all previous work. Phase 2 builds on Phase 1's completed branch.

Result: Linear chain across all phases.

Mental Model Check

If you're thinking:

"Create worktrees from {runid}-main" → WRONG. Use current branch.
"Parallel tasks should start fresh" → WRONG. They inherit previous work.
"Phase boundaries break the stack" → WRONG. Stack is continuous across phases.

Correct mental model:

Main worktree is a moving cursor pointing to latest work
Each phase extends the cursor position, doesn't reset it
Stack is one continuous chain, not per-phase segments

Quick Reference

Starting parallel phase:

BASE_BRANCH=$(git -C .worktrees/{runid}-main branch --show-current)
# Use $BASE_BRANCH for all worktree creation

Starting sequential phase:

# Already on correct branch - just create next branch
gs branch create {runid}-task-{phase}-{task}-{name}
# Automatically stacks on current HEAD

Verifying cross-phase chain:

cd .worktrees/{runid}-main
gs log short
# Should show linear progression through all phases

The Bottom Line

Phases chain automatically through main worktree's current branch.

If you're manually specifying base branches or creating worktrees from {runid}-main, you're breaking the automatic inheritance system.

Trust the pattern: main worktree tracks progress, new phases build from current state.