/mz:lifecycle

Orchestrate the full milestone lifecycle: audit verification status, archive the current milestone, collect deferred items, and prepare the next version. Uses existing CLI tools (milestone audit, milestone archive, milestone create, roadmap list, roadmap add-phase) as the execution backbone while providing a guided interactive experience.

Note: This skill handles the entire end-of-milestone flow in a single entry point. When audit finds gaps, it proposes gap-closure phases and exits. When audit passes, it proceeds through archive, deferred item collection, and next-version preparation.

Reference @skills/init/design-system.md for visual output formatting. Reference @skills/shared/presentation-standards.md for content formatting rules. Reference @skills/shared/terminology.md for official term definitions.

Step 1: Display Banner

Output the stage banner:

+===============================================+
|  MEGAZORD > LIFECYCLE                         |
+===============================================+

Step 2: Load Context and Validate

Read .planning/megazord.config.json. If missing, display error and stop:

## Error

Project not initialized — no megazord.config.json found.

`/mz:init`

If config exists, continue loading:

• Read .planning/STATE.md for current position.
• Read .planning/ROADMAP.md for phase details.
• Read .planning/MILESTONE.md if it exists (for version detection and phase scope).

Determine the plugin path for CLI commands:

1. Read plugin_path from the config JSON.
2. If plugin_path is not set in config, try ~/.claude/plugins/mz. Check if ~/.claude/plugins/mz/bin/megazord.mjs exists.
3. If neither exists, display error and stop:

## Error

Plugin path not configured.

`/mz:settings` to set plugin_path, or `/mz:init` to re-initialize.

Parse the user's message (text after /mz:lifecycle) for arguments:

• --skip-audit -- bypass the audit step entirely (for informal projects)
• {version} -- specify the milestone version to archive (optional; auto-detected from MILESTONE.md if present)

Use the resolved {plugin_path} for all node {plugin_path}/bin/megazord.mjs commands below.

Step 3: Milestone Status Summary

LOCKED decision: Always show a milestone status summary before proceeding with any destructive action.

1. Run node {plugin_path}/bin/megazord.mjs tools roadmap list to get all phases.
2. Run node {plugin_path}/bin/megazord.mjs tools progress for overall progress.
3. Display a summary box:

+===============================================+
|  Milestone Status                             |
+-----------------------------------------------+
|  Version: {version}                           |
|  Total phases: {N}                            |
|  Completed: {M}/{N}                           |
|  Progress: {percentage}%                      |
|                                               |
|  ✓ Phase 1: {Name} — {functional_sentence}   |
|  ✓ Phase 2: {Name} — {functional_sentence}   |
|  ◆ Phase 3: {Name} — {functional_sentence}   |
|  ○ Phase 4: {Name} — {functional_sentence}   |
+===============================================+

Use status symbols (✓ complete, ◆ in progress, ○ pending) instead of [done] tags. Extract functional sentences from the phase Goal in ROADMAP.md — one line per phase, never a bare phase number.

4. If no version argument was provided:

   • Check .planning/MILESTONE.md for a version: field in frontmatter. If found, use it.
   • If no MILESTONE.md or no version field, prompt the user: "What version is this milestone? (e.g., v1.0):"

5. If no completed phases found, display error and stop:

## Error

No completed phases found. Complete at least one phase first.

`/mz:go` to execute the current phase.

Step 4: Audit (or Skip)

If --skip-audit was provided: Display note and jump to Step 6:

> Note: Skipping audit (--skip-audit).

If --skip-audit was NOT provided:

1. Check for existing MILESTONE-AUDIT.md in .planning/:

   • If found, read it and check the date in the file.
   • If the audit is recent (same day), offer to reuse:

     > Existing audit from {date} found. Reuse? (yes/re-run)
     

   • If user chooses "reuse" and audit passed, proceed to Step 6.
   • If user chooses "reuse" and audit has gaps, proceed to Step 5.

2. If no existing audit or user wants re-run:

   • Determine phase scope: Read MILESTONE.md for phases: field. If not available, use all completed phases from ROADMAP.md.
   • Run:

     node {plugin_path}/bin/megazord.mjs tools milestone audit --phases "{comma-separated phase numbers}"
     

   • Parse the JSON result.
   • Write the audit results to .planning/MILESTONE-AUDIT.md with version, date, status, and per-phase details.

Step 5: Handle Audit Result

If all_passed is true

Display passed box and proceed to Step 6:

+===============================================+
|  Milestone Audit: PASSED                      |
+-----------------------------------------------+
|  Phases verified: {N}/{N}                     |
|  All verification gates passed.               |
+===============================================+

