kandev/.agents/skills/spec-driven-development/SKILL.md

name, description

name	description
spec-driven-development	Single-session Kandev feature workflow: clarify intent, create durable specs, plans, and task files on a strong model, then implement and verify them after the user switches the main session to a lower-cost model.

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

Intent -> Spec -> Plan + task files -> User model switch -> 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. The request references an approved spec, plan, and current task file; or
2. 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 model switch 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 pausing for review or a model switch. 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. Pause for the user to switch the main model
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.

Model-Switch Checkpoint

Before any implementation, report the spec path, plan path, task-file list, planned test commands, and any open risks. Ask the user to manually switch the main conversation to the lower-cost implementation model.

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.

Resume only after approval or an explicit instruction to continue at the current model. Never infer a successful switch from a model's prose; inspect runtime model-usage metadata when 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.