LeanSpec SDD Skill

Teach agents how to run Spec-Driven Development (SDD) in LeanSpec projects. This skill is an addon: it does not replace MCP or CLI tools.

Core Principles

Context Economy: Keep specs under 2000 tokens when possible. Split large specs.
Discovery First: Always run board/search before creating new specs.
Intent Over Implementation: Capture why first, then how.
No Manual Frontmatter: Use tools to update status, tags, dependencies.
Verify Against Reality: Check actual codebase, commits, and changes—not just spec status.

SDD Lifecycle

1. Discover

Before creating or modifying anything:

Run board to see current project state and identify gaps
Run search "relevant keywords" to find related specs
If similar spec exists, consider extending it or linking as dependency

2. Create Spec

Use create tool (preferred) or lean-spec create "spec-name".

Always pass all known fields in the create call — title, content, priority, tags, etc. Never create empty specs then populate with follow-up update.

Gather requirements first:

Problem/Goal: What needs to be solved?
Scope: What's in and out?
Success Criteria: How do we know it's done?
Dependencies: What needs to exist first?

Naming conventions: kebab-case, descriptive — user-auth-oauth-integration, not bug-fix.

Quality content sections:

Overview (1-3 sentences) — problem and importance
Requirements — - [ ] checklist, independently verifiable items
Non-Goals — prevents scope creep
Technical Notes (optional) — architecture, APIs
Acceptance Criteria — measurable success conditions

After creation:

Link relationships (parent, depends_on) — see "Choosing Relationship Type"
Run validate to check quality; check tokens — keep under 2000

3. Refine Spec

Pre-implementation research to ensure the spec is implementation-ready. Use when spec is drafted and approaching in-progress.

Research the codebase:

Search for files/modules mentioned in the spec
Find existing patterns to follow
Locate integration points; review test patterns

Validate technical approach:

Do referenced files/APIs exist?
Are proposed interfaces compatible?
Does architecture match current patterns?
Are there existing solutions to leverage?

Update spec with findings:

Specific file paths to modify
Exact function/class names and API signatures
Existing code to reuse; edge cases and blockers

Readiness checklist:

All referenced code paths verified
Technical approach validated against codebase
Dependencies confirmed available
No blocking unknowns remain
Checklist items are specific and actionable

4. Implement Spec

Before starting:

Use view <spec> — includes parent, children, depends_on, required_by
Set status to in-progress: update <spec> --status in-progress
⚠️ Do NOT call list, list_children, or list_umbrellas — view provides all relationships
If draft is enabled, move draft → planned first (skipping requires --force)

For umbrella specs: Implement children first; parent completes when all children complete.

For child specs: Complete independently once requirements are met.

During implementation:

Follow spec's checklist items in order
Stay within defined scope boundaries
Run tests frequently
Document discoveries in the spec

Verification (MANDATORY — do NOT skip):

pnpm typecheck    # Zero type errors
pnpm test         # All tests pass
pnpm lint         # No lint errors
lean-spec validate

All must pass before marking complete. If any fail, fix and re-run.

Completing:

Mark all checklist items as done
Add implementation notes if needed
Set status to complete: update <spec> --status complete

5. Check Progress

Verify spec completion against actual implementation.

Extract from spec: checklist items, acceptance criteria, scope boundaries, technical requirements.

Verify against codebase:

git log --oneline --since="<spec-created-date>" -- <relevant-paths>

Verify new files/modules exist
Read actual code to verify it matches spec design
Check test coverage for spec requirements
Run pnpm test

For each checklist item:

Determine if verifiable via code, tests, or manual check
Search codebase for evidence of completion
Mark complete only if implementation is verified

Update status based on findings. Never trust status alone — always verify against actual code.

Managing Specs

Updating Specs

Use during draft/revision phase when requirements are evolving.

Content updates (edit spec file):

Add/remove requirements (- [ ] items)
Clarify scope and non-goals
Update technical approach
Document decisions with rationale

Metadata updates (use tools):

Status: update <spec> --status <status>
Dependencies: relationships with action=add, type=depends_on
Parent: relationships with action=add, type=parent

Handling scope creep:

Evaluate fit — does it belong in this spec?
Split if needed — create new spec for out-of-scope work
Link appropriately (parent or depends_on)
Update original non-goals to reference new spec

Organizing Specs

Use when specs need structure, relationships are unclear, or project board is cluttered.

Survey first:

board — specs by status
board --group-by priority — priority imbalances
board --group-by parent — hierarchy
stats — overall health

