# Planu

**Spec Driven Development for AI coding agents.**

![Build](https://img.shields.io/badge/build-passing-brightgreen)
![License](https://img.shields.io/badge/license-MIT-blue)
![Node](https://img.shields.io/badge/node-%3E%3D22.0.0-green)

📚 **[Documentation](https://planu.dev)** · 🇪🇸 **[Documentación en Español](https://planu.dev/es)**

## Installation

### Claude Desktop / Claude Code

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

```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

| Tool | Description |
|------|-------------|
| `set_locale` | Change the active locale for messages and spec templates |
| `init_project` | Initialize a project -- detects language, framework, architecture, and stores project knowledge; also detects AI-native architecture patterns (inference mode, orchestration frameworks), frontend performance setup (Core Web Vitals budgets, SSR frameworks), and K3s/Nomad workload orchestrators |
| `init_constitution` | Generate the project constitution -- immutable architectural principles extracted from CLAUDE.md, .cursorrules; auto-enforced in create_spec, audit, and drift detection |

### B -- Spec Lifecycle

| Tool | Description |
|------|-------------|
| `clarify_requirements` | Generate targeted clarification questions before creating a spec |
| `create_spec` | Create a full SDD spec with auto-generated sections: ADR hints, DB schema, UI contracts, test plan, execution plan, DoR checklist; generates AI-native architecture criteria (latency budgets, fallback chains, prompt versioning) and frontend performance criteria (Core Web Vitals, SSR hydration, MFE boundaries) when detected |
| `list_specs` | List all specs for a project, optionally filtering by status |
| `update_status` | Transition a spec through its lifecycle with DoR/DoD validation at each step |
| `summarize_spec` | Generate a concise summary of a spec |
| `generate_checklist` | Generate a quality checklist for a spec |
| `reconcile_spec` | Reconcile spec with implementation changes, with per-change approval and Constitution compliance check |
| `manage_scope` | Manage the project scope definition and backlog |
| `detect_contradictions` | Analyze all specs in a project for semantic contradictions |
| `check_readiness` | Evaluate if a spec is ready for implementation -- completeness, criteria quality, and dependency status |
| `package_handoff` | Generate a structured handoff package for an AI agent to implement a spec, including objective, criteria, file list, and constraints |

### C -- Analysis and Estimation

| Tool | Description |
|------|-------------|
| `estimate` | Estimate effort, cost, and token usage for a spec using multi-agent analysis |
| `reverse_engineer` | Analyze existing code and generate an SDD spec from it |
| `validate` | Validate implementation against its spec -- coverage, drift, and quality |
| `detect_drift` | Detect drift between spec and implementation -- includes Constitution compliance, downstream spec impact |
| `audit` | Audit code for SOLID, clean code, architecture, and Constitution violations; generates quality score 0-100 |
| `learn_pattern` | Teach the system a new pattern (architecture, convention, estimation, stack, quality) |
| `security_check` | Analyze a spec against OWASP Top 10, scan code for insecure patterns, and generate a security score (A–F) with drift detection |
| `capture_learning` | Capture a discovered pattern or lesson into the spec system with semantic deduplication |
| `paradigm_report` | Detect and report the programming paradigms used in a project |
| `reality_check` | Evaluate whether a set of requirements is feasible given the project context |

### D -- Design and Planning

| Tool | Description |
|------|-------------|
| `generate_adr` | Generate Architecture Decision Records for a spec |
| `design_schema` | Design database schema from spec requirements |
| `define_ui_contract` | Define UI component contracts, data flow, and state management |
| `challenge_spec` | Stress-test a spec for failures, concurrency, scale, and edge cases |
| `generate_execution_plan` | Generate a step-by-step PLAN.md for implementing a spec -- RED/GREEN/VERIFY cycle with parallelizable steps |
| `generate_orchestration_script` | Generate a 3-layer parallel automation script (worktrees + claude -p) for running specs concurrently |
| `event_contracts` | Manage event-driven architecture contracts -- generate JSON Schema event contracts for producer/consumer validation |

### E -- Stack and Agents

| Tool | Description |
|------|-------------|
| `suggest_stack` | Suggest a technology stack based on project requirements |
| `check_versions` | Check dependency versions for updates, deprecations, and security issues |
| `generate_skill` | Generate an agent skill file for a specific platform |
| `detect_agent` | Detect the AI coding agent platform in use |
| `generate_sub_agent` | Generate a sub-agent definition for multi-agent orchestration |
| `generate_rules` | Generate agent rules files (.cursorrules, CLAUDE.md, etc.) |

### F -- Dev Lifecycle

| Tool | Description |
|------|-------------|
| `suggest_tooling` | Assess and suggest dev lifecycle tooling (CI/CD, testing, monitoring, etc.); includes AI-native tooling recommendations (LLM observability, semantic cache, prompt management, guardrails) and frontend performance tooling (Lighthouse CI, visual regression, component libraries) |
| `generate_tests` | Generate test plan and test files from a spec |
| `generate_docs` | Generate documentation from specs and code |
| `integrate_pm` | Integrate with project management tools (Jira, Linear, GitHub Issues, etc.) |

### G -- Infrastructure

| Tool | Description |
|------|-------------|
| `manage_context` | Save, load, and manage persistent context notes across sessions |
| `manage_git` | Git integration -- branches, PRs, changelogs, hooks linked to specs |
| `orchestrate` | Multi-agent orchestration -- register agents, lock resources, distribute tasks |
| `consult_docs` | Consult framework documentation for a specific topic |
| `discover_mcps` | Discover MCP servers configured in the environment |
| `suggest_mcps` | Suggest MCP servers that could benefit the project |
| `migrate_tech` | Guide tech stack migration -- analyze source codebase, map equivalences, generate migration plan, validate functional parity, and plan DB migration |
| `orchestrate_agents` | Declare agent capabilities, route tasks to the best agent, generate structured handoff contexts, and detect file-ownership conflicts before parallel execution |
| `validate_workflow` | Validate developer workflow conventions: suggest the right AI model for a task, detect Git Flow violations, audit MCP tool conventions, or run a full workflow audit |
| `log_decision` | Register, list, search, or supersede architectural and process decisions for a project |
| `facilitate` | Entry point for users unfamiliar with Planu -- guides them through the SDD workflow interactively |
| `request_context` | Generate a prompt that asks the user for reference documentation (README, PRD, architecture docs) |
| `contribute_context` | Persist structured knowledge extracted from user-provided documents into the project knowledge base |

### H -- Governance & Stack Health

| Tool | Description |
|------|-------------|
| `data_governance` | Detect PII in specs, generate retention policies, draft privacy notices, and audit GDPR/CCPA/LGPD compliance |
| `audit_stack` | Audit all project dependencies, classify as up_to_date/outdated/vulnerable/unmaintained, and generate a StackHealthScore (0–100) |
| `plan_upgrade` | Generate a migration plan for upgrading a specific package -- breaking changes, estimated effort, and rollback procedure |
| `detect_deprecations` | Scan project source files for deprecated API patterns (no network) and return a deprecation report with tech-debt estimate |

## Quick Setup

```bash
pnpm install
pnpm build
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```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

```bash
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

| Variable | Description | Default |
|----------|-------------|---------|
| `SDD_DATA_DIR` | Path to data storage directory | `./data` |
| `SDD_HOURLY_RATE` | Developer hourly rate (USD) for cost estimation | `50` |
| `SDD_LOCALE` | Default locale (`en`, `es`, `pt`) | `en` |

## Control Panel

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

### Launchers

| Platform | How to run |
|----------|-----------|
| macOS | Double-click `sdd.command` or `bash sdd.sh` |
| Linux / WSL | `bash sdd.sh` |
| Windows | Double-click `sdd.bat` (requires WSL or Git Bash) |
| Makefile | `make watch` / `make status` / `make auto` / `make batch SPECS="..."` |

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
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

| Command | Description |
|---------|-------------|
| `pnpm build` | Compile TypeScript |
| `pnpm dev` | Watch mode |
| `pnpm lint` | Lint with ESLint (zero warnings) |
| `pnpm lint:fix` | Lint and auto-fix |
| `pnpm test` | Run tests with Vitest |
| `pnpm format` | Format with Prettier |
| `pnpm format:check` | Check formatting |
| `pnpm typecheck` | Type-check without emitting |
| `pnpm check` | Run typecheck + lint + format check |

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](https://www.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

```bash
# 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](CONTRIBUTING.md) for the GitFlow strategy, branch naming, commit conventions, and PR process.

## License

[MIT](LICENSE)
