Planu

Spec Driven Development for AI coding agents.

Documentation · Docs in Spanish · Docs in Portuguese

What is Planu?

Planu is an MCP server that enforces Spec Driven Development — a structured workflow where AI coding agents write specs before writing code. Think of it as BDD for the AI era: define behavior first, implement second, validate continuously.

Spec first, always. No approved spec means no code. This eliminates vibe-coding debt at scale.

• 556 MCP tools across spec lifecycle, Figma, analysis, documentation, git, integrations, and autopilot
• Works with any language or framework: TypeScript, Python, Go, Rust, Ruby, Java, and more
• Compatible with Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client
• All data stored locally as JSON — no cloud, no accounts required
• Available in English, Spanish, and Portuguese

Installation

Add to your MCP client config (Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "planu": {
      "command": "npx",
      "args": ["-y", "@planu/cli@latest"]
    }
  }
}

Requirements: Node.js >= 22. No API keys needed for core functionality.

Using @latest means npx auto-updates on every start — no reinstall needed.

The SDD Lifecycle

init_project → create_spec → challenge_spec → check_readiness → implement → validate → done

Every transition is gated by Definition of Ready (DoR) and Definition of Done (DoD) checks. Specs are the single source of truth — implementation is validated against them, not the other way around.

Autopilot: tools cascade automatically

Planu runs follow-up actions automatically after each step. You don't need to know tool names or chain calls manually:

• create_spec automatically runs challenge_spec + check_readiness
• update_status(done) automatically runs validate + generates changelog + scans crash risks
• update_status(approved) automatically snapshots the spec version
• Tools act — they don't suggest. Output tells you what was done, not what you should do next.

Lean Spec Format

Specs are intentionally lightweight: 2 files per spec, ~30-50 lines each, with YAML frontmatter.

planu/specs/SPEC-001-auth/
├── spec.md       # requirements, criteria (GIVEN/WHEN/THEN), status
└── technical.md  # files, stack, implementation notes

Criteria use zero-ambiguity GIVEN/WHEN/THEN format — no vague acceptance criteria that LLMs misinterpret.

Figma Integration

Connect your Figma designs directly to specs:

configure_figma → list_figma_frames → get_figma_context_for_spec → enrich_specs_from_figma

• Extract design tokens (colors, spacing, typography) into code-ready variables
• Map Figma components to codebase components via Code Connect
• Auto-generate .claude/rules/figma-design-system.md with your design system rules
• Detect visual drift between Figma and implementation
• Generate Figma-aware e2e tests

Tool Categories

Planu ships 556 tools total. Key tools per category:

Spec Lifecycle

create_spec · list_specs · update_status · validate · reconcile_spec · challenge_spec · check_readiness · decompose_spec · diff_spec_versions · lock_spec · branch_spec

Figma

configure_figma · list_figma_frames · get_figma_context_for_spec · enrich_specs_from_figma · generate_figma_rules_file · extract_figma_design_tokens · sync_figma_code_connect · check_figma_design_drift

Analysis & Estimation

estimate · reverse_engineer · detect_drift · validate · audit · security_scan · scan_crash_risks · spec_quality_score · calibrate_estimates

Documentation

generate_docs_site · export_pdf · generate_release_notes · generate_changelog · generate_diagram · export_specs_markdown

Git & CI

manage_git · generate_planu_ci · create_pr_from_spec · link_pr_to_spec · review_pr_against_spec

Integrations

configure_slack · configure_jira · configure_linear · configure_notion · sync_to_jira · sync_to_linear · sync_to_notion

Autopilot

configure_autopilot · agent_health · workspace_health · auto_fix_health · workspace_overview

Getting Started

1. Initialize your project

"Initialize my project at /path/to/my-app with planu"

Planu scans the directory, detects your language, framework, and architecture. Sets up hooks, rules, and skills automatically. No manual configuration.

2. Create a spec

"Create a spec for Google OAuth authentication"

Planu generates a lean spec with GIVEN/WHEN/THEN criteria, automatically stress-tests it with challenge_spec, and checks readiness. You approve, then implement.

3. Implement against the spec

Claude uses the spec as a contract while coding. When done:

"Validate SPEC-001 against the implementation"

Planu reports which criteria are covered, missing, or drifted.

4. Living specs

As the codebase evolves, reconcile implementation back to specs:

"Reconcile SPEC-001 with the recent changes"

Configuration

Telemetry

Planu collects anonymous usage data by default: tool names, version, and platform. No file paths, no code, no PII is ever collected.

To opt out, set PLANU_TELEMETRY=off in your MCP config environment:

{
  "mcpServers": {
    "planu": {
      "command": "npx",
      "args": ["-y", "@planu/cli@latest"],
      "env": {
        "PLANU_TELEMETRY": "off"
      }
    }
  }
}

Architecture

src/
├── index.ts          # MCP server entry point
├── tools/            # 556 MCP tool handlers
├── resources/        # MCP resources (read-only)
├── engine/           # Business logic (estimator, analyzer, validator)
├── storage/          # JSON persistence layer
├── types/            # TypeScript interfaces (16 domain files)
└── config/           # Extensible registries and signatures

data/                 # Local storage (gitignored)
├── projects/{hash}/  # Per-project: specs, metrics, patterns, knowledge
└── global/           # Shared: templates, pricing

Development

pnpm install       # Install dependencies
pnpm build         # Compile TypeScript
pnpm dev           # Watch mode
pnpm typecheck     # Type-check src/ + tests/
pnpm lint          # ESLint (zero warnings)
pnpm test          # Run all tests
pnpm test:coverage # Run tests with coverage thresholds
pnpm check         # typecheck + lint + format check

Contributing

See CONTRIBUTING.md for GitFlow strategy, branch naming, commit conventions, and PR process.

License

MIT