| name | leanspec-sdd |
| description | Spec-Driven Development methodology for AI-assisted development. Use when working in a LeanSpec project. |
| compatibility | Requires lean-spec CLI or @leanspec/mcp server |
| metadata | {"author":"LeanSpec","version":"0.1.0","homepage":"https://leanspec.dev"} |
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.
