milestone-lifecycle

source	shipped
name	milestone-lifecycle
description	Use when starting, completing, archiving, or transitioning milestones between project stages
type	colony
domains	["project-management","milestone-tracking","lifecycle"]
agent_roles	["keeper","chronicler","queen"]
workflow_triggers	["seal","init"]
task_keywords	["milestone","archive","wrap up","new milestone","transition"]
priority	normal
version	1.0

Milestone Lifecycle

Purpose

Full milestone lifecycle management: creation, completion, archival, and next milestone preparation. Tracks milestone state across phases and ensures clean transitions between project stages.

When to Use

• Starting a new milestone after the previous one completes or project begins
• All phases in a milestone are complete and ready for final review
• User says "new milestone", "complete milestone", "archive", or "wrap up vN"
• Before archiving to ensure all phases are properly documented
• Transitioning from one version/iteration to the next

Instructions

Create Milestone

1. Verify no active milestone exists (check .aether/data/milestone-state.json)
2. If a previous milestone exists, prompt to complete or archive it first
3. Create milestone record:

   {
     "id": "MS-{NN}",
     "name": "{user-provided name}",
     "version": "{semver if applicable}",
     "created": "ISO8601",
     "status": "active",
     "phases": [],
     "goals": ["{goal 1}", "{goal 2}"],
     "success_criteria": ["{criterion 1}"]
   }
   

4. Create directory: .aether/milestones/{NN}/
5. Write .aether/milestones/{NN}/MILESTONE.md with goals, scope, and success criteria
6. Update .aether/data/milestone-state.json to set this as the active milestone

Track Progress

1. As phases are planned and executed, update the milestone's phase list
2. Track per-phase status: planned, in-progress, complete, skipped, reverted
3. Compute milestone completion percentage: (complete / total) * 100
4. Report progress via aether status

Complete Milestone

1. Verify all phases are in terminal state (complete or skipped)
2. Run completion checklist:
   • All phases have LEARNINGS.md
   • All phase manifests are up to date
   • No open todos reference this milestone's phases
   • Tests pass on the final state
   • Documentation reflects the current state
3. Extract milestone-wide learnings (invoke learning-extractor --milestone {NN})
4. Generate milestone summary in .aether/milestones/{NN}/SUMMARY.md
5. Update status to complete with completion timestamp

Archive Milestone

1. Verify milestone is complete
2. Run learning-extractor --milestone {NN} if not already done
3. Compress all milestone artifacts into .aether/archive/{NN}/
4. Remove active phase directories (optional, controlled by --keep-phases flag)
5. Update .aether/data/milestone-state.json to clear the active milestone
6. Retain colony knowledge base entries (they are cumulative, not milestone-scoped)

Prepare Next Milestone

1. Review previous milestone's lessons and surprises
2. Scan .aether/data/todos.jsonl for promoted but unimplemented items
3. Review .aether/data/seeds.jsonl for triggered seeds
4. Present a "carry forward" list: items from the previous milestone that should inform the next
5. Invoke aether init or prompt user for new milestone goal

Key Patterns

• One active milestone: Only one milestone can be active at a time
• Terminal states only: A milestone can only be archived if all phases are terminal (not in-progress)
• Knowledge preservation: Archiving removes files but preserves colony knowledge base entries
• Carry-forward: Always surface unfinished items and lessons when transitioning milestones

Output Format

Milestone MS-02: "User Authentication & Profiles" -- CREATED
  Goals: OAuth login, profile management, role-based access
  Success criteria: Users can sign up, log in, edit profile, see role-appropriate content
  Directory: .aether/milestones/02/

Phase 1/5 complete (20%) | Phase 2 in-progress (40%)

Milestone MS-02 progress: 2/5 phases (40%)

Examples

# Create new milestone
> milestone-lifecycle create "User Authentication & Profiles"

# Check progress
> milestone-lifecycle progress

# Complete and archive
> milestone-lifecycle complete
> milestone-lifecycle archive