@sienklogic/plan-build-run 2.0.0

package/plugins/pbr/skills/milestone/SKILL.md

@@ -0,0 +1,673 @@
+---
+name: milestone
+description: "Manage milestones: new, complete, audit, gaps."
+allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
+argument-hint: "new|complete|audit|gaps [version]"
+---
+
+# /pbr:milestone — Milestone Management
+
+You 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`.
+
+---
+
+## Context Budget
+
+Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
+
+Additionally for this skill:
+- **Never** perform integration checks yourself — delegate to the integration-checker subagent
+- **Minimize** reading audit and verification outputs — read only frontmatter and status fields
+- **Delegate** all cross-phase integration analysis to the integration-checker subagent
+
+---
+
+## Core Principle
+
+**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.
+
+---
+
+## Argument Parsing
+
+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: /pbr: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
+```
+
+---
+
+## Subcommand: `new`
+
+Start a new milestone cycle with new phases.
+
+### Flow
+
+1. **Read current state:**
+   - Read ROADMAP.md to see existing phases
+   - Read STATE.md for current position
+   - Read PROJECT.md if it exists (milestone history)
+
+2. **Get milestone details** via AskUserQuestion:
+   - "What's the name/goal for this new milestone?"
+   - "What are the major features or capabilities it should deliver?"
+   - If the user provided a name in `$ARGUMENTS`, use it and skip the name question
+
+3. **Determine phase numbering:**
+   - Find the highest phase number in the current ROADMAP.md
+   - New phases start at highest + 1
+   - Example: if phases 1-5 exist, new milestone starts at phase 6
+
+4. **Mini roadmap session:**
+   Run a condensed version of the `/pbr:begin` questioning flow:
+
+   a. Ask about major components needed (via AskUserQuestion):
+      - "What are the 2-5 major areas of work for this milestone?"
+
+   b. For each area, ask:
+      - "Any specific requirements or constraints for {area}?"
+
+   c. Generate phases from the areas:
+      - Each major area becomes a phase
+      - Order by dependency (foundations first)
+      - Include brief description and success criteria
+
+5. **Update ROADMAP.md:**
+   Append new milestone section:
+
+   ```markdown
+   ---
+
+   ## 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}
+   ...
+   ```
+
+6. **Create phase directories:**
+   For each new phase:
+   ```
+   .planning/phases/{NN}-{slug}/
+   ```
+
+7. **Update PROJECT.md** (create if needed):
+   Add milestone to the active milestones list:
+
+   ```markdown
+   ## Active Milestones
+
+   ### {name}
+   - **Phases:** {start} - {end}
+   - **Created:** {date}
+   - **Status:** In progress
+   ```
+
+8. **Update STATE.md:**
+   - Set current phase to the first new phase
+   - Update milestone info
+
+9. **Commit** if `planning.commit_docs: true`:
+   ```
+   docs(planning): start milestone "{name}" (phases {start}-{end})
+   ```
+
+10. **Confirm** with branded output:
+    ```
+    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+     PLAN-BUILD-RUN ► MILESTONE CREATED ✓
+    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    **Milestone: {name}** — {count} phases
+
+    Phases:
+    {N}. {name}
+    {N+1}. {name}
+    ...
+
+    ───────────────────────────────────────────────────────────────
+
+    ## ▶ Next Up
+
+    **Phase {N}: {name}** — start with discussion or planning
+
+    `/pbr:discuss {N}`
+
+    <sub>`/clear` first → fresh context window</sub>
+
+    ───────────────────────────────────────────────────────────────
+
+    **Also available:**
+    - `/pbr:plan {N}` — skip discussion, plan directly
+    - `/pbr:status` — see project status
+
+    ───────────────────────────────────────────────────────────────
+    ```
+
+---
+
+## Subcommand: `complete`
+
+Archive a completed milestone and prepare for the next one.
+
+### Flow
+
+1. **Determine version:**
+   - If provided in `$ARGUMENTS`: use it (auto-prefix `v` if missing)
+   - If not provided: ask via AskUserQuestion: "What version number for this milestone? (e.g., v1.0)"
+
+2. **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:
+       - Phase {N}: {name}
+       - Phase {M}: {name}
+
+     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 /pbr:review for unverified phases first"
+     - If "Stop and review" or "Other": stop and suggest the review commands for each unverified phase
+     - If "Continue anyway": proceed with warning noted
+
+   **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`:
+   - Warn: "Phase {N} ({name}) was modified after verification. The VERIFICATION.md may not reflect the current code state."
+   - List affected phases with their freshness details
+
+   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 /pbr:review for affected phases (recommended)"
+       - label: "Continue anyway"   description: "Proceed with potentially outdated verification"
+   - If "Re-verify" or "Other": suggest the review commands for affected phases and stop
+   - If "Continue anyway": proceed with warning noted
+
+3. **Gather milestone stats:**
+
+   ```bash
+   # 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:
+   - Total commits in milestone
+   - Total files changed
+   - Lines added / removed
+   - Duration (start date to now)
+   - Number of phases completed
+   - Number of plans executed
+   - Number of quick tasks
+
+4. **Extract accomplishments:**
+   Read all SUMMARY.md files for milestone phases:
+   - Collect `provides` fields (what was built)
+   - Collect `key_decisions` fields
+   - Collect `patterns` fields
+   - Collect `tech_stack` union
+
+5. **Archive 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 statistics
+
+   **Stats 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.
+
+6. **Update PROJECT.md:**
+   - Move milestone from "Active" to "Completed"
+   - Add completion date and version tag
+
+   ```markdown
+   ## Completed Milestones
+
+   ### {name} ({version})
+   - **Completed:** {date}
+   - **Phases:** {start} - {end}
+   - **Key deliverables:** {summary}
+   ```
+
+   - Move validated requirements from active to completed section
+
+7. **Collapse completed phases in ROADMAP.md:**
+   Replace detailed phase entries with collapsed summaries:
+
+   ```markdown
+   ## 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 |
+   ```
+
+8. **Git tag:**
+   ```bash
+   git tag -a {version} -m "Milestone: {name}"
+   ```
+
+9. **Commit:**
+   ```bash
+   git add .planning/milestones/ .planning/ROADMAP.md .planning/PROJECT.md .planning/STATE.md
+   git commit -m "docs(planning): complete milestone {version}"
+   ```
+
+10. **Confirm** with branded output:
+    ```
+    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+     PLAN-BUILD-RUN ► 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
+
+    `/pbr:milestone new`
+
+    <sub>`/clear` first → fresh context window</sub>
+
+    ───────────────────────────────────────────────────────────────
+
+    **Also available:**
+    - `/pbr:status` — see project status
+    - `/pbr:help` — see all commands
+
+    ───────────────────────────────────────────────────────────────
+    ```
+
+---
+
+## Subcommand: `audit`
+
+Verify milestone completion with cross-phase integration checks.
+
+### Flow
+
+1. **Determine target:**
+   - If version provided: audit that specific milestone
+   - If no version: audit the current milestone (most recent active)
+
+2. **Read all VERIFICATION.md files** for milestone phases:
+   - Collect verification results
+   - Note any `gaps_found` statuses
+   - Note any phases without verification
+
+3. **Spawn integration checker:**
+
+   Display to the user: `◐ Spawning integration checker...`
+
+   Spawn `Task(subagent_type: "pbr:integration-checker")` with:
+
+   ```
+   You are 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
+   ```
+
+4. **Check requirements coverage:**
+   - Read REQUIREMENTS.md
+   - For each requirement tagged for this milestone:
+     - Search VERIFICATION.md files for coverage
+     - Search SUMMARY.md `provides` fields
+     - Flag uncovered requirements
+
+5. **Write 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.
+
+6. **Report to user** using branded banners:
+
+   **If PASSED:**
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    PLAN-BUILD-RUN ► MILESTONE AUDIT PASSED ✓
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   All phases verified, integration checks passed, requirements covered.
+
+   ───────────────────────────────────────────────────────────────
+
+   ## ▶ Next Up
+
+   **Complete the milestone** — archive and tag
+
+   `/pbr:milestone complete {version}`
+
+   <sub>`/clear` first → fresh context window</sub>
+
+   ───────────────────────────────────────────────────────────────
+
+   **Also available:**
+   - `/pbr:milestone gaps` — address any minor issues first
+   - `/pbr:status` — see project status
+
+   ───────────────────────────────────────────────────────────────
+   ```
+
+   **If GAPS FOUND:**
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    PLAN-BUILD-RUN ► MILESTONE AUDIT — GAPS FOUND ⚠
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   Found {count} gaps:
+   - {gap 1}
+   - {gap 2}
+
+   ───────────────────────────────────────────────────────────────
+
+   ## ▶ Next Up
+
+   **Close the gaps** — create fix phases
+
+   `/pbr:milestone gaps`
+
+   <sub>`/clear` first → fresh context window</sub>
+
+   ───────────────────────────────────────────────────────────────
+
+   **Also available:**
+   - `/pbr:milestone complete` — proceed despite gaps
+   - `/pbr:status` — see project status
+
+   ───────────────────────────────────────────────────────────────
+   ```
+
+   **If TECH DEBT:**
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    PLAN-BUILD-RUN ► MILESTONE AUDIT — TECH DEBT ⚠
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   Milestone functional but has {count} tech debt items.
+
+   ───────────────────────────────────────────────────────────────
+
+   ## ▶ Next Up
+
+   **Address tech debt or proceed**
+
+   `/pbr:milestone gaps` — create cleanup phases
+   `/pbr:milestone complete` — proceed as-is
+
+   <sub>`/clear` first → fresh context window</sub>
+
+   ───────────────────────────────────────────────────────────────
+   ```
+
+---
+
+## Subcommand: `gaps`
+
+Create phases to close gaps found during an audit.
+
+### Flow
+
+1. **Find most recent audit:**
+   - Search for `*-MILESTONE-AUDIT.md` in `.planning/`
+   - If multiple, use the most recent
+   - If none: "No audit found. Run `/pbr:milestone audit` first."
+
+2. **Read audit report:**
+   - Extract all gaps and tech debt items
+   - Parse severity levels
+
+3. **Prioritize gaps:**
+
+   Group by priority:
+   - **Must fix** (critical/high): Blocking issues, broken integration, uncovered requirements
+   - **Should fix** (medium): Non-critical integration issues, important tech debt
+   - **Nice to fix** (low): Minor tech debt, optimization opportunities
+
+4. **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
+
+5. **Group into logical phases:**
+   - Group related gaps together (same subsystem, same files)
+   - Each group becomes a phase
+   - Name phases descriptively: "{N+1}. Fix {area} integration" or "{N+1}. Address {component} gaps"
+
+6. **Update ROADMAP.md:**
+   Add gap-closure phases after the current milestone phases:
+
+   ```markdown
+   ### 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
+   ```
+
+7. **Create phase directories:**
+   ```
+   .planning/phases/{NN}-fix-{slug}/
+   ```
+
+8. **Commit:**
+   ```
+   docs(planning): add gap-closure phases from milestone audit
+   ```
+
+9. **Confirm** with branded output:
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    PLAN-BUILD-RUN ► GAP PHASES CREATED ✓
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   Created {count} gap-closure phase(s):
+   - Phase {N}: {name}
+   - Phase {N+1}: {name}
+
+   ───────────────────────────────────────────────────────────────
+
+   ## ▶ Next Up
+
+   **Plan the first gap-closure phase**
+
+   `/pbr:plan {N}`
+
+   <sub>`/clear` first → fresh context window</sub>
+
+   ───────────────────────────────────────────────────────────────
+
+   **Also available:**
+   - `/pbr:status` — see project status
+
+   ───────────────────────────────────────────────────────────────
+   ```
+
+---
+
+## State Integration
+
+All subcommands update STATE.md:
+- `new`: Sets current milestone, resets phase
+- `complete`: Clears current milestone, updates history
+- `audit`: Notes audit status and date
+- `gaps`: Updates phase count and roadmap info
+
+---
+
+## Git Integration
+
+Reference: `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 audit`
+
+Tags (complete only):
+- `git tag -a {version} -m "Milestone: {name}"`
+
+---
+
+## Edge Cases
+
+### No ROADMAP.md exists
+- For `new`: Create one from scratch (this is a fresh start)
+- For others, display:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+No roadmap found.
+
+**To fix:** Run `/pbr:begin` or `/pbr:milestone new` first.
+```
+
+### Milestone has no phases
+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.
+```
+
+### Audit finds no gaps
+- Status: PASSED
+- Skip the recommendations section
+- Suggest proceeding to complete
+
+### Version already exists (tag collision)
+Display:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+Git tag {version} already exists.
+
+**To fix:** Use a different version number (e.g., {version}.1).
+```
+Ask for alternative via AskUserQuestion.
+
+### Partially verified milestone
+- `complete` warns but allows proceeding with user confirmation
+- `audit` treats unverified phases as gaps
+
+### Large milestone (8+ phases)
+- `audit` may take longer due to integration checking
+- Warn: "This milestone has {count} phases. The audit may take a few minutes."
+
+---
+
+## Anti-Patterns
+
+1. **DO NOT** skip the audit before completing — integration issues hide at boundaries
+2. **DO NOT** auto-complete milestones without user confirmation
+3. **DO NOT** create gap phases without user approval of priorities
+4. **DO NOT** delete audit reports — they're historical records
+5. **DO NOT** reuse version numbers — each milestone gets a unique version
+6. **DO NOT** modify code during milestone operations — this is project management only
+7. **DO NOT** collapse phases in ROADMAP.md before archiving — archive first, collapse second
+8. **DO NOT** skip the git tag — tags make milestone boundaries findable