Planu

Spec Driven Development for AI coding agents.

📚 Documentation · 🇪🇸 Documentación en Español

Installation

Claude Desktop / Claude Code

Add to your claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

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

Requires Node.js ≥ 22. No API keys or accounts needed — all data is stored locally.

Auto-updates: Using @latest ensures users always get the current version. Every time the MCP server starts, npx checks the npm registry and downloads any newer release automatically — no reinstall needed.

What is Planu?

Planu is an MCP (Model Context Protocol) server that brings Spec Driven Development to AI coding agents. It manages the full spec lifecycle -- from requirements clarification and spec creation to estimation, validation, and drift detection. It enforces a project Constitution (immutable architectural principles extracted from CLAUDE.md and .cursorrules), validates DoR/DoD at every lifecycle transition, generates PLAN.md execution files for implementing specs step-by-step, and detects spec versioning drift with cascading downstream impact analysis. Language and framework agnostic, it works with any stack and learns from your codebase over time.

SDD Lifecycle

clarify → create_spec → DoR check → implement (PLAN.md) → validate → drift detection → done

Each transition is gated by DoR (Definition of Ready) and DoD (Definition of Done) checklists. Constitution compliance is enforced automatically at create_spec, audit, and detect_drift. Spec versioning tracks every change and flags downstream spec impact when a dependency drifts.

Getting Started

1. Initialize your project

"Initialize my project at /Users/me/my-app with planu"

Planu scans the directory and auto-detects your language, framework, package manager, and architecture style. It returns a projectId (e.g., proj_abc123) you'll use in all subsequent commands. No manual configuration needed.

2. Create your first spec

"Create a spec for adding Google OAuth authentication to my project proj_abc123"

Planu generates a full HU.md with acceptance criteria, a DoR checklist, database schema hints, and a step-by-step PLAN.md. All stored locally — no accounts, no cloud.

3. Implement guided by the spec

Claude uses the spec as a development contract while you code. When you're done, validate coverage:

"Validate spec SPEC-001 against the code at /Users/me/my-app/src"

4. Detect drift

As the codebase evolves, keep specs in sync:

"Check if my implementation matches SPEC-001 spec"

Planu reports which criteria are covered, missing, or drifted — and flags downstream specs affected by the change.

Use Cases

New feature

"Use planu to create a spec for [feature] in project [id]"

Audit dependencies

"Audit the stack of my project [id] and suggest improvements"

Plan a migration

"Create a migration plan from Express to Fastify for project [id]"

Reverse engineer existing code

"Reverse engineer my codebase at /path/to/project and generate specs"

Detect tech debt

"Analyze tech debt in project [id]"

Features

A -- Configuration

B -- Spec Lifecycle

C -- Analysis and Estimation

D -- Design and Planning

E -- Stack and Agents

F -- Dev Lifecycle

G -- Infrastructure

H -- Governance & Stack Health

Quick Setup

pnpm install
pnpm build

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "planu": {
      "command": "node",
      "args": ["/absolute/path/to/planu/dist/index.js"],
      "env": {
        "SDD_DATA_DIR": "/absolute/path/to/planu/data",
        "SDD_HOURLY_RATE": "50",
        "SDD_LOCALE": "en"
      }
    }
  }
}

Claude Code

claude mcp add planu node /absolute/path/to/planu/dist/index.js

Architecture

src/
├── index.ts          # MCP server entry point
├── tools/            # MCP tool handlers (58 tools, 8 streams A-H)
├── 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
└── i18n/             # Internationalization (en, es, pt)

Data is stored as JSON files in data/ (gitignored):

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

Configuration

Control Panel

Planu ships with a cross-platform interactive launcher and a parallel spec execution system.

Launchers

The menu provides: real-time worker dashboard, system status, automatic batch detection, explicit spec batches, tests, lint, and cleanup.

Parallel Spec Execution

Specs are implemented by autonomous claude -p workers running in isolated git worktrees. Resource allocation is dynamic -- computed at runtime from the machine's physical cores and available RAM.

bash scripts/parallel-specs.sh --status    # show spec readiness and worker state
bash scripts/parallel-specs.sh --auto      # detect and launch next ready batch
bash scripts/parallel-specs.sh SPEC-014a SPEC-021   # launch specific specs
bash scripts/watch-workers.sh 10           # real-time dashboard, refresh every 10s

Worker limits are computed as min(phys_cores / 2, (avail_ram - 3 GB) / 0.35 GB) and capped at 10. A background health monitor warns on high swap and kills the highest-memory worker if swap exceeds 3 GB.

Development

Pre-commit hooks (Husky + lint-staged) run automatically: typecheck, eslint, prettier, commitlint, and secretlint.

Releasing a New Version

Releases are automated via GitHub Actions (.github/workflows/publish.yml). When a commit lands on main with a version bump in package.json, the workflow publishes to npm automatically — no manual npm publish needed.

One-time setup: NPM_TOKEN secret

The workflow requires an NPM_TOKEN secret configured in GitHub:

1. Go to npmjs.com → your account → Access Tokens → Generate New Token
2. Select type Automation (scoped to publish)
3. Copy the token
4. Go to your GitHub repo → Settings → Secrets and variables → Actions → New repository secret
5. Name: NPM_TOKEN — Value: the token from step 3

How to cut a release

# 1. Bump version in package.json (e.g. 0.1.1 → 0.1.2)
# 2. Commit and push to develop
git add package.json && git commit -m "chore(release): bump version to 0.1.2"
git push origin develop

# 3. Merge develop → main (triggers auto-publish)
git checkout main && git merge --ff-only develop && git push origin main

The workflow checks if the version in package.json already exists on npm. If not, it publishes. If yes, it skips silently.

Contributing

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

License

MIT