agentleFS
emingoemingo/claude-skills/skills/implement/SKILL.md

implement

Skill0 starsChanged 40 days agoMITView on GitHub

Implement the plan's milestones from their milestone docs. Guided mode works one work package at a time in this session — implement, stack review, commit, pause — and syncs docs when the milestone lands. Swarm mode runs parallel worktree agents, unattended by default, and resumes cleanly after interruptions. Use when the user says "let's start implementing M3", "implement the next milestone", "continue implementing", or asks to resume an interrupted implementation run.

192 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use setup-ts-deep-modules, ask-matt and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • liufeng1976Skill

    setup-ts-deep-modules

    Wire dependency-cruiser into a TypeScript repo so each package is a deep module — implementation hidden in subfolders, reachable only through its entry-point files. User-invoked.

    Also in 43 projects that use this

  • GoogleSkill

    ask-matt

    Ask which skill or flow fits your situation. A router over the skills in this repo.

    Also in 91 projects that use this

  • RoentekSkill

    loop-me

    Grill me about specs for the workflows I want to build, within this workspace.

    Also in 50 projects that use this

  • AWSSkill

    to-questionnaire

    Turn a decision you can't fully answer into a questionnaire for someone else to fill in.

    Also in 88 projects that use this

  • ryotaroh180105Skill

    claude-handoff

    Hand the current conversation off to a fresh background agent that picks up the work immediately.

    Also in 42 projects that use this

  • GoogleSkill

    to-spec

    Turn the current conversation into a spec and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.

    Also in 168 projects that use this

  • +3 more from google

The file

We split this skill into the rules it gives an agent

2 rules. 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 175 edited versions we read keep these.

  • 0

    Distinctive

    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. Very specific:

    Refresh and approve: every doc that is proposed, or approved but stale (doc-model's Staleness rule):

    line 56
  2. Very specific:

    When it ends, print the run report (as status does), leading with what needs the user.

    line 70

“Common” is measured: kept by at least 6 in 10 of the 175 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.

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

/implement — implement milestones from their docs

Arguments: $ARGUMENTS

Hard rules

  1. Read ${CLAUDE_SKILL_DIR}/../impl-plan/reference/doc-model.md first — doc roles, layout, status words and "Who changes what", WP markers, staleness, ledger kinds, execution modes. Not doc-authoring.md: that is for the skills that write docs.
  2. Write only the progress markers doc-model's "Who changes what" gives this skill, plus the plan's draft → approved when the user confirms it in preflight, and the approval of a doc written just in time (reference/jit.md). They are 1–3 line edits of values you already know; never re-read a doc to make them. Every other approval is /milestone refresh's, ledger entries are /followup's, everything evidence-backed is doc-sync's.
  3. Self-invocation gate. If Claude loaded this skill without the user typing /implement (e.g. "let's start implementing M7"), ask before anything else: "Implement <M> guided — one commit per work package, pausing after each, docs synced when it lands?" — and then run guided mode on that one milestone only. If resume finds swarm state (agent worktrees, unmerged agent branches), print the resume table and ask the user to type /implement instead. Swarm mode, all, ranges and --agents require the user's own /implement or an explicit request for the agent swarm.
  4. Committing is the job; nothing beyond it. Typing /implement (or a yes to rule 3) is consent to commit on the current branch: WP commits (which in guided mode carry their ledger entries and progress marker), --no-ff merges, integration fixes, reverts, doc-sync commits. Never push. Never amend, rebase, reset --hard, clean, checkout --/restore over uncommitted work, branch -D, worktree remove --force, or force anything else. Never edit or commit inside a submodule or any path outside the repo; a submodule pointer bump happens only when the user asks.
  5. Main stays green. Build and test after every commit or merge. If the branch can't be made green, halt the whole run and report.
  6. Stack reviewer before every code commit — WP commits, and the coordinator's own integration-fix and stub commits — using the agent the global CLAUDE.md "Agents" section prescribes for the stack (never hardcode the roster here). Brief it with the change, not the code: the repo or worktree path, the diff to review (git diff <base>...HEAD -- <paths>, or the uncommitted diff), the WP file, and the WP's Review: depth (full / light); it runs git itself. Launch it with an explicit model: opus for Review: full, sonnet for light — reviewers never inherit this session's model. No "Agents" section in the global or project CLAUDE.md → resolve it in preflight: use the generic reviewer agent and say so in the run plan; if it isn't installed either, stop and ask which agent to use.
  7. No package outside the plan's Stack. Guided: ask the user (what it does / the no-dependency alternative). Swarm: the WP is blocked until the user decides.
  8. Ledger ids are assigned only by the main session, through /followup, one at a time. Workers never touch docs or the ledger; doc-sync only appends Updates and flips statuses.
  9. Nothing survives a merge cycle among: notes to the coordinator in code, FU-TBD-* placeholders, TODO/FIXME/HACK without an FU id.
  10. Deferred criteria become ledger entries: a criterion moved to a later milestone → /followup with Kind: deferred, Revisit when: <that later milestone>.
  11. Branch hygiene without losing work: remove the worktree and delete the branch (git branch -d) of every WP that merged or never produced anything (git worktree unlock first if a dead process left it locked). A blocked or abandoned WP's branch holds unmerged work — keep it and list it in the run report.
  12. State lives in docs, git and worktrees — never only in context. Re-running /implement resumes (${CLAUDE_SKILL_DIR}/reference/resume.md).
  13. Keep this session's context small, and keep it for judgment. In swarm mode this session decides — eligibility, merges, conflicts, integration fixes, autonomous refreshes, follow-ups — and delegates everything that is only execution: workers implement every WP, .0 included, and a verification runner executes the acceptance commands (swarm.md §1). Builds, tests and scripts write to a log file and you print only the summary lines; never dump process listings, whole logs or whole docs. Read docs by section (Grep the headings, Read with offset/limit). Hand doc-sync and workers paths, shas and ids — not pasted content.
  14. Slow commands run guarded. No baseline run of slow end-to-end checks (packaging/consumer smoke, full screenshot runs) — the preflight baseline is the build and unit tests; slow checks run in the milestone's verification. Run a script as pwsh -NoProfile -File <script> *> <log> (or the shell's equivalent) in the background with a timeout of about 3× its usual duration and watch it with Monitor; on a timeout, stop its process tree, retry once, then report.
  15. Design and implementation never share a session. After the Approve … commit, swarm milestones run through the unattended loop (below); --step runs and guided milestones end the turn with "approved — /clear, then /implement to start" — resume picks it up. Every milestone gets a fresh coordinator session. The exception is a doc written just in time (reference/jit.md): a writer agent holds its design context, so this session approves it and goes straight on to implement it.

