shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

spec-driven

-

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

Spec-Driven Development

Recommended effort: xhigh for design and audit phases; medium for implement, quick mode, and status checks.

Structured development workflow with adaptive depth.

Workflow

specify --> design* --> tasks* --> implement --> verify --> audit --> done
  ^______________________________________|  (verify after each task)

Adaptive: Specify and Implement always run; Design and Tasks auto-skip when scope is small enough. Verify runs after every task/range.

Triggers

Feature-Level (auto-sized)

| Trigger Pattern | Reference | | -------------------------------------------------------------------------- | -------------------------------------------------- | | Create new feature, specify feature | specify.md | | From PRD, extract from document, use this PRD | specify.md (via @file.md) | | Modify feature, improve feature | specify.md (brownfield) | | Discuss feature, capture context, how should this work | discuss.md | | Create technical design, plan feature | design.md | | Research technology, cache research | research.md | | Create tasks | tasks.md | | Implement task, execute task | implement.md | | Verify implementation, check adherence, verify code | verify.md | | Audit feature, validate goals, audit goals and success criteria | audit.md | | Validate, UAT, manual testing, test manually | validate.md | | Quick fix, quick task, quick mode, start quick mode, small change, bug fix | quick-mode.md | | List features, show status | status-specs.md |

Guidelines

| Trigger Pattern | Reference | | ------------------------------------------ | ------------------------------------------------------------- | | Phase transitions, session dump protocol | phases.md | | How to decompose tasks | tasks.md | | Codebase exploration | codebase-exploration.md | | Research patterns | research.md | | Coding principles | coding-principles.md | | Status workflow, when to update status | status-workflow.md | | Knowledge format, Codebase Feedback format | knowledge.md |

Notes:

  • code-correctness.md not a direct trigger; loaded by verify.md Step 5.
  • discovery.md not a direct trigger; loaded by specify.md Step 7.
  • auto-sizing.md not a direct trigger; loaded by specify.md Step 1.

Cross-References

specify.md --------> discovery.md (feature discovery before drafting)
specify.md --------> auto-sizing.md (scope assessment)
specify.md --------> discuss.md (when gray areas detected)
specify.md --------> quick-mode.md (when Small scope)
specify.md --------> design.md (Large/Complex)
specify.md --------> implement.md (Medium, skip design/tasks)
design.md ---------> tasks.md (Large/Complex)
design.md ---------> research.md (if new tech)
tasks.md ----------> implement.md
implement.md ------> coding-principles.md (before coding)
implement.md ------> verify.md (after every task/range)
verify.md ---------> code-correctness.md (code correctness analysis)
verify.md ---------> spec.md (marks AC [x] on pass, reverts on regression)
implement.md ------> audit.md (after to-review)
audit.md ----------> spec.md (marks Goals/Success [x], transitions done)
implement.md ------> validate.md (on-demand UAT)
validate.md -------> audit.md (re-run after UAT reproves any [x])
implement.md ------> tasks.md (safety valve: >5 inline steps)
phases.md ---------> specify/design/tasks/implement (session dump + dispatch protocol)
design.md ---------> project-index (integrate feedback after Step 8)
implement.md ------> project-index (integrate feedback after Step 10)
domain-model -----> spec-driven      (entities+rules as impl contracts)
spec-driven ------> domain-model     (domain gaps trigger update mode)

Artifact Structure Authority

templates/ is canonical for every artifact's structure. Load the relevant template before reading any existing artifact in .artifacts/ -- existing files are context, not structural reference. When structure diverges from the template, template wins. Do not propagate legacy structure.

Knowledge Verification Chain

For all technical decisions, follow in order: (1) Codebase → (2) Project docs → (3) Context7 MCP → (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." Referenced by design.md and implement.md as ../SKILL.md#knowledge-verification-chain.

Guidelines

DO:

  • 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)
  • Reuse research cache across features (.artifacts/research/)
  • Consume .agents/ for project context and codebase info (optional)
  • Queue codebase discoveries to .agents/knowledge.md Codebase Feedback
  • Auto-size depth based on complexity -- skip phases that add no value
  • Run verify after each task or range -- never deferred to the end

DON'T:

  • Reuse Feature IDs from previous features
  • Mix spec, design, and task content in a single file
  • Skip status transitions (e.g., jumping from draft to done)
  • Force full pipeline on small/medium changes -- respect auto-sizing
  • Assume or fabricate -- follow Knowledge Verification Chain
  • Defer verification to the end -- verify runs per task/range

Output

Artifacts in .artifacts/ (excluded via .git/info/exclude):

.artifacts/features/{ID}-{name}/   spec.md, design.md, tasks.md, decisions.md
.artifacts/quick/NNN-{slug}/       task.md
.artifacts/research/{topic}.md     research cache (reusable across features)

Project context (.agents/ -- not committed):

.agents/knowledge.md               cross-feature decisions (spec-driven)

Templates in templates/ define every artifact's canonical structure.

Error Handling

  • No .artifacts/: Create it (subdirs created on demand)
  • Spec not found: List available features
  • Open questions blocking architecture: Resolve via discuss before planning
  • Design not found: Suggest design before tasks (or skip if Medium scope)
  • Tasks not found: Suggest tasks before implement (or skip if Medium scope)
  • Scope misjudged: Safety valve in implement catches this

Compact Instructions

Heavy phases write a mid-phase checkpoint to disk before autocompact fires (design.md Step 9a). If autocompact fires before that checkpoint, preserve:

  • Current phase and step number
  • Feature ID and path (.artifacts/features/{ID}-{name}/)
  • Open decisions not yet captured in any artifact
  • AC check status (which [x] are marked and which are not)
  • Session dump path if already written

Drop everything else -- spec.md, design.md, and tasks.md survive autocompact on disk.