Archive a completed milestone, preparing for the next version, marking a milestone complete, shipping a version, or wrapping up milestone work. Triggers include "complete milestone", "finish milestone", "archive milestone", "ship version", "mark milestone done", "milestone complete", "release version", "create release", and "ship milestone".
Archive a completed milestone, preparing for the next version, marking a milestone complete, shipping a version, or wrapping up milestone work. Triggers include "complete milestone", "finish milestone", "archive milestone", "ship version", "mark milestone done", "milestone complete", "release version", "create release", and "ship milestone".
metadata
{"version":"0.1.0"}
Mark milestone {{version}} complete, archive to milestones/, and update ROADMAP.md and REQUIREMENTS.md.
Purpose: Create historical record of shipped version, archive milestone artifacts (roadmap + requirements), and prepare for next milestone.
Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tagged.
<execution_context>
Load these files NOW (before proceeding):
You MUST create a release branch BEFORE proceeding. All milestone completion work goes on that branch.
# Determine version from user input or detect from project files# (version-detector.md handles detection across project types)
VERSION="X.Y.Z"# Set from user input or detection
Release branches always use the main/ working directory. Do NOT create a separate worktree for release work. Milestone completion is sequential admin work with no parallelism — a separate worktree adds complexity with no benefit.
Create the release branch in the current working directory. In bare repo layout, CWD is already main/. In normal repos, CWD is the project root. Both cases use the same command:
⚠ pr_workflow is enabled — creating release branch.
Branch: $RELEASE_BRANCH
All milestone completion commits will go to this branch.
After completion, a PR will be created to merge to main.
If PR_WORKFLOW=false OR already on a non-main branch:
Proceed with current branch (commits go to main or current branch).
GATE: Do NOT proceed until branch is correct:
If pr_workflow=true, you must be on release/vX.Y.Z branch
If pr_workflow=false, main branch is OK
All subsequent steps work in the current working directory. Do NOT cd to any other directory.
0.1. Pre-flight: Check roadmap format (auto-migration)
Read workflow-specific overrides for milestone completion. Also check and auto-migrate roadmap format if needed:
if [ -f .planning/ROADMAP.md ]; then
node "${CLAUDE_PLUGIN_ROOT}/skills/kata-complete-milestone/scripts/kata-lib.cjs" check-roadmap 2>/dev/null
FORMAT_EXIT=$?
if [ $FORMAT_EXIT -eq 1 ]; thenecho"Old roadmap format detected. Running auto-migration..."fifi
version_files: overrides version-detector.md auto-detection when non-empty
pre_release_commands: run after version bump, before archive (failures blocking)
Store for use in release workflow steps. See milestone-complete.md read_workflow_config step.
0.2. Generate release artifacts:
Proactively generate changelog and version bump. Use the functions defined in version-detector.md and changelog-generator.md. Run these steps using the exact function definitions from those references:
# 1. Get current version (version-detector.md: get_current_version)
CURRENT_VERSION=$(node -p "require('./package.json').version" 2>/dev/null || git describe --tags --abbrev=0 2>/dev/null | sed 's/^v//' || echo"0.0.0")
# 2. Get commits since last tag (version-detector.md: commit_parsing)
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo"")
if [ -n "$LAST_TAG" ]; then
COMMITS=$(git log --oneline --format="%s""$LAST_TAG"..HEAD)
else
COMMITS=$(git log --oneline --format="%s")
fi# 3. Categorize commits
BREAKING=$(echo"$COMMITS" | grep -E "^[a-z]+(\(.+\))?!:|BREAKING CHANGE:" || true)
FEATURES=$(echo"$COMMITS" | grep -E "^feat(\(.+\))?:" || true)
FIXES=$(echo"$COMMITS" | grep -E "^fix(\(.+\))?:" || true)
# 4. Determine bump typeif [ -n "$BREAKING" ]; then BUMP_TYPE="major"elif [ -n "$FEATURES" ]; then BUMP_TYPE="minor"elif [ -n "$FIXES" ]; then BUMP_TYPE="patch"else BUMP_TYPE="none"fiecho"CURRENT=$CURRENT_VERSION BUMP=$BUMP_TYPE"echo"FEATURES: $FEATURES"echo"FIXES: $FIXES"
Calculate next version using calculate_next_version from version-detector.md. Generate changelog entry using changelog-generator.md format. Update version in project files using update_versions from version-detector.md (if version changed).
question: "Review the release changes above. Approve?"
options:
"Approve" — Keep changes and proceed to verify readiness
"Edit changelog first" — Pause for user edits, then confirm
"Revert and skip release" — Undo release file changes, proceed to verify readiness without release artifacts
Check for audit:
Look for .planning/v{{version}}-MILESTONE-AUDIT.md
If missing or stale: recommend /kata-audit-milestone first
If audit status is gaps_found: recommend /kata-plan-milestone-gaps first
If audit status is passed: proceed to step 1
## Pre-flight Check
{If no v{{version}}-MILESTONE-AUDIT.md:}
⚠ No milestone audit found. Run `/kata-audit-milestone` first to verify
requirements coverage, cross-phase integration, and E2E flows.
{If audit has gaps:}
⚠ Milestone audit found gaps. Run `/kata-plan-milestone-gaps` to create
phases that close the gaps, or proceed anyway to accept as tech debt.
{If audit passed:}
✓ Milestone audit passed. Proceeding with completion.
Verify readiness:
Check all phases in milestone have completed plans (SUMMARY.md exists)
Present milestone scope and stats
Wait for confirmation
Gather stats:
Count phases, plans, tasks
Calculate git range, file changes, LOC
Extract timeline from git log
Present summary, confirm
Extract accomplishments:
Read all phase SUMMARY.md files in milestone range
# Push branch (use --head for bare repo layout where gh can't auto-detect)
git push -u origin "$CURRENT_BRANCH"# Collect all phase issues for this milestone
GITHUB_ENABLED=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-complete-milestone/scripts/kata-lib.cjs" read-config "github.enabled""false")
ISSUE_MODE=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-complete-milestone/scripts/kata-lib.cjs" read-config "github.issue_mode""never")
CLOSES_LINES=""if [ "$GITHUB_ENABLED" = "true" ] && [ "$ISSUE_MODE" != "never" ]; then# Get all phase issue numbers for this milestone# --state all includes already-closed issues (GitHub ignores redundant Closes #X,# but including them ensures PR body reflects all related work)# gh issue list --milestone only searches open milestones; use API to include closed
REPO_SLUG=$(gh repo view --json nameWithOwner --jq '.nameWithOwner' 2>/dev/null)
MS_NUM=$(gh api "repos/${REPO_SLUG}/milestones?state=all" --jq ".[] | select(.title==\"v{{version}}\") | .number" 2>/dev/null)
PHASE_ISSUES=""if [ -n "$MS_NUM" ]; then
PHASE_ISSUES=$(gh api "repos/${REPO_SLUG}/issues?milestone=${MS_NUM}&state=all&labels=phase&per_page=100" \
--jq '.[].number' 2>/dev/null)
fiif [ -z "$PHASE_ISSUES" ]; thenecho"Note: No phase issues found for milestone v{{version}}. This is expected for milestones without GitHub issues."fi# Build multi-line closes sectionfor num in${PHASE_ISSUES}; do
CLOSES_LINES="${CLOSES_LINES}Closes #${num}
"donefi# Create PR (--head required for bare repo worktree layout)
gh pr create \
--head"$CURRENT_BRANCH" \
--base main \
--title "v{{version}}: [Milestone Name]" \
--body "$(cat <<EOF
## Summary
Completes milestone v{{version}}.
**Key accomplishments:**
- [accomplishment 1]
- [accomplishment 2]
- [accomplishment 3]
## Release Files
[list version files that were updated]
- `CHANGELOG.md` — v{{version}} entry added
## After Merge
Create GitHub Release with tag `v{{version}}`.
## Closes
${CLOSES_LINES}
EOF
)"
Display:
✓ PR created: [PR URL]
After merge:
→ Create GitHub Release with tag v{{version}}
Offer to merge PR:
Use AskUserQuestion:
header: "Merge Release PR"
question: "PR is ready. Merge now?"
options:
"Yes, merge now" — merge and return to main
"No, I'll merge later" — leave PR open
If "Yes, merge now":
gh pr merge "$PR_NUMBER" --merge
Then update local state:
if [ "$WORKTREE_ENABLED" = "true" ]; then# Bare repo layout: update main/ worktree, reset workspace/ to workspace-base
git -C main pull
bash "${CLAUDE_PLUGIN_ROOT}/skills/kata-complete-milestone/scripts/manage-worktree.sh" cleanup-phase workspace "$PHASE_BRANCH"else
git checkout main
git pull
fi
If PR_WORKFLOW=false (on main):
Create tag locally:
Tag: git tag -a v{{version}} -m "[milestone summary]"
Ask about pushing tag
Post-release verification:
After the release PR is merged (or tag is pushed), offer active verification tasks.
Task menu loop: Present available tasks, execute the selected one, then re-present remaining tasks until the user exits.
Use AskUserQuestion:
header: "Post-Release Tasks"
question: "Release committed. What would you like to verify?"
options (show only uncompleted tasks):
"Run smoke tests" — Execute the project's test suite and report results
"Verify release artifacts" — Check version files, changelog entry, and git tag
"Check CI/CD status" — Show recent workflow runs and their status
User knows next steps (including need for fresh requirements)
If release workflow was run:
CHANGELOG.md updated with v{{version}} entry (reviewed and approved)
Version bumped in all detected project version files
GitHub Release created (if pr_workflow=false) OR instructions provided (if pr_workflow=true)
</success_criteria>
<critical_rules>
Load workflow first: Read milestone-complete.md before executing
Verify completion: All phases must have SUMMARY.md files
User confirmation: Wait for approval at verification gates
Archive before deleting: Always create archive files before updating/deleting originals
One-line summary: Collapsed milestone in ROADMAP.md should be single line with link
Context efficiency: Archive keeps ROADMAP.md and REQUIREMENTS.md constant size per milestone
Fresh requirements: Next milestone starts with /kata-add-milestone which includes requirements definition
</critical_rules>
$VERSION
"$f"
echo
"✓ $f contains $VERSION"
echo
"✗ $f missing $VERSION"
fi
done
echo
"=== Changelog Check ==="
"$VERSION"
echo
"✓ CHANGELOG.md has $VERSION entry"
echo
"✗ CHANGELOG.md missing $VERSION entry"
echo
"=== Git Tag Check ==="
"v$VERSION"
echo
"✓ Tag v$VERSION exists"
echo
"✗ Tag v$VERSION not found"
Report results. If mismatches found, use AskUserQuestion:
header: "Artifact Issues"
question: "Release artifact issues detected. How to proceed?"
options:
"Fix issues" — Correct the mismatches (update version files, create missing tag)
"Continue anyway" — Return to task menu
If "Fix issues": Apply fixes, commit, then return to task menu.
If "Check CI/CD status":
Query recent workflow runs:
gh run list --limit 3 2>/dev/null || echo"No CI/CD runs found (gh CLI not configured or no workflows)"
Report status. If failures found, use AskUserQuestion:
header: "CI/CD Failures"
question: "CI/CD failures detected. How to proceed?"
options:
"Investigate" — Show logs for the failed run (gh run view --log-failed)
"Continue anyway" — Return to task menu
If "Investigate": Display failure logs, then return to task menu.
If "Everything looks good": Proceed to step 9.
Loop behavior: After each completed task, remove it from the options and re-present the menu. When all three tasks have been run or user selects "Everything looks good", proceed to step 9.
