Init Milestone — Bootstrap a Project with Milestone Records

Borderline cases (a flutter create or cargo init the user just ran): lean toward accepting. The scaffolding is generated, not authored — the design history hasn't started yet.

If the repo isn't greenfield:

"This repo already has substantive code or history, so I can't start the milestone record — the system needs to begin with the project to capture the full design history. Use /next-milestone to add milestones to an existing project."

Step 2 — Understand the target

The user provides [Initial target] — what they want to build. This might be one sentence or a detailed spec.

If the target is too vague to scope milestones, ask one clarifying question. If it needs more than one, ask the user to write a few more sentences about what they envision. Don't over-interview — the milestones themselves will force specificity.

Step 3 — Design the plan and milestones

Use plan mode (EnterPlanMode) if available. If plan mode isn't available in the current environment, design the plan inline in the conversation — the important thing is the content, not the tool.

The plan should include:

1. Project context — what the project is, who it's for, what problem it solves
2. Repo layout — planned directory structure with inline annotations
3. Key decisions — choices being locked in from the start, with the why (these are the decisions that future milestones will build on and that future agents need to understand)
4. Milestones M0–MX — the initial build order

Include additional sections (Architecture, State Machine, UI Style, etc.) when the project warrants them — match the complexity of the plan to the complexity of the project.

Milestone design guidelines

• M0 is scaffolding: project init, dependencies, empty modules, prove basic connectivity end-to-end. M0 should be trivially small — its job is to make the skeleton compile and pass a smoke test.
• M1–MX are features, ordered by dependency — build what later milestones need first.
• Each milestone should be independently shippable and testable.
• Keep milestones focused. Better to have 8 small milestones than 4 sprawling ones. A milestone that takes more than ~500 lines of diff is probably too big.
• The plan should read as a narrative — a stranger reading M0 through MX should understand not just what was built but why it's shaped that way.

Milestone format

- **MX — Title**: Dense paragraph describing the goal and approach.
  (a) concrete deliverable one
  (b) concrete deliverable two
  (c) concrete deliverable three
  **Out of scope:** things explicitly excluded from this milestone.

Conventions:

• Sort strictly by (major, minor) numerically: M4 → M4.5 → M4.10 → M5
• Sub-milestones MX.y are for follow-ups, polish, and scoped fixes to a parent MX
• Lettered deliverables (a) (b) (c) for scannable handoff to implementer agents
• Explicit **Out of scope:** line when there's ambiguity about what's included
• Include the why — future readers want reasoning, not just a diff description
• Follow-up milestones open with a sentence referencing the parent: "M3 introduced the WebSocket client; this milestone adds reconnect with exponential backoff because..."

Exit plan mode and present the complete plan to the user.

Step 4 — User approval

Show the full plan including all milestones. This is the only manual gate in the entire workflow. Wait for explicit approval.

If the user requests changes, revise and re-present. After two revision rounds, ask what's fundamentally off rather than nibbling at wording.

Step 5 — Write milestones.md and commit

After approval, write the plan to milestones.md at the project root. The file's sections should match what the plan designed — at minimum Context, Key Decisions, and Build Order, plus whatever other sections the project needs.

Commit the milestone record on its own, before any implementation:

git add milestones.md
git commit -m "docs: init milestone records"

This is the one commit that doesn't follow the MX: subject convention — it's the meta-commit that creates the tracking system itself. Every commit after this one uses the milestone prefix.

Step 6 — Offer to implement

Ask: "Milestone record is committed. Want me to start implementing from M0?"

• Yes → enter the implementation pipeline. Read references/implementation-pipeline.md for the full implement → verify → commit loop. Queue all milestones (M0 through MX) and work through them automatically — each implementation commit uses the MX: subject format.
• No → tell them to use /next-milestone when they're ready.

What this skill does NOT do

• It does not work on repos with existing code history. The record must start at project inception.
• It does not manage git branches or push to remotes. Branching and pushing are the user's responsibility.
• It does not skip the verifier, even for "simple" milestones.
• It does not delete or rewrite shipped milestones. The record is append-only.
• It does not implement milestones in the main thread unless the milestone is trivially small (a handful of lines, no new files) or the user explicitly asked to do it themselves.