Milestone

Milestone

Sharpen a phase of one project into a created milestone — an ordered checkpoint per the hierarchy defined in reference/pm-seam.md § Hierarchy, carrying a name, an optional target date, and a phase-level description; nothing more. This is a standalone utility skill, not a lifecycle stage: it runs the defining dialogue against template.md, then creates or retrofits the milestone via saveMilestone per reference/pm-seam.md. It creates no issues — filing issues into milestones is the lifecycle's and the breakdown stage's job.

Arguments

• $ARGUMENTS (optional, freeform) — any of the milestone's fields the user already knows: the target project (URL, ID, or name), the milestone name, a target date, and a description. Everything is optional at invocation; the dialogue prompts only for what's missing.

Workflow

1. Resolve the project. An explicit project in $ARGUMENTS wins. Otherwise default to .adlc/config.json's pm.project (when pm.provider is "linear" — the same detection the lifecycle stages use) and confirm that default with the user as part of step 4's draft. With no explicit project and no configured provider, fall back to the draft-only path in step 5 — the milestone becomes a local mirror file instead.
2. Pre-flight the checkpoint order. With Linear configured, call listMilestones(projectRef) per reference/pm-seam.md and show the project's existing milestones in order, so the user sees where the new checkpoint lands (always at the end — the seam exposes no reordering). The listing also fixes the new checkpoint's number: names follow the seam's § Hierarchy Naming rule (M<n>: <Name>), so the next checkpoint takes the next n; a checkpoint the user places mid-sequence in an already-numbered project is that rule's per-case question — next number, or renumber the siblings — never an automatic renumber. A same-name hit becomes a question, never a silent write: retrofit that milestone (its milestoneRef flows to step 5) or rename the new one.
3. Sharpen the template's parts, one question at a time, until each clears its bar in template.md:
   • Name — the M<n>: prefix from step 2's pre-flight, per the seam's § Hierarchy Naming, then 1–4 words, outcome-flavored: a state the project reaches ("M2: Beta", "M3: Coach can view"), never a task.
   • Description — 1–3 sentences of exit criteria: what "done" means for this phase. Spec-level detail is declined, not stored — it belongs on the milestone's issues per the seam's § Hierarchy.
   • Target date — optional; a single ISO date, skipped freely.
4. Draft against the template. Render the ingredients into the format defined in template.md — including the resolved project and where the checkpoint lands in the existing order — and present the draft for the user's approval. Iterate until approved. A worked example lives at example.md.
5. Create or retrofit the milestone.
   • Linear configured: call saveMilestone(projectRef, milestoneRef?, name, targetDate?, description?) per reference/pm-seam.md — no milestoneRef creates; the milestoneRef from a step 2 retrofit choice updates that milestone in place.
   • No PM configured: write the draft to .ai/product/milestones/<kebab-slug>.md (slug derived from the Name), creating directories as needed, and report the path. This is the only file write this skill makes.
6. Report. Give the user the milestone's URL, constructed per the seam's Provider Mapping (<project-url>/milestone/<milestoneRef>), and note that it sits at 0% until issues are filed into it.

Boundaries

• Never create or update the milestone before the user approves the draft — the approval gate in step 4 happens first, always.
• Never retrofit a milestone the user hasn't explicitly chosen to retrofit — a same-name hit is a question (step 2), and on create no update identifier is ever passed, per the seam's Provider Mapping footgun note.
• Never accept spec-level detail into the description — the milestone carries a phase-level description only; detail belongs on its issues.
• Never create issues or assign issues to the milestone here — that is the lifecycle's and the breakdown stage's job.
• This is not a lifecycle stage: no task card, no status changes, no /adlc:next hand-off. One milestone per run — deriving a project's full phase skeleton is the breakdown stage; repeat invocations are fine.

Done when

The approved milestone exists in the target project with its templated name, optional target date, and phase-level description (or, with no PM, as .ai/product/milestones/<kebab-slug>.md), and the user has its URL or path. Nothing else changed — no issues touched, no other milestones altered.