If gaps found

Display gaps clearly with a per-phase status table:

+===============================================+
|  Milestone Audit: GAPS FOUND                  |
+-----------------------------------------------+
|  Phases verified: {passed}/{total}            |
|                                               |
|  Failed:                                      |
|  - Phase {N}: {Name} — {reason}              |
|  - Phase {M}: {Name} — No VERIFICATION.md    |
+===============================================+

Then propose gap-closure phases:

1. Group gaps by nature (missing verification, failed verification, etc.).
2. For each gap group, propose a new phase:

   node {plugin_path}/bin/megazord.mjs tools roadmap add-phase --description "{gap description}"
   

3. Display:

   > Gap-Closure Proposal
     {N} gap-closure phase(s) proposed to address these gaps.
     After completing them, re-run `/mz:lifecycle` to re-audit.
   
     Proposed phases:
     - Phase {X}: {description}
     - Phase {Y}: {description}
   
     Add these phases? (yes/no)
   

4. If user confirms:
   • Add phases via CLI tool.
   • Display next steps:

     ## Next Up
     
     **Plan gap-closure Phase {X}: {description}** — address audit gaps
     `/mz:plan {X}`
     
     <sub>`/clear` — start fresh context for the next step</sub>
     

5. EXIT -- Do NOT proceed to archive when gaps exist.

Step 6: Confirm Archive

Show what will be archived:

+===============================================+
|  Archive Confirmation                         |
+-----------------------------------------------+
|  The following will be archived:              |
|                                               |
|  ROADMAP.md    -> milestones/{ver}-ROADMAP.md |
|  REQUIREMENTS  -> milestones/{ver}-REQUIRE... |
|  phases/       -> milestones/{ver}-phases/    |
|  STATE.md      -> milestones/{ver}-STATE.md   |
|  Git tag: milestone/{version}                 |
+===============================================+

Check for duplicate archive: If milestones/{version}-ROADMAP.md already exists, display warning:

> Warning: Milestone {version} appears already archived.
  Proceeding will overwrite the existing archive.
  Continue? (yes/abort)

If no duplicate (or user confirms override):

Proceed with archive? (yes/no)

Step 7: Execute Archive

1. Run the archive via CLI:

   node {plugin_path}/bin/megazord.mjs tools milestone archive --version "{version}"
   

   Parse the JSON result to confirm archived files.

2. Additionally archive STATE.md manually (since archiveMilestone() does not archive STATE.md):

   • Read .planning/STATE.md
   • Write contents to .planning/milestones/{version}-STATE.md

3. Update MILESTONE.md status from "active" to "archived":

   • Read .planning/MILESTONE.md
   • Replace status: active with status: archived
   • Write back

4. Display archive confirmation:

   > Archive Complete
     {N} files archived to .planning/milestones/
     Git tag: milestone/{version}
   

Step 8: Collect Deferred Items

LOCKED decision: Collect deferred items from CONTEXT.md files; user selects which to carry forward.

1. Scan all .planning/phases/*/NN-CONTEXT.md files (glob pattern: .planning/phases/*/*-CONTEXT.md).
2. For each file:
   • Read the file content.
   • Extract text between <deferred> and </deferred> tags.
   • Parse bullet points (lines starting with - ).
   • Skip entries that are just "None", contain only "None", or match "None -- discussion stayed within phase scope".
3. Strip phase references from items -- present clean action items, not "Phase 6 (Agent Teams Integration)" prefixes.
4. If no deferred items found after filtering:

   > No deferred items found across phase contexts.
   

   Skip to Step 9.
5. If deferred items found, present numbered list:

   > Deferred Items from {version}
   
     1. Git worktree isolation for parallel agents
     2. Reviewer feedback loops during execution
     3. Auto-advance to next phase after completion
     4. Agent Teams review-fix loop with direct inter-agent communication
     5. Reviewer-executor real-time feedback via SendMessage
     6. Full clean code audit of entire codebase
   
     Select which deferred items to carry forward as requirements
     for the next milestone (comma-separated numbers, 'all', or 'none'):
   

6. Collect user selection. Parse response:
   • all -- carry forward everything
   • none -- carry forward nothing
   • 1,3,5 -- carry forward selected items

Step 9: Prepare Next Version

LOCKED decisions: Semver bump suggestion with user confirmation; config inherited as-is.

1. Suggest next version:

   • Parse current version string.
   • Suggest semver major bump by default (e.g., v1.0 -> v2.0).
   • Display:

     > Next Version
       Current: {version}
       Suggested: {suggestion}
     
       Next milestone version? (suggested: {suggestion}, or type a version):
     

