What is 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.
Think of it as "Markdown for Project Management": Simple, structured, and machine-readable.
Quick Start
# Try with a tutorial project
npx -p @leanspec/cli leanspec init --example dark-theme
cd dark-theme && npm install && npm start
# Or add to your existing project
npm install -g @leanspec/cli && leanspec init
Visualize your project:
leanspec board # Kanban view
leanspec stats # Project metrics
leanspec 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 →
Features
| Feature | Description |
|---|---|
| 📊 Kanban Board | leanspec board - visual project tracking |
| 🔍 Smart Search | leanspec search - find specs by content or metadata |
| 🔗 Dependencies | Track spec relationships with depends_on and related |
| 🎨 Web UI | leanspec ui - browser-based dashboard |
| 📈 Project Stats | leanspec stats - health metrics and bottleneck detection |
| 🤖 AI-Native | MCP server + CLI for AI assistants |
AI Integration
Works with any AI coding assistant via MCP or CLI:
{
"mcpServers": {
"leanspec": { "command": "npx", "args": ["@leanspec/mcp"] }
}
}
Compatible with: VS Code Copilot, Cursor, Windsurf, Claude Code, Gemini CLI, and more.
What You Get
- Core CLI: Manage specs, track status, and visualize dependencies.
- MCP Server: Give AI agents direct access to read and search your specs.
- Visual Mode: A beautiful web interface for browsing your project's spec graph.
A Simple Example
A LeanSpec is just a Markdown file with frontmatter:
---
status: in-progress
created: 2025-11-07
priority: high
tags: [api, auth]
---
# User Authentication API
## Goal
Enable secure user login and session management for the mobile app.
## Key Scenarios
1. User logs in with email/password → receives JWT token
2. User accesses protected endpoint with token → gets data
3. User token expires → receives 401, must re-authenticate
## Acceptance Criteria
- [ ] Login endpoint returns valid JWT on success
- [ ] JWT includes user ID and expiration
- [ ] Protected endpoints verify JWT signature
## Non-Goals
- Social login (future feature)
- Password reset (separate spec)
Documentation
📖 Full Documentation · CLI Reference · First Principles · FAQ
Community
💬 Discussions · 🐛 Issues · 🤝 Contributing
Next Steps
- Getting Started: Install the CLI and create your first spec.
- Why LeanSpec?: Understand the benefits of LeanSpec over other tools.
- Understanding LeanSpec: Dive deeper into the "Context Economy" philosophy.
- AI Integration: Connect LeanSpec to your AI coding assistant.
Contact Me
If you feel LeanSpec could benefit your daily work or your company, please add the author's Wechat account noting "LeanSpec" to enter the discussion group.
