| name | maestro-milestone-complete |
| description | Archive completed milestone and prepare for next |
| argument-hint | ["<milestone>"] |
| allowed-tools | ["ask_question","define_subagent","grep_search","invoke_subagent","manage_subagents","run_command","send_message","view_file","write_to_file"] |
Produces milestones/{M}/artifacts/ archive and specs/learnings.md knowhow entries.
Supports two milestone types: standard (advances to next milestone) and adhoc (self-contained, sets idle).
Pipeline position: downstream of maestro-milestone-audit (requires PASS verdict). Upstream of maestro-milestone-release (cut a release) or next milestone planning (maestro-analyze / maestro-plan).
<required_reading> @~/.maestro/workflows/milestone-complete.md </required_reading>
<deferred_reading>
Requires: /maestro-milestone-audit should have passed.
State files:
.workflow/state.json — artifacts[], milestones[] (with type field: "standard" | "adhoc"), current_milestone, milestone_history[].workflow/roadmap.md — milestone structure (standard milestones only; adhoc milestones may not have roadmap).workflow/milestones/{milestone}/audit-report.md — audit results
Archive flow steps (validation, directory archival, artifact history, knowhow extraction, state advancement, cleanup) are defined in workflow milestone-complete.md.
After knowhow extraction (step 4), scan learnings.md for promotion candidates:
High-frequency pattern detection: Scan all <spec-entry> entries with roles="implement" for keyword overlap (≥2 entries sharing keywords):
→ Ask: "Keyword '{keyword}' appears in {N} knowhow entries. Should this be promoted to a formal coding convention? (/spec-add coding)"
Convention drift detection: Compare executed task summaries against coding-conventions.md and architecture-constraints.md:
→ Ask: "Were any established conventions bypassed during this milestone? Should conventions be updated?"
Wiki island check: Auto-trigger wiki-connect --fix to link newly extracted knowledge.
If user confirms promotion, invoke view_file(AbsolutePath="<agy-skills-dir>/spec-add/SKILL.md") + execute inline (args: "<category> <content>") with promoted content, preserving original date and source traceability.
Adhoc milestone (D-008): When completing an adhoc milestone, skip roadmap snapshot and do not advance to next milestone. Set current_milestone = null, status = "idle". Adhoc milestones are self-contained — no successor in roadmap chain.
=== MILESTONE COMPLETE ===
Milestone: {milestone_id}
Status: ARCHIVED
Artifacts archived: {count}
Knowhow extracted: {count} entries
Next milestone: {next_id | "none (adhoc)"}
==============================
End the step by calling the CLI (no text block output):
maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
Status verdicts:
--concerns--reason| Condition | Suggestion |
|---|---|
| Cut a release | /maestro-milestone-release |
| Next milestone (standard) | /maestro-analyze or /maestro-plan 1 |
| View state | /manage-status |
<error_codes>
| Code | Severity | Condition | Recovery |
|---|---|---|---|
| E001 | error | Milestone identifier required | Check arguments |
| E002 | error | Audit not passed | Run maestro-milestone-audit first |
| E003 | error | Incomplete artifacts remain | Complete remaining work first |
| W001 | warning | Knowhow extraction produced 0 entries | Review milestone work for missed learnings |
| W002 | warning | Wiki-connect found unlinked knowledge islands | Run /manage-wiki --fix manually |
| </error_codes> |
<success_criteria>
Use when a topic needs structured multi-dimensional investigation before planning or decision-making
Generate formal specification package (Product Brief, PRD, Architecture, Epics) through 6-phase document chain
Use when exploring ideas, evaluating approaches, or needing multi-perspective analysis before implementation
Use when a confirmed plan is ready for implementation
Use when stress-testing a plan, idea, or requirement against codebase reality before brainstorming
Initialize project with auto state detection