agentleFS
emingoemingo/claude-skills/skills/impl-plan/SKILL.md

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

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    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.

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
  1. Distinctive:

    If the request above is empty, ask what to build before anything else.

    line 31
  2. Distinctive:

    Use AskUserQuestion with options you inferred from discovery.

    line 39
  3. Distinctive:

    Round 2: only for decisions that surfaced while drafting (and the plan filename on greenfield if the default doesn't fit).

    line 47
  4. Distinctive:

    Every path in the layout tree names the milestone that introduces it.

    line 58
  5. Very specific:

    Every [VERIFY] has a register row with an owner.

    line 59
  6. Very specific:

    Ask before editing. Add or update its Documentation Workflow section (≈2 paragraphs.

    line 77

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/impl-plan — write the master implementation plan

Request: $ARGUMENTS

Hard rules

  • Read ${CLAUDE_SKILL_DIR}/reference/doc-model.md and ${CLAUDE_SKILL_DIR}/reference/doc-authoring.md first — 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, the docs/ 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 → recommend git init before planning (Written against and /milestone refresh depend on history); if the user declines, write Written against: n/a and 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):

  1. Non-goals — multiSelect of plausible scope items to exclude.
  2. Open stack decisions — one per unresolved choice; for any new dependency state what it does and the no-dependency alternative.
  3. Testing approach — basic smoke tests (user's default) / detailed unit tests / TDD. Mark TDD "(Recommended)" for greenfield or multi-milestone plans.
  4. 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:

  • M0 is 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's Execution; switch with /milestone mode), which refreshes docs written ahead of time first;
  • the ledger path and the /followup rule;
  • 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.