| 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
- Verify no active milestone exists (check
.aether/data/milestone-state.json)
- If a previous milestone exists, prompt to complete or archive it first
- 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}"]
}
- Create directory:
.aether/milestones/{NN}/
- Write
.aether/milestones/{NN}/MILESTONE.md with goals, scope, and success criteria
- Update
.aether/data/milestone-state.json to set this as the active milestone
Track Progress
- As phases are planned and executed, update the milestone's phase list
- Track per-phase status:
planned, in-progress, complete, skipped, reverted
- Compute milestone completion percentage:
(complete / total) * 100
- Report progress via
aether status
Complete Milestone
- Verify all phases are in terminal state (
complete or skipped)
- Run completion checklist:
- Extract milestone-wide learnings (invoke
learning-extractor --milestone {NN})
- Generate milestone summary in
.aether/milestones/{NN}/SUMMARY.md
- Update status to
complete with completion timestamp
Archive Milestone
- Verify milestone is
complete
- Run
learning-extractor --milestone {NN} if not already done
- Compress all milestone artifacts into
.aether/archive/{NN}/
- Remove active phase directories (optional, controlled by
--keep-phases flag)
- Update
.aether/data/milestone-state.json to clear the active milestone
- Retain colony knowledge base entries (they are cumulative, not milestone-scoped)
Prepare Next Milestone
- Review previous milestone's lessons and surprises
- Scan
.aether/data/todos.jsonl for promoted but unimplemented items
- Review
.aether/data/seeds.jsonl for triggered seeds
- Present a "carry forward" list: items from the previous milestone that should inform the next
- 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