---
name: kdlbs/spec-driven-development
source: https://app.decimal.ai/s/kdlbs-spec-driven-development@1/SKILL.md
source_sha256: 8ed57a0584fc
---

# 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.