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

• If draft is enabled, move draft → planned once the spec is reviewed, then set in-progress before coding.
• Skipping planned from draft requires a --force override (CLI/MCP/UI).
• 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.

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
• references/COMMANDS.md

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.