Classifies a task's risk, creates a branch, plans and implements the change, writes tests, runs an Opus code review, and performs post-session maintenance.
/implement runs in the dev role, cost-attribution phase implementation — being in this phase means code is actually being written, tested, and reviewed.
/implement <ADDRESS> | <prompt> [@file…] [@spec-folder] [@repo…] [--no-commit] [--skip-costs] [--skip-feedback] [--enforce-model=<model>]
$ARGUMENTS resolves to one of two modes: keyed when a positional address is present — a <KEY>, or an @<path> naming a folder in the specs tree — and direct otherwise (free-text or @file). The keyed branch resolves through workflows-core:addressing §3, the same entry point /document uses.
/implement implements one Epic per run. When the resolved item already names a focus Epic (a bare Epic key — the folder's EPIC- prefix sets the altitude, never the kind it asserts, and a legacy folder with no prefix is placed by what it holds; no second positional is accepted), that Epic is the scope. A BRD container holds no Epic to implement and stops the run (IMPLEMENT_BRD_NOT_SLICED), naming each of its slices instead or, where it has none, /product-workflows:brd-split to carve one. That stop, and the folder read below, are taken only after the specs-repo preflight has settled the specs checkout's branch, so a stale plugin branch cannot hide a slice, an Epic or its artifacts. When the PRD is bare, a cheap folder read classifies it: a PRD with exactly one Epic sets that Epic as the scope automatically, unless the PRD folder also holds a flat specification.md — a broad PRD-level slice, which /design designs as one unit — in which case it asks which of the two to implement, with no recommendation; a PRD with two or more Epics renders a progress-aware picker — each row showing the Epic's own artifacts (specification.md but no design.md → ○ not started; design.md present but no block in implementation.md → ◐ in progress, selectable and where the default cursor lands, since a merged design is exactly what this command wants; an implementation.md holding at least one block (a file holding only its heading records nothing) → ● done, greyed and not default-selectable, and selecting it offers to implement again), plus, on the same condition as the one-Epic case above — only where the PRD folder also holds a flat specification.md — the explicit choice to implement one broad PRD-level slice instead, since without that file the slice is a unit nothing specified: with it, that choice counts against the prompt's four options, so the array names at most two Epics and lets you type the key of any other; without it, the array names at most three and lets you type any other; a PRD with no Epics offers to split with /product-workflows:epics first, or to implement a broad PRD-level slice. Selecting an Epic scopes that run only — there is no "next Epic" loop, because code-writing is heavy and branchy enough that each run targets one Epic.
All three run flags apply to this command. --skip-costs (or WORKFLOWS_SKIP_COSTS) skips Phase 7's session-cost entry, still advancing the checkpoint and dropping any deferred cost record a ceded /prompt-brainstorm or /prompt-grill-me run left pending in this session (workflows-core:run-flags §5 step 3) — see Session cost. --skip-feedback (or WORKFLOWS_SKIP_FEEDBACK) narrows Phase 4's maintenance step to bugs-only, dispatching defect-reporter in place of Agent 4 (impl-maintenance) — see Session feedback. --enforce-model=<model> (or WORKFLOWS_ENFORCE_MODEL) pins every dispatched agent in this run — risk-planner and code-review included, overriding their frontmatter Opus pin — to one model, bypassing the fallback chains model-routing/classification §2 and §2.1 otherwise select — see Model routing. In direct mode, the free-text <prompt> is protected the same way: a run flag forms a leading run — mixed, in any order, with this command's own --no-commit, an address/key and any @path token (workflows-core:run-flags §3 step 1) — before the prompt begins, or a trailing run at the very end, which may carry --no-commit and @path tokens too; a run flag in either position is stripped, one written inside the prompt itself is kept as prompt text.
/implement has 19 ## Phase headings. Rather than walk every one, the diagram below deliberately names none of them: it compresses the whole run into its two real decision points instead of naming each phase.
flowchart TD
IN["/implement"] --> C{"Classify complexity (model-routing)"}
C -->|SIMPLE · MODERATE| P1["Standard plan → approve"]
C -->|"SIGNIFICANT · HIGH-RISK (multi-source input floors here)"| P2["Opus risk-planner → approve"]
P1 --> BR["Branch + capture test baseline"]
P2 --> BR
BR --> G{"SIGNIFICANT · HIGH-RISK? (set at classification)"}
G -->|No| IMA["Implement"] --> TWA["test-writer — without running tests"] --> TS["Lint/build + verify vs baseline (fix loop)"]
G -->|Yes| IMB["Implement"] --> TWB["test-writer — before the review diff is captured"] --> RV["Opus code-review → triage (verify each finding) → review-fixer (gate before tests)"]
RV -->|review cleared| TS
TS --> MT["Post-impl maintenance (4 agents)"] --> RP["Final report"]
IN covers Phase 0 through Phase 1.8 — loading and classifying the input, the Phase 0.5 readiness pre-flight, clarification, and, only when the input is multi-source, the Phase 1.6 floor at SIGNIFICANT and the Phase 1.7 fan-out scan it triggers. BR covers Pre-Phase 3 (branch creation) and Pre-Phase 3.5 (test-baseline capture) together — the baseline is always captured immediately after branching and before any file is edited, on either path. G is not a new decision: it is the classification Phase 1.5 already made, drawn where the two paths part. IMA/TWA are Phase 3A and Phase 3.5's test-writer dispatch, which runs no tests; IMB/TWB are Phase 3B and its step 4a, which dispatches test-writer before the review diff is captured. RV is Phase 3B's review-triage-fixer sequence, which therefore sees code and tests together. TS runs lint/build, the test-baseliner verify against the captured baseline, and the fix loop — after RV clears on the reviewed path. A recorded test skip still runs lint/build and is reported, as described under Gates below. MT is Phase 4's four maintenance agents. RP is the Phase 5 Final Report — folded into it is Phase 4.5 (a silent no-op unless Phase 3B's review escalated spec/design conformance notes onto the source spec/design; otherwise its handoff outcome line appears in the report's own ### Spec/design conformance section), which runs between Phase 4 and RP and is not separately pictured. Two more phases sit in the same gap and are likewise not pictured: Phase 4.6, the code-repo handoff that commits the work and — behind a consent choice — pushes it and opens a pull request, and Phase 4.7, which appends this run's refs to implementation.md on a keyed run — in the folder of the unit it implemented: the Epic's, whether you named the Epic or the picker chose it, or the PRD folder's for a broad PRD-level slice. Two further terminal phases run after RP: Phase 6 (follow-up tasks) and Phase 7 (session cost, plus the terminal artifact commit).
Seven named subagents are dispatched: workflows-core:code-scanner (Phase 1.7, only when the input is multi-source — one code-scanner per repo, capped at 4 concurrent, plus a seeded round 2 for any theme round 1 left inconclusive), risk-planner (Phase 2B, SIGNIFICANT/HIGH-RISK only), test-baseliner (captured in Pre-Phase 3.5, verified again in Phase 3.5), test-writer (Phase 3.5, or step 4a of Phase 3B before the review diff is captured), code-review (Phase 3B), review-fixer (Phase 3B, only on a BLOCK or PASS WITH RECOMMENDATIONS verdict), and workflows-core:impl-maintenance (Phase 4). All but risk-planner and code-review run at the caller's detection_model — the Sonnet chain; those two keep their frontmatter Opus pin regardless of classification (unless --enforce-model overrides it). Beyond those seven, general-purpose agents are dispatched too: a read-only codebase-exploration subagent at Phase 2A, and at Phase 2B wherever Phase 1.7 did not run, on the same Sonnet chain; and Phase 4 dispatches three general-purpose agents (a documentation review, a knowledge-base review, and an instructions review) alongside impl-maintenance — all four in a single message, independent of each other.
- The resolved input itself — classified in Phase 0: free-text prose plus any
@pathtokens, each classified by inspection, with a key or specs folder resolved against$SPECS_PATHthroughresolve-address. A key that resolves to no folder stops the run, offering to re-enter it or cancel — it never falls through to a direct-prompt run. A key given while$SPECS_PATHis unset stops before it is resolved, naming the variable and offering to set it or cancel, since there is no tree to find it in; an@<path>address names its folder directly and runs without the variable. If the primary description is a design doc (/design's output) carrying unresolved open questions,/implementrefuses to proceed by default — a design must be decision-complete before implementation; overriding is logged in the Final Report. Aspecification.md-level open question is exempt, since the design phase is where those are meant to resolve. - Specs, for keyed runs. When Phase 0's address resolution finds no
specsat all,/implementprompts for one rather than planning blind. Direct-mode runs are exempt — the prompt or spec file supplied is the instruction. - Any in-scope
specification.md/design.md, gated on$SPECS_PATH's main (Phase 0). An unmerged one (an open pull request, not yet on main) is a hard stop, naming$SPECS_PATHexplicitly since/implementstands in a code repo, not the specs repo. An absent one is not a stop at all — the run behaves exactly as it did before this gate existed, and a direct-prompt run, which resolves no in-scope spec, is unaffected either way. This is the reverse of/design'sspecification.md, which stops on absence (see the/designpage). - The multi-source rule (Phase 1.6): more than one code repo, or any directory input (a PRD folder or a spec folder), floors classification at
SIGNIFICANT— overridable at plan approval — and triggers the Phase 1.7 fan-out scan in place of the single Explore subagent. A referenced directory that is missing, or that is neither a recognized folder type nor a git repo, is always surfaced to the user immediately and never silently skipped — the run asks whether to continue without it or stop. - An optional ARD (Phase 1.8, keyed runs only) —
status: noneskips;status: unmergedstops, naming$SPECS_PATHexplicitly;status: foundcarries its invariants as implementation guardrails, passed tocode-reviewasapplicable_ardon theSIGNIFICANT/HIGH-RISKpath (guidance only onSIMPLE/MODERATE, which has no review gate). - A clean working tree, or explicit consent to stash or proceed dirty, before Pre-Phase 3 creates the feature branch — never implemented directly on the default branch.
Code changes on a freshly created feature branch — named per the target repo's own documented convention, or <prefix>/<key>-<slug> as the fallback — committed in Phase 4.6 without asking, then pushed and opened as a pull request behind a three-option consent choice (push + PR recommended, push only, or neither). The commit subject ends with [<key>] — the key of the unit the run implemented, which the branch name carries too: the Epic's wherever it implements an Epic, even one the picker or the one-Epic path chose under a PRD address, and the PRD's for a broad PRD-level slice — and carries a Work-Item: trailer where that unit's folder has one, which is what lets /document and /release-notes find the work later. A run whose review or tests did not clear is committed like any other, and still offered for push and pull request under the same consent choice — a failed gate never downgrades what you are offered. What changes is the pull request itself: where one is opened it is a draft whose body leads with a DO-NOT-MERGE line naming the blocking fact. --no-commit skips the phase entirely and leaves everything in the working tree.
Four Phase 4 maintenance outputs, always collected together: a documentation update (or an explicit "no update required"), a knowledge-base entry, an instructions (CLAUDE.md) update, and an impl-maintenance Lessons Learned report. On a SIGNIFICANT/HIGH-RISK run with a spec/design in scope, unresolved missing/contradicts findings from code-review's conformance dimension are escalated as open-question notes written back onto the source specification.md/design.md (Phase 3B step 7.5) and, behind a consent choice, handed off onto the specs repo's main branch (Phase 4.5) — a silent no-op when nothing was escalated, which covers every SIMPLE/MODERATE run and every run with no spec/design in scope.
A structured Phase 5 Final Report (classification, branch, files changed, review verdict and triage, spec/design conformance, deferred items, next step); Phase 6 follow-up tasks for any qualifying manual or out-of-scope items; and Phase 7's session-cost entry plus the terminal commit of $SPECS_PATH's bounded session-artifact paths — never the code repo this run just changed.
Pre-Phase 3.5 captures a test baseline before any source file is edited, on both the SIMPLE/MODERATE and SIGNIFICANT/HIGH-RISK paths. On SIGNIFICANT/HIGH-RISK work, Phase 3B's Opus code-review runs before tests, never after — the plugin's invariant is that tests never run on risky work until the review returns a non-BLOCK verdict. Between the review and review-fixer, the orchestrator runs its own finding triage (workflows-core:finding-triage) — each finding verified at the location it names, kept or dismissed, every dismissal recorded with a reason that disposes of that finding's own claim; review-fixer is handed survivors only, and dismissed findings never reach it. review-fixer fixes BLOCKER and MAJOR findings; a BLOCK verdict gets one re-review after the fix cycle, and a still-BLOCK result stops the run rather than looping.
test-writer is mandatory for any code change; when no test framework is detected at all (no marker in test-baseliner's detection table qualified and the repository declares no test command of its own in its CI configuration, contributing guide or README) — and equally when every suite the capture actually ran aborted with no counts it could parse, which is not the same as the detected set and not the same as failing to start — the run asks the user to specify a command or explicitly skip (logged in the Final Report) rather than silently proceeding without tests. A skip is scoped to what was asked: the lint and build still run, only the test verification and its fix loop are dropped. That question is asked at Pre-Phase 3.5, where a supplied command is re-run as a capture and still becomes a real baseline — after the edits there is nothing left to baseline, so the answer the run already has is applied rather than asked for again. A repository with several test suites is not that case — test-baseliner baselines every one of them that table covers and test-writer writes against each stack the diff touches, and a repository where one of those suites could not be run is baselined PARTIAL: the suites that ran are still verified, and the Final Report names the ones that were not. The Phase 3.5 fix loop caps at two attempts; regressions still present after that are surfaced to the user rather than looped on, and so is a test this run itself wrote that fails — which is a new failure rather than a regression, and so moves no status of its own. A verify that compared nothing is surfaced too, rather than read as a pass.
Implement one Epic from a multi-Epic PRD whose specification and design are already merged:
/dev-workflows:implement EPIC-98760
The run resolves EPIC-98760 as the focus Epic, gates its in-scope specification.md/design.md on the specs repo's main branch, classifies the task (typically SIGNIFICANT once a merged design is in scope), delegates planning to risk-planner, creates a feature branch, captures the test baseline, implements, writes tests, runs the Opus code review and triage, verifies against the baseline, and closes with the four Phase 4 maintenance agents and the Final Report — recommending the next Epic, or /docs-workflows:document once every Epic under the PRD is implemented.
- Roles and phases — what the
devrole owns, including how an unmerged in-scope spec/design stops the run while an absent one does not. /design— the upstream command whose mergeddesign.md/implementgates on when it's in scope (a resolvedspecification.mdwith nodesign.mdyet is gated the same way, independently)./docs-workflows:document— the downstream command, run once every Epic under the PRD is implemented; it ships in the companiondocs-workflowsplugin and is documented there.- Model routing — the classification rules, the multi-source floor, and the Opus fallback chain
risk-plannerandcode-reviewresolve against. - Session cost, Session feedback, and Follow-ups — the terminal Phase 5–7 bookkeeping every run emits.
workflows-core:finding-triage— the triage step run betweencode-reviewandreview-fixer.workflows-core:ard-resolution— how the optional ARD is resolved and inherited as implementation guardrails.