Skip to content
Back to search

leanspec

Lightweight, flexible Spec-Driven Development (SDD) for modern AI-powered development

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/codervisor-leanspec/badge.svg)](/listings/codervisor-leanspec)

HTML

<a href="/listings/codervisor-leanspec"><img src="/api/listings/codervisor-leanspec/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Markdown specs (default — works out of the box)
npm install -g @leanspec/cli && leanspec init

# Or try with a tutorial project
npx -p @leanspec/cli leanspec init --example dark-theme
cd dark-theme && npm install && npm start

**Configure your spec backend:**

# leanspec.provider.yaml

# Option 1: Markdown files (default, zero config)
provider: markdown
directory: specs

# Option 2: GitHub Issues as specs
# provider: github
# owner: myuser
# repo: myproject

# Option 3: Azure DevOps Work Items as specs
# provider: ado
# organization: mycompany
# project: myproject

**Visualize your project (works with any backend):**

leanspec board    # Kanban view
leanspec stats    # Project metrics
leanspec ui       # Web UI at localhost:3000

**Next:** [Your First Spec with AI](https://www.lean-spec.dev/docs/tutorials/first-spec-with-ai) (10 min tutorial)

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 267 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # LeanSpec
  2. <p align="center">
  3. <img src="https://github.com/codervisor/lean-spec-docs/blob/main/static/img/logo-with-bg.svg" alt="LeanSpec Logo" width="120" height="120">
  4. </p>
  5. <p align="center">
  6. <a href="https://github.com/codervisor/leanspec/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/codervisor/leanspec/ci.yml?branch=main" alt="CI Status"></a>
  7. <a href="https://www.npmjs.com/package/@leanspec/cli"><img src="https://img.shields.io/npm/v/@leanspec/cli.svg" alt="npm version"></a>
  8. <a href="https://www.npmjs.com/package/@leanspec/cli"><img src="https://img.shields.io/npm/dm/@leanspec/cli.svg" alt="npm downloads"></a>
  9. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
  10. </p>
  11. <p align="center">
  12. <a href="https://www.lean-spec.dev"><strong>Documentation</strong></a>
  13. •
  14. <a href="https://www.lean-spec.dev/zh-Hans/docs/guide/"><strong>中文文档</strong></a>
  15. •
  16. <a href="https://web.lean-spec.dev"><strong>Live Examples</strong></a>
  17. •
  18. <a href="https://www.lean-spec.dev/docs/tutorials/first-spec-with-ai"><strong>Tutorials</strong></a>
  19. </p>
  20. ---
  21. **The tool-agnostic spec framework. Use any spec backend — your workflow, your rules.**
  22. LeanSpec is a spec coding framework that works with whatever spec workflow you already use. GitHub Issues for personal projects, ADO Work Items for enterprise, Jira, Linear, or plain markdown — LeanSpec provides the unified interface, AI integration, and intelligence layer on top.
  23. ---
  24. ## Quick Start
  25. ```bash
  26. # Markdown specs (default — works out of the box)
  27. npm install -g @leanspec/cli && leanspec init
  28. # Or try with a tutorial project
  29. npx -p @leanspec/cli leanspec init --example dark-theme
  30. cd dark-theme && npm install && npm start
  31. ```
  32. **Configure your spec backend:**
  33. ```yaml
  34. # leanspec.provider.yaml
  35. # Option 1: Markdown files (default, zero config)
  36. provider: markdown
  37. directory: specs
  38. # Option 2: GitHub Issues as specs
  39. # provider: github
  40. # owner: myuser
  41. # repo: myproject
  42. # Option 3: Azure DevOps Work Items as specs
  43. # provider: ado
  44. # organization: mycompany
  45. # project: myproject
  46. ```
  47. **Visualize your project (works with any backend):**
  48. ```bash
  49. leanspec board # Kanban view
  50. leanspec stats # Project metrics
  51. leanspec ui # Web UI at localhost:3000
  52. ```
  53. **Next:** [Your First Spec with AI](https://www.lean-spec.dev/docs/tutorials/first-spec-with-ai) (10 min tutorial)
  54. ---
  55. ## Why LeanSpec?
  56. **Your workflow, not ours.** Other SDD frameworks force you to adopt their spec format and tooling. LeanSpec adapts to whatever you already use:
  57. - **Tool-agnostic** - GitHub Issues, ADO, Jira, Linear, Notion, or plain markdown
  58. - **One interface** - Same CLI, MCP, and UI regardless of backend
  59. - **AI-native** - Structured spec data for any AI coding assistant
  60. - **Fast iteration** - Living documents that grow with your code
  61. - **Context economy** - Small specs (<2K tokens) = better AI output
  62. 📖 [Compare with Spec Kit, OpenSpec, Kiro →](https://www.lean-spec.dev/docs/guide/why-leanspec)
  63. ---
  64. ## AI Integration
  65. Works with any AI coding assistant via MCP or CLI:
  66. ```json
  67. {
  68. "mcpServers": {
  69. "leanspec": { "command": "npx", "args": ["@leanspec/mcp"] }
  70. }
  71. }
  72. ```
  73. **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.
  74. 📖 [Full AI integration guide →](https://www.lean-spec.dev/docs/guide/usage/ai-coding-workflow)
  75. ---
  76. ## Spec Providers
  77. LeanSpec connects to your existing spec workflow through a provider architecture:
  78. | Provider | Backend | Status |
  79. |----------|---------|--------|
  80. | `markdown` | Local `specs/` directory (default) | **Available** |
  81. | `github` | GitHub Issues + Projects | Planned |
  82. | `ado` | Azure DevOps Work Items | Planned |
  83. | `jira` | Jira tickets | Future |
  84. | `linear` | Linear issues | Future |
  85. Core LeanSpec concepts map naturally to each backend:
  86. | Concept | GitHub Issues | ADO Work Items | Markdown |
  87. |---------|--------------|----------------|----------|
  88. | Spec ID | Issue number | Work Item ID | Directory name |
  89. | Status | Labels | State field | Frontmatter |
  90. | Priority | Labels | Priority field | Frontmatter |
  91. | Tags | Labels | Tags | Frontmatter |
  92. | Assignee | Assignees | Assigned To | Frontmatter |
  93. | Content | Issue body | Description | Markdown body |
  94. 📖 [Provider architecture →](https://www.lean-spec.dev/docs/guide/providers)
  95. ---
  96. ## Agent Skills
  97. Teach your AI assistant the Spec-Driven Development methodology:
  98. ```bash
  99. # Install the leanspec skill
  100. npx skills add codervisor/leanspec@leanspec
  101. ```
  102. This installs the **leanspec** skill which teaches AI agents:
  103. - When to create specs vs. implement directly
  104. - How to discover existing specs before creating new ones
  105. - Best practices for context economy and progressive disclosure
  106. - Complete SDD workflow (Discover → Design → Implement → Validate)
  107. **Compatible with:** Claude Code, Cursor, Windsurf, GitHub Copilot, and other [Agent Skills](https://skills.sh/) compatible tools.
  108. 📖 [Skill source →](skills/leanspec/SKILL.md)
  109. ---
  110. ## Features
  111. | Feature | Description |
  112. | ------------------- | ------------------------------------------------------------------------------------------------- |
  113. | **📊 Kanban Board** | `leanspec board` - visual project tracking |
  114. | **🔍 Smart Search** | `leanspec search` - find specs by content or metadata |
  115. | **🔗 Dependencies** | Track spec relationships with `depends_on` and `related` |
  116. | **🎨 Web UI** | `leanspec ui` - browser-based dashboard |
  117. | **📈 Project Stats** | `leanspec stats` - health metrics and bottleneck detection |
  118. | **🤖 AI-Native** | MCP server + CLI for AI assistants |
  119. | **🖥️ Desktop App** | Desktop app repo: [codervisor/lean-spec-desktop](https://github.com/codervisor/lean-spec-desktop) |
  120. <p align="center">
  121. <img src="https://github.com/codervisor/lean-spec-docs/blob/main/static/img/ui/ui-board-view.png" alt="Kanban Board View" width="800">
  122. </p>
  123. ---
  124. ## Requirements
  125. ### Runtime
  126. - **Node.js**: `>= 20.0.0`
  127. - **pnpm**: `>= 10.0.0` (preferred package manager)
  128. ### Development
  129. - **Node.js**: `>= 20.0.0`
  130. - **Rust**: `>= 1.70` (for building CLI/MCP/HTTP binaries)
  131. - **pnpm**: `>= 10.0.0`
  132. **Quick Check:**
  133. ```bash
  134. node --version # Should be v20.0.0 or higher
  135. pnpm --version # Should be 10.0.0 or higher
  136. rustc --version # Should be 1.70 or higher (dev only)
  137. ```
  138. ---
  139. ## Desktop App
  140. The desktop application has moved to a dedicated repository:
  141. - https://github.com/codervisor/lean-spec-desktop
  142. Use that repository for desktop development, CI, and release workflows.
  143. ---
  144. ## Developer Workflow
  145. Common development tasks using `pnpm`:
  146. ```bash
  147. # Development
  148. pnpm install # Install dependencies
  149. pnpm build # Build all packages
  150. pnpm dev # Start dev mode (UI + Core)
  151. pnpm dev:web # UI only
  152. pnpm dev:cli # CLI only
  153. # Testing
  154. pnpm test # Run all tests
  155. pnpm test:ui # Tests with UI
  156. pnpm test:coverage # Coverage report
  157. pnpm typecheck # Type check all packages
  158. # Rust
  159. pnpm rust:build # Build Rust packages (release)
  160. pnpm rust:build:dev # Build Rust (dev, faster)
  161. pnpm rust:test # Run Rust tests
  162. pnpm rust:check # Quick Rust check
  163. pnpm rust:clippy # Rust linting
  164. pnpm rust:fmt # Format Rust code
  165. # CLI (run locally)
  166. pnpm cli board # Show spec board
  167. pnpm cli list # List specs
  168. pnpm cli create my-feat # Create new spec
  169. pnpm cli validate # Validate specs
  170. # Documentation
  171. pnpm docs:dev # Start docs site
  172. pnpm docs:build # Build docs
  173. # Release
  174. pnpm pre-release # Run all pre-release checks
  175. pnpm prepare-publish # Prepare for npm publish
  176. pnpm restore-packages # Restore after publish
  177. ```
  178. See [package.json](package.json) for all available scripts.
  179. ---
  180. ## Documentation
  181. 📖 [Full Documentation](https://www.lean-spec.dev) · [CLI Reference](https://www.lean-spec.dev/docs/reference/cli) · [First Principles](https://www.lean-spec.dev/docs/advanced/first-principles) · [FAQ](https://www.lean-spec.dev/docs/faq) · [中文文档](https://www.lean-spec.dev/zh-Hans/)
  182. ## Community
  183. 💬 [Discussions](https://github.com/codervisor/leanspec/discussions) · 🐛 [Issues](https://github.com/codervisor/leanspec/issues) · 🤝 [Contributing](CONTRIBUTING.md) · 📋 [Changelog](CHANGELOG.md) · 📄 [LICENSE](LICENSE)
  184. ---
  185. ### Contact Me | 联系我
  186. If you find LeanSpec helpful, feel free to add me on WeChat (note "LeanSpec") to join the discussion group.
  187. 如果您觉得 LeanSpec 对您有帮助,欢迎添加微信(备注 "LeanSpec")加入交流群。
  188. <p align="center">
  189. <img src="https://github.com/codervisor/lean-spec-docs/blob/main/static/img/qr-code.png" alt="WeChat Contact | 微信联系" height="280">
  190. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.