spec-driven

What this skill does

# Spec-Driven Development

Structured development workflow with adaptive depth.

## Triggers

### Feature-level (auto-sized)

- **New feature** ("create new feature", "specify feature", "from PRD",
  "modify feature") → [specify.md](references/specify.md)
- **Discuss / capture context** ("discuss feature", "how should this
  work") → [discuss.md](references/discuss.md)
- **Technical design** ("create technical design", "plan feature") →
  [design.md](references/design.md)
- **Research technology** ("cache research", "research topic") →
  [research.md](references/research.md)
- **Tasks** ("create tasks") → [tasks.md](references/tasks.md)
- **Implement** ("implement task", "execute task", "implement story
  S-1", "implement task T-1") → [implement.md](references/implement.md)
- **Audit** ("audit feature", "validate goals", "audit goals and
  success criteria") → [audit.md](references/audit.md)
- **Manual testing** ("manual testing", "test manually") →
  [validate.md](references/validate.md)
- **Quick mode** ("quick fix", "quick task", "small change", "bug
  fix") → [quick-mode.md](references/quick-mode.md)
- **Status overview** ("list features", "show status") →
  [status-specs.md](references/status-specs.md)

### Methodological refs (loaded by other refs)

- **Verification (internal check)** →
  [verify.md](references/verify.md) (loaded by `implement.md` Step 7-After)
- **Sub-agent dispatch protocol** →
  [phases.md](references/phases.md)
- **Codebase exploration** →
  [codebase-exploration.md](references/codebase-exploration.md)
- **Coding principles** →
  [coding-principles.md](references/coding-principles.md)
- **Status workflow** ("when to update status") →
  [status-workflow.md](references/status-workflow.md)
- **Knowledge format** (decisions, gotchas, conventions) →
  [knowledge.md](references/knowledge.md)
- **Auto-sizing scope assessment** →
  [auto-sizing.md](references/auto-sizing.md) (loaded by `specify.md` Step 1)
- **Discovery topics** →
  [discovery.md](references/discovery.md) (loaded by `specify.md` Step 7)
- **Code-correctness analysis** →
  [code-correctness.md](references/code-correctness.md) (loaded by
  `verify.md` Step 5)

## Workflow

```text
specify --> design* --> tasks* --> implement --> audit --> done
                                       ^           ^
                                       |           |__ per-story commit OR pre-PR
                                       |__ verify runs inside implement per task
```

Adaptive: Specify and Implement always run; Design and Tasks auto-skip
when scope is small. Verify is internal to implement. Audit runs at the
commit boundary (per-story or end-of-spec), always before PR.

## Knowledge Verification Chain

For all technical decisions, follow in order:

1. Codebase
2. Project docs
3. External docs lookup (documentation service or vendored references)
4. Web search
5. Flag or ask

Never skip to step 5 if steps 1-4 are available. **Never assume or
fabricate** — follow the chain or say "I don't know."

## Artifact Structure Authority

Every artifact's structure is canonical in the matching reference (each
ref carries its template inline, 1:1). Load the reference before reading
any existing artifact in `.artifacts/` -- existing files are context,
not structural reference. Template wins on divergence.

## Guidelines

- Separate content by purpose: spec = WHAT, design = HOW, tasks = WHEN
- Follow status flow: `draft → ready → in-progress → to-review → done`
- Use sequential Feature IDs (`001`, `002`); never reuse
- Reuse research cache across features (`.artifacts/research/`)
- Auto-size depth based on complexity — skip phases that add no value
- Run audit at the commit boundary, before any PR

## Anti-Pattern: Forced Full Pipeline

Forcing every change through specify → design → tasks → implement on
small or medium scopes is process tax. Auto-sizing exists for a reason:
small fixes go through `quick-mode.md`, medium scopes skip design and
tasks, large/complex scopes get the full pipeline. Respect the sizing
decision.

## Anti-Pattern: Deferred Verification

Implementing all tasks first and verifying at the end loses traceability
between implementation and acceptance criteria. Verify runs internally
after every task or range -- never a final phase, never user-invoked.
Failed verification reverts checked AC and reopens the relevant tasks.

## Anti-Pattern: PR Before Audit

Opening a PR with `status: to-review` and running `audit` afterwards
puts Goals and Success Criteria validation on the wrong side of the
merge gate. Audit runs first at the commit boundary -- per-story or
end-of-spec -- and only then does the commit/PR proceed.

## Anti-Pattern: Knowledge Skipping

Jumping to "I'll guess based on dependency name" or "let me web-search
that" without exhausting steps 1-4 of the Knowledge Verification Chain
produces fabricated patterns that don't match the codebase. Read the
codebase first, then project docs, then external docs, then web. Only
flag or ask after the chain is exhausted.

## Anti-Pattern: Training Memory as Ground Truth

Treating trained-in knowledge as authoritative for version-sensitive
facts -- engine constraints, defaults, API surfaces, deprecations,
runtime requirements -- silently bypasses the chain. Verify against the
project's declared dep metadata, lockfile, and the dep's current
documentation. Training cutoffs lag dep behavior.