LeanSpec SDD Skill

When to Use This Skill

• 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

board

lean-spec board

list

lean-spec list

search

lean-spec search "query"

view

lean-spec view <spec>

create

lean-spec create <name>

update

lean-spec update <spec> --status <status>

deps

lean-spec deps <spec>

relationships

lean-spec rel <spec>

link

unlink

lean-spec link/unlink <spec> --depends-on <other>

tokens

lean-spec tokens <spec>

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

• "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

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

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

• 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.