implement-dev-plan

Files (7)

• SKILL.md
• consistency-check.md · references/
• report-template.md · references/
• review-and-rework.md · references/
• skill-selection.md · references/
• subagent-brief.md · references/
• verification.md · references/

SKILL.md (first lines)

# implement-dev-plan — From Approved Plan to Reviewed, Uncommitted Implementation

## Core Principle

The plan already made the decisions: which files, which tasks in which order, which interfaces,
and which test proves which requirement. Implementation is where those decisions meet reality, and
reality pushes back — a signature does not fit, a test name is wrong for the framework, a spec
criterion turns out ambiguous once the code exists. This workflow exists so that every push-back
is **seen, decided by the user, and recorded**, instead of being absorbed silently into code that
no longer matches its plan. Three habits make that possible: nothing is trusted that the main agent
did not run itself, nothing changes in the plan except checkboxes and Change Log rows, and nothing
is committed — the user reviews the diff and decides what enters history.

The output is uncommitted code plus three documents:

| Artifact | Path | Purpose |
|---|---|---|
| Plan updates | `docs/plans/<slug>.md` | Ticked Todos, task `Status`, and Change Log rows — nothing else |
| Review report | `docs/reviews/YYYY-MM-DD-<branch>-<mode>.md` | Written by the review sub-agent per the reviewer skill's convention |
| Implementation report | `docs/implementation/<slug>.md` | Decisions, skills, results, deviations, review outcome |

`<slug>` is the plan's slug (`docs/plans/<slug>.md`); a plan-set part keeps its full file name.

**Explicit invocation.** This skill starts only when it was named — `/implement-dev-plan`,
`/cc-ai-dev:implement-dev-plan`, the name in the prompt, or a hand-off from `create-dev-plan`'s
closing step. A request that merely describes implementation work ("implement
docs/plans/<slug>.md", "setze den Plan um") is handled as an ordinary request without this
workflow.

## Flow Overview

```
Phase 0  Intake            — locate plan and spec, plan-set state, working tree, headless check
Phase 1  Consistency       — plan vs. spec vs. code; blocking findings become questions
Phase 2  Skill Discovery   — runtime skill list → candidates → user keeps / drops / adds
Phase 3  Skill Mapping     — task → skills table; user confirms or changes
Phase 4  Mode              — direct or sub-agents; parallel or sequential
Phase 5  Implementation    — per task: (brief →) implement → VERIFY → tick → Change Log
Phase 6  Review            — one sub-agent: tech-stack review + plan conformance → docs/reviews/
Phase 7  Rework Decision   — top findings; user selects; selected → Phase 5 → Phase 6 again
Phase 8  Report            — docs/implementation/<slug>.md; hand the diff to the user
```

## Critical Rules (read before every phase)

1. **Every decision goes through the structured question tool.** Use your runtime's tool for
   structured user questions (in Claude Code: `AskUserQuestion`), never a prose question. Each
   question carries 2–4 concrete options, the recommended one first and marked "(Recommended)",
   each with its consequence in one sentence. Where the user picks a set (skills, findings), use
   the tool's multi-select. Up to four *independent* questions per call; questions whose options
   depend on an earlier answer go in a later call. Every answer is recorded as a decision `D-n` with its origin for the
   report.

2. **Plan and spec are read-only, with three exceptions in the plan.** You may tick Todo
   checkboxes, set a task's `Status`, and append rows to the Change Log. You never rewrite a task,
   rename a planned test, or "correct" the plan to match what the code ended up doing — that is
   exactly the drift the Change Log exists to make visible. A plan-level problem is a question to
   the user, whose options include fixing the documents with `create-dev-plan`.

3. **Skills are discovered at runtime and actually loaded.** The skills that fit are taken from
   the skill list your runtime exposes *now* — never from memory of another project, never from
   names quoted in the plan. A skill not in that list cannot be invoked; a skill in it is what the
   user installed. The mapped skills are **binding, not advisory**: every one of them is loaded
   before the first line of that task's code — by you in direct mode, by the sub-agent in sub-agent
   mode, and the sub-agent proves it in its report. Confidence in your own knowledge of the stack
   is not a reason to skip one; it is the reason the rule exists. The user chose these skills so
   that the code follows their team's rules, not the model's habits, and the two differ in exactly
   the places nobody checks. A task implemented without all of its mapped skills loaded is not
   verified — it is redone (Phase 5.3, check 0).

4. **Trust nothing you did not run.** A sub-agent's "all tests green" is a claim. After every task
   you run the build and the full test command yourself, check the planned test names against the
   files and the passing set, and compare the changed files with the task's `Files`. Only then is
   a Todo ticked. This is the one place the workflow pays with time, and it is what makes the final
   matrix honest.

5. **Deviations never change behaviour; every deviation is a Change Log row.** Departing from the
   plan is allowed for a good technical reason (a signature that cannot compile as written, a test
   name the framework rejects) and never for scope (dropping an acceptance criterion, adding a
   feature). A deviation that changes what a spec ID means is not a deviation — it is a plan
   change and goes to the user as a question.

6. **Tests first, in Todo order, the ID stays in the name.** The plan's Todos begin with the
   Verifies tests for a reason: a test written before the code constrains it. The plan proposed a
   name for every test; the implementer may adapt it to the framework's or the project's naming
   convention, but the requirement ID stays part of the name (`it('AC-3: …')`,
   `Export_AC3_…`) — it is how the review finds the test for each matrix row without reading the
   whole suite. Every rename is a Change Log row (old → new, reason), because the plan's matrix
   still shows the old name and the reader must be able to follow it.

7. **Git is read-only for you.** `status`, `diff`, `log` — yes. `add`, `commit`, `stash`, `reset`,
   `checkout` — never; the user does those. Sub-agents get the same rule in their brief.

8. **Urgency waives nothing.** "Just implement it" is not permission to skip the consistency
   check, the skill selection, verification, or the review. Run the workflow at speed — batch
   independent questions, keep status messages short — never at reduced rigour.

## Precondition — Interactive User Required

This workflow has no non-interactive mode. Phases 1–4 and 7 need a person deciding; without one,
every default would be your choice standing in for the user's, applied to their codebase.

**Judge the run, not your message channel:** the precondition is unmet only when the whole run has
no user behind it — you were dispatched by a script, CI, cron, or another agent whose output is
consumed by a program.

**When it is unmet:** STOP immediately, before reading beyond what is needed to name the plan.
Reply `Blocked — interactive user required`, the plan path you were pointed at, and one line that
an interactive user can start this skill on that plan. Create no files, change no code.

## Phase 0 — Intake

1. **Locate the plan.** The user names a path, a slug, or just "the plan". Resolve to
   `docs/plans/<slug>.md`. Several plans and none named → ask which one (question tool, one option
   per plan, most recently modified first). Only a draft exists (`docs/draft/plan_*.md`) → STOP:
   a draft is not approved, its test names and interfaces are not frozen, and implementing it
   would leave nothing stable to verify against; point the user to the `create-dev-plan` gate. No
   plan at all → STOP and point to `create-dev-plan` (and `create-dev-spec` if there is no spec
   either). Never implement from a description of a plan.

From CreativeCodersTeam/ai-store, Apache-2.0.

More from CreativeCodersTeam/ai-store