planmo

PlanMo — CLI-first, agent-native project planning and execution workspace generator. Turns an idea or an existing repository into a structured, agent-ready project workspace: a canonical project model, generated planning docs, and an ownership manifest — deterministically, with no LLM API key required.

Install

npx planmo --version
# or, as a project dependency
npm install -D planmo

Requires Node.js >= 24.

Quick start

npx planmo init my-project --yes
npx planmo status --dir my-project

init writes a canonical workspace — the project model plus a full, agent-ready planning tree:

my-project/.planmo/
├── project.yml     # canonical project model
├── state.yml       # phase/status state
└── manifest.json   # ownership + lineage for every generated file

my-project/planning/
├── README.md                      # index of the workspace
├── MASTER-PLAN.md  ROADMAP.md  TRACKER.md  tasks.csv
├── CONTEXT.md  STANDARDS.md  DECISIONS.md
├── OPEN-QUESTIONS.md  RISKS.md  REQUIREMENTS-TRACEABILITY.md
├── architecture/   ARCHITECTURE.md  DOMAIN-MODEL.md
│                   SECURITY-PRIVACY.md  STATE-MACHINES.md
├── compliance/     POLICY-REGISTER.md
├── design/         DESIGN-BRIEF.md  DESIGN-SYSTEM.md
├── handoffs/       TEMPLATE.md
├── phases/         phase-00.md … phase-NN.md
├── policies/       <one per standard class in use — only when a pack applies>
├── prompts/        README.md  phase-prompt.md
├── requirements/   PRODUCT-REQUIREMENTS.md
└── testing/        TEST-STRATEGY.md

Documents PlanMo derives from the model (MASTER-PLAN.md, tasks.csv, the architecture/compliance/design/requirements/testing sets) are regenerated by planmo generate. Documents that accumulate your decisions (DECISIONS.md, OPEN-QUESTIONS.md, RISKS.md, prompts/) are written once and then belong to you — regeneration never touches them.

status validates that model and summarizes it:

PlanMo workspace: /path/to/my-project
project: my-project (web-application, greenfield, risk=medium)
state: phase=00 status=planned completed=[]
status: HEALTHY

Adopting an existing repository

npx planmo adopt --dir ./existing-repo

adopt scans a repository read-only and prints a report. It writes nothing and never executes project scripts.

Commands

| Command | Description | | --------------------- | --------------------------------------------------------- | | planmo init [dir] | Create a workspace, compiling the planning tree with it | | planmo generate | Recompile the planning documents from the project model | | planmo diff | Show what generate would change, writing nothing | | planmo plan | Author the plan document with a model, once (ADR-0027) | | planmo validate | Validate the workspace documents and invariants (CI gate) | | planmo doctor | Report environment and workspace health | | planmo next | Print the task to work next, and what to read first | | planmo trace [id] | Render the requirements → tasks → tests trace graph | | planmo handoff | Record the current phase's handoff document | | planmo pack | Inspect the pack catalog and reconcile the lockfile | | planmo agent init | Install PlanMo command files into your coding agent | | planmo agent apply | Validate an agent proposal and record it (ADR-0026) | | planmo status | Validate and summarize the workspace | | planmo adopt [dir] | Analyze an existing repo (dry-run report; writes nothing) | | planmo --version | Print the version | | planmo --help | Show help |

init options

| Option | Values | | --------------------- | --------------------------------------------------------------------------------------------------- | | --name <name> | Project display name (default: directory name) | | --type <type> | web-application · cli · library · service · mobile-application · desktop-application · other | | --lifecycle <v> | greenfield · brownfield | | --risk <v> | low · medium · high | | --agent <v> | opencode · claude-code · generic | | --style <v> | minimal · editorial · neobrutalism · soft-product · dense-dashboard · developer-tool · luxury · playful | | --depth <v> | lean · standard · production · high-assurance · custom | | --phase-mode <v> | gated · continuous | | --yes | Accept defaults for anything not provided | | --dry-run | Print the plan and write nothing | | --force | Overwrite existing unmanaged files |

status, adopt, generate and validate take --dir <path> (default: walk up from cwd).

generate options

| Option | Description | | ------------- | ----------------------------------------------------------------------------- | | --dir <path>| Project root (default: walk up from cwd) | | --dry-run | Print the plan and write nothing | | --force | Overwrite files the manifest already owns, and unmanaged files it collides with |

validate options

| Option | Description | | ------------- | ---------------------------------------------- | | --dir <path>| Project root (default: walk up from cwd) |

