executing-plan

What this skill does

# Executing Plans

## Overview

This skill orchestrates the execution of implementation plans generated by the `decomposing-tasks` skill. It handles the complete lifecycle of plan execution including worktree verification, resume detection, phase-by-phase execution (sequential or parallel), quality verification, and final stack completion.

## When to Use

Use this skill when:
- Executing an implementation plan from `/spectacular:execute`
- Resuming interrupted plan execution
- Orchestrating multi-phase feature implementation

**Announce:** "I'm using executing-plan to orchestrate implementation of the plan."

## Architecture

The execute command uses an orchestrator-with-embedded-instructions architecture for cognitive load reduction:

**Orchestrator Skills** (`executing-sequential-phase`, `executing-parallel-phase`)
- Responsibilities: Setup, worktree management, dispatch coordination, code review orchestration
- Size: ~464 lines (sequential), ~850 lines (parallel)
- Dispatches: Task tool with embedded execution instructions (~150 lines per task)
- Focus: Manages workflow lifecycle, embeds focused task instructions for subagents

**Verification Skill** (`phase-task-verification`)
- Responsibilities: Shared git operations (add, branch create, HEAD verify, detach)
- Size: ~92 lines
- Used by: Task subagents via Skill tool (both sequential and parallel)
- Focus: Eliminates duplication of branch creation/verification logic

**Cognitive Load Reduction:**
- Original: 750-line monolithic skills (orchestration + task + verification mixed)
- Current: Subagents receive ~150 lines of focused task execution instructions via Task tool
- Benefit: 80% reduction in content subagents must parse (only see task instructions, not orchestration)
- Verification: Shared 92-line skill eliminates duplication

**Maintainability benefit:** Orchestrator features (resume support, enhanced error recovery, verification improvements) can be added without affecting task execution instructions. Subagents receive focused, consistent instructions while orchestrators handle workflow complexity.

**Testing framework:** This plugin uses Test-Driven Development for workflow documentation. See `tests/README.md` and `CLAUDE.md` for the complete testing system. All changes to commands and skills must pass the test suite before committing.

## Available Skills

**Skills are referenced on-demand when you encounter the relevant step. Do not pre-read all skills upfront.**

**Phase Execution** (read when you encounter the phase type):

- `executing-parallel-phase` - Mandatory workflow for parallel phases (Step 2)
- `executing-sequential-phase` - Mandatory workflow for sequential phases (Step 2)

**Support Skills** (read as needed when referenced):

- `understanding-cross-phase-stacking` - Reference before starting any phase (explains base branch inheritance)
- `validating-setup-commands` - Reference if CLAUDE.md setup validation needed (Step 1.5)
- `using-git-spice` - Reference for git-spice command syntax (as needed)
- `requesting-code-review` - Reference after each phase completes (Step 2)
- `verification-before-completion` - Reference before claiming completion (Step 3)
- `finishing-a-development-branch` - Reference after all phases complete (Step 4)
- `troubleshooting-execute` - Reference if execution fails (error recovery)
- `using-git-worktrees` - Reference if worktree issues occur (diagnostics)

## Multi-Repo Support

### Detecting Multi-Repo Mode

At the start of execution, detect workspace mode:

```bash
# Detect workspace mode
REPO_COUNT=$(find . -maxdepth 2 -name ".git" -type d 2>/dev/null | wc -l | tr -d ' ')
if [ "$REPO_COUNT" -gt 1 ]; then
  echo "Multi-repo workspace detected ($REPO_COUNT repos)"
  WORKSPACE_MODE="multi-repo"
  REPOS=$(find . -maxdepth 2 -name ".git" -type d | xargs -I{} dirname {} | sed 's|^\./||' | tr '\n' ' ')
  echo "Available repos: $REPOS"
else
  echo "Single-repo mode"
  WORKSPACE_MODE="single-repo"
fi
```

### Multi-Repo Execution Differences

| Aspect | Single-Repo | Multi-Repo |
|--------|-------------|------------|
| Worktree | `.worktrees/{runId}-main/` | Per-task: `{repo}/.worktrees/{runId}-task-X-Y/` |
| Spec location | `specs/{runId}-{feature}/` | `./specs/{runId}-{feature}/` (workspace root) |
| Setup commands | One CLAUDE.md | Per-repo CLAUDE.md |
| Constitution | `@docs/constitutions/current/` | `@{repo}/docs/constitutions/current/` |
| Git-spice stack | Single stack | Per-repo stacks |

