kata-execute-phase

📁 gannonh/kata-skills 📅 7 days ago

总安装量

周安装量

#28674

全站排名

安装命令

npx skills add https://github.com/gannonh/kata-skills --skill kata-execute-phase

Agent 安装分布

opencode 7

gemini-cli 7

github-copilot 7

codex 7

amp 7

kimi-cli 7

Skill 文档

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.

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

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

Read model profile for agent spawning:

MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")

Default to “balanced” if not set.

Model lookup table:

Agent	quality	balanced	budget
general-purpose (executor)	opus	sonnet	sonnet
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.

Validate phase exists Find phase directory using the discovery script:
```
bash "${SKILL_BASE_DIR}/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)

# 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 (pr_workflow only)

Read pr_workflow config:

PR_WORKFLOW=$(cat .planning/config.json 2>/dev/null | grep -o '"pr_workflow"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "false")

If PR_WORKFLOW=false: Skip to step 2.

If PR_WORKFLOW=true:

Get milestone version from ROADMAP.md:

MILESTONE=$(grep -oE 'v[0-9]+\.[0-9]+(\.[0-9]+)?' .planning/ROADMAP.md | head -1 | tr -d 'v')

Get phase number and slug from PHASE_DIR:

PHASE_NUM=$(basename "$PHASE_DIR" | sed -E 's/^([0-9]+)-.*/\1/')
SLUG=$(basename "$PHASE_DIR" | sed -E 's/^[0-9]+-//')

Infer branch type from phase goal (feat/fix/docs/refactor/chore, default feat):

PHASE_GOAL=$(grep -A 5 "Phase ${PHASE_NUM}:" .planning/ROADMAP.md | grep "Goal:" | head -1 || echo "")
if echo "$PHASE_GOAL" | grep -qi "fix\|bug\|patch"; then
  BRANCH_TYPE="fix"
elif echo "$PHASE_GOAL" | grep -qi "doc\|readme\|comment"; then
  BRANCH_TYPE="docs"
elif echo "$PHASE_GOAL" | grep -qi "refactor\|restructure\|reorganize"; then
  BRANCH_TYPE="refactor"
elif echo "$PHASE_GOAL" | grep -qi "chore\|config\|setup"; then
  BRANCH_TYPE="chore"
else
  BRANCH_TYPE="feat"
fi

Create branch with re-run protection:

BRANCH="${BRANCH_TYPE}/v${MILESTONE}-${PHASE_NUM}-${SLUG}"
if git show-ref --verify --quiet refs/heads/"$BRANCH"; then
  git checkout "$BRANCH"
  echo "Branch $BRANCH exists, resuming on it"
else
  git checkout -b "$BRANCH"
  echo "Created branch $BRANCH"
fi

Store BRANCH variable for use in step 4.5 and step 10.5.

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
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})

Execute waves For each wave in order:

Spawn general-purpose executor for each plan in wave (parallel Task calls)
Wait for completion (Task blocks)
Verify SUMMARYs created

Update GitHub issue checkboxes (if enabled):

Build COMPLETED_PLANS_IN_WAVE from SUMMARY.md files created this wave:

# Get plan numbers from SUMMARYs that exist after this wave
COMPLETED_PLANS_IN_WAVE=""
for summary in $(find "${PHASE_DIR}" -maxdepth 1 -name "*-SUMMARY.md" 2>/dev/null); do
  # Extract plan number from filename (e.g., 04-01-SUMMARY.md -> 01)
  plan_num=$(basename "$summary" | sed -E 's/^[0-9]+-([0-9]+)-SUMMARY\.md$/\1/')
  # Check if this plan was in the current wave (from frontmatter we read earlier)
  if echo "${WAVE_PLANS}" | grep -q "plan-${plan_num}"; then
    COMPLETED_PLANS_IN_WAVE="${COMPLETED_PLANS_IN_WAVE} ${plan_num}"
  fi
done

Check github.enabled and issueMode:

GITHUB_ENABLED=$(cat .planning/config.json 2>/dev/null | grep -o '"enabled"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "false")
ISSUE_MODE=$(cat .planning/config.json 2>/dev/null | grep -o '"issueMode"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "never")

If GITHUB_ENABLED != true OR ISSUE_MODE = never: Skip GitHub update.

Otherwise:

Find phase issue number:

VERSION=$(grep -oE 'v[0-9]+\.[0-9]+(\.[0-9]+)?' .planning/ROADMAP.md | head -1 | tr -d 'v')
ISSUE_NUMBER=$(gh issue list \
  --label "phase" \
  --milestone "v${VERSION}" \
  --json number,title \
  --jq ".[] | select(.title | startswith(\"Phase ${PHASE}:\")) | .number" \
  2>/dev/null)

If issue not found: Warn and skip (non-blocking).

Read current issue body:

ISSUE_BODY=$(gh issue view "$ISSUE_NUMBER" --json body --jq '.body' 2>/dev/null)

For each completed plan in this wave, update checkbox:

for plan_num in ${COMPLETED_PLANS_IN_WAVE}; do
  # Format: Plan 01, Plan 02, etc.
  PLAN_ID="Plan $(printf "%02d" $plan_num):"
  # Update checkbox: - [ ] -> - [x]
  ISSUE_BODY=$(echo "$ISSUE_BODY" | sed "s/^- \[ \] ${PLAN_ID}/- [x] ${PLAN_ID}/")
done

Write and update:

printf '%s\n' "$ISSUE_BODY" > /tmp/phase-issue-body.md
gh issue edit "$ISSUE_NUMBER" --body-file /tmp/phase-issue-body.md 2>/dev/null \
  && echo "Updated issue #${ISSUE_NUMBER}: checked off Wave ${WAVE_NUM} plans" \
  || echo "Warning: Failed to update issue #${ISSUE_NUMBER}"

This update happens ONCE per wave (after all plans in wave complete), not per-plan, avoiding race conditions.

Open Draft PR (first wave only, pr_workflow only):

After first wave completion (orchestrator provides PHASE_ARG):

# Re-read config (bash blocks don't share state)
PR_WORKFLOW=$(cat .planning/config.json 2>/dev/null | grep -o '"pr_workflow"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "false")
GITHUB_ENABLED=$(cat .planning/config.json 2>/dev/null | grep -o '"enabled"[[:space:]]*:[[:space:]]*[^,}]*' | head -1 | grep -o 'true\|false' || echo "false")
ISSUE_MODE=$(cat .planning/config.json 2>/dev/null | grep -o '"issueMode"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "never")
MILESTONE=$(grep -E "^\- \[.\] \*\*Phase|^### v" .planning/ROADMAP.md | grep -E "In Progress" | grep -oE "v[0-9]+\.[0-9]+(\.[0-9]+)?" | head -1 | tr -d 'v')
[ -z "$MILESTONE" ] && MILESTONE=$(grep -oE 'v[0-9]+\.[0-9]+(\.[0-9]+)?' .planning/ROADMAP.md | head -1 | tr -d 'v')
# PHASE_DIR already set by universal discovery in step 1
PHASE_NUM=$(basename "$PHASE_DIR" | sed -E 's/^([0-9]+)-.*/\1/')
BRANCH=$(git branch --show-current)

if [ "$PR_WORKFLOW" = "true" ]; then
  # Check if PR already exists (re-run protection - also handles wave > 1)
  EXISTING_PR=$(gh pr list --head "$BRANCH" --json number --jq '.[0].number' 2>/dev/null)
  if [ -n "$EXISTING_PR" ]; then
    echo "PR #${EXISTING_PR} already exists, skipping creation"
    PR_NUMBER="$EXISTING_PR"
  else
    # Push branch and create draft PR
    git push -u origin "$BRANCH"

    # Get phase name from ROADMAP.md (format: #### Phase N: Name)
    PHASE_NAME=$(grep -E "^#### Phase ${PHASE_NUM}:" .planning/ROADMAP.md | sed -E 's/^#### Phase [0-9]+: //' | xargs)

    # Build PR body (Goal is on next line after phase header)
    PHASE_GOAL=$(grep -A 3 "^#### Phase ${PHASE_NUM}:" .planning/ROADMAP.md | grep "Goal:" | sed 's/.*Goal:[[:space:]]*//')

    # Get phase issue number for linking (if github.enabled)
    CLOSES_LINE=""
    if [ "$GITHUB_ENABLED" = "true" ] && [ "$ISSUE_MODE" != "never" ]; then
      PHASE_ISSUE=$(gh issue list --label phase --milestone "v${MILESTONE}" \
        --json number,title --jq ".[] | select(.title | startswith(\"Phase ${PHASE_NUM}:\")) | .number" 2>/dev/null)
      [ -n "$PHASE_ISSUE" ] && CLOSES_LINE="Closes #${PHASE_ISSUE}"
      # Store PHASE_ISSUE for use in step 10.6 merge path
    fi

    # Build plans checklist (all unchecked initially)
    PLANS_CHECKLIST=""
    for plan in $(find "${PHASE_DIR}" -maxdepth 1 -name "*-PLAN.md" 2>/dev/null); do
      plan_name=$(grep -m1 "<name>" "$plan" | sed 's/.*<name>//;s/<\/name>.*//' || basename "$plan" | sed 's/-PLAN.md//')
      plan_num=$(basename "$plan" | sed -E 's/^[0-9]+-([0-9]+)-PLAN\.md$/\1/')
      PLANS_CHECKLIST="${PLANS_CHECKLIST}- [ ] Plan ${plan_num}: ${plan_name}\n"
    done

    # Collect source_issue references from all plans
    SOURCE_ISSUES=""
    for plan in $(find "${PHASE_DIR}" -maxdepth 1 -name "*-PLAN.md" 2>/dev/null); do
      source_issue=$(grep -m1 "^source_issue:" "$plan" | cut -d':' -f2- | xargs)
      if echo "$source_issue" | grep -q "^github:#"; then
        issue_num=$(echo "$source_issue" | grep -oE '#[0-9]+')
        [ -n "$issue_num" ] && SOURCE_ISSUES="${SOURCE_ISSUES}Closes ${issue_num}\n"
      fi
    done
    SOURCE_ISSUES=$(echo "$SOURCE_ISSUES" | sed '/^$/d')  # Remove empty lines

    cat > /tmp/pr-body.md << PR_EOF

Phase Goal

${PHASE_GOAL}

Plans

${PLANS_CHECKLIST} ${CLOSES_LINE} ${SOURCE_ISSUES:+

Source Issues

${SOURCE_ISSUES}} PR_EOF

     # Create draft PR
     gh pr create --draft \
       --base main \
       --title "v${MILESTONE} Phase ${PHASE_NUM}: ${PHASE_NAME}" \
       --body-file /tmp/pr-body.md

     PR_NUMBER=$(gh pr list --head "$BRANCH" --json number --jq '.[0].number')
     echo "Created draft PR #${PR_NUMBER}"
   fi
 fi
 ```

 Store PR_NUMBER for step 10.5.

 **Note:** PR body checklist items remain unchecked throughout execution. The PR body is static after creation â it does NOT update as plans complete. The GitHub issue (updated after each wave above) is the source of truth for plan progress during execution.

