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
lean-spec list

Output:

📋 Specs (18 total)

┌─────┬────────────────────────┬──────────────┬──────────┐
│ ID  │ Name                   │ Status       │ Priority │
├─────┼────────────────────────┼──────────────┼──────────┤
│ 042 │ auth-refactor          │ in-progress  │ high     │
│ 043 │ api-redesign           │ planned      │ medium   │
│ 044 │ dashboard-performance  │ complete     │ low      │
└─────┴────────────────────────┴──────────────┴──────────┘

Filter by Status​

# Show only in-progress specs
lean-spec list --status in-progress

# Show planned specs
lean-spec list --status planned

# Show completed specs
lean-spec list --status complete

Filter by Tag​

# Show specs with specific tag
lean-spec list --tag api

# Show specs with multiple tags
lean-spec list --tag api --tag backend

Filter by Priority​

# High priority specs
lean-spec list --priority high

# Low priority specs
lean-spec list --priority low

Search by Content​

# Search all spec content
lean-spec 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
lean-spec search "API" --status in-progress

# Search with tag filter
lean-spec search "cache" --tag performance

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

Search is case-insensitive by default:

lean-spec search "api"      # Matches "API", "api", "Api"
lean-spec search "JWT"      # Matches "jwt", "JWT", "Jwt"

Visual Navigation​

Kanban Board​

lean-spec board

Shows specs grouped by status:

┌─────────── PLANNED ───────────┬──── IN-PROGRESS ────┐
│ 043 api-redesign [medium]     │ 042 auth-refactor   │
│ 045 notification-system [low] │ 046 db-migration    │
└───────────────────────────────┴─────────────────────┘

Project Completion: 60% (3/5 specs complete)
- 2 in progress, 2 planned, 3 complete

See also: Board & Stats

Dependency View​

# Show dependencies for a spec
lean-spec 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

AI Agent Access (MCP)​

MCP Server Integration​

The LeanSpec MCP server enables AI agents to search and retrieve specs:

// AI agent uses MCP tools
search_specs("authentication system")
get_spec("042")
list_specs({status: "in-progress"})

This powers:

  • Semantic memory: AI retrieves past decisions across sessions
  • Context-aware: AI finds relevant specs for current task
  • Cross-reference: AI follows dependencies automatically

See also: MCP Server Reference

AI Search Workflow​

When working with AI agents:

  1. Agent queries: "Why did we choose PostgreSQL?"
  2. MCP search: search_specs("database decision")
  3. Agent retrieves: Spec 023 with rationale
  4. Agent answers: "Per spec 023, PostgreSQL chosen because..."

This eliminates repetitive questions and maintains consistency.

Advanced Filtering​

Combine Multiple Criteria​

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

# In-progress API work
lean-spec list --status in-progress --tag api

# Completed security work
lean-spec list --status complete --tag security

Exclude Archived​

By default, archived specs are excluded from lean-spec list:

# Default: excludes archived
lean-spec list

# Include archived
lean-spec list --archived

Project Stats​

Quick Overview​

lean-spec stats

Output (simplified view by default):

📊 Project Statistics

Status Distribution:
  ⏳ In Progress: 2
  📋 Planned: 5
  ✅ Complete: 3

Priority Breakdown:
  🔴 High: 3
  🟠 Medium: 4
  🟢 Low: 3

Top Tags:
  #api: 4 specs
  #backend: 6 specs
  #security: 2 specs

See also: Board & Stats

Common Search Patterns​

Find Work to Start​

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

Check Active Work​

# What's in progress?
lean-spec list --status in-progress

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

Review Completed Work​

# Recently completed
lean-spec list --status complete

# Completed work by tag
lean-spec list --status complete --tag api

Check Dependencies​

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

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

DO:

  • ✅ Use lean-spec board for visual overview
  • ✅ Use lean-spec list with filters for focused views
  • ✅ Use lean-spec search for content-based discovery
  • ✅ Use lean-spec deps to understand relationships
  • ✅ Let AI agents search via MCP for semantic retrieval

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?
lean-spec board

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

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

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

Research Flow​

# 1. Find relevant specs
lean-spec search "authentication"

# 2. View promising spec
lean-spec view 042

# 3. Check related work
lean-spec deps 042

# 4. Read related spec
lean-spec view 041

Next Steps​

Reference: CLI Documentation for complete command options