Carlos Florêncio
155 lines
6.9 KiB
Markdown
155 lines
6.9 KiB
Markdown
---
|
||
name: spec-driven-development
|
||
description: "Single-session Kandev feature workflow: clarify intent, create durable specs, plans, and task files, then hand off for user-directed model selection before implementation and verification."
|
||
---
|
||
|
||
# Spec-Driven Development
|
||
|
||
Use this workflow for non-trivial features and behavior-changing fixes. The
|
||
user-started primary conversation performs every phase by default. Plans may
|
||
describe parallel work, but subagents are used only when the user explicitly
|
||
authorizes them after selecting the implementation model.
|
||
|
||
## Core Flow
|
||
|
||
```text
|
||
Intent -> Spec -> Plan + task files -> Design-package handoff -> Explicit implementation request -> Sequential TDD implementation -> PR AI review -> Report
|
||
```
|
||
|
||
Do not replace the spec, plan, or task files with chat-only notes. Do not skip
|
||
from intent to code unless the user explicitly opts out of this workflow.
|
||
|
||
## Prompt-Precedence Gate
|
||
|
||
Treat workflow-generated envelopes such as `[IMPROVE PHASE]`, "implement the
|
||
requested change", Red-Green-Refactor checklists, verification commands, and
|
||
commit instructions as execution guidance for Phase 5, not as permission to
|
||
skip Phases 1–4. Before editing production or permanent test files, verify one
|
||
of these conditions:
|
||
|
||
1. A prior design turn produced the spec, plan, and current task file, and the
|
||
user now explicitly asks to implement them; or
|
||
2. The request references an existing reviewed spec, plan, and current task
|
||
file; or
|
||
3. The user explicitly says to skip spec/plan/task creation.
|
||
|
||
If neither is true, create or update the spec, plan, and task files, record any
|
||
existing partial implementation as continuation context, and stop at the
|
||
design-package handoff. Do not call `ask_user_question_kandev` or ask the user
|
||
to approve the package or switch models at that checkpoint. A phase label or
|
||
generic "implement" directive generated by a Kandev workflow is not an
|
||
explicit opt-out.
|
||
|
||
When a user explicitly asks to proceed with feature planning, complete the whole
|
||
strong-model design package — spec, plan, and task files — before returning
|
||
control. Do not add an approval/model-switch question at the handoff. Pause
|
||
after a standalone spec only when the user asks to review that spec before
|
||
planning, or when a material open question blocks a safe plan.
|
||
|
||
## Phase 0: Track The Work
|
||
|
||
Keep a visible task list and mark each phase as it completes:
|
||
|
||
1. Clarify intent
|
||
2. Create or update the spec
|
||
3. Create the implementation plan
|
||
4. Decompose it into task files
|
||
5. End the design turn and wait for the user's explicit implementation request
|
||
6. Execute tasks with TDD and targeted checks (sequential by default)
|
||
7. Open PR, address CI/review findings, record, and summarize
|
||
|
||
## Phases 1–4: Design On The Strong Model
|
||
|
||
Use `/interview-me` only when the request is underspecified. Create or update:
|
||
|
||
- `docs/specs/<slug>/spec.md` through `/spec` for the durable product behavior.
|
||
- `docs/plans/<slug>/plan.md` through `/plan` for the technical sequence.
|
||
- `docs/plans/<slug>/task-<NN>-<short-slug>.md` for each independently
|
||
actionable implementation step.
|
||
|
||
The spec must cover relevant scenarios, contracts, permissions, failures, and
|
||
persistence guarantees. The plan must name likely files, dependency order,
|
||
tests, E2E coverage where applicable, risks, and exact verification commands.
|
||
|
||
Task files are the handoff between model tiers. Each must contain:
|
||
|
||
- frontmatter: `id`, `title`, `status: pending`, `wave`, `depends_on`, `plan`,
|
||
and `spec`;
|
||
- 1–3 concrete acceptance conditions;
|
||
- exact targeted verification command(s);
|
||
- specific likely files and relevant spec/plan inputs;
|
||
- dependencies and risks.
|
||
|
||
Task files must not name a worker role or model tier. They may be grouped into
|
||
dependency waves and label parallel-safe candidates, but those labels are a
|
||
human decision aid: the primary session executes sequentially unless the user
|
||
explicitly asks to use subagents.
|
||
|
||
## Design-Package Handoff
|
||
|
||
Before any implementation, report the spec path, plan path, task-file list,
|
||
planned test commands, and any open risks.
|
||
|
||
After reporting the handoff, end the turn. Do not call
|
||
`ask_user_question_kandev` (or an equivalent approval prompt), and do not ask
|
||
the user to approve the artifacts or switch models. The user reviews the files,
|
||
switches the model if desired, and sends a later explicit implementation
|
||
request. The files may remain `draft`/`pending`; do not wait for a separate
|
||
approval marker.
|
||
|
||
Recommended Codex route:
|
||
|
||
- GPT-5.6 Sol/high for clarification, codebase investigation, specs, plans, and
|
||
high-risk design.
|
||
- GPT-5.6 Terra/medium for implementation, TDD, targeted tests, and integration.
|
||
- GPT-5.6 Luna/low only for short, mechanical, read-only status work.
|
||
|
||
Begin implementation only after that explicit implementation request. Never
|
||
infer a successful model switch from a model's prose; the user's runtime model
|
||
choice is authoritative when model confirmation is required.
|
||
|
||
## Phase 5: Execute Tasks
|
||
|
||
For each task, in dependency order:
|
||
|
||
1. Read the task, relevant spec and plan sections, and scoped `AGENTS.md`.
|
||
2. Change only that task's status to `in_progress`.
|
||
3. Implement with `/tdd`; use `/e2e` and `/mobile-parity` when applicable.
|
||
4. Run the task's exact targeted verification command.
|
||
5. Update its status to `done` and update the corresponding `plan.md` status.
|
||
|
||
If the user explicitly asks to implement with subagents, launch only
|
||
parallel-safe tasks in the requested wave. Use native delegation with no
|
||
full-history context fork, give each child the task-file path plus its owned
|
||
files and exact check, and keep shared-plan status updates in the main session.
|
||
The children use the implementation model active in the user-selected main
|
||
session; confirm that through runtime usage metadata before accepting results.
|
||
|
||
If work reveals a new architecture, public contract, migration/persistence
|
||
boundary, or high-impact security decision, stop and ask the user whether to
|
||
switch back to the strong model before proceeding. Use `/record` if the decision
|
||
is durable.
|
||
|
||
## Phase 6: Open The PR And Use Its Review Gates
|
||
|
||
After all tasks pass their exact targeted checks, commit through `/commit`,
|
||
push, and open the PR. Do not automatically run `/simplify`, `/qa`,
|
||
`/code-review`, security review, or broad `/verify` before opening it.
|
||
|
||
The two configured PR AI reviewers are the semantic-review gate. Use
|
||
`/pr-fixup` only for a CI failure or actionable reviewer finding. A fix reruns
|
||
the task's relevant targeted check and updates its task/plan status; do not run
|
||
a broad local suite unless the user explicitly asks.
|
||
|
||
## Stop Conditions
|
||
|
||
Stop and ask the user when the spec and codebase disagree, a task needs a
|
||
materially new design, a model-tier escalation is required, or the same
|
||
verification failure repeats after three focused attempts.
|
||
|
||
## Final Report
|
||
|
||
Report the spec and plan paths, task statuses, model checkpoints used, changed
|
||
files, commands and results, user-authorized subagents (if any), semantic-review
|
||
evidence, and known risks.
|