cut-milestones
Skill2 starsChanged 19 days agoMITView on GitHub
Cuts an approved spec into ROADMAP milestones, each behind one measurable exit gate, with a dependency graph, and creates in the tracker only those ready to start, at most 3 open at once; or drafts one version milestone, named by its target month, for a release after the MVP. Use when the user asks to plan, cut, draft or split milestones — "cut milestones from the spec", "what are the milestones for the MVP", "split M4 in two", "plan 26.11", "plan 1.3". Not for filing a milestone's issues (use scope-issue) or closing one (use milestone-close).
In this repository16 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ask-teamSkill
- assemble-metaSkill
- brainstormSkill
- build-issueSkill
- frictionSkill
- milestone-closeSkill
- qa-reviewSkill
- review-benchSkill
- scope-commitSkill
- scope-issueSkill
- scope-mrSkill
- scope-specSkill
- setup-dream-teamSkill
- ship-itSkill
- triage-issueSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 2 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 24
Every milestone has a measurable exit criterion.
- Very specific: line 48
Leave each as a placeholder, <N days>, <max SERVFAIL %>, for the user to set.
- Very specific: line 52
Read the spec, the existing ROADMAP and the tracker milestones.
- Very specific: line 60
Create each milestone whose dependencies are all closed, in draft order until 3 M<n> milestones are open, through the host's tooling skill, …
- Very specific: line 66
Add workflow::future to every open issue already in a milestone whose Depends on: has an open milestone.
- Very specific: line 68
Add one ROADMAP row per M<n> milestone, created or planned, in the same table as existing ones, when a ROADMAP exists, a row is planned, …
- Distinctive: line 103
No earlier version milestone to copy the release criteria from → draft them for the user to edit: CI green on the release commit, upgrade …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
cut-milestones
Drafts milestones for the user to approve. Creates nothing in the tracker until the user sets the numbers.
- An open tracker milestone is not numbered
M<n>,YY.MMorv<major>.<minor>(SemVer past 1.0) → stop before drafting and tell the user the repo may not be set up for dream-team, namingsetup-dream-team.
Rules
- Every milestone has a measurable exit criterion.
- One milestone, one exit gate: a design review, a build test, or field evidence.
- Two gates → two milestones.
- Work deferred to "its own plan" or "before Mn" is a ROADMAP row. List it now.
- The first milestone is the cheapest proof the approach works.
- A first milestone that can disprove the approach is a kill-gate: its criterion names the redesign on failure.
- Milestones with no dependency between them are listed as parallel.
- The dependency graph is drawn as a mermaid flowchart below the ROADMAP table.
- A milestone is
M<n>: a capital M and a plain integer, no dash. - A milestone is created in the tracker only once every milestone in its
Depends on:is closed and fewer than 3M<n>milestones are open; until then it is aplannedROADMAP row, named by its title. - A version milestone is its target month
YY.MMwith no leading zero, such as26.11or27.5; in a SemVer repo past 1.0,v<major>.<minor>. - The milestone that completes the MVP carries
MVPin its title. - A split takes the next free
M<n>, never a letter. - Work spanning several milestones is a
Meta:issue perscope-issue, not a milestone. - An issue in a milestone with an open dependency carries
workflow::future; an issue in a ready milestone carries none.
Numbers
- Thresholds, durations and percentages in a criterion are product decisions.
- Leave each as a placeholder,
<N days>,<max SERVFAIL %>, for the user to set.
Steps
- Read the spec, the existing ROADMAP and the tracker milestones; the ROADMAP's path is what
<base directory>/../../references/repo-conventions.mdresolves. - Draft each milestone: title, exit criterion, gate type, what it depends on, and for each to be
created now a
<due date>placeholder, 2–4 weeks out (the appetite). A dependency that gates only the exit measurement goes in the exit criterion, as "on a commit with Mn closed". - Draw the dependency graph: which milestones run in parallel, what waits on what.
- Show the draft to the user. Stop until the user sets every placeholder.
- Create each milestone whose dependencies are all closed, in draft order until 3
M<n>milestones are open, through the host's tooling skill, numbered with the next freeM<n>, and for anM<n>milestone with the due date the user set as its tracker due date. Its description is three bullets:- **Exit:**,- **Gate:**,- **Depends on:**(milestones that must close before work can start, ornone). - Add
workflow::futureto every open issue already in a milestone whoseDepends on:has an open milestone. - Add one ROADMAP row per
M<n>milestone, created orplanned, in the same table as existing ones, when a ROADMAP exists, a row isplanned, two or moreM<n>milestones are open, or aDepends on:names an openM<n>milestone. A new ROADMAP gets a row for every openM<n>milestone andplannedrow. - Below a ROADMAP table with
M<n>orplannedrows, keep the dependency graph as a mermaid flowchart: one node per such row, labelled with its title, one edge perDepends on:entry. - Report the milestones created, the
plannedrows and the dependency graph.
ROADMAP row
- Columns:
#,Milestone,Status. #is the trackerM<n>, empty in aplannedrow.Milestoneis the title, thenExit:and the criterion, thenDepends on:and the titles of the milestones it waits on, ornone.Statusstartsnot startedin a created milestone's row andplannedin the others. Onlymilestone-closechanges it.
A field-evidence milestone gets its Evidence: issue when its issues are filed, per
scope-issue.
Version milestone
A release after the MVP: one headline feature, optional in flow mode, plus backlog.
- It needs no spec.
- Outside flow mode, its exit criterion: the headline issue closed.
- The project
CLAUDE.mdsaysVersion milestones release in flow mode.→ itsExit:is its due date, plus a headline as a target only when the user names one. - Its
Gate:bullet holds the release criteria. - Outside flow mode, a headline with a spec takes its gate from the spec in place of the issue close.
- A
YY.MMmilestone gets the last day of its month as its tracker due date:26.11→ 2026-11-30. - A
v<major>.<minor>milestone's criterion may add a ship-by date, left as a<ship-by date>placeholder; in flow mode the ship-by date is required and becomes its tracker due date. - Backlog issues join the milestone as they are filed and carry no criterion of their own.
- No earlier version milestone to copy the release criteria from → draft them for the user to edit: CI green on the release commit, upgrade from the previous version works, and in a SemVer repo no breaking change in a minor version.
- Steps 1–3 shrink to: read the tracker milestones; outside flow mode, ask the user for the headline issue; draft the one milestone.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

