kata-execute-phase

What this skill does

<objective>
Execute all plans in a phase using wave-based parallel execution.

Orchestrator stays lean: discover plans, analyze dependencies, group into waves, spawn subagents, collect results. Each subagent loads the full execute-plan context and handles its own plan.

Context budget: ~15% orchestrator, 100% fresh per subagent.
</objective>

<execution_context>
@./references/ui-brand.md
@./references/planning-config.md
@./references/phase-execute.md
</execution_context>

<context>
Phase: $ARGUMENTS

**Flags:**

- `--gaps-only` — Execute only gap closure plans (plans with `gap_closure: true` in frontmatter). Use after phase-verify creates fix plans.

@.planning/ROADMAP.md
@.planning/STATE.md
</context>

<process>

0. **Resolve Model Profile**

Read model profile for agent spawning:

```bash
MODEL_PROFILE=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-execute-phase/scripts/kata-lib.cjs" read-config "model_profile" "balanced")
```

Default to "balanced" if not set.

0.5. **Read Workflow Config**

Read workflow config for executor injection:

```bash
EXEC_POST_TASK_CMD=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-execute-phase/scripts/kata-lib.cjs" read-pref "workflows.execute-phase.post_task_command" "")
EXEC_COMMIT_STYLE=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-execute-phase/scripts/kata-lib.cjs" read-pref "workflows.execute-phase.commit_style" "conventional")
EXEC_COMMIT_SCOPE_FMT=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-execute-phase/scripts/kata-lib.cjs" read-pref "workflows.execute-phase.commit_scope_format" "{phase}-{plan}")
```

Store these three variables for injection into executor prompts in the `<wave_execution>` Task() calls.

0.6. **Read GitHub Config**

```bash
GITHUB_ENABLED=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-execute-phase/scripts/kata-lib.cjs" read-config "github.enabled" "false")
ISSUE_MODE=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-execute-phase/scripts/kata-lib.cjs" read-config "github.issue_mode" "never")
```

Store for use in PR creation and issue checkbox updates.

0.7. **Check Worktree and PR Config**

Read worktree and PR workflow configuration for conditional lifecycle:

```bash
WORKTREE_ENABLED=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-execute-phase/scripts/kata-lib.cjs" read-config "worktree.enabled" "false")
PR_WORKFLOW=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-execute-phase/scripts/kata-lib.cjs" read-config "pr_workflow" "false")
```

Store `WORKTREE_ENABLED` and `PR_WORKFLOW` for use in steps 1.5, 4, 10, and 10.5. When `WORKTREE_ENABLED=false` (default), plan-level worktree operations are skipped. When `PR_WORKFLOW=false`, all branch/worktree/PR operations are skipped and execution proceeds on the current branch.

**Model lookup table:**

| Agent                      | quality | balanced | budget |
| -------------------------- | ------- | -------- | ------ |
| general-purpose (executor) | opus    | sonnet   | sonnet |
| general-purpose (mapper)   | haiku   | haiku    | haiku  |
| kata-verifier              | sonnet  | sonnet   | haiku  |
| kata-code-reviewer         | opus    | sonnet   | sonnet |
| kata-\*-analyzer           | sonnet  | sonnet   | haiku  |

_Note: Review agents (kata-code-reviewer, kata-_-analyzer) are spawned by the kata-review-pull-requests skill, which handles its own model selection based on the agents' frontmatter. The table above documents expected model usage for cost planning.\*

Store resolved models for use in Task calls below.

1. **Pre-flight: Check roadmap format (auto-migration)**

   If ROADMAP.md exists, check format and auto-migrate if old:

   ```bash
   if [ -f .planning/ROADMAP.md ]; then
     node "${CLAUDE_PLUGIN_ROOT}/skills/kata-execute-phase/scripts/kata-lib.cjs" check-roadmap 2>/dev/null
     FORMAT_EXIT=$?

     if [ $FORMAT_EXIT -eq 1 ]; then
       echo "Old roadmap format detected. Running auto-migration..."
     fi
   fi
   ```

   **If exit code 1 (old format):**

   Invoke kata-doctor in auto mode:

   ```
   Skill("kata-doctor", "--auto")
   ```

   Continue after migration completes.

   **If exit code 0 or 2:** Continue silently.

   ```bash
   # Validate config and template overrides
   node "${CLAUDE_PLUGIN_ROOT}/skills/kata-execute-phase/scripts/kata-lib.cjs" check-config 2>/dev/null || true
   node "${CLAUDE_PLUGIN_ROOT}/skills/kata-execute-phase/scripts/kata-lib.cjs" check-template-drift 2>/dev/null || true
   ```

1.1. **Validate phase exists**
Find phase directory using the discovery script:

```bash
bash "${CLAUDE_PLUGIN_ROOT}/skills/kata-execute-phase/scripts/find-phase.sh" "$PHASE_ARG"
```

Outputs `PHASE_DIR`, `PLAN_COUNT`, and `PHASE_STATE` as key=value pairs. Exit code 1 = not found, 2 = no plans. Parse the output to set these variables for subsequent steps.

1.25. **Move phase to active (state transition)**

```bash
# Move from pending to active when execution begins
# PHASE_STATE is from find-phase.sh output (step 1)
if [ "$PHASE_STATE" = "pending" ]; then
  DIR_NAME=$(basename "$PHASE_DIR")
  mkdir -p ".planning/phases/active"
  mv "$PHASE_DIR" ".planning/phases/active/${DIR_NAME}"
  PHASE_DIR=".planning/phases/active/${DIR_NAME}"
  echo "Phase moved to active/"
fi
```

1.5. **Create phase branch and commit activation changes**

**If PR_WORKFLOW=false:** Skip to step 2.

**If PR_WORKFLOW=true:**

Create the phase branch FIRST. Uncommitted activation changes from step 1.25 float to the new branch via `git checkout -b`. Then commit on the phase branch (not main — respects branch protection).

```bash
if ! BRANCH_OUTPUT=$(bash "${CLAUDE_PLUGIN_ROOT}/skills/kata-execute-phase/scripts/create-phase-branch.sh" "$PHASE_DIR"); then
  echo "Error: Failed to create phase branch" >&2
  exit 1
fi
eval "$BRANCH_OUTPUT"
# Outputs: WORKSPACE_PATH, BRANCH, BRANCH_TYPE, MILESTONE, PHASE_NUM, SLUG
```

Store WORKSPACE_PATH and PHASE_BRANCH for steps 4 and 10.5.

```bash
WORKSPACE_PATH=$WORKSPACE_PATH
PHASE_BRANCH=$BRANCH
```

Now commit the activation changes on the phase branch. The orchestrator runs from workspace/, so plain git commands work directly. This ensures worktrees branch from a clean state and prevents merge conflicts on STATE.md.

```bash
if [ -n "$(git status --porcelain .planning/)" ]; then
  git add .planning/ && git commit -m "docs(${PHASE_NUM}): activate phase"
fi
```

2. **Discover plans**
   - List all \*-PLAN.md files in phase directory
   - Check which have \*-SUMMARY.md (already complete)
   - If `--gaps-only`: filter to only plans with `gap_closure: true`
   - Build list of incomplete plans

3. **Group by wave**
   - Read `wave` from each plan's frontmatter
   - Group plans by wave number

3.5. **Display execution banner**

Display stage banner and wave structure:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Kata ► EXECUTING PHASE {X}: {Phase Name}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

**{N} plans, {M} waves:**

| Wave | Plans  | Description                   |
| ---- | ------ | ----------------------------- |
| 1    | 01, 02 | {plan names from frontmatter} |
| 2    | 03     | {plan name}                   |

**Model profile:** {profile} (executor → {model})
{If WORKTREE_ENABLED=true: **Worktree isolation:** enabled (each plan gets isolated worktree)}

4. **Execute waves**
   For each wave in order:
   - **Create plan worktrees (if enabled):**
     If `WORKTREE_ENABLED=true` and `PR_WORKFLOW=true`, create a worktree for each plan in the wave, forking from the phase branch:

     ```bash
     if [ "$WORKTREE_ENABLED" = "true" ] && [ "$PR_WORKFLOW" = "true" ]; then
       for plan_num in $WAVE_PLAN_NUMBERS; do
         WT_OUTPUT=$(bash "${CLAUDE_PLUGIN_ROOT}/skills/kata-execute-phase/scripts/manage-worktree.sh" create "$PHASE_NUM" "$plan_num" "$PHASE_BRANCH")
         eval "$WT_OUTPUT"
         # Stores WORKTREE_PATH, WORKTREE_BRANCH, STATUS for each plan
         # Save per-plan: WORKTREE_PATH_${plan_num}=$WORKTREE_PATH
       done
     fi
     ```

   - Spawn `general-purpose` executor for each plan in wave (parallel T