Manage milestones: new, complete, audit, gaps.
Manages project milestones by creating, completing, auditing, and generating gap-closure phases.
npx claudepluginhub sienklogic/towlineThis skill is limited to using the following tools:
templates/audit-report.md.tmpltemplates/stats-file.md.tmplYou are running the milestone skill. Milestones represent significant project checkpoints — a set of phases that together deliver a cohesive chunk of functionality. This skill handles the full milestone lifecycle: creation, completion, auditing, and gap analysis.
This skill runs inline for most subcommands, but spawns agents for audit.
Reference: skills/shared/context-budget.md for the universal orchestrator rules.
Additionally for this skill:
Milestones are the rhythm of the project. They force you to step back, verify everything works together, and create a clean snapshot before moving on. Never skip the audit — integration issues hide at milestone boundaries.
Parse $ARGUMENTS for the subcommand and optional version:
$ARGUMENTS format: {subcommand} [{version/name}]
Examples:
"new" → subcommand=new, arg=none
"new User Auth" → subcommand=new, arg="User Auth"
"complete v1.0" → subcommand=complete, arg="v1.0"
"complete 1.0" → subcommand=complete, arg="v1.0" (auto-prefix v)
"audit v1.0" → subcommand=audit, arg="v1.0"
"audit" → subcommand=audit, arg=current milestone
"gaps" → subcommand=gaps, arg=most recent audit
If no subcommand recognized: Show usage:
Usage: /dev:milestone <subcommand> [version]
Subcommands:
new [name] — Start a new milestone cycle
complete [ver] — Archive completed milestone
audit [ver] — Verify milestone completion
gaps — Create phases to close audit gaps
newStart a new milestone cycle with new phases.
Read current state:
Get milestone details via AskUserQuestion:
$ARGUMENTS, use it and skip the name questionDetermine phase numbering:
Mini roadmap session:
Run a condensed version of the /dev:begin questioning flow:
a. Ask about major components needed (via AskUserQuestion):
b. For each area, ask:
c. Generate phases from the areas:
Update ROADMAP.md: Append new milestone section:
---
## Milestone: {name}
**Goal:** {goal statement}
**Phases:** {start_num} - {end_num}
### Phase {N}: {name}
**Goal:** {goal}
**Requirements:** {list}
**Success criteria:** {criteria}
**Depends on:** {prior phases}
### Phase {N+1}: {name}
...
Create phase directories: For each new phase:
.planning/phases/{NN}-{slug}/
Update PROJECT.md (create if needed): Add milestone to the active milestones list:
## Active Milestones
### {name}
- **Phases:** {start} - {end}
- **Created:** {date}
- **Status:** In progress
Update STATE.md:
Commit if planning.commit_docs: true:
docs(planning): start milestone "{name}" (phases {start}-{end})
Confirm with branded output:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TOWLINE ► MILESTONE CREATED ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
**Milestone: {name}** — {count} phases
Phases:
{N}. {name}
{N+1}. {name}
...
───────────────────────────────────────────────────────────────
## ▶ Next Up
**Phase {N}: {name}** — start with discussion or planning
`/dev:discuss {N}`
<sub>`/clear` first → fresh context window</sub>
───────────────────────────────────────────────────────────────
**Also available:**
- `/dev:plan {N}` — skip discussion, plan directly
- `/dev:status` — see project status
───────────────────────────────────────────────────────────────
completeArchive a completed milestone and prepare for the next one.
Determine version:
$ARGUMENTS: use it (auto-prefix v if missing)Verify all phases are complete:
Read ROADMAP.md to find milestone phases
For each phase, check for VERIFICATION.md
If any phase lacks VERIFICATION.md:
Present the warning context: Unverified phases:
Use AskUserQuestion (pattern: yes-no from skills/shared/gate-prompts.md):
question: "{count} phases haven't been verified. Continue with milestone completion?"
header: "Unverified"
options:
- label: "Continue anyway" description: "Proceed despite unverified phases (not recommended)"
- label: "Stop and review" description: "Run /dev:review for unverified phases first"
Timestamp freshness check:
For each phase that has a VERIFICATION.md, compare its checked_at frontmatter timestamp against the most recent SUMMARY.md file modification date in that phase directory (use ls -t or file stats).
If any SUMMARY.md is newer than its VERIFICATION.md checked_at:
Use AskUserQuestion (pattern: stale-continue from skills/shared/gate-prompts.md):
question: "{count} phases were modified after verification. Re-verify or continue?"
header: "Stale"
options:
- label: "Re-verify" description: "Run /dev:review for affected phases (recommended)"
- label: "Continue anyway" description: "Proceed with potentially outdated verification"
Gather milestone stats:
# Get commit range for this milestone's phases
git log --oneline --since="{milestone start date}" --until="now"
# Count files changed
git diff --stat {first_milestone_commit}..HEAD
Collect:
Extract accomplishments: Read all SUMMARY.md files for milestone phases:
provides fields (what was built)key_decisions fieldspatterns fieldstech_stack unionArchive milestone documents:
Copy/create archive files:
.planning/milestones/{version}-ROADMAP.md — snapshot of ROADMAP.md at completion.planning/milestones/{version}-REQUIREMENTS.md — snapshot of REQUIREMENTS.md.planning/milestones/{version}-STATS.md — milestone statisticsStats file content:
Read skills/milestone/templates/stats-file.md.tmpl for the stats file format. Fill in all {variable} placeholders with actual data gathered in Steps 3-4.
Update PROJECT.md:
## Completed Milestones
### {name} ({version})
- **Completed:** {date}
- **Phases:** {start} - {end}
- **Key deliverables:** {summary}
Collapse completed phases in ROADMAP.md: Replace detailed phase entries with collapsed summaries:
## Milestone: {name} ({version}) -- COMPLETED
Phases {start}-{end} completed on {date}. See `.planning/milestones/{version}-ROADMAP.md` for details.
| Phase | Status |
|-------|--------|
| {N}. {name} | Completed |
| {N+1}. {name} | Completed |
Git tag:
git tag -a {version} -m "Milestone: {name}"
Commit:
git add .planning/milestones/ .planning/ROADMAP.md .planning/PROJECT.md .planning/STATE.md
git commit -m "docs(planning): complete milestone {version}"
Confirm with branded output:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TOWLINE ► MILESTONE COMPLETE 🎉
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
**{version}**
Stats:
- {count} phases, {count} plans
- {count} commits, {lines} lines of code
- {duration} days
Archived to: .planning/milestones/{version}-*
Git tag: {version}
───────────────────────────────────────────────────────────────
## ▶ Next Up
**Start the next milestone** — plan new features
`/dev:milestone new`
<sub>`/clear` first → fresh context window</sub>
───────────────────────────────────────────────────────────────
**Also available:**
- `/dev:status` — see project status
- `/dev:help` — see all commands
───────────────────────────────────────────────────────────────
auditVerify milestone completion with cross-phase integration checks.
Determine target:
Read all VERIFICATION.md files for milestone phases:
gaps_found statusesSpawn integration checker:
Display to the user: ◐ Spawning integration checker...
Spawn Task(subagent_type: "dev:towline-integration-checker") with:
You are towline-integration-checker. Perform cross-phase integration verification.
Milestone: {version or "current"}
Phases to check: {list of phase directories}
Instructions:
1. Read all SUMMARY.md files for the milestone phases
2. Build a dependency graph from provides/affects/requires fields
3. Verify integration points:
a. Every "requires" in a later phase is "provided" by an earlier phase
b. Every "affects" target still exists and hasn't been broken
c. No circular dependencies
d. No orphaned provides (things built but never consumed)
4. Check for:
- Broken imports/references between phases
- API contract mismatches
- Missing error handling at integration points
- Configuration inconsistencies
5. Return findings as a structured report
Check requirements coverage:
provides fieldsWrite audit report:
Create .planning/{version}-MILESTONE-AUDIT.md using the template:
Read skills/milestone/templates/audit-report.md.tmpl for the audit report format. Fill in all {variable} placeholders with actual data from the audit.
Report to user using branded banners:
If PASSED:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TOWLINE ► MILESTONE AUDIT PASSED ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
All phases verified, integration checks passed, requirements covered.
───────────────────────────────────────────────────────────────
## ▶ Next Up
**Complete the milestone** — archive and tag
`/dev:milestone complete {version}`
<sub>`/clear` first → fresh context window</sub>
───────────────────────────────────────────────────────────────
**Also available:**
- `/dev:milestone gaps` — address any minor issues first
- `/dev:status` — see project status
───────────────────────────────────────────────────────────────
If GAPS FOUND:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TOWLINE ► MILESTONE AUDIT — GAPS FOUND ⚠
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Found {count} gaps:
- {gap 1}
- {gap 2}
───────────────────────────────────────────────────────────────
## ▶ Next Up
**Close the gaps** — create fix phases
`/dev:milestone gaps`
<sub>`/clear` first → fresh context window</sub>
───────────────────────────────────────────────────────────────
**Also available:**
- `/dev:milestone complete` — proceed despite gaps
- `/dev:status` — see project status
───────────────────────────────────────────────────────────────
If TECH DEBT:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TOWLINE ► MILESTONE AUDIT — TECH DEBT ⚠
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Milestone functional but has {count} tech debt items.
───────────────────────────────────────────────────────────────
## ▶ Next Up
**Address tech debt or proceed**
`/dev:milestone gaps` — create cleanup phases
`/dev:milestone complete` — proceed as-is
<sub>`/clear` first → fresh context window</sub>
───────────────────────────────────────────────────────────────
gapsCreate phases to close gaps found during an audit.
Find most recent audit:
*-MILESTONE-AUDIT.md in .planning//dev:milestone audit first."Read audit report:
Prioritize gaps:
Group by priority:
Present to user:
Gaps from milestone audit:
Must fix ({count}):
- {gap}: {description}
Should fix ({count}):
- {gap}: {description}
Nice to fix ({count}):
- {gap}: {description}
Use AskUserQuestion (pattern: multi-option-priority from `skills/shared/gate-prompts.md`):
question: "Which gaps should we address? ({must_count} must-fix, {should_count} should-fix, {nice_count} nice-to-fix)"
header: "Priority"
options:
- label: "Must-fix only" description: "Address {must_count} critical/high gaps"
- label: "Must + should" description: "Address {must_count + should_count} critical through medium gaps"
- label: "Everything" description: "Address all {total_count} gaps including low priority"
- label: "Let me pick" description: "Choose specific gaps to address"
- If "Must-fix only": filter to must-fix gaps for phase creation
- If "Must + should": filter to must-fix + should-fix gaps
- If "Everything": include all gaps
- If "Let me pick" or "Other": present individual gaps for selection
Group into logical phases:
Update ROADMAP.md: Add gap-closure phases after the current milestone phases:
### Phase {N}: Fix {area} (gap closure)
**Goal:** Address gaps found in milestone audit
**Gaps addressed:**
- {gap 1}
- {gap 2}
**Success criteria:** All addressed gaps pass verification
Create phase directories:
.planning/phases/{NN}-fix-{slug}/
Commit:
docs(planning): add gap-closure phases from milestone audit
Confirm with branded output:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TOWLINE ► GAP PHASES CREATED ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Created {count} gap-closure phase(s):
- Phase {N}: {name}
- Phase {N+1}: {name}
───────────────────────────────────────────────────────────────
## ▶ Next Up
**Plan the first gap-closure phase**
`/dev:plan {N}`
<sub>`/clear` first → fresh context window</sub>
───────────────────────────────────────────────────────────────
**Also available:**
- `/dev:status` — see project status
───────────────────────────────────────────────────────────────
All subcommands update STATE.md:
new: Sets current milestone, resets phasecomplete: Clears current milestone, updates historyaudit: Notes audit status and dategaps: Updates phase count and roadmap infoReference: skills/shared/commit-planning-docs.md for the standard commit pattern.
All subcommands commit if planning.commit_docs: true:
new: docs(planning): start milestone "{name}" (phases {start}-{end})complete: docs(planning): complete milestone {version}audit: docs(planning): audit milestone {version} - {status}gaps: docs(planning): add gap-closure phases from milestone auditTags (complete only):
git tag -a {version} -m "Milestone: {name}"new: Create one from scratch (this is a fresh start)╔══════════════════════════════════════════════════════════════╗
║ ERROR ║
╚══════════════════════════════════════════════════════════════╝
No roadmap found.
**To fix:** Run `/dev:begin` or `/dev:milestone new` first.
Display:
╔══════════════════════════════════════════════════════════════╗
║ ERROR ║
╚══════════════════════════════════════════════════════════════╝
No phases found for this milestone.
**To fix:**
- For `complete`: Nothing to complete — add phases first.
- For `audit`: Nothing to audit — build phases first.
Display:
╔══════════════════════════════════════════════════════════════╗
║ ERROR ║
╚══════════════════════════════════════════════════════════════╝
Git tag {version} already exists.
**To fix:** Use a different version number (e.g., {version}.1).
Ask for alternative via AskUserQuestion.
complete warns but allows proceeding with user confirmationaudit treats unverified phases as gapsaudit may take longer due to integration checkingActivates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
This skill should be used when the user wants to "create a skill", "add a skill to plugin", "write a new skill", "improve skill description", "organize skill content", or needs guidance on skill structure, progressive disclosure, or skill development best practices for Claude Code plugins.