leanspec-sdd

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

1. Context Economy: Keep specs under 2000 tokens when possible. Split large specs.
2. Discovery First: Always run board/search before creating new specs.
3. Intent Over Implementation: Capture why first, then how.
4. Progressive Disclosure: Keep SKILL.md concise; use references for details.
5. No Manual Frontmatter: Use tools to update status, tags, dependencies.
6. 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:

• references/WORKFLOW.md
• references/BEST-PRACTICES.md
• references/EXAMPLES.md

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.