DOCSEARCHbyAlgolia
Submit Docs

LeanSpec Documentation

website·Indexed 31 days ago

https://www.lean-spec.dev/docs/guide/

A lightweight, flexible Spec-Driven Development (SDD) methodology and toolkit designed for modern AI-powered development. LeanSpec provides a CLI, a standalone web UI via the @leanspec/ui package, and an MCP (Model Context Protocol) server to enable AI assistants like Claude Desktop and GitHub Copilot to access and navigate project specifications.

Tokens
40K
Snippets
220
Records
312
Agent score
57%

What's inside LeanSpec

  1. Overview of LeanSpec Spec-Driven Development

    LeanSpec is a lightweight, flexible Spec-Driven Development (SDD) methodology designed for AI-powered development. It aims to provide AI coding agents with clear, actionable context without the overhead of traditional, exhaustive documentation. It is designed to be AI-native and compatible with tools such as Cursor, GitHub Copilot, Aider, and custom agents.

  2. Overview of LeanSpec Spec-Driven Development (SDD)

    LeanSpec is a lightweight and flexible Spec-Driven Development (SDD) methodology specifically designed to optimize the development process for modern AI-powered workflows.

  3. Overview of LeanSpec SDD Framework

    LeanSpec is a lightweight Spec-Driven Development (SDD) framework designed to increase development velocity by improving human-AI alignment. It focuses on reducing cognitive load and context rot through a flexible, local-first approach to technical specifications.

    Core Strengths:

    • Lightweight: Minimal setup with no heavy dependencies.
    • Simplicity: Allows starting with a single file and growing as needed.
    • Agility: Supports direct editing without multi-step workflows.
    • Adaptivity: Editor-agnostic; works with any AI tool (e.g., Copilot, Claude, Cursor, Windsurf) and any editor (e.g., VS Code, JetBrains, Vim, Emacs).
    • Tooling: Includes a CLI, MCP server, and validation tools.

  4. Overview of LeanSpec MCP Integration

    The Model Context Protocol (MCP) is an open standard that allows AI assistants to access external tools and data. By using the LeanSpec MCP server, AI agents gain persistent semantic memory of project decisions, enabling them to search specs by topic, retrieve content directly into the conversation context, create or update specs via natural language, and automatically navigate dependencies.

  5. Overview of LeanSpec Visual Mode

    Visual Mode is a local web application that provides a visual interface for browsing and managing specs. It is designed for visual learners, team presentations, and exploratory browsing. Key capabilities include an interactive spec browser with syntax highlighting, dependency visualization via an interactive graph, project metrics dashboards, search/filtering by status or tags, and a Kanban-style Board View for tracking spec status.

  6. Overview of the Lean Spec methodology

    Lean Spec is an agile approach to technical documentation that avoids heavyweight processes and 'spec-first' waterfall planning. It emphasizes writing specifications concurrently with coding and capturing decisions in real-time. Key principles include:

    • Context Economy: Specifications are kept under 300 lines and designed to be read in 5-10 minutes, ensuring they fit within both human and AI working memory.
    • Adaptive Planning: Specs are updated as insights emerge, allowing teams to respond to change faster than traditional documentation workflows.
    • Incremental Scaling: Teams can start with basic README.md files and status tracking, adding complexity only as the project or team grows.

  7. Overview of LeanSpec MCP Server capabilities

    The LeanSpec MCP server enables AI assistants to interact with LeanSpec projects. It provides three primary interaction methods:

    • Tools: Actions to list, search, create, update, link/unlink, archive, and validate specifications, as well as getting project stats and Kanban board views.
    • Resources: Browseable content including individual specifications (spec://<spec-name>), the Kanban board (board://kanban), and project statistics (stats://overview).
    • Prompts: Templates for common workflows like creating feature specs, updating status, and discovering related specs.

  8. List and filter specifications using leanspec list

    The leanspec list command provides an overview of specifications. By default, it excludes archived specs. You can refine the list using status, tag, and priority filters. Multiple filters can be combined to narrow down results.
    # List all active specs
leanspec list

# Include archived specs
leanspec list --archived

# Filter by status (planned, in-progress, complete)
leanspec list --status in-progress

# Filter by one or more tags
leanspec list --tag api
leanspec list --tag api --tag backend

# Filter by priority (high, low)
leanspec list --priority high

# Combine multiple filters
leanspec list --priority high --tag backend --status planned

  9. Use LeanSpec specs as semantic memory for AI agents

    AI agents typically rely on ephemeral working memory (chat history), which is limited by context windows and lost between sessions. LeanSpec solves this by using specs as 'semantic memory'—a persistent, structured knowledge layer that stores long-term facts, decisions, and rationale. This allows agents to maintain consistent behavior across sessions and reduces hallucinations by grounding responses in documented project history.

  10. Understand the role of specifications in AI-assisted development

    LeanSpec addresses the inherent unpredictability of AI agents and the theoretical limits of automation:

    • AI Unpredictability: Specifications do not eliminate AI non-determinism (the tendency to generate unrequested features or change assumptions), but they reduce it by providing better-informed context for human review.
    • The Automation Reality: LeanSpec focuses on alignment and intent documentation rather than promising specific automation percentages. The goal is a 10-30% productivity improvement through better human-AI collaboration.
    • Theoretical Grounding (Rice's Theorem): Because all non-trivial semantic properties of programs are undecidable, an AI cannot algorithmically determine 'what the user wants.' Specifications provide the necessary semantic grounding, translating human intent into checkable assertions that make verification tractable.

  11. Structure a spec using Core Anatomy

    A standard spec should consist of four primary sections to ensure clarity and machine-readability:

    1. Frontmatter: Machine-readable metadata such as status, priority, tags, and dependencies.
    2. Overview: Description of the problem, why it matters, and the desired outcome.
    3. Plan / Design: Detailed phases, trade-offs, or approach notes.
    4. Validation: Specific criteria for confirming the work is complete.

  12. Visualize project status with the LeanSpec board

    The leanspec board command provides a Kanban-style overview of the entire project, organizing specs into status columns: Planned → In Progress → Complete → Archived. It also displays project health metrics such as completion rate, recent activity, and identifies 'blocked' specs (those with unmet depends_on relationships).
    leanspec board