LeanSpec

Ship faster with higher quality. Lean specs that both humans and AI understand.

LeanSpec brings agile principles to SDD (Spec-Driven Development)—small, focused documents (<2,000 tokens) that keep you and your AI aligned.

Quick Start

# Try with a tutorial project
npx lean-spec init --example dark-theme
cd dark-theme && npm install && npm start

# Or add to your existing project
npm install -g lean-spec && lean-spec init

Visualize your project:

lean-spec board    # Kanban view
lean-spec stats    # Project metrics
lean-spec ui       # Web UI at localhost:3000

Next: Your First Spec with AI (10 min tutorial)

Why LeanSpec?

High velocity + High quality. Other SDD frameworks add process overhead (multi-step workflows, rigid templates). Vibe coding is fast but chaotic (no shared understanding). LeanSpec hits the sweet spot:

• Fast iteration - Living documents that grow with your code
• AI performance - Small specs = better AI output (context rot is real)
• Always current - Lightweight enough that you actually update them

📖 Compare with Spec Kit, OpenSpec, Kiro →

AI Integration

Works with any AI coding assistant via MCP or CLI:

{
  "mcpServers": {
    "lean-spec": { "command": "npx", "args": ["@leanspec/mcp"] }
  }
}

Compatible with: VS Code Copilot, Claude Code, Gemini CLI, Cursor, Windsurf, Kiro CLI, Kimi CLI, Qodo CLI, Amp, Trae Agent, Qwen Code, Droid, and more.

📖 Full AI integration guide →

Agent Skills

Teach your AI assistant the Spec-Driven Development methodology:

# Recommended (uses skills.sh)
lean-spec skill install

# Or directly via skills.sh
npx skills add codervisor/lean-spec -y

This installs the leanspec-sdd skill which teaches AI agents:

• When to create specs vs. implement directly
• How to discover existing specs before creating new ones
• Best practices for context economy and progressive disclosure
• Complete SDD workflow (Discover → Design → Implement → Validate)

Compatible with: Claude Code, Cursor, Windsurf, GitHub Copilot, and other Agent Skills compatible tools.

📖 View skill documentation →

Features

| Feature | Description | | ------------------- | ------------------------------------------------------------- | | 📊 Kanban Board | lean-spec board - visual project tracking | | 🔍 Smart Search | lean-spec search - find specs by content or metadata | | 🔗 Dependencies | Track spec relationships with depends_on and related | | 🎨 Web UI | lean-spec ui - browser-based dashboard | | 📈 Project Stats | lean-spec stats - health metrics and bottleneck detection | | 🤖 AI-Native | MCP server + CLI for AI assistants | | 🖥️ Desktop App | Native Tauri shell with tray + shortcuts (pnpm dev:desktop) |

Requirements

Runtime

• Node.js: >= 20.0.0
• pnpm: >= 10.0.0 (preferred package manager)

Development

• Node.js: >= 20.0.0
• Rust: >= 1.70 (for building CLI/MCP/HTTP binaries)
• pnpm: >= 10.0.0

Quick Check:

node --version   # Should be v20.0.0 or higher
pnpm --version   # Should be 10.0.0 or higher
rustc --version  # Should be 1.70 or higher (dev only)

Desktop App

The @leanspec/desktop package wraps the Vite UI (@leanspec/ui) in a lightweight Tauri shell for local, multi-project workflows backed by Rust commands:

# Launch the desktop shell with hot reload
pnpm install
pnpm dev:desktop

# Produce signed installers + embedded UI bundle
pnpm build:desktop

Key capabilities:

• Frameless window with custom title bar + native controls
• Global shortcuts (Cmd/Ctrl+Shift+L to toggle, Cmd/Ctrl+Shift+K to open the project switcher, Cmd/Ctrl+Shift+N to add a spec)
• Shared project registry + native folder picker backed by ~/.lean-spec/projects.json
• System tray with recent projects, background notifications, and update checks
• Embedded Vite static build + Rust HTTP server for offline packaging (macOS .dmg, Windows .msi/.exe, Linux .AppImage/.deb/.rpm)

See packages/desktop/README.md for configuration details.

Developer Workflow

Common development tasks using pnpm:

# Development
pnpm install             # Install dependencies
pnpm build               # Build all packages
pnpm dev                 # Start dev mode (UI + Core)
pnpm dev:web             # UI only
pnpm dev:cli             # CLI only
pnpm dev:desktop         # Desktop app

# Testing
pnpm test                # Run all tests
pnpm test:ui             # Tests with UI
pnpm test:coverage       # Coverage report
pnpm typecheck           # Type check all packages

# Rust
pnpm rust:build          # Build Rust packages (release)
pnpm rust:build:dev      # Build Rust (dev, faster)
pnpm rust:test           # Run Rust tests
pnpm rust:check          # Quick Rust check
pnpm rust:clippy         # Rust linting
pnpm rust:fmt            # Format Rust code

# CLI (run locally)
pnpm cli board           # Show spec board
pnpm cli list            # List specs
pnpm cli create my-feat  # Create new spec
pnpm cli validate        # Validate specs

# Documentation
pnpm docs:dev            # Start docs site
pnpm docs:build          # Build docs

# Release
pnpm pre-release         # Run all pre-release checks
pnpm prepare-publish     # Prepare for npm publish
pnpm restore-packages    # Restore after publish

See package.json for all available scripts.

Documentation

📖 Full Documentation · CLI Reference · First Principles · FAQ · 中文文档

Community

💬 Discussions · 🐛 Issues · 🤝 Contributing · 📋 Changelog · 📄 LICENSE

Contact Me | 联系我

If you find LeanSpec helpful, feel free to add me on WeChat (note "LeanSpec") to join the discussion group.

如果您觉得 LeanSpec 对您有帮助，欢迎添加微信（备注 "LeanSpec"）加入交流群。