validate exits 0 when the report has no errors (warnings are allowed) and 1 when it does, so it can gate CI. A freshly generated workspace validates clean.

Using your coding agent

PlanMo holds no LLM key. The agent you already run does the AI; PlanMo installs the commands that tell it what to do.

npx planmo agent init

It detects which agents the project already uses, shows you the evidence, and lets you pick — no --agent needed:

$ planmo agent init

Detected in this project:
  opencode (already installed) — .opencode/, .opencode/commands/planmo-next.md

◆  Which agent(s) should PlanMo install commands for?
│  ◼ opencode        .opencode/commands
│  ◻ claude-code     .claude/skills
│  ◻ codex           .agents/skills
│  ◻ copilot         .github/skills
│  ◻ hermes          ~/.hermes/skills (global)
│  ◻ generic         .planmo/agents/commands
└
◆  Install 1 command set(s) now? (Y/n)
✓ wrote .opencode/commands/planmo-next.md
Installed for opencode. Invoke in your agent with:
  /planmo-next

Detection reads filesystem markers only — .opencode/, .claude/ or CLAUDE.md, .codex/ or AGENTS.md, .github/copilot-instructions.md, ~/.hermes/ — so it is deterministic, and the evidence is printed so a wrong guess is visible and can be unticked. For scripts and CI: --agent <id> skips detection and every prompt, and --yes never prompts.

Supported agents, each with its own documented layout — 31 in all, including Claude Code, Codex, Copilot, Cursor, Gemini CLI, Kiro, Kimi, Grok, Kilo Code, Command Code, Windsurf, Cline, Roo Code, Qwen Code, Junie, Trae, Tabnine, Zed, Goose, Crush and a generic fallback:

npx planmo agent list

A few examples:

| --agent | Directory | Layout | Invoke as | | ------------- | -------------------------------- | ----------------- | ---------------- | | opencode | .opencode/commands/ | <name>.md | /planmo-next | | claude-code | .claude/skills/ | <name>/SKILL.md | /planmo-next | | codex | .agents/skills/ | <name>/SKILL.md | $planmo-next | | gemini-cli | .gemini/commands/ | <name>.toml | /planmo-next | | cline | .clinerules/workflows/ | <name>.md | /planmo-next.md| | hermes | ~/.hermes/skills/ (global) | <name>/SKILL.md | /planmo-next | | generic | .planmo/agents/commands/ | <name>.md | /planmo-next |

The complete table, with the official documentation each row was verified against, is in docs/02-architecture/agent-command-files.md.

hermes installs outside the project, so it is refused unless --global is passed explicitly. Re-running agent init is a clean no-op; a command file you have edited is reported as a collision and kept, unless you pass --force.

Closing the loop: propose → apply

The planmo-propose command asks the agent for one JSON document describing what it thinks should change. PlanMo validates it strictly and records it:

npx planmo agent apply proposal.json

✓ wrote .planmo/proposals/add-planmo-next-to-the-command-surface.json
Recorded proposal "Add planmo next to the command surface" from cursor

2 item(s):
  cli-next  proposed  Wire the next command.
      ref: REQ-001

Plan documents are never rewritten by apply. An item states what should change, not a mechanical edit, so changing the plan stays a human decision — that is the invariant that keeps agent output out of canonical state (ADR-0026). An invalid proposal writes nothing at all, and a proposal already recorded is refused rather than silently replaced (--force to replace).

Exit codes

| Code | Meaning | | ---- | ---------------------------------------------------------- | | 0 | ok | | 1 | error | | 2 | collision refused — existing files kept; use --force | | 3 | no project found |

Safety

• User-owned files are never silently overwritten: a collision exits 2 unless you pass --force.
• --dry-run prints the plan and writes nothing.
• Every generated file is tracked in .planmo/manifest.json.
• Scanning an existing repository does not execute its scripts.

Deterministic by design

The same PlanMo version, normalized model, locked packs and options produce equivalent output. The core needs no API key and no network access.

Status (v1)

The CLI surface is init, generate, validate, agent init, status and adopt. init compiles the planning tree as part of creating the workspace, generate recompiles it, validate checks the canonical documents and their cross-document invariants, and agent init installs the command files your coding agent needs. The remaining engines (workflow, trace, agent-bridge, design-engine) ship inside the published packages but are not yet exposed as CLI commands; they arrive in a later release. --help always lists exactly the implemented commands.

Links

• Repository: https://github.com/doofx0071/planmo
• Issues: https://github.com/doofx0071/planmo/issues
• License: MIT