LeanSpec — Summary

LeanSpec is a tool-agnostic spec framework that provides a unified CLI (leanspec), MCP server (@leanspec/mcp), and optional web UI / desktop app over whatever spec backend a team already uses — local markdown files, GitHub Issues, Azure DevOps Work Items, Jira, Linear, or Notion. Unlike every other SDD framework in this corpus, LeanSpec treats the spec storage backend as a pluggable provider, meaning the same CLI and AI skill work identically whether specs live in a specs/ markdown folder or in GitHub Issues. It ships a Kanban board (leanspec board), project stats, web UI at localhost:3000 (leanspec ui), and an @leanspec/skills package that teaches AI agents the five-phase SDD workflow (Discover → Create → Refine → Implement → Verify). The binary is implemented in Rust (for CLI/MCP binaries) with TypeScript packages (Node.js >= 20), and integrates with virtually every AI coding assistant via MCP. Compared to seeds, LeanSpec differs most strongly from openspec (also a multi-tool, npm-published CLI for SDD) by its provider abstraction and web UI, and from spec-kit (Python CLI, hooks) by having first-class GitHub Issues and ADO integration rather than a file-only spec store. It has 252 stars, active development (last commit May 2026).

LeanSpec — Origin & Philosophy

Origin

Maintained by the codervisor organization (same org that built spec-kit and OpenSpec — this is the third-generation tool from the same authors). Last commit May 2026, 252 stars, 5 contributors. Active development with CI and a published docs site at lean-spec.dev.

Core Philosophy

"Your workflow, not ours." Other SDD frameworks force you to adopt their spec format and tooling. LeanSpec adapts to whatever you already use.

Manifesto-style Quotes (verbatim from README)

"Tool-agnostic — GitHub Issues, ADO, Jira, Linear, Notion, or plain markdown. One interface — Same CLI, MCP, and UI regardless of backend. AI-native — Structured spec data for any AI coding assistant. Fast iteration — Living documents that grow with your code. Context economy — Small specs (<2K tokens) = better AI output."

"📖 Compare with Spec Kit, OpenSpec, Kiro →"

"The tool-agnostic spec framework. Use any spec backend — your workflow, your rules."

Provider Architecture

LeanSpec's key architectural bet: a provider abstraction layer maps universal concepts (Spec ID, Status, Priority, Tags, Assignee, Content) to each backend's native fields. The leanspec capabilities -o json command returns the active adapter's field vocabulary at runtime, and the AI skill is instructed to use only that vocabulary — no hard-coded field names.

Lineage

The README explicitly names spec-kit and OpenSpec as predecessors from the same team. LeanSpec is positioned as the "third evolution" that adds the provider abstraction layer and multi-tool web UI on top of the SDD methodology proven by the earlier tools.

LeanSpec — Architecture

Distribution

npm packages: @leanspec/cli, @leanspec/mcp, @leanspec/skills. Binaries compiled from Rust.

Install

npm install -g @leanspec/cli && leanspec init
# or try with tutorial project:
npx -p @leanspec/cli leanspec init --example dark-theme

Packages (pnpm workspace)

packages/
├── cli/           # @leanspec/cli — main CLI, Rust binaries bundled
├── mcp/           # @leanspec/mcp — MCP server
├── http-server/   # HTTP server variant
└── ui/            # @leanspec/ui — web dashboard (React/Vite)

Required Runtime

• Node.js >= 20.0.0
• pnpm >= 10.0.0
• Rust >= 1.70 (development only, binaries pre-compiled for distribution)

Configuration

# leanspec.provider.yaml
provider: markdown   # or: github, ado, jira, linear
directory: specs     # for markdown provider
# provider: github
# owner: myuser
# repo: myproject

Directory Structure (markdown provider)

specs/
└── <spec-id>/
    ├── index.md    # spec content with YAML frontmatter
    └── ...
leanspec.provider.yaml   # backend configuration

AI Integration

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

Claude Code Skills Install

npx skills add codervisor/leanspec@leanspec

Target AI Tools

Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI, Kiro CLI, Kimi CLI, Qodo CLI, Amp, Trae Agent, Qwen Code, Droid, and more.

Spec Providers (Status as of analysis)

• markdown — Available
• github — Planned
• ado — Planned
• jira — Future
• linear — Future

Desktop App

Separate repo: codervisor/lean-spec-desktop

LeanSpec — Components

CLI Commands (leanspec binary)

MCP Server (@leanspec/mcp)

Exposes spec CRUD and board operations to any MCP-compatible AI tool. Same functionality as CLI, accessible to agents via MCP protocol.

Skills (@leanspec/skills — the leanspec skill)

Installed via npx skills add codervisor/leanspec@leanspec. A single skill file (skills/leanspec/SKILL.md) that teaches AI agents:

• Five-phase workflow: Discover → Create → Refine → Implement → Verify
• Provider-agnostic vocabulary pattern (use capabilities output, never hard-code field names)
• Spec as durable artifact (not ephemeral scratch pad)

Claude Code Hooks (project .claude/settings.json)

{
  "hooks": {
    "SessionStart": [{"type": "command", "command": "bash .claude/hooks/session-start.sh"}]
  }
}

1 hook: SessionStart → runs session-start.sh.

Claude Code Skills (.claude/skills/)

4 project-internal skills:

• leanspec-dev-process — development process for LeanSpec itself
• leanspec-pr-lifecycle — PR lifecycle for LeanSpec contributors
• leanspec-pre-push — pre-push checklist
• watch-ci — CI monitoring

Hooks (.husky/)

• commit-msg — commit message lint (commitlint)

Web UI

React/Vite-based dashboard. leanspec ui serves it at localhost:3000. Features: Kanban board, spec list, search, stats.

LeanSpec — Uniqueness & Positioning

differs_from_seeds

Most similar to openspec (same authorship lineage, same multi-command npm CLI for spec-driven development), but LeanSpec adds the provider abstraction that openspec lacks — where openspec stores specs as local markdown files only, LeanSpec routes to GitHub Issues, ADO, Jira, or markdown via a provider layer. Versus spec-kit (same origin team), LeanSpec replaces the Python CLI + hooks pattern with an npm CLI + MCP + web UI pattern, adding a kanban board and removing the hook-per-command structure. Against kiro (also ships spec format + workflow states), LeanSpec is open-source, multi-tool, and doesn't require a proprietary IDE. The leanspec capabilities -o json runtime vocabulary discovery pattern is unique: no other seed uses a live query to determine what field names are valid before operating on specs.

Unique Positioning

The only framework in this batch (and corpus) with: (1) pluggable spec backends (markdown, GitHub Issues, ADO), (2) a built-in web kanban dashboard, (3) a runtime vocabulary discovery pattern via capabilities query. It is explicitly positioned as the successor to spec-kit and openspec by the same team.

Observable Failure Modes

1. Planned providers not implemented: GitHub Issues and ADO providers are "Planned" as of analysis date — only markdown works.
2. Desktop app in separate repo: fragmentation risk; desktop and CLI may diverge.
3. No TDD enforcement: despite calling itself spec-driven, there is no hook or gate that prevents code-before-spec.
4. Context economy claim unverified: the "<2K tokens" spec size guidance is aspirational, not enforced.
5. Rust build requirement: contributors need Rust for local development, raising the barrier vs pure-Node projects.

Explicit Antipatterns (from skill)

• Creating a spec and then patching it (use single-call creation)
• Hard-coding field names instead of using capabilities output
• Expanding scope instead of creating a new linked spec
• Trusting spec status field without verifying code/tests/CI