Patterns to look for:

Pattern	Action
3+ related specs, no parent	Create umbrella and group
Spec can't start without another	Add `depends_on`
Completed spec still `in-progress`	Update status
Low-value spec, no activity	Archive
Large spec (>2000 tokens)	Split into parent + children
Duplicate/overlapping specs	Merge or archive redundant one

Status definitions:

Status	Meaning
`planned`	Defined, work not started
`in-progress`	Active development
`complete`	All requirements verified
`archived`	No longer relevant

Priority levels:

Priority	When to Use
`critical`	Blocking release or breaking production
`high`	Important for current milestone
`medium`	Standard priority (default)
`low`	Nice-to-have, backlog

Bulk organization checklist:

Review board for misplaced/stale specs
Group related specs under umbrellas
Add missing depends_on links
Correct stale statuses
Adjust priorities to match current goals
Archive obsolete specs
Run validate and stats after changes

Tool Reference

Use MCP tools when available. Use CLI as fallback.

Action	MCP Tool	CLI Command
Project status	`board`	`lean-spec board`
List specs	`list`	`lean-spec list`
Search specs	`search`	`lean-spec search "query"`
View spec	`view`	`lean-spec view <spec>`
Create spec	`create`	`lean-spec create <name>`
Update status	`update`	`lean-spec update <spec> --status <status>`
View relationships	`relationships`	`lean-spec rel <spec>`
Set parent	`relationships` (`action=add`, `type=parent`)	`lean-spec rel add <child> --parent <parent>`
Add child	`relationships` (`action=add`, `type=child`)	`lean-spec rel add <parent> --child <child>`
Add dependency	`relationships` (`action=add`, `type=depends_on`)	`lean-spec rel add <spec> --depends-on <other>`
Remove dependency	`relationships` (`action=remove`, `type=depends_on`)	`lean-spec rel rm <spec> --depends-on <other>`
Dependency graph	`deps`	`lean-spec deps <spec>`
List children	`children`	`lean-spec children <parent>`
Token count	`tokens`	`lean-spec tokens <spec>`
Validate	`validate`	`lean-spec validate`
Stats	`stats`	`lean-spec stats`

Choosing Relationship Type

IMPORTANT: Critical decision. Read carefully before linking specs.

Parent/Child (Umbrella Decomposition)

Use when a large initiative is broken into child specs that together form the whole.

"This spec is a piece of that umbrella's scope"
Child spec doesn't make sense without parent context
Parent completes when all children complete

Tools: relationships with action=add, type=parent, target=<parent> (MCP) / lean-spec rel add <child> --parent <parent> (CLI)

Example: "CLI UX Overhaul" umbrella → children: "Help System", "Error Messages", "Progress Indicators"

Depends On (Technical Blocker)

Use when a spec cannot start until another independent spec is done first.

"This spec needs that spec done first"
Both specs are independent work items with separate goals
Removal of the dependency doesn't change the spec's scope

Tools: relationships with action=add, type=depends_on, target=<other> (MCP) / lean-spec rel add <spec> --depends-on <other> (CLI) Remove: relationships with action=remove, type=depends_on (MCP) / lean-spec rel rm <spec> --depends-on <other> (CLI)

Example: "Search API" depends on "Database Schema Migration"

Decision Flowchart

Is spec B part of spec A's scope? → Parent/child (type=parent)
Does spec B just need spec A finished first? → Depends on (type=depends_on)
Never use both parent AND depends_on for the same spec pair.

Litmus test: If spec A didn't exist, would spec B still make sense?

NO → B is a child of A
YES → B depends on A

Umbrella Workflow

Create the umbrella spec: create
Create each child spec: create
Assign children: relationships (action=add, type=parent) for each child
Verify structure: children
Add cross-cutting deps if needed: relationships (action=add, type=depends_on)

Best Practices

Never create spec files manually; use create.
Always pass all known fields in the create call — never create empty then edit.
Keep specs short and focused; split when >2000 tokens.
Search first — never create duplicates; link related specs instead.
Checkboxes only for actions — use plain lists for non-actionable items.
Use parent/child for decomposition, depends_on for blockers.
Archive, don't delete — preserve history.
Survey before organizing — use board and stats first.
Research before implementing — refine specs to avoid surprises.
Verify before completing — pnpm typecheck, pnpm test, pnpm lint must ALL pass.
Document trade-offs and decisions as they happen.
Out-of-scope discoveries become new specs, not scope creep.

See detailed guidance in:

leanspec-sdd