Skip to main content

Finding Specs

Learn how to discover and navigate specs using search, list commands, and the MCP server for AI agent access.

Quick Discovery​

List All Specs​

# Show all specs
leanspec list

Output:

📋 Spec List

🟡 ✅ 107-ui-ux-refinements #ui #ux #lessons-learned
🟡 ✅ 106-ui-package-documentation
🟡 ⏳ 105-docs-site-enhancements
🟠 ✅ 104-ui-packaging-fix #packaging #bug-fix

Filter by Status​

# Show only in-progress specs
leanspec list --status in-progress

# Show planned specs
leanspec list --status planned

# Show completed specs
leanspec list --status complete

Filter by Tag​

# Show specs with specific tag
leanspec list --tag api

# Show specs with multiple tags
leanspec list --tag api --tag backend

Filter by Priority​

# High priority specs
leanspec list --priority high

# Low priority specs
leanspec list --priority low

Search by Content​

# Search all spec content
leanspec search "authentication"

Searches across:

  • Spec titles and descriptions
  • All README.md content
  • Sub-spec files (DESIGN.md, TESTING.md, etc.)
  • Frontmatter fields

Search with Filters​

# Search in specific status
leanspec search "API" --status in-progress

# Search with tag filter
leanspec search "cache" --tag performance

# Combine multiple filters
leanspec search "refactor" --status planned --tag backend --priority high

Search is case-insensitive by default:

leanspec search "api"      # Matches "API", "api", "Api"
leanspec search "JWT"      # Matches "jwt", "JWT", "Jwt"

Dependency Navigation​

# Show dependencies for a spec
leanspec deps 042

Output:

Dependency Graph for 042-auth-refactor

Depends On:
  → 041-jwt-library [complete]       # Required to start

Required By:
  ← 043-api-redesign [planned]       # Blocked until 042 done
  ← 044-dashboard [planned]

Related Specs:
  ⟷ 045-security-audit [in-progress]  # Coordinated work

Navigate relationships:

  • Depends On (→): What this spec requires before it can start
  • Required By (←): What's blocked waiting for this
  • Related (⟷): Informational connections

See also: Dependencies

Advanced Filtering​

Combine Multiple Criteria​

# High-priority backend work that's planned
leanspec list --priority high --tag backend --status planned

# In-progress API work
leanspec list --status in-progress --tag api

# Completed security work
leanspec list --status complete --tag security

Exclude Archived​

By default, archived specs are excluded from leanspec list:

# Default: excludes archived
leanspec list

# Include archived
leanspec list --archived

Common Search Patterns​

Find Work to Start​

# What's ready to work on?
leanspec list --status planned --priority high

Check Active Work​

# What's in progress?
leanspec list --status in-progress

# Who's working on what?
leanspec list --status in-progress
# (shows assignee if set)

Review Completed Work​

# Recently completed
leanspec list --status complete

# Completed work by tag
leanspec list --status complete --tag api

Check Dependencies​

# What's ready to start?
leanspec list --status planned

# Check if dependencies are met
leanspec deps <spec-id>
# (verify required specs are complete)

DO:

  • ✅ Use leanspec search for content-based discovery
  • ✅ Use leanspec list with filters for focused views
  • ✅ Use leanspec deps to understand relationships
  • ✅ Check Board & Stats for visual overview

DON'T:

  • ❌ Manually grep through specs/ directory
  • ❌ Rely on filesystem naming (use IDs/search instead)
  • ❌ Forget archived specs exist (use --archived to include them)

Keyboard-Driven Workflows​

Quick Discovery Flow​

# 1. What's the project state?
leanspec list --status in-progress

# 2. What should I work on?
leanspec list --status planned --priority high

# 3. What's this spec about?
leanspec view <spec-id>

# 4. Start working
leanspec update <spec-id> --status in-progress
leanspec open <spec-id>

Research Flow​

# 1. Find relevant specs
leanspec search "authentication"

# 2. View promising spec
leanspec view 042

# 3. Check related work
leanspec deps 042

# 4. Read related spec
leanspec view 041

Next Steps​

Reference: CLI Documentation for complete command options