create-dev-plan

Files (6)

• SKILL.md
• codebase-survey.md · references/
• plan-template.md · references/
• spec-review.md · references/
• task-design.md · references/
• traceability.md · references/

SKILL.md (first lines)

# create-dev-plan — From Approved Specification to Reviewed Development Plan

## Core Principle

A plan is the contract between the specification and whoever implements it one task at a time.
The person or agent who picks up Task #4 has not done Tasks #1–3 and will not read the spec end
to end. The plan has to tell them what already exists, what they consume, what they must deliver,
and which test proves it. Two things make that possible: every decision in the plan traces back
to a requirement ID or to a recorded clarification, and nothing that shapes the plan is guessed —
a gap in the spec becomes a question, and the user has the final say at a gate. A plan built on
assumptions is the most common cause of rework; this workflow exists to prevent it.

The output is two files:

| Artifact | Path | Purpose |
|---|---|---|
| Draft | `docs/draft/plan_<slug>.md` | Everything decided so far, written for review |
| Plan | `docs/plans/<slug>.md` | The final document, produced only after explicit approval |

`<slug>` is the spec's slug (`docs/specs/<slug>.md`). For a raw requirement without a spec it is
decided in Phase 2. When the spec is cut into several plans (Phase 2, `C-scope`), each part is
`docs/plans/<slug>-<n>-<part>.md` and every part carries the same *Plan Set* table.

**Explicit invocation.** This skill starts only when it was named — `/create-dev-plan`,
`/cc-ai-dev:create-dev-plan`, the name in the prompt, or a hand-off from another skill such as
`implement-dev-plan`. A request that merely describes plan-shaped work ("break this into tasks",
"Entwicklungsplan erstellen") is handled as an ordinary request without this workflow.

## Flow Overview

```
Phase 0  Intake           — classify the input; complete spec or not; headless check      (step 1)
Phase 1  Spec Review      — read everything, classify every requirement, list the gaps     (steps 2–3)
Phase 2  Clarification    — one structured question per blocking gap; scope decision       (step 4)
Phase 3  Codebase Survey  — constraints, conventions, patterns, test setup, mock boundaries (step 5)
Phase 4  Decomposition    — files → tasks → interfaces → Verifies blocks → matrix           (steps 6–8)
Phase 5  Draft            — self-check, write docs/draft/plan_<slug>.md                     (step 9)
GATE     Plan review      — STOP; user edits, discusses (→ Phase 2 or 4), or approves       (steps 10–11)
Phase 6  Plan             — re-read the draft from disk, write docs/plans/<slug>.md          (step 12)
```

## Critical Rules (read before every phase)

1. **Every open point 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 proposals, the recommended one first and marked "(Recommended)",
   each with its consequence in one sentence, and a free-form escape (Claude Code's tool adds
   "Other" itself; add "Something else — I'll describe it" where the tool does not).

2. **The spec is read-only.** Nothing you learn here changes `docs/specs/`. Answers to your
   questions go into the plan's *Clarification Log*; everything the spec should absorb — assigned
   IDs, answered questions, gaps, untestable criteria — goes into *Spec Feedback*. The user decides
   when and whether the spec is updated; the plan makes sure nothing is lost meanwhile.

3. **Every requirement ID lands in a Verifies block and in the matrix.** Acceptance criteria
   exactly once across the whole plan set; functional, non-functional, and interface IDs at least
   once. No empty matrix cell — a non-functional requirement without a measurable target reads
   `manual` with a named check step, never a blank. A draft that fails this self-check is not
   presented; it is fixed first.

4. **The test comes first — in the plan.** A task's Todos begin with one test per ID it verifies,
   then the implementation, then documentation. The order is part of the plan because it is what
   makes the Verifies block honest: a test named before the code is a promise, one named after it
   is a description.

5. **The draft gate is mandatory and only explicit approval passes it.** After writing the draft
   you STOP. "Looks good", "continue", "ok" after a question, or silence are not approvals — see
   the Gate section.

6. **After approval, test names and interfaces are frozen.** The only permitted edits to an
   approved plan are ticking checkboxes, setting a task's `Status`, and appending to its *Change
   Log*. Renaming a test, changing a signature, or re-cutting a task during implementation is a
   plan change and is recorded as one, with the reason. This is what lets a reviewer check the
   matrix against the test suite at the end.

7. **Never commit, never overwrite silently.** You create the draft and the plan; the user
   commits. If the target file exists, ask before replacing it.

8. **Urgency waives nothing.** "Just give me the task list" is not permission to skip the review,
   the questions, or the gate. Run the workflow at speed: fewer but sharper questions, batched
   where independent, never zero.

## Precondition — Interactive User

Phases 2 and the gate need a person. **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, what you can do depends on the input:

| Input | Headless behaviour |
|---|---|
| Complete spec (Phase 0 criteria) | Run Phases 1, 3, 4, 5. Every Phase 2 item goes **unanswered** into *Open Questions* as `unresolved — blocks Task #n`, and each affected task is marked `blocked`. Write the draft with status `DRAFT — headless, unresolved questions`. Do **not** write `docs/plans/`. Reply `Draft only — interactive user required for approval`, followed by the path and the list of unresolved items. |
| Anything else | Run Phase 0 and Phase 1 only, then STOP with a `Blocked — interactive user required` handoff: the requirement inventory and the gap list, and one line that an interactive user can resume at Phase 2. Create no files. Deriving acceptance criteria without the user is inventing the requirement. |

## Phase 0 — Intake

1. Identify the input: a spec path, pasted text, an issue URL, or another document. Fetch a URL
   with the runtime's tool; if you cannot fetch, ask the user to paste the content. Never plan
   from a title.
2. Decide whether it is a **complete spec**. All four must hold:
   - numbered functional requirements (`FR-n`) and acceptance criteria (`AC-n`);
   - non-functional requirements (`NFR-n`) present, or the section explicitly `n/a`;
   - every acceptance criterion names the functional requirement(s) it verifies;
   - a Decisions Log or an equivalent record of the decisions behind the requirements.

   A document with some of this is *incomplete*, and takes the same branch as raw text.
3. If it is not complete, ask via the question tool: **(a) Recommended — run `create-dev-spec`
   first** and resume here with the finished spec; the interview there is what turns gaps into
   decisions. **(b) Plan directly from this requirement** — you will assign IDs, propose
   acceptance criteria the user confirms one by one, and list all of it as Spec Feedback. On (a),
   invoke `create-dev-spec` and re-enter this phase with the spec path when it is done. On (b),
   add `L-1` (language) and `L-2` (slug) to the Phase 2 list; with a spec they are inherited.
4. Record the spec source for the plan header: path and commit (`git log -1 --format=%h --
   <path>`) or date, so that a later spec change is detectable.

## Phase 1 — Spec Review

Goal: know every requirement and every hole before deciding anything.

From CreativeCodersTeam/ai-store, Apache-2.0.

More from CreativeCodersTeam/ai-store