@planu/cli

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

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

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 (174 tools, 9 streams A-I)
├── 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 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:

• Go to npmjs.com → your account → Access Tokens → Generate New Token
• Select type Automation (scoped to publish)
• Copy the token
• Go to your GitHub repo → Settings → Secrets and variables → Actions → New repository secret
• 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