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.

When to Use This Skill

Activate this skill when any of the following are true:

The repository contains a specs/ folder or .lean-spec/config.json
The user mentions LeanSpec, specs, SDD, or spec-driven planning
The task requires multi-step changes, breaking changes, or design decisions

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.
Progressive Disclosure: Keep SKILL.md concise; use references for details.
No Manual Frontmatter: Use tools to update status, tags, dependencies.
Verify Against Reality: When asked about completion or progress, check the actual codebase, commits, and changes—not just the spec status.

Core SDD Workflow

1) Discover

Get the project state: run board (or lean-spec board).
Search for related work before creating anything: search (or lean-spec search "query").

2) Design

If a spec is needed, create it with create (or lean-spec create).
Prefer standard templates and keep scope clear.
Validate token count using tokens (or lean-spec tokens).

3) Implement

Update spec status to in-progress before coding.
Document decisions and progress inside the spec as work happens.
Link dependencies using link/unlink as they are discovered.

4) Validate & Complete

Run validate (or lean-spec validate) before completion.
Ensure all checklist items are checked.
Verify actual implementation: When asked about completion status or progress:
- Check git commits and file changes
- Review actual code implementations
- Verify test coverage and results
- Don't rely solely on spec status field
Update status to complete only when both spec criteria and actual implementation are verified.

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>`
Dependencies	`deps`	`lean-spec deps <spec>`
Relationships	`relationships`	`lean-spec rel <spec>`
Link / unlink (deprecated)	`link` / `unlink`	`lean-spec link/unlink <spec> --depends-on <other>`
Token count	`tokens`	`lean-spec tokens <spec>`
Validate	`validate`	`lean-spec validate`

Best Practices (Summary)

Keep AGENTS.md project-specific only; put SDD methodology here.
Never create spec files manually; use create.
Keep specs short and focused; split when >2000 tokens.
Always check dependencies and link specs that block each other.
Document trade-offs and decisions as they happen.

Choosing Relationship Type

Parent/Child = Decomposition (organizational)

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

Depends On = Blocking (technical)

"This spec needs that spec done first"
Specs are independent work items
Could be completely unrelated areas

Rule: Never use both parent AND depends_on for the same spec pair.

Test: If the other spec didn't exist, would your spec still make sense?

NO → Use parent (it's part of that scope)
YES → Use depends_on (it's just a blocker)

See detailed guidance in:

Setup & Activation

Project-level installation

Place this folder in:

$PROJECT_ROOT/.lean-spec/skills/leanspec-sdd/

User-level installation (optional)

Agent-specific skill folders may include:

~/.codex/skills/leanspec-sdd/
~/.cursor/skills/leanspec-sdd/

Exact paths vary by tool. See https://agentskills.io for current locations.

Auto-activation hints

If the tool supports auto-activation, detect:

.lean-spec/config.json
specs/ folder
AGENTS.md referencing the skill

Compatibility Notes

Works with any Agent Skills-compatible tool (Claude, Cursor, Codex, Letta, Factory).
Requires either LeanSpec MCP tools or CLI access to manage specs.
This skill is additive and does not change existing LeanSpec tooling.

leanspec-sdd