Loading...
Loading...
Plan detailed roadmap phases. Triggers include "plan phase n", "create phase plan", "create a plan" "roadmap planning", and "roadmap phase creation".
npx skill4agent add gannonh/kata-skills kata-plan-phase--research--skip-research--gaps--skip-verifyls .planning/ 2>/dev/null/kata-new-projectMODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")| Agent | quality | balanced | budget |
|---|---|---|---|
| kata-phase-researcher | opus | sonnet | haiku |
| kata-planner | opus | opus | sonnet |
| kata-plan-checker | sonnet | sonnet | haiku |
2.1--research--skip-research--gaps--skip-verify# Normalize phase number (8 → 08, but preserve decimals like 2.1 → 02.1)
if [[ "$PHASE" =~ ^[0-9]+$ ]]; then
PHASE=$(printf "%02d" "$PHASE")
elif [[ "$PHASE" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
fi# Find phase directory across state subdirectories
PADDED=$(printf "%02d" "$PHASE" 2>/dev/null || echo "$PHASE")
PHASE_DIR=""
for state in active pending completed; do
PHASE_DIR=$(find .planning/phases/${state} -maxdepth 1 -type d -name "${PADDED}-*" 2>/dev/null | head -1)
[ -z "$PHASE_DIR" ] && PHASE_DIR=$(find .planning/phases/${state} -maxdepth 1 -type d -name "${PHASE}-*" 2>/dev/null | head -1)
[ -n "$PHASE_DIR" ] && break
done
# Fallback: flat directory (backward compatibility for unmigrated projects)
if [ -z "$PHASE_DIR" ]; then
PHASE_DIR=$(find .planning/phases -maxdepth 1 -type d -name "${PADDED}-*" 2>/dev/null | head -1)
[ -z "$PHASE_DIR" ] && PHASE_DIR=$(find .planning/phases -maxdepth 1 -type d -name "${PHASE}-*" 2>/dev/null | head -1)
fi
# Collision check: detect duplicate phase numbering that requires migration
MATCH_COUNT=0
for state in active pending completed; do
MATCH_COUNT=$((MATCH_COUNT + $(find .planning/phases/${state} -maxdepth 1 -type d -name "${PADDED}-*" 2>/dev/null | wc -l)))
done
# Include flat fallback matches
MATCH_COUNT=$((MATCH_COUNT + $(find .planning/phases -maxdepth 1 -type d -name "${PADDED}-*" 2>/dev/null | wc -l)))
if [ "$MATCH_COUNT" -gt 1 ]; then
echo "COLLISION: ${MATCH_COUNT} directories match prefix '${PADDED}-*' across phase states."
echo "This project uses old per-milestone phase numbering that must be migrated first."
fi/kata-migrate-phases/kata-plan-phasefind "${PHASE_DIR}" -maxdepth 1 -name "*-RESEARCH.md" 2>/dev/null
find "${PHASE_DIR}" -maxdepth 1 -name "*-PLAN.md" 2>/dev/nullgrep -A5 "Phase ${PHASE}:" .planning/ROADMAP.md 2>/dev/null# PHASE is already normalized (08, 02.1, etc.) from step 2
# Use universal phase discovery: search active/pending/completed with flat fallback
PADDED=$(printf "%02d" "$PHASE" 2>/dev/null || echo "$PHASE")
PHASE_DIR=""
for state in active pending completed; do
PHASE_DIR=$(find .planning/phases/${state} -maxdepth 1 -type d -name "${PADDED}-*" 2>/dev/null | head -1)
[ -z "$PHASE_DIR" ] && PHASE_DIR=$(find .planning/phases/${state} -maxdepth 1 -type d -name "${PHASE}-*" 2>/dev/null | head -1)
[ -n "$PHASE_DIR" ] && break
done
# Fallback: flat directory (backward compatibility for unmigrated projects)
if [ -z "$PHASE_DIR" ]; then
PHASE_DIR=$(find .planning/phases -maxdepth 1 -type d -name "${PADDED}-*" 2>/dev/null | head -1)
[ -z "$PHASE_DIR" ] && PHASE_DIR=$(find .planning/phases -maxdepth 1 -type d -name "${PHASE}-*" 2>/dev/null | head -1)
fi
if [ -z "$PHASE_DIR" ]; then
# Create phase directory in pending/ from roadmap name
PHASE_NAME=$(grep "Phase ${PHASE}:" .planning/ROADMAP.md | sed 's/.*Phase [0-9]*: //' | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
mkdir -p ".planning/phases/pending/${PHASE}-${PHASE_NAME}"
PHASE_DIR=".planning/phases/pending/${PHASE}-${PHASE_NAME}"
fi--gaps--skip-researchWORKFLOW_RESEARCH=$(cat .planning/config.json 2>/dev/null | grep -o '"research"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")workflow.researchfalse--researchfind "${PHASE_DIR}" -maxdepth 1 -name "*-RESEARCH.md" 2>/dev/null--researchUsing existing research: ${PHASE_DIR}/${PHASE}-RESEARCH.md--research# Get phase description from roadmap
PHASE_DESC=$(grep -A3 "Phase ${PHASE}:" .planning/ROADMAP.md)
# Get requirements if they exist
REQUIREMENTS=$(cat .planning/REQUIREMENTS.md 2>/dev/null | grep -A100 "## Requirements" | head -50)
# Get prior decisions from STATE.md
DECISIONS=$(grep -A20 "### Decisions Made" .planning/STATE.md 2>/dev/null)
# Get phase context if exists
PHASE_CONTEXT=$(cat "${PHASE_DIR}/${PHASE}-CONTEXT.md" 2>/dev/null)<objective>
Research how to implement Phase {phase_number}: {phase_name}
Answer: "What do I need to know to PLAN this phase well?"
</objective>
<context>
**Phase description:**
{phase_description}
**Requirements (if any):**
{requirements}
**Prior decisions:**
{decisions}
**Phase context (if any):**
{phase_context}
</context>
<output>
Write research findings to: {phase_dir}/{phase}-RESEARCH.md
</output>Task(
prompt="<agent-instructions>\n{phase_researcher_instructions_content}\n</agent-instructions>\n\n" + research_prompt,
subagent_type="general-purpose",
model="{researcher_model}",
description="Research Phase {phase}"
)## RESEARCH COMPLETEResearch complete. Proceeding to planning...## RESEARCH BLOCKEDfind "${PHASE_DIR}" -maxdepth 1 -name "*-PLAN.md" 2>/dev/null@.planning/STATE.md.planning/ROADMAP.md.planning/REQUIREMENTS.md${PHASE_DIR}/*-CONTEXT.md${PHASE_DIR}/*-RESEARCH.md${PHASE_DIR}/*-VERIFICATION.md${PHASE_DIR}/*-UAT.mdreferences/planner-instructions.mdplanner_instructions_contentreferences/phase-researcher-instructions.mdphase_researcher_instructions_contentreferences/plan-checker-instructions.mdplan_checker_instructions_content# Normalize phase identifier
PHASE_DIR_NAME=$(basename "$PHASE_DIR")
PHASE_NUM=$(echo "$PHASE_DIR_NAME" | grep -oE '^[0-9.]+')
# Extract linked issues from both sections
LINKED_ISSUES=""
# Check Pending Issues (from check-issues "Link to existing phase")
if grep -q "^### Pending Issues" .planning/STATE.md 2>/dev/null; then
PENDING=$(awk '
/^### Pending Issues/{found=1; next}
/^### |^## /{if(found) exit}
found && /→ Phase/ {
# Match phase number or full phase dir name
if ($0 ~ /→ Phase '"${PHASE_NUM}"'-/ || $0 ~ /→ Phase '"${PHASE_DIR_NAME}"'/) {
print
}
}
' .planning/STATE.md)
[ -n "$PENDING" ] && LINKED_ISSUES="${PENDING}"
fi
# Check Milestone Scope Issues (from add-milestone issue selection)
if grep -q "^### Milestone Scope Issues" .planning/STATE.md 2>/dev/null; then
SCOPE=$(awk '
/^### Milestone Scope Issues/{found=1; next}
/^### |^## /{if(found) exit}
found && /→ Phase/ {
if ($0 ~ /→ Phase '"${PHASE_NUM}"'-/ || $0 ~ /→ Phase '"${PHASE_DIR_NAME}"'/) {
print
}
}
' .planning/STATE.md)
[ -n "$SCOPE" ] && LINKED_ISSUES="${LINKED_ISSUES}${SCOPE}"
fiISSUE_CONTEXT_SECTION=""
if [ -n "$LINKED_ISSUES" ]; then
ISSUE_CONTEXT_SECTION="
**Linked Issues:**
${LINKED_ISSUES}
Note: Set \`source_issue:\` in plan frontmatter for traceability:
- GitHub issues: \`source_issue: github:#N\` (extract from provenance field)
- Local issues: \`source_issue: [file path]\`
"
fi<planning_context>
**Phase:** {phase_number}
**Mode:** {standard | gap_closure}
**Project State:**
{state_content}
**Roadmap:**
{roadmap_content}
**Requirements (if exists):**
{requirements_content}
**Phase Context (if exists):**
{context_content}
**Research (if exists):**
{research_content}
**Linked Issues (from STATE.md):**
{issue_context_section}
**Gap Closure (if --gaps mode):**
{verification_content}
{uat_content}
</planning_context>
<downstream_consumer>
Output consumed by /kata-execute-phase
Plans must be executable prompts with:
- Frontmatter (wave, depends_on, files_modified, autonomous)
- Tasks in XML format
- Verification criteria
- must_haves for goal-backward verification
</downstream_consumer>
<quality_gate>
Before returning PLANNING COMPLETE:
- [ ] PLAN.md files created in phase directory
- [ ] Each plan has valid frontmatter
- [ ] Tasks are specific and actionable
- [ ] Dependencies correctly identified
- [ ] Waves assigned for parallel execution
- [ ] must_haves derived from phase goal
</quality_gate>Task(
prompt="<agent-instructions>\n{planner_instructions_content}\n</agent-instructions>\n\n" + filled_prompt,
subagent_type="general-purpose",
model="{planner_model}",
description="Plan Phase {phase}"
)## PLANNING COMPLETEPlanner created {N} plan(s). Files on disk.--skip-verifyWORKFLOW_PLAN_CHECK=$(cat .planning/config.json 2>/dev/null | grep -o '"plan_check"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")workflow.plan_checkfalse## CHECKPOINT REACHED## PLANNING INCONCLUSIVE# Read all plans in phase directory
PLANS_CONTENT=$(cat "${PHASE_DIR}"/*-PLAN.md 2>/dev/null)
# Read requirements (reuse from step 7 if available)
REQUIREMENTS_CONTENT=$(cat .planning/REQUIREMENTS.md 2>/dev/null)<verification_context>
**Phase:** {phase_number}
**Phase Goal:** {goal from ROADMAP}
**Plans to verify:**
{plans_content}
**Requirements (if exists):**
{requirements_content}
</verification_context>
<expected_output>
Return one of:
- ## VERIFICATION PASSED — all checks pass
- ## ISSUES FOUND — structured issue list
</expected_output>Task(
prompt="<agent-instructions>\n{plan_checker_instructions_content}\n</agent-instructions>\n\n" + checker_prompt,
subagent_type="general-purpose",
model="{checker_model}",
description="Verify Phase {phase} plans"
)## VERIFICATION PASSEDPlans verified. Checking GitHub integration...## ISSUES FOUNDChecker found issues:iteration_countSending back to planner for revision... (iteration {N}/3)PLANS_CONTENT=$(cat "${PHASE_DIR}"/*-PLAN.md 2>/dev/null)<revision_context>
**Phase:** {phase_number}
**Mode:** revision
**Existing plans:**
{plans_content}
**Checker issues:**
{structured_issues_from_checker}
</revision_context>
<instructions>
Make targeted updates to address checker issues.
Do NOT replan from scratch unless issues are fundamental.
Return what changed.
</instructions>Task(
prompt="<agent-instructions>\n{planner_instructions_content}\n</agent-instructions>\n\n" + revision_prompt,
subagent_type="general-purpose",
model="{planner_model}",
description="Revise Phase {phase} plans"
)Max iterations reached. {N} issues remain: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")GITHUB_ENABLED != trueISSUE_MODE = neverSkipping GitHub issue update (github.enabled=${GITHUB_ENABLED}, issueMode=${ISSUE_MODE})<offer_next># Get milestone version from ROADMAP.md (the one marked "In Progress")
VERSION=$(grep -E "^### v[0-9]+\.[0-9]+.*\(In Progress\)" .planning/ROADMAP.md | grep -oE "v[0-9]+\.[0-9]+(\.[0-9]+)?" | head -1 | tr -d 'v' || echo "")
# Fallback: try to find any version if no "In Progress" found
[ -z "$VERSION" ] && VERSION=$(grep -oE 'v[0-9]+\.[0-9]+(\.[0-9]+)?' .planning/ROADMAP.md | head -1 | tr -d 'v' || echo "")
if [ -z "$VERSION" ]; then
echo "Warning: Could not determine milestone version. Skipping GitHub issue update."
# Continue to offer_next (non-blocking)
fi
# Find phase issue number
ISSUE_NUMBER=$(gh issue list \
--label "phase" \
--milestone "v${VERSION}" \
--json number,title \
--jq ".[] | select(.title | startswith(\"Phase ${PHASE}:\")) | .number" \
2>/dev/null)
if [ -z "$ISSUE_NUMBER" ]; then
echo "Warning: Could not find GitHub Issue for Phase ${PHASE}. Skipping checklist update."
# Continue to offer_next (non-blocking)
fiPLAN_CHECKLIST=""
PLAN_COUNT=0
for plan_file in $(find "${PHASE_DIR}" -maxdepth 1 -name "*-PLAN.md" 2>/dev/null | sort); do
PLAN_NUM=$(basename "$plan_file" | sed -E 's/.*-([0-9]+)-PLAN\.md/\1/')
# Extract brief objective from plan (first line after <objective>)
PLAN_OBJECTIVE=$(grep -A2 "<objective>" "$plan_file" | head -2 | tail -1 | sed 's/^ *//' | head -c 60)
# Fallback if objective extraction fails
if [ -z "$PLAN_OBJECTIVE" ]; then
PLAN_OBJECTIVE=$(basename "$plan_file" .md | sed 's/-PLAN$//' | sed 's/-/ /g')
fi
PLAN_CHECKLIST="${PLAN_CHECKLIST}- [ ] Plan ${PLAN_NUM}: ${PLAN_OBJECTIVE}
"
PLAN_COUNT=$((PLAN_COUNT + 1))
done./scripts/update-issue-plans.py# Write checklist to temp file
printf '%s\n' "$PLAN_CHECKLIST" > /tmp/phase-plan-checklist.md
# SKILL_BASE_DIR should be set to the base directory from skill invocation header
# e.g., SKILL_BASE_DIR="/path/to/skills/plan-phase"
python3 "${SKILL_BASE_DIR}/scripts/update-issue-plans.py" "$ISSUE_NUMBER" /tmp/phase-plan-checklist.md \
&& GITHUB_UPDATE_SUCCESS=true \
|| echo "Warning: Script failed, but continuing (non-blocking)"
# Clean up
rm -f /tmp/phase-plan-checklist.mdISSUE_NUMBERPLAN_COUNT<offer_next><offer_next>| Wave | Plans | What it builds |
|---|---|---|
| 1 | 01, 02 | [objectives] |
| 2 | 03 | [objective] |