Modes

ArgumentsBehavior
(none)A milestone in progress (WP…) or in progress (verification) → resume it. Else a milestone in progress (awaiting user check) → handle it (below) first. Else → next.
statusRead-only: the run report (${CLAUDE_SKILL_DIR}/templates/run-report.md) regenerated from docs + git, plus stale/locked agent worktrees, kept blocked branches, and doc drift. Offers cleanup of merged/empty leftovers; does nothing without a yes.
nextFirst milestone in plan order that isn't landed, isn't awaiting a user check, and whose dependencies are landed or awaiting a user check.
<id>That milestone (normalized as in /milestone; a split parent means both halves). Landed → refuse. Awaiting a user check → handle it (below). A dependency not yet landed or awaiting a user check → list the blockers and stop (suggest next, or a range that includes them).
<id>..<id>Inclusive range in plan order. Every dependency outside the range must be landed or awaiting a user check — else list them and stop.
allEvery milestone not landed.
--agents NSwarm concurrency cap (default 4).
--model <m>The unattended coordinator's model (default opus) — passed to the loop as -Model. Workers and reviewers get theirs per WP.
--auto-approveJust-in-time docs only: don't ask their open D<n> questions — take each Proposal and record it as an autonomous decision (reference/jit.md). Docs written ahead of time still go through refresh.
--stepSwarm without the loop: run one milestone in this session, then stop with "<M> done — /clear, then /implement to continue".
--unattendedPassed only by the loop script — see Unattended.

Awaiting user check — print that milestone's interactive checks (exact command + what to look for) and ask whether the user has done them. Confirmed → pass the user's words to doc-sync as evidence, which ticks them and lands the milestone; commit Sync docs for <M>: user checks confirmed. Not yet → skip it; its dependents may still proceed.

