# Planu

**The high-performance SDD stack for AI coding agents.**

[![npm version](https://img.shields.io/npm/v/@planu/cli?color=blue&label=npm)](https://www.npmjs.com/package/@planu/cli)
![Node](https://img.shields.io/badge/node-%3E%3D22.0.0-green)
![Rust](https://img.shields.io/badge/core-rust-orange)
![License](https://img.shields.io/badge/license-MIT-blue)

**[Documentation](https://planu.dev)** · **[Docs in Spanish](https://planu.dev/es)** · **[Docs in Portuguese](https://planu.dev/pt)**

---

## What is Planu?

Planu is the **complete Spec Driven Development stack** for AI coding agents — an MCP server that enforces a structured workflow from brainstorm to validation. Powered by a **native Rust core**, Planu provides the performance and reliability needed for large-scale AI development.

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

- **Native Rust Engine** — 10x faster project scanning, parallel hashing, and regex extraction.
- **Instant Drift Detection** — OS-level file watcher reacts to changes with 0% CPU overhead.
- **Unified Spec Format** — Requirements and technical details in a single, context-efficient `spec.md`.
- **Atomic Integrity** — Indestructible writes and **Freeze-on-done** immutability (P0).
- **14 official MCP tools** for the complete SDD loop, with advanced workflows kept in skills, CLI commands, and internal pipelines.
- **Multi-agent compatible** — Optimized for Claude Code, Cursor, Windsurf, and Gemini CLI.

---

## Installation

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

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

**Requirements:** Node.js >= 22. The native Rust core is bundled and auto-detected for macOS (Intel/M1), Linux, and Windows.

---

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

### Autopilot: tools cascade automatically

Planu runs follow-up actions automatically after each step:

- `create_spec` automatically runs `challenge_spec` + `check_readiness`.
- `update_status(done)` automatically runs `validate` + scans crash risks + **freezes the spec**.
- `update_status(approved)` automatically snapshots the spec version.

---

## Unified Spec Format (v3.0)

Specs are context-efficient: **1 single file per spec** containing both functional requirements and technical implementation details.

```
planu/specs/SPEC-001-auth/
└── spec.md       # Requirements + Technical + Criteria + Status
```

Criteria use **zero-ambiguity GIVEN/WHEN/THEN format** — ensuring your AI never misinterprets the goal.

---

## Native Performance (v3.0)

Planu v3.0 introduces **The Rust Revolution**:

| Feature | Node.js (Legacy) | **Planu-RS (v3.0)** | Benefit |
|---------|:----------------:|:-------------------:|:-------:|
| Project Scanning | Sequential (Slow) | **Parallel (Rayon)** | **10x Speedup** |
| File Watching | Polling/Event Loop | **OS-level (Notify)** | **0% CPU Idle** |
| Spec Hashing | JS Crypto | **Native SHA-256** | Instant Sync |
| Drift Monitor | Memory Heavy | **Streaming Scan** | Monorepo Ready |

---

## Architecture

```
src/
├── engine/           # Hybrid Core: TS Business Logic + Rust Native Engine
│   └── planu-core.node # High-performance native module
├── tools/            # Canonical SDD MCP tools + internal workflow handlers
├── storage/          # Atomic persistence layer
└── types/            # Strict TypeScript contracts

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

---

## Development

```bash
pnpm install       # Install dependencies
pnpm build         # Compile TS + Build Rust bridge
pnpm dev           # Watch mode
pnpm test          # Run 31,000+ tests
```

---

## License

[MIT](LICENSE)
