devflow-design

Design — Spec + Plan

Spec = design contract. Plan = executable task list. Short, decisive, no fluff.

File vs inline

Mode	Spec	Plan
tiny	none	none
standard	inline (≤20 lines)	file at docs/devflow/plans/<kebab-slug>.md (always — checkbox state = resumability)
deep	file at docs/devflow/specs/<kebab-slug>.md	file at docs/devflow/plans/<kebab-slug>.md

Templates: ${CLAUDE_PLUGIN_ROOT}/templates/spec-template.md, ${CLAUDE_PLUGIN_ROOT}/templates/plan-template.md.

Spec sections

1. Goal — what success looks like, one paragraph
2. Non-goals — explicitly out of scope
3. Context — current state, why now
4. Constraints — perf, compat, security, deadlines
5. Proposed approach — the chosen design, not a survey
6. Alternatives considered — 1–3 lines each + why rejected
7. Risks — what could go wrong, mitigations
8. Test strategy — unit/integration/e2e/manual, what each covers
9. Acceptance criteria — verifiable bullets

Rules: no restating obvious context; bullets over paragraphs; real file paths only; empty section → "n/a — "; readable in under 2 minutes.

Plan sections

1. Overview — one paragraph linking the spec
2. Assumptions — each external assumption (library/API behavior, version default, config key, infra contract) verified via devflow-research and marked verified (source) or assumption — unverified. Unverified load-bearing assumptions are review blockers.
3. Tasks — ordered checkboxes: [ ] Task N: <verb-led goal> + files to touch + per-task verification command
4. Files touched — flat dedup list
5. Test commands — full suite, lint, typecheck (from the project profile)
6. Rollback plan — revert commit / flag off / migration down
7. Completion criteria — tied to the spec's acceptance criteria

Task sizing: one task = one logical change verifiable on its own; order keeps the build green; split multi-file-refactor + behavior-change tasks in two; TDD task before behavior changes where practical. Every task in verifiable form: <task> → verify: <check> — strong criteria let the agent loop independently.

Output: compact, checkboxes, no prose between tasks.

Gate

A plan is not done until reviewed: run devflow-plan-review via the independent devflow-plan-reviewer subagent (max-reasoning tier). Revise on REQUEST CHANGES, re-review (round 2 = revision diff vs round-1 findings). Cap 2 rounds, then surface open findings to the user. No execution on an unreviewed plan.