Skip to main content

Frequently Asked Questions

What is LeanSpec?​

LeanSpec is a lightweight spec framework optimized for AI-assisted development. It's a CLI tool + markdown files that live in your repo, helping you document technical decisions and guide AI coding tools while keeping specs under 300 lines for optimal performance.

Key features:

  • Numbered specs for easy reference
  • CLI tools for creating, searching, and managing specs
  • MCP server for AI tool integration (GitHub Copilot, Claude Code, Cursor, etc.)
  • Validation to ensure spec quality
  • Kanban board and stats for project visibility

5-minute setup:

npm install -g lean-spec
cd your-project
lean-spec init
lean-spec create my-first-spec

No configuration files, no database, no server. Works with any editor and any AI tool.

Why use LeanSpec?​

Use LeanSpec when you need:

  • Team alignment on complex features
  • Documentation for design decisions
  • Context to reduce AI hallucinations
  • Onboarding materials for new team members

Skip LeanSpec for:

  • Simple bug fixes
  • Throwaway prototypes
  • Solo projects with clear requirements

Philosophy: Get 80% of vibe coding speed with 80% of structured spec benefits. Minimal overhead for maximum agility.

Why the 300-line limit?​

Attention is the scarce resource, not storage.

Three reasons:

  1. Human attention span - Read and understand in 5-10 minutes
  2. AI performance - Context quality degrades beyond 50K tokens
  3. Working memory - Keep specs cognitively manageable

If your spec exceeds 300 lines, split it into sub-spec files (DESIGN.md, IMPLEMENTATION.md, TESTING.md, etc.). See First Principles for details.

Troubleshooting​

My spec was corrupted by AI editing it​

Cause: Spec exceeded context window, AI lost track of structure.

Fix:

git checkout HEAD -- specs/042-my-spec/  # Restore from git
lean-spec validate                        # Check for issues

Prevention: Keep specs under 300 lines (warning at 300, error at 400).

lean-spec update says "spec not found"​

Debug:

lean-spec list          # See all active specs
lean-spec list --all    # Include archived

Common causes:

  • Not in git repo with specs/ directory
  • Typo in spec name/number
  • Spec was archived

Frontmatter validation failed​

Common mistakes:

  • Manually editing system-managed fields (status, created_at, transitions, etc.)
  • Invalid YAML syntax
  • Typos in field names

Fix:

lean-spec validate      # See exactly what's wrong

Always use CLI commands to update metadata:

lean-spec update 042 --status in-progress
lean-spec update 042 --priority high
lean-spec update 042 --tags api,backend

How do I recover deleted specs?​

Specs are just files in git:

git log --all --full-history -- "specs/042-my-spec/*"
git checkout <commit> -- specs/042-my-spec/

Or restore from archived:

mv archived/042-my-spec specs/
lean-spec update 042 --status in-progress

CLI command not working​

Check installation:

which lean-spec
lean-spec --version

Reinstall if needed:

npm install -g lean-spec

Verify you're in a git repo:

git rev-parse --git-dir

Contributing & Support​

How do I report bugs or request features?​

Can I contribute?​

Yes! See CONTRIBUTING.md.

Common contributions:

  • Documentation improvements
  • Bug fixes
  • New templates
  • MCP server enhancements

Where can I get help?​

What's the license?​

MIT License - free for commercial and personal use.

More questions? Check the full documentation or ask in GitHub Discussions.