### Passing Repo Context to Phase Skills

When dispatching phase execution, include repo context:

```markdown
**Multi-repo context for phase:**
- WORKSPACE_MODE: multi-repo
- WORKSPACE_ROOT: {absolute path}
- Task repos: {list of repos with tasks in this phase}
- Per-task repo: extracted from plan's `**Repo**: {repo}` field
```

## The Process

### Input

User will provide: `/spectacular:execute {plan-path}`

Example: `/spectacular:execute @specs/a1b2c3-magic-link-auth/plan.md`

Where `a1b2c3` is the runId and `magic-link-auth` is the feature slug.

### Step 0a: Extract Run ID from Plan

**User provided plan path**: The user gave you a plan path like `.worktrees/3a00a7-main/specs/3a00a7-agent-standardization-refactor/plan.md`

**Extract RUN_ID from the path:**

The RUN_ID is the first segment of the spec directory name (before the first dash).

For example:

- Path: `.worktrees/3a00a7-main/specs/3a00a7-agent-standardization-refactor/plan.md`
- Directory: `3a00a7-agent-standardization-refactor`
- RUN_ID: `3a00a7`

```bash
# Extract RUN_ID and FEATURE_SLUG from plan path (replace {the-plan-path-user-provided} with actual path)
PLAN_PATH="{the-plan-path-user-provided}"
DIR_NAME=$(echo "$PLAN_PATH" | sed 's|^.*specs/||; s|/plan.md$||')
RUN_ID=$(echo "$DIR_NAME" | cut -d'-' -f1)
FEATURE_SLUG=$(echo "$DIR_NAME" | cut -d'-' -f2-)

echo "Extracted RUN_ID: $RUN_ID"
echo "Extracted FEATURE_SLUG: $FEATURE_SLUG"

# Verify RUN_ID and FEATURE_SLUG are not empty
if [ -z "$RUN_ID" ]; then
  echo "Error: Could not extract RUN_ID from plan path: $PLAN_PATH"
  exit 1
fi

if [ -z "$FEATURE_SLUG" ]; then
  echo "Error: Could not extract FEATURE_SLUG from plan path: $PLAN_PATH"
  exit 1
fi
```

**CRITICAL**: Execute this entire block as a single multi-line Bash tool call. The comment on the first line is REQUIRED - without it, command substitution `$(...)` causes parse errors.

**Store RUN_ID and FEATURE_SLUG for use in:**

- Branch naming: `{run-id}-task-X-Y-name`
- Filtering: `git branch | grep "^  {run-id}-"`
- Spec path: `specs/{run-id}-{feature-slug}/spec.md`
- Cleanup: Identify which branches/specs belong to this run

**Announce:** "Executing with RUN_ID: {run-id}, FEATURE_SLUG: {feature-slug}"

### Step 0b: Verify Worktree Exists

**Multi-repo mode:** Skip worktree verification at orchestrator level. Each task will create its own worktree in its repo during phase execution.

```bash
if [ "$WORKSPACE_MODE" = "multi-repo" ]; then
  echo "Multi-repo mode: Worktrees created per-task during execution"
  # Verify spec exists at workspace root
  if [ ! -f "specs/${RUN_ID}-${FEATURE_SLUG}/plan.md" ]; then
    echo "Error: Plan not found at specs/${RUN_ID}-${FEATURE_SLUG}/plan.md"
    exit 1
  fi
  echo "Plan verified: specs/${RUN_ID}-${FEATURE_SLUG}/plan.md"
fi
```

**Single-repo mode:** Continue with existing worktree verification.

**After extracting RUN_ID, verify the worktree exists:**

```bash
# Get absolute repo root (stay in main repo, don't cd into worktree)
REPO_ROOT=$(git rev-parse --show-toplevel)

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

# Verify it's a valid worktree
git worktree list | grep "${RUN_ID}-main"
```

**IMPORTANT: Orchestrator stays in main repo. All worktree operations use `git -C .worktrees/{run-id}-main` or absolute paths.**

**This ensures task worktrees are created at the sam