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".
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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 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 scripts/kata-lib.cjs read-config "github.enabled""false")
ISSUE_MODE=$(node 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 "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.