Preflight (every run)

  1. Resume check first: derive state per reference/resume.md. If anything is in flight, print the resume table and ask "Resume?" before anything else.
  2. Clean tree: no modified or staged tracked files (git status --porcelain --untracked-files=no empty, .claude/worktrees/ aside — and except an interrupted guided WP the user chose to continue). Untracked files don't stop a run: name them once in the run plan, and stop only for one that sits inside a path a work package in scope owns (a merge would refuse to overwrite it). State the branch the run will commit to. Swarm: agent worktrees start from this HEAD only when Claude Code's worktree.baseRef setting is "head"; by default they start from the remote's default branch. So when origin/HEAD exists (git rev-parse -q --verify origin/HEAD) and git merge-base --is-ancestor origin/HEAD HEAD exits 1, say in the run plan that workers may start from a commit this branch doesn't contain and that setting worktree.baseRef to "head" avoids it (the brief's first step re-branches them meanwhile). No origin/HEAD, or any other exit code → nothing to say.
  3. Green baseline. Build and test commands from the project CLAUDE.md → the plan's Testing section → the active doc's first two acceptance criteria — never the slow end-to-end checks (rule 14). Empty .implement/logs/ first — what is there is an earlier run's scratch, and its briefs and scripts are not to be reused. Run the commands now, quietly (rule 13): red → stop. Running them here also surfaces permission prompts while the user is present — if they aren't allow-listed, warn that background workers will stall on prompts and suggest /fewer-permission-prompts.
  4. Plan exists (else suggest /impl-plan); draft → ask "Treat as approved?" — yes sets approved (<date>) (the one transition this skill owns).
  5. Docs exist for every milestone in scope that can start now — milestones are written just in time, so a later one may legitimately have none yet. A startable milestone without a doc → ${CLAUDE_SKILL_DIR}/reference/jit.md, started right after step 1 and before anything that waits on the user: a writer agent scans and then writes it while the user answers its questions, this skill approves it without a recheck (asking its open questions, or taking the Proposals with --auto-approve), and the run goes on to implement it. That doc skips steps 7 and 8. Never write milestone docs by hand.
  6. Mode per milestone: the doc's Execution → the plan's default → guided. In a mixed range, a guided milestone runs on its own; the swarm resumes once it is landed or awaiting a user check.
  7. Refresh and approve every doc that is proposed, or approved but stale (doc-model's Staleness rule):
    • Guided: interactive /milestone refresh <id>; commit Approve the <M> milestone doc (including any walkthrough log and ledger entries it produced, so the tree stays clean).
    • Swarm — one up-front design round: (a) run refresh steps 1–3 for every in-scope doc; (b) collect every undecided D<n> across them; (c) ask in AskUserQuestion batches of four — Proposal marked Recommended, plus "Decide autonomously"; (d) approve each doc, recording the user's answers as refresh.md §4 step 2 does (the overview's D<n> bullets) and "Decide autonomously" answers exactly as refresh.md's Autonomous approval does; commit Approve <first>–<last> milestone docs. Mid-run, when a later milestone becomes eligible and its doc is stale, run /milestone refresh <id> --autonomous, then re-run the swarm-readiness check on it.
    • Refresh recommends a rewrite → halt that milestone and its dependents; continue the rest of the graph.
  8. Swarm readiness for swarm milestones: the Swarm-readiness check in the milestone skill's reference/refresh.md, with undecided D<n> counted as failures here. Failure → offer guided mode for that milestone, or stop.
  9. Forbidden paths: git submodule status + .gitmodules paths, plus anything the project CLAUDE.md marks hands-off. They go into every brief.
  10. Run plan: milestones · mode each · how it runs (swarm: the unattended loop by default, or --step; guided: in a fresh session after this one) · the stack reviewer (rule 6 — say so when it is the fallback) · models: the coordinator's (swarm loop: Opus unless --model), each WP's worker (Sonnet unless the WP says opus) and reviewer (full → Opus, light → Sonnet) · first wave (swarm) or first WP (guided) · cap N · expected agent count (nested reviewer agents roughly double concurrent load). Print it and go on — the user typed /implement and can interrupt. Ask "Start?" only when the plan holds something they wouldn't expect: the fallback reviewer, a milestone that has to run guided, a readiness failure, a worktree-base warning (self-invoked runs already asked in rule 3).

Unattended (the default for swarm)

From the interactive session, after preflight and the design round's Approve … commit:

  1. Start the loop detached, so it outlives this session and no background-task time cap kills it mid-milestone: on Windows Start-Process pwsh -WindowStyle Minimized -ArgumentList '-NoProfile','-File','${CLAUDE_SKILL_DIR}/scripts/implement-loop.ps1','-Scope','<the scope typed>' (plus '-Model','<m>' when --model was given; the script defaults to Opus); elsewhere nohup pwsh -NoProfile -File … >/dev/null 2>&1 &. Tell the user how to stop it (… implement-loop.ps1 -Stop ends it after the current milestone) and that closing this session doesn't.
  2. Watch .implement/loop/loop.log with Monitor (re-arm it when it expires) and relay each RUN / DONE / FAIL / INTERRUPTED / LIMIT / NEEDS YOU / ALL DONE / STOP / END line as one line. Also send one PushNotification for a NEEDS YOU, STOP or ALL DONE line, leading with what the user must do (load the tool with ToolSearch if it isn't listed; carry on without it if it is unavailable). Never read the run's runs/<start time>-<scope>/run-<n>.jsonl streams unless a run failed and the user asks; history.jsonl has one summary line per session (result, minutes, cost per model, agents launched, session id).
  3. When it ends, print the run report (as status does), leading with what needs the user.

A session started with --unattended (only the loop does that):

  • Never asks. Resume without asking (skip resume step 0 — the loop's own lock names your parent). A startable milestone without a doc → reference/jit.md (writer agent, Proposals taken); docs written ahead of time that need refresh or approval → /milestone refresh <id> --autonomous. Anything "never autonomous" (swarm.md §4) → blocked with a "needs user" follow-up. A guided milestone, modified tracked files outside .claude/worktrees/ and .implement/, or swarm state it can't classify → stop with needs-user.
  • Never ends a turn while a worker is running — it waits in the foreground (swarm.md §2). A turn that ends with a worker still out kills the session about ten minutes later.
  • Exactly one milestone: the first in scope that is in progress, else the next eligible one. Run it to landed or awaiting user check (never wait for interactive checks), or to a stop condition.
  • Before ending, write .implement/loop/state.json: {"milestone": "<M>", "result": "landed|awaiting-check|needs-user|blocked|red|limit|all-done", "sha": "<HEAD>", "summary": "<one line>", "needsUser": ["FU-NNN — <question>"], "resetAt": "<ISO time or null>"}. Nothing eligible → all-done. A usage limit → swarm.md §5's salvage, then limit with the reset time if known. Then end — never start the next milestone.

Run

  • Guided milestones: ${CLAUDE_SKILL_DIR}/reference/guided.md.
  • Swarm milestones: ${CLAUDE_SKILL_DIR}/reference/swarm.md (worker brief templates/agent-brief.md, worker report templates/wp-report.md).

End of run

  1. Each milestone's verification (once every WP is landed; guided: run by this session, swarm: delegated per swarm.md §1): run every acceptance criterion; anything unmet that belongs to a later milestone → rule 10; interactive-only criteria → offer the checks now, otherwise doc-sync sets awaiting user check; doc-sync lands what qualifies. This is the milestone's only doc-sync, in either mode (a swarm run that stops early syncs what is merged — swarm.md §3 step 6).
  2. No separate final doc-sync. Each landing doc-sync also updates the project CLAUDE.md status lines and README; the one that lands the plan's last gate sets the plan header implemented (only with Definition-of-done evidence and no open deferred entry naming a landed milestone).
  3. Whole-tree gates: git grep -nE 'NOTE FOR|FU-TBD' -- . ':!.claude' ':!docs' → nothing; no worktree or worktree-agent-* branch remains for a merged or empty WP (kept blocked branches, and empty harness branches git refused to delete, are listed instead).
  4. Run report from ${CLAUDE_SKILL_DIR}/templates/run-report.md, in chat. Lead with what needs the user: interactive checks with exact commands, decisions marked "needs user", blocked work, decisions to review grouped by Kind.

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.