Proceed to next wave

Aggregate results
- Collect summaries from all plans
- Report phase completion status
Commit any orchestrator corrections Check for uncommitted changes before verification:
```
git status --porcelain
```
If changes exist: Orchestrator made corrections between executor completions. Commit them:
```
git add -u && git commit -m "fix({phase}): orchestrator corrections"
```
If clean: Continue to test suite.

6.5. Run project test suite

Before verification, run the project’s test suite to catch regressions early:

TEST_SCRIPT=$(cat package.json 2>/dev/null | grep -o '"test"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1)

If package.json has a test script:

Run npm test
If tests pass: proceed to step 7
If tests fail: report test failures, still proceed to step 7

If no test script detected:

Skip this step, proceed to step 7

Skip for gap phases: If mode is gap_closure, skip test suite

Verify phase goal Check config: WORKFLOW_VERIFIER=$(cat .planning/config.json 2>/dev/null | grep -o '"verifier"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")

If workflow.verifier is false: Skip to step 8 (treat as passed).

Otherwise:
- Spawn kata-verifier subagent with phase directory and goal
- Verifier checks must_haves against actual codebase (not SUMMARY claims)
- Creates VERIFICATION.md with detailed report
- Route by status:
  - passed â continue to step 8
  - human_needed â present items, get approval or feedback
  - gaps_found â present gaps, offer /kata:kata-plan-phase {X} --gaps

7.5. Validate completion and move to completed

After verification passes, validate completion artifacts before moving phase to completed:

# Validate completion artifacts
PLAN_COUNT=$(find "$PHASE_DIR" -maxdepth 1 -name "*-PLAN.md" 2>/dev/null | wc -l | tr -d ' ')
MISSING=""
if [ "$PLAN_COUNT" -eq 0 ]; then
  MISSING="${MISSING}\n- No PLAN.md files found"
fi
for plan in $(find "$PHASE_DIR" -maxdepth 1 -name "*-PLAN.md" 2>/dev/null); do
  plan_id=$(basename "$plan" | sed 's/-PLAN\.md$//')
  [ ! -f "$PHASE_DIR/${plan_id}-SUMMARY.md" ] && MISSING="${MISSING}\n- Missing SUMMARY.md for ${plan_id}"
done
# Non-gap phases require VERIFICATION.md
IS_GAP=$(find "$PHASE_DIR" -maxdepth 1 -name "*-PLAN.md" -exec grep -l "gap_closure: true" {} + 2>/dev/null | head -1)
if [ -z "$IS_GAP" ] && ! find "$PHASE_DIR" -maxdepth 1 -name "*-VERIFICATION.md" 2>/dev/null | grep -q .; then
  MISSING="${MISSING}\n- Missing VERIFICATION.md (required for non-gap phases)"
fi

if [ -z "$MISSING" ]; then
  DIR_NAME=$(basename "$PHASE_DIR")
  mkdir -p ".planning/phases/completed"
  mv "$PHASE_DIR" ".planning/phases/completed/${DIR_NAME}"
  PHASE_DIR=".planning/phases/completed/${DIR_NAME}"
  echo "Phase validated and moved to completed/"
else
  echo "Warning: Phase incomplete:${MISSING}"
fi

Update roadmap and state
- Update ROADMAP.md, STATE.md
Update requirements Mark phase requirements as Complete:
- Read ROADMAP.md, find this phase’s Requirements: line (e.g., “AUTH-01, AUTH-02”)
- Read REQUIREMENTS.md traceability table
- For each REQ-ID in this phase: change Status from “Pending” to “Complete”
- Write updated REQUIREMENTS.md
- Skip if: REQUIREMENTS.md doesn’t exist, or phase has no Requirements line
Commit phase completion Check COMMIT_PLANNING_DOCS from config.json (default: true). If false: Skip git operations for .planning/ files. If true: Bundle all phase metadata updates in one commit:
- Stage: git add .planning/ROADMAP.md .planning/STATE.md
- Stage REQUIREMENTS.md if updated: git add .planning/REQUIREMENTS.md
- Commit: docs({phase}): complete {phase-name} phase

10.5. Mark PR Ready (pr_workflow only)

After phase completion commit:
```bash
if [ "$PR_WORKFLOW" = "true" ]; then
  # Push final commits
  git push origin "$BRANCH"

  # Mark PR ready for review
  gh pr ready

  PR_URL=$(gh pr view --json url --jq '.url')
  echo "PR marked ready: $PR_URL"
fi
```

Store PR_URL for offer_next output.

10.6. Post-Verification Checkpoint (REQUIRED â Loop until user chooses “Skip to completion”)

After PR is ready (or after phase commits if pr_workflow=false), present the user with post-verification options. This is the decision point before proceeding to completion output.

**Control flow:**
- UAT â returns here after completion
- PR review â step 10.7 â returns here
- Merge â executes merge â returns here
- Skip â proceeds to step 11

**IMPORTANT:** Do NOT skip this step. Do NOT proceed directly to step 11. The user must choose how to proceed.

Use AskUserQuestion:
- header: "Phase Complete"
- question: "Phase {X} execution complete. What would you like to do?"
- options:
  - "Run UAT (Recommended)" â Walk through deliverables for manual acceptance testing
  - "Run PR review" â 6 specialized agents review code quality
  - "Merge PR" â (if pr_workflow=true) Merge to main
  - "Skip to completion" â Trust automated verification, proceed to next phase/milestone

**Note:** Show "Merge PR" option only if `pr_workflow=true` AND PR exists AND not already merged.

**If user chooses "Run UAT":**
1. Invoke skill: `Skill("kata:kata-verify-work", "{phase}")`
2. UAT skill handles the walkthrough and any issues found
3. After UAT completes, return to this step to ask again (user may want PR review or merge)

**If user chooses "Run PR review":**
4. Invoke skill: `Skill("kata:review-pull-requests")`
5. Display review summary with counts: {N} critical, {M} important, {P} suggestions
6. **STOP and ask what to do with findings** (see step 10.7)
7. After findings handled, return to this step

**If user chooses "Merge PR":**
8. Execute merge:
   ```bash
   gh pr merge "$PR_NUMBER" --merge --delete-branch
   git checkout main && git pull

   # Explicitly close the phase issue (backup in case Closes #X didn't trigger)
   if [ -n "$PHASE_ISSUE" ]; then
     gh issue close "$PHASE_ISSUE" --comment "Closed by PR #${PR_NUMBER} merge" 2>/dev/null \
       && echo "Closed issue #${PHASE_ISSUE}" \
       || echo "Note: Issue #${PHASE_ISSUE} may already be closed"
   fi

   # Close source issues from plans (backup in case Closes #X didn't trigger)
   for plan in $(find "${PHASE_DIR}" -maxdepth 1 -name "*-PLAN.md" 2>/dev/null); do
     source_issue=$(grep -m1 "^source_issue:" "$plan" | cut -d':' -f2- | xargs)
     if echo "$source_issue" | grep -q "^github:#"; then
       issue_num=$(echo "$source_issue" | grep -oE '[0-9]+')
       gh issue close "$issue_num" --comment "Closed by PR #${PR_NUMBER} merge (source issue for plan)" 2>/dev/null || true
     fi
   done
   ```
9. Set MERGED=true
10. Return to this step to ask if user wants UAT or review before continuing

**If user chooses "Skip to completion":**
Continue to step 11.

10.7. Handle Review Findings (required after PR review completes)

**STOP here. Do not proceed until user chooses an action.**

Use AskUserQuestion with options based on what was found:
- header: "Review Findings"
- question: "How do you want to handle the review findings?"
- options (show only applicable ones):
  - "Fix critical issues" â (if critical > 0) Fix critical, then offer to add remaining to backlog
  - "Fix critical & important" â (if critical + important > 0) Fix both, then offer to add suggestions to backlog
  - "Fix all issues" â (if any issues) Fix everything
  - "Add to backlog" â Create issues for all findings without fixing
  - "Ignore and continue" â Skip all issues

**After user chooses:**

**Path A: "Fix critical issues"**
1. Fix each critical issue
2. If important or suggestions remain, ask: "Add remaining {N} issues to backlog?"
   - "Yes" â Create issues, store TODOS_CREATED count
   - "No" â Continue
3. Return to step 10.6 checkpoint

**Path B: "Fix critical & important"**
1. Fix each critical and important issue
2. If suggestions remain, ask: "Add {N} suggestions to backlog?"
   - "Yes" â Create issues, store TODOS_CREATED count
   - "No" â Continue
3. Return to step 10.6 checkpoint

**Path C: "Fix all issues"**
1. Fix all critical, important, and suggestion issues
2. Return to step 10.6 checkpoint

**Path D: "Add to backlog"**
1. Create issues for all findings using `/kata:kata-add-issue`
2. Store TODOS_CREATED count
3. Return to step 10.6 checkpoint

**Path E: "Ignore and continue"**
1. Return to step 10.6 checkpoint

Store REVIEW_SUMMARY and TODOS_CREATED for offer_next output.

**Note:** After handling findings, return to step 10.6 so user can choose UAT, merge, or skip. The checkpoint loop continues until user explicitly chooses "Skip to completion".

11. Offer next steps – Route to next action (see <offer_next>)

<offer_next> Output this markdown directly (not as a code block). Route based on status:

Status	Route
`gaps_found`	Route C (gap closure)
`human_needed`	Present checklist, then re-route based on approval
`passed` + more phases	Route A (next phase)
`passed` + last phase	Route B (milestone complete)

Route A: Phase verified, more phases remain

(Merge status already determined in step 10.6)

âââââââââââââââââââââââââââââââââââââââââââââââââââââ Kata âº PHASE {Z} COMPLETE â âââââââââââââââââââââââââââââââââââââââââââââââââââââ

Phase {Z}: {Name}

{Y} plans executed Goal verified â {If github.enabled: GitHub Issue: #{issue_number} ({checked}/{total} plans checked off)} {If PR_WORKFLOW and MERGED: PR: #{pr_number} â merged â} {If PR_WORKFLOW and not MERGED: PR: #{pr_number} ({pr_url}) â ready for review} {If REVIEW_SUMMARY: PR Review: {summary_stats}} {If TODOS_CREATED: Backlog: {N} issues created from review suggestions}

âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ

â¶ Next Up

Phase {Z+1}: {Name} â {Goal from ROADMAP.md}

/kata:kata-discuss-phase {Z+1} â gather context and clarify approach

/clear first â fresh context window

âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ

Also available:

/kata:kata-plan-phase {Z+1} â skip discussion, plan directly
/kata:kata-verify-work {Z} â manual acceptance testing before continuing {If PR_WORKFLOW and not MERGED: – gh pr view --web â review PR in browser before next phase}

âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ

Route B: Phase verified, milestone complete

âââââââââââââââââââââââââââââââââââââââââââââââââââââ Kata âº MILESTONE COMPLETE ð âââââââââââââââââââââââââââââââââââââââââââââââââââââ

v1.0

{N} phases completed All phase goals verified â {If PR_WORKFLOW and MERGED: All phase PRs merged â} {If PR_WORKFLOW and not MERGED: Phase PRs ready â merge to prepare for release}

âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ

â¶ Next Up

Audit milestone â verify requirements, cross-phase integration, E2E flows

/kata:kata-audit-milestone

/clear first â fresh context window

âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ

Also available:

/kata:kata-verify-work â manual acceptance testing
/kata:kata-complete-milestone â skip audit, archive directly

âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ

Route C: Gaps found â need additional planning

âââââââââââââââââââââââââââââââââââââââââââââââââââââ Kata âº PHASE {Z} GAPS FOUND â âââââââââââââââââââââââââââââââââââââââââââââââââââââ

Phase {Z}: {Name}

Score: {N}/{M} must-haves verified Report: .planning/phases/{phase_dir}/{phase}-VERIFICATION.md

What’s Missing

{Extract gap summaries from VERIFICATION.md}

âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ

â¶ Next Up

Plan gap closure â create additional plans to complete the phase

/kata:kata-plan-phase {Z} –gaps

/clear first â fresh context window

âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ

Also available:

cat .planning/phases/{phase_dir}/{phase}-VERIFICATION.md â see full report
/kata:kata-verify-work {Z} â manual testing before planning

âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ

After user runs /kata:kata-plan-phase {Z} –gaps:

Planner reads VERIFICATION.md gaps
Creates plans 04, 05, etc. to close gaps
User runs /kata:kata-execute-phase {Z} again
phase-execute runs incomplete plans (04, 05…)
Verifier runs again â loop until passed </offer_next>

<wave_execution> Parallel spawning:

Before spawning, read file contents using Read tool. The @ syntax does not work across Task() boundaries – content must be inlined in the Task prompt.

Read these files:

Each plan file in the wave (e.g., {plan_01_path}, {plan_02_path}, etc.)
.planning/STATE.md
references/executor-instructions.md (relative to skill base directory) â store as executor_instructions_content

Spawn all plans in a wave with a single message containing multiple Task calls, with inlined content:

Task(prompt="<agent-instructions>\n{executor_instructions_content}\n</agent-instructions>\n\nExecute plan at {plan_01_path}\n\n<plan>\n{plan_01_content}\n</plan>\n\n<project_state>\n{state_content}\n</project_state>", subagent_type="general-purpose", model="{executor_model}")
Task(prompt="<agent-instructions>\n{executor_instructions_content}\n</agent-instructions>\n\nExecute plan at {plan_02_path}\n\n<plan>\n{plan_02_content}\n</plan>\n\n<project_state>\n{state_content}\n</project_state>", subagent_type="general-purpose", model="{executor_model}")
Task(prompt="<agent-instructions>\n{executor_instructions_content}\n</agent-instructions>\n\nExecute plan at {plan_03_path}\n\n<plan>\n{plan_03_content}\n</plan>\n\n<project_state>\n{state_content}\n</project_state>", subagent_type="general-purpose", model="{executor_model}")

All three run in parallel. Task tool blocks until all complete.

No polling. No background agents. No TaskOutput loops. </wave_execution>

<checkpoint_handling> Plans with autonomous: false have checkpoints. The phase-execute.md workflow handles the full checkpoint flow:

Subagent pauses at checkpoint, returns structured state
Orchestrator presents to user, collects response
Spawns fresh continuation agent (not resume)

See @./references/phase-execute.md step checkpoint_handling for complete details. </checkpoint_handling>

<deviation_rules> During execution, handle discoveries automatically:

Auto-fix bugs – Fix immediately, document in Summary
Auto-add critical – Security/correctness gaps, add and document
Auto-fix blockers – Can’t proceed without fix, do it and document
Ask about architectural – Major structural changes, stop and ask user

Only rule 4 requires user intervention. </deviation_rules>

<commit_rules> Per-Task Commits:

After each task completes:

Stage only files modified by that task
Commit with format: {type}({phase}-{plan}): {task-name}
Types: feat, fix, test, refactor, perf, chore
Record commit hash for SUMMARY.md

Plan Metadata Commit:

After all tasks in a plan complete:

Stage plan artifacts only: PLAN.md, SUMMARY.md
Commit with format: docs({phase}-{plan}): complete [plan-name] plan
NO code files (already committed per-task)

Phase Completion Commit:

After all plans in phase complete (step 7):

Stage: ROADMAP.md, STATE.md, REQUIREMENTS.md (if updated), VERIFICATION.md
Commit with format: docs({phase}): complete {phase-name} phase
Bundles all phase-level state updates in one commit

NEVER use:

git add .
git add -A
git add src/ or any broad directory

Always stage files individually. </commit_rules>

<success_criteria>

All incomplete plans in phase executed
Each plan has SUMMARY.md
Phase goal verified (must_haves checked against codebase)
VERIFICATION.md created in phase directory
STATE.md reflects phase completion
ROADMAP.md updated
REQUIREMENTS.md updated (phase requirements marked Complete)
GitHub issue checkboxes updated per wave (if github.enabled)
User informed of next steps </success_criteria>

GitHub 仓库 ↗ ← 返回陌讯 Skills 聚合平台

kata-execute-phase

Agent 安装分布

Skill 文档

Phase Goal

Plans

Source Issues

â¶ Next Up

â¶ Next Up

What’s Missing

â¶ Next Up

â¶ Next Up

â¶ Next Up

â¶ Next Up