impl-plan
Skill0 starsChanged 40 days agoMITView on GitHub
Write a gated implementation plan (master plan doc) for a new project or a large feature — goal/non-goals, decisions with rejected alternatives, pinned stack, annotated repo layout, spec sections, milestone gates, assumption register, conventions — then hand off to /milestone to split it into milestone docs. Use when the user runs /impl-plan <what to build> or asks to "write an implementation plan", "plan the build of X", or "create a roadmap".
1 other project uses a version of this.
Adopted by
Most recently taken up by
- listener-He/java-harness-agenttheir own version, first seen Oct 20, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- listener-He/java-harness-agent★ 16same 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
- milestoneSkill
- sketchSkill
- walkthroughSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 31
If the request above is empty, ask what to build before anything else.
- Distinctive: line 39
Use AskUserQuestion with options you inferred from discovery.
- Distinctive: line 47
Round 2: only for decisions that surfaced while drafting (and the plan filename on greenfield if the default doesn't fit).
- Distinctive: line 58
Every path in the layout tree names the milestone that introduces it.
- Very specific: line 59
Every [VERIFY] has a register row with an owner.
- Very specific: line 77
Ask before editing. Add or update its Documentation Workflow section (≈2 paragraphs.
≈ “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
/impl-plan — write the master implementation plan
Request: $ARGUMENTS
Hard rules
- Read
${CLAUDE_SKILL_DIR}/reference/doc-model.mdand${CLAUDE_SKILL_DIR}/reference/doc-authoring.mdfirst — doc roles and status words; convention detection, defaults, header fields, links, content rules and style. Everything below assumes them. - Follow the project's detected conventions; defaults apply only where the project has none.
- Never commit. Suggest the commit message at the end.
- The ledger is written only through
/followup(Skill tool), which also creates it on first use. Never hand-write ledger entries or its skeleton. - No new dependency enters the Stack section unapproved — ask with what it does and what the alternative without it looks like.
- Never silently rewrite an existing plan's §Decisions or the gate of a landed milestone; changes are dated, reviewed edits.
- At most two question rounds. Anything still open after that becomes a
[VERIFY]tag plus an assumption-register row with an owning milestone.
1. Discovery (≈15 reads max)
- Project
CLAUDE.md(especially Documentation Workflow),README.md, thedocs/listing. - Any existing plan (
docs/*plan*.md,docs/*IMPLEMENTATION*.md,docs/*roadmap*.md), milestone dir + index +_template.md, one sample milestone doc's headings. - Ledger — open entries only: grep the entry folder's front matter (doc-model "Finding entries"), never the generated index.
- Manifests for the real stack and versions (
*.csproj,*.sln,package.json,pyproject.toml,Cargo.toml, …) and the top-level source layout. git log --oneline -20,git rev-parse --short HEAD. Not a git repo → recommendgit initbefore planning (Written againstand/milestone refreshdepend on history); if the user declines, writeWritten against: n/aand refresh falls back to file dates.
If the request above is empty, ask what to build before anything else. If a plan already exists, ask one question: new companion plan / extend (append milestones and spec sections) / revise in place (dated edits; landed gates and §Decisions untouched unless the user names them).
2. Conventions profile
Resolve conventions per doc-authoring.md and print the five-line profile before writing anything. On greenfield say "defaults" per line so the user can object early.
3. Questions
Use AskUserQuestion with options you inferred from discovery; skip anything the request or existing docs already answer.
Round 1 (up to 4):
- Non-goals — multiSelect of plausible scope items to exclude.
- Open stack decisions — one per unresolved choice; for any new dependency state what it does and the no-dependency alternative.
- Testing approach — basic smoke tests (user's default) / detailed unit tests / TDD. Mark TDD "(Recommended)" for greenfield or multi-milestone plans.
- Default execution mode — guided: pause after each work package for review (Recommended) / swarm: parallel worktree agents wherever the parallelism allows. Milestone docs are swarm-ready either way; the mode can be switched per milestone later with
/milestone mode.
Round 2 only for decisions that surfaced while drafting (and the plan filename on greenfield if the default doesn't fit).
4. Draft
Write the plan from ${CLAUDE_SKILL_DIR}/templates/plan.md (or the project's existing plan structure when extending). Strip every <!-- guidance --> comment; leave out a section the template marks Optional when it would be empty, and keep every other heading (None — <reason>). Split the spec into as many numbered sections as the subsystems need and fix every § reference after renumbering.
Gate rules for the Milestones section:
M0is a runnable, testable skeleton plus the first frozen contracts.- Each milestone is independently demonstrable; its acceptance bullets are observable by a test or command.
- The dependency graph has no cycles and matches each gate's scope; say which milestones can run in parallel and why.
- A milestone likely to need more than 5 work packages, or an
After:chain more than 3 deep (not counting.0), is flagged in the plan as a split candidate (a/b), with whether the halves would be parallel or sequential. - Every path in the layout tree names the milestone that introduces it.
- Every
[VERIFY]has a register row with an owner.
Header: Status: draft, Execution: = the round-1 answer, Written against = HEAD.
5. Critique
Launch one general-purpose subagent (fresh context, so it doesn't share your blind spots) with ${CLAUDE_SKILL_DIR}/templates/critique-brief.md, filling in the placeholders. Apply its findings:
fix-in-place→ edit the plan.[VERIFY]+register→ tag inline, add the register row with an owner.follow-up→ candidates for step 6.ask-user→ batch into Round 2 if unused; otherwise tag each[VERIFY]with a register row and an owner, and list it in the step 8 report as an open decision.
6. Seed the ledger
Follow-up candidates include whatever comes after this plan — work that is visibly out rather than forgotten becomes Kind: deferred entries, not a plan section. If there are candidates, ask one multiSelect "Record these as follow-ups?" (entries can never be deleted, so confirm first). Invoke /followup once per confirmed item, with Origin naming the plan section (— plan review §N).
7. Wire the project CLAUDE.md
Ask before editing. Add or update its Documentation Workflow section (≈2 paragraphs; what it must say is in ${CLAUDE_SKILL_DIR}/reference/claude-md-section.md), naming:
- the plan path — doc-sync updates only the header status, gate status lines, and resolved
[VERIFY]tags/register rows; - the milestone dir and id pattern — the active milestone folder carries the checklist and an append-only as-built record of what differed; landed docs are frozen; implement with
/implement <id>(guided or swarm per the doc'sExecution; switch with/milestone mode), which refreshes docs written ahead of time first; - the ledger path and the
/followuprule; - anything doc-sync must not touch (spec docs, templates).
This section doubles as the declared conventions for future runs.
8. Hand-off
Report, briefly: plan path and line count; open [VERIFY] count; unresolved ask-user decisions; follow-ups recorded; suggested commit message Add implementation plan for <X>. If ask-user decisions remain, offer to settle them with /walkthrough before the question below.
Then ask: "Plan approved — generate the milestone docs now?" with options Yes, the next milestones (Recommended — /milestone all writes just in time: the ones that can start soon; the rest when they come up) / Every milestone doc now (all --full) / Not yet — I'll review first / Only M0 for now. On a yes, set the plan Status: approved (<date>) and invoke the milestone skill with all, all --full or M0. Its report ends by pointing at /implement next.
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.

