milestone
Skill0 starsChanged 40 days agoMITView on GitHub
Write or refresh milestone execution docs from the project's implementation plan — a folder per milestone with an overview, one small file per work package and an as-built record — and switch milestones between guided and swarm implementation. Use when the user asks to split a plan into milestones, phases or steps, to switch a milestone to guided or agent-swarm mode, or before implementing a milestone whose doc is still proposed, or approved but stale.
10 other projects use a version of this.
Adopted by
Most recently taken up by
- Jasenpan1987/multi-codetheir own version, first seen Nov 8, 2026
- ArcticFox2029/chamnantheir own version, first seen Nov 5, 2026
- omnigami-ai/milestonetheir own version, first seen Nov 1, 2026
- frbar/claude-skillstheir own version, first seen Oct 15, 2026
- zajca/pohunektheir own version, first seen Oct 13, 2026
- enjunear/skillstheir own version, first seen Oct 13, 2026
Other versions10 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 10
- ArcticFox2029/chamnan★ 10same name
- zajca/pohunek★ 9same name
- Eipi-Tong/agentic-coding-starter-kit★ 3same name
- ahamedzoha/atelier★ 2same name
- j4rk0r/claude-skills★ 2same name
- gihwan-dev/claude-code-gui★ 1same name
- Jasenpan1987/multi-code★ 1same name
- enjunear/skills★ 0same name
- frbar/claude-skills★ 0same name
- omnigami-ai/milestone★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository7 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- main-agent/CLAUDE.mdCLAUDE.md
- followupSkill
- implementSkill
- impl-planSkill
- sketchSkill
- walkthroughSkill
The file
We split this skill into the rules it gives an agent
10 rules. 0 are common, 3 are distinctive, and 7 are very specific to this project.
0
Common
Most of the 9 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 24
Follow the project's genre: when it has one (its _template.md, its section names, a split design-doc/implementation-record model) — map …
- Distinctive: line 65
Run the consistency checklist (below) against the skeleton and fix it before drafting.
- Very specific: line 80
No two work packages that After: leaves unordered share a file — within a doc, or across docs that can run alongside each other.
- Distinctive: line 81
Every contract is introduced in exactly one doc.
- Very specific: line 82
Every § reference exists in the plan.
- Distinctive: line 83
Every plan acceptance bullet is covered by the doc's criteria (for a split, by the pair together).
- Very specific: line 84
Every open overlapping ledger entry is in a WP's Ledger: field with a disposition, or was re-deferred.
- Very specific: line 85
Every [VERIFY] / register question has exactly one owning milestone, where it appears as a D<n> design question.
- Very specific: line 94
Write (or update) <milestones dir>/README.md from ${CLAUDE_SKILL_DIR}/templates/index.md, listing only docs that exist: Documents table (no …
- Very specific: line 110
Never change Status or Written against.
“Common” is measured: kept by at least 6 in 10 of the 9 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
/milestone — milestone execution docs
Arguments: $ARGUMENTS
Hard rules
- Read
${CLAUDE_SKILL_DIR}/../impl-plan/reference/doc-model.mdanddoc-authoring.md(same folder) first — doc roles, layout, status words and who changes them; convention detection, ids, header fields, links, content rules, style. Everything below assumes them. - Never edit a landed doc (
☑ landed). Point the user at a dated As-built correction or a new milestone instead. - Never touch an
in progressdoc except on an explicitrefresh <id>from the user — and then never change its Status — or viamode, which changes only itsExecutionfield (for the remaining WPs). - Never overwrite an existing doc wholesale — that's what
refreshis for. - Never commit. Suggest the commit message at the end.
- Never create the ledger or write entries by hand —
/followuponly. - Stay within the size budgets (doc-model, Milestone doc layout): overview 12 KB as the aim and 16 KB at most, each WP file ≤ 6 KB. Reference the plan by
§, put a decision's reasoning in one line, and split a WP that won't fit. - Keep every required template heading (an empty one says
None — <reason>) and leave out the ones the template marks Optional when they'd be empty; strip every<!-- guidance -->comment. The<Project obligation>placeholder becomes the Section profile's sections, or is removed when the profile is "Default sections only". - No work package introduces a dependency outside the plan's Stack. If one is needed, ask the user (what it does / the no-dependency alternative) before drafting, and edit Stack only on approval.
- Skeleton fields are the main agent's alone: dependencies, work-package file ownership, contracts, acceptance criteria, Section profile. Drafting subagents may object, never change them.
- Follow the project's genre when it has one (its
_template.md, its section names, a split design-doc/implementation-record model) — map this skill's sections onto theirs.
Load (every mode)
- Conventions profile per doc-authoring.md (print it in five lines on first use this session).
- The plan — header (incl.
Execution; missing →guided), Decisions, Stack, Conventions, Milestones section and dependency graph, Testing strategy, assumption register. No plan → stop and suggest/impl-plan. No testing strategy in the plan → ask the three-option testing question (smoke / detailed unit / TDD) once. - The milestone index (if any) and the header block of each existing milestone doc (Status, Depends on, Blocks, Execution, Written against).
- The ledger's open entries — grep the entry folder's front matter (doc-model "Finding entries"); never the generated index.
git rev-parse --short HEADand today's date.
Unless the mode is read-only: if the plan's Status is draft, ask once "Treat the plan as approved?" — yes sets approved (<date>); no stops with "review the plan first".
Dependencies come from each doc's Depends on, or from the plan's dependency graph for milestones without a doc.
Modes
| Arguments | Behavior |
| (none) | No milestone docs yet → all. Otherwise read-only: print a status table (id · doc · Status · Execution · Written against · blocked by) and suggest next. |
all | Just in time: write docs (steps A–E) only for milestones that can start soon — the first milestone in plan order that isn't landed or awaiting a check, the ones that can run alongside it, and at most two more beyond those whose dependencies are among them. Every other gate stays not written, and the report says /milestone next — or /implement, whose writer agent follows this skill's single-doc path for a startable milestone without a doc — writes it when it comes up. all --full writes every missing doc. Then the index. Existing docs are read into the skeleton as fixed rows; unlanded ones are listed with an offer to refresh. |
<id> | Case-insensitive, normalized to the project's scheme (m3 → M3). If it names a split parent (M3 with M3a/M3b): parallel halves → act on each; sequential → the first unlanded half. Then: no doc → write it (single-doc path below); proposed/approved → refresh; in progress (WP…) → report it as the active milestone and its first open WP; in progress (verification) → report it as active, with /implement <id> to finish it; awaiting user check → say so and suggest /implement <id> to confirm the checks; landed → refuse. Unknown id → list valid ids. |
next | If a milestone is in progress (WP…) or in progress (verification), report it (and its first open WP, if any) as active and stop. Report milestones awaiting user check as such and pass over them. Otherwise take the first milestone in plan order that isn't landed or awaiting a check and whose dependencies are landed or awaiting a check → write it (no doc) or refresh it. Also list other milestones eligible to run alongside. Nothing eligible: all landed → say so and suggest setting the plan implemented; else print the status table with blockers. |
mode <guided|swarm> <target> | Switch execution mode — see mode below. |
refresh <id> | proposed/approved docs: follow ${CLAUDE_SKILL_DIR}/reference/refresh.md. in progress: only on explicit user request — update sections per refresh.md steps 1–3, list the changes for the commit message, leave Status alone, skip approval. Landed: refuse. --autonomous (only when invoked by /implement swarm): refresh.md's Autonomous approval instead of asking. |
all — write the milestone docs
A. Skeleton (main agent)
Build one table covering every milestone being written before any doc is written, plus fixed rows for milestones that already have a doc (copied from it: header, WP file ownership, contracts — not regenerated) and plan-graph rows for the ones left not written (their dependencies and the files they are expected to touch, so ownership conflicts still show).
- id + slug; split proposals (a/b, parallel or sequential) — ask the user before splitting, since it changes the gate structure;
- Depends on / Blocks / Can run alongside;
Execution: the plan's default (existing docs keep theirs);- work packages
WP<n>.0…WP<n>.N(id form per doc-authoring):.0apply reviewer decisions, confirm entry criteria, and pre-edit the shared hotspots (package refs, project/solution files, registries) — no "before" evidence capture or slow end-to-end check in.0or any WP's Definition of done, those are acceptance criteria; no verification WP — the acceptance criteria are run once every WP is landed; each withAfter:, files owned,Model:andReview:(doc-model's rules) and gating notes — swarm-ready per doc-model's Execution modes, whatever the mode; - contracts introduced and consumed;
- acceptance criteria expanded from the plan gate (build/test gates first; repeat grep-able conventions);
- which
[VERIFY]tags / register questions each milestone owns (each becomes aD<n>design question); - a disposition for every open ledger entry whose
files:orareas:overlap, in theLedger:field of the WP that owns those files (resolved here / must not worsen / interacts — how); an entry no WP takes is re-deferred through/followup, not listed in the doc; - the Section profile: the index's existing one, or decide it now from the project's architecture (layer-named change sections, cross-cutting obligations such as tracing) — "Default sections only" if nothing warrants one.
Run the consistency checklist (below) against the skeleton and fix it before drafting.
B. Draft
Template: the project's own if it has one; else ${CLAUDE_SKILL_DIR}/templates/folder/overview.md, one ${CLAUDE_SKILL_DIR}/templates/folder/wp.md per work package (WP<id>.md) and ${CLAUDE_SKILL_DIR}/templates/folder/as-built.md. Status proposed; Written against = HEAD. A milestone whose dependencies haven't landed gets a Projected "What exists".
- Fewer than 4 docs to write: draft inline.
- 4 or more: launch
general-purposesubagents in parallel, ~5 docs each, with${CLAUDE_SKILL_DIR}/templates/drafter-brief.mdfilled in — the full skeleton table and Section profile go into every brief. Subagents can't ask the user; open points come back as Proposals or[VERIFY]tags. Resolve each skeleton objection: change the skeleton and patch the affected docs, or record why not under that doc's Risks.
C. Consistency pass (main agent)
Re-read every doc's header, work packages (incl. their Ledger: fields), contracts and criteria, and check:
- (
allonly) Every plan gate maps to exactly one doc or a declared a/b pair; the index lists the same set. - Depends on ↔ Blocks are symmetric; Can run alongside is symmetric; no cycles; matches the plan's dependency graph.
- No two work packages that
After:leaves unordered share a file — within a doc, or across docs that can run alongside each other. An extension of an earlier milestone's file is marked*(<owner>-owned — extended here)*and the owner is an ancestor. - Every contract is introduced in exactly one doc; every consumer depends (transitively) on the introducer.
- Every
§reference exists in the plan. - Every plan acceptance bullet is covered by the doc's criteria (for a split, by the pair together).
- Every open overlapping ledger entry is in a WP's
Ledger:field with a disposition, or was re-deferred; ledger links are relative paths to the entry files. - Every
[VERIFY]/ register question has exactly one owning milestone, where it appears as aD<n>design question. - WP ids are unique, sequential and in the doc-authoring form;
.0follows the convention and no WP is a verification step; every required template heading is present; no guidance comments remain; no WP uses a package outside Stack. - Every WP has
After:,Model:andReview:; eachModel: opusnames the unsettled design choice that earns it, and more than a third of a doc's WPs onopusis reported with the WPs to reconsider; theAfter:graph is acyclic and no chain in it is longer than 3 WPs beyond.0, and more than 5 WPs besides.0is reported as a split candidate (ask before splitting); manifests, project/solution files and registries are owned by.0or explicitly sequenced; every header hasExecution. - Size budgets hold (
wc -c): overview ≤ 16 KB (aim for 12; one trimming pass at most — the budget saves reading, and repeated trimming costs more than it saves), each WP file ≤ 6 KB. Over → cut restated plan text and long rationale first, then split the WP.
Fix what's fixable; report anything that needs the user.
D. Index
Write (or update) <milestones dir>/README.md from ${CLAUDE_SKILL_DIR}/templates/index.md, listing only docs that exist: Documents table (no status column), split semantics, parallelism matrix, Section profile. The dependency graph stays in the plan only.
E. Plan + report
- Only for gates whose doc was written in this run: fill the
_Execution doc:_link (the overview, in the folder layout) and set the gate status toproposed. Touch nothing else in the plan. - Report: docs written (path · overview KB · WP count · largest WP file KB), gates left
not written(just in time), skeleton objections and how they were resolved, new[VERIFY]tags, consistency issues left for the user, suggested commit messageAdd milestone docs <first>–<last>. - Close with: "Review the docs, then implement with
/implement next— it refreshes and approves each doc written ahead of time before starting (or run/milestone refresh <id>to review one yourself first)."
mode — switch guided ↔ swarm
Targets: <id> (one milestone; a split parent means both halves) · from <id> (every unlanded milestone from that id on, in plan order, and the plan's default) · all (every unlanded milestone and the plan's default).
- Resolve the targets; list landed ones as skipped. With
from/all, targets without a doc just inherit the new plan default. A single<id>without a doc → refuse and suggest/milestone <id>first, ormode … from <id>. - Switching to
swarm: run the Swarm-readiness check from${CLAUDE_SKILL_DIR}/reference/refresh.mdon each target — openD<n>questions are reported as a note here, not a failure (/implementasks them up front). A target that fails is not switched — report its failures with the fix (add anAfter:edge, move a file to.0, split a WP) and suggest/milestone refresh <id>to apply them. Switching toguidedneeds no check. - For each target that passes: set
**Execution:**— the commit message records the switch. For anin progressdoc say which WPs it applies to ((WP3.4–3.6)); landed WPs are unaffected. from/all: set the plan header's**Execution:**too.- Never change Status or
Written against; touch nothing else. - Report the switched / skipped / blocked targets and suggest the commit message
Switch <targets> to <mode> execution.
Single-doc path (<id>, next)
Same as all steps A–E for one milestone: the skeleton row is built fresh for the target; neighbours' rows come from their docs, or from the plan graph where they have none. Consistency checks 2–11 apply to the target and its direct neighbours. The index gains (or is created with) the new row only.
After this skill
/implement implements the docs; who changes which status from then on is doc-model's "Who changes what". Before starting implementation of a milestone whose doc is proposed, or approved but stale (doc-model's staleness rule), run refresh first, unprompted. Never refresh the doc you're currently implementing just because new commits exist.
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.