2. Ask for milestone name:

   Milestone name? (e.g., 'Second Release'):
   

3. Confirm version and name with the user before proceeding.

Step 10: Reset State Files

1. Create fresh ROADMAP.md:

   # Roadmap: {project_name}
   
   ## Overview
   
   {project_name} - {next_version}
   
   ## Phases
   
   (No phases planned yet. Run `/mz:plan` to create a roadmap.)
   
   ## Progress
   
   | Phase | Plans Complete | Status | Completed |
   |-------|----------------|--------|-----------|
   

2. Create fresh STATE.md:

   # Project State
   
   ## Project Reference
   
   See: .planning/PROJECT.md
   
   **Core value:** {from archived STATE.md}
   **Current focus:** {next_version} - Ready for planning
   
   ## Current Position
   
   Phase: 0 of 0
   Plan: 0 of 0
   Status: Ready for planning
   Last activity: {today} -- Milestone {old_version} archived, starting {next_version}
   
   Progress: [                    ] 0%
   
   ## Performance Metrics
   
   (New milestone -- no metrics yet)
   
   ## Accumulated Context
   
   ### Decisions
   
   (None yet)
   
   ### Pending Todos
   
   (None yet)
   
   ### Blockers/Concerns
   
   (None)
   
   ## Session Continuity
   
   Last session: {today}
   Stopped at: Milestone {next_version} initialized
   Resume file: None
   Stash ref: None
   Last error: None
   

3. Create fresh REQUIREMENTS.md with selected deferred items as initial requirements:

   # Requirements: {project_name} {next_version}
   
   ## Requirements
   
   | ID | Description | Priority | Status |
   |----|-------------|----------|--------|
   {For each selected deferred item: | NEW-{NN} | {item text} | Medium | Pending |}
   
   (Requirements will be refined during `/mz:plan` roadmap creation.)
   

   If no deferred items were selected, the table has no rows (just the header).

4. Create new MILESTONE.md via CLI:

   node {plugin_path}/bin/megazord.mjs tools milestone create --version "{next_version}" --name "{name}" --phases ""
   

   Note: phases is empty because the new milestone has no planned phases yet. /mz:plan will populate them.

Step 11: Display Completion

+===============================================+
|  Milestone {old_version} Archived             |
+===============================================+
|  Archived: {N} files to milestones/           |
|  Git tag: milestone/{old_version}             |
|  Deferred items carried: {M} of {total}       |
|  Next milestone: {next_version} - {name}      |
+===============================================+

## Next Up

**Ready for {next_version}: {name}.** Create the roadmap and start planning.
`/mz:plan`

<sub>`/clear` — start fresh context for the next step</sub>

Error Handling

Error	Step	Action
Config missing	Step 2	Error box, suggest /mz:init. Stop.
ROADMAP.md missing	Step 2	Error box, suggest /mz:plan. Stop.
No completed phases	Step 3	Error: "No completed phases found. Complete at least one phase before running lifecycle." Stop.
Archive already exists	Step 6	Warning: "Milestone {version} appears already archived." Ask to proceed or abort.
Archive CLI fails	Step 7	Display error, suggest manual recovery. Stop.
No CONTEXT.md files found	Step 8	Skip deferred items: "No deferred items found."
Milestone create fails	Step 10	Display error with CLI output. State files already reset; suggest manual MILESTONE.md creation.

Notes

• All CLI commands use the resolved {plugin_path} pattern (from config or fallback ~/.claude/plugins/mz).
• ALWAYS use bun/bunx for JavaScript/TypeScript operations (never npm/npx).
• The skill does NOT auto-invoke /mz:plan after completion -- it suggests it as the next step (matches the verify pattern).
• Configuration (megazord.config.json) is inherited as-is per user decision -- no config review prompt on new milestone.
• The skill orchestrates existing CLI tools (milestone audit, milestone archive, milestone create, roadmap list, roadmap add-phase). It does NOT reimplement their logic.
• archiveMilestone() copies files (does not move). Originals remain for gap-closure context. The state reset (Step 10) replaces them with fresh skeletons.
• archiveMilestone() does not archive STATE.md. The skill handles this manually in Step 7.
• archiveMilestone() does not update MILESTONE.md status. The skill handles this in Step 7.
• Gap-closure iteration has no limit. The user runs /mz:lifecycle repeatedly until audit passes.
• Deferred items are extracted from <deferred> tags in CONTEXT.md files. Phase references are stripped for clean presentation.