Open Source · MIT Licensed · v1.7.0

Your AI agent writes code.
Now it reads the plan first.

OpenPlanr is a CLI that generates structured agile plans and teaches Claude Code, Cursor, and Codex to gather full project context before writing a single line of code.

View on GitHubnpm →
01 · The system

Three components, one contract.

Three things you use, one schema they share. Each component is independently useful; together they form an end-to-end loop where artifacts written by one are read verbatim by the next — no glue scripts, no schema drift.

Authoringv1.4.2

planr CLI

@openplanr/planr

Node CLI that scaffolds .planr/ markdown artifacts. Three planning postures: agile (epic→feature→story→task), quick task, spec-driven for AI handoff.

.planr/specs/.planr/tasks/spec shapespec decompose
Runs as · Humannpm i -g openplanr
Executionv0.4.0

openplanr-pipeline

Claude Code plugin

Eight-subagent factory. PO Phase decomposes specs & PNGs into tasks; DEV Phase ships code, tests, Docker and docs. Tool-layer enforced rules.

/openplanr-pipeline:plan/openplanr-pipeline:ship8 subagents
Runs as · Claude Codev0.4.0 · MIT
Orchestrationv1.2.0

openplanr/skills

Claude Code skill plugin

Teaches Claude when to reach for planr CLI vs the pipeline, and how to chain spec-driven mode end-to-end. Model-invoked, no slash command needed.

skills/openplanr/SKILL.mdmodel-invoked
Runs as · Claude (auto)v1.2.0 · MIT
02 · How they compose

One artifact contract, read by every layer.

planr spec decompose writes .planr/specs/SPEC-NNN-{slug}/. The pipeline reads that exact directory. No conversion adapters, no schema drift — the authoring surface and the executor share the spec format verbatim.

OpenPlanr ecosystem composition diagramUser talks to Claude, guided by the openplanr skill. Claude drives the planr CLI which writes specs, then invokes the openplanr-pipeline plugin which reads those specs and ships source, tests, Docker and docs. The marketplace installs the pipeline plugin.HUMANSYSTEMOUTPUTUserPO · TL · DevClaude+ openplanr skill/openplanr-pipeline:planplanr CLIspec create · shape · decomposeauthoring surface.planr/specs/SPEC-NNN-{slug}/design/ · stories/ · tasks/ · the contractread verbatimopenplanr-pipelinePO · review · DEV8 subagents · plugin v0.4.0marketplace/plugin installinstall pipesrc/codetests/qa-agentDockerdevopsDocs/doc-gen⚠ human review between PO & DEV
Authoring (planr)Execution (pipeline)Distribution (marketplace)Orchestration (skills)Shared spec contract
03 · planr CLI · three postures

Pick the planning style that matches the work.

Same CLI, three planning styles. Pick one per project, mix per task. The spec-driven posture is the bridge to the pipeline; the others are standalone and ceremony-free.

Posture 01

Agile

epic → feature → story → task

Full SDLC artifacts in markdown. Stories carry Gherkin acceptance criteria, tasks reference parents via frontmatter, ADRs document binding decisions. Sprints, backlog, the lot.

~/team-project
$ planr init $ planr epic create "Marketplace v2" $ planr plan --epic EPIC-001 ✓ 4 features → 12 stories + Gherkin ✓ 4 task lists generated $ planr sprint create ✓ Sprint 1 · 2w · 8 tasks selected
Best for— teams, multi-sprint work, formal review.
Posture 02

Quick Task

one chore, no ceremony

A single markdown checklist file under .planr/quick/. AI optionally generates the breakdown from a one-liner. Skip the agile hierarchy entirely.

~/side-project
$ planr quick create "add OAuth login" ✓ QT-001-add-oauth-login.md ✓ 6 subtasks · 2 acceptance checks $ planr quick refine QT-001 ✓ Refined to match repo style # open in editor and ship
Best for— solo dev, < 1 day of work, no reviewers.
Posture 03 · the bridge

Spec-driven

handoff to AI agents

Author a SPEC, shape it via 4 questions, decompose into US + tasks via AI. Output lands in .planr/specs/SPEC-NNN-{slug}/— the exact contract the pipeline reads.

~/agent-built
$ planr spec init $ planr spec create "User Auth" --slug auth $ planr spec shape SPEC-001 ↳ 4 questions · context, FRs, rules, AC $ planr spec decompose SPEC-001 ✓ 3 stories · 5 tasks · ready for pipeline
Best for— you have a spec, you want an agent to ship it.

Continue exploring OpenPlanr

Read the full blueprint →Read the docs →
~/my-project
// The Protocol

What your agent does before
writing a single line

The generated rules file teaches your AI coding agent a 4-step context-gathering protocol. No more blind coding.

  1. Read the Task
    Parse subtasks, frontmatter IDs, status, and parent references from the task list artifact.
    TASK-001.md → frontmatter
  2. Walk the Parent Chain
    Story with Gherkin acceptance criteria → Feature requirements → Epic business context.
    Task → Story → Feature → Epic
  3. Read Architecture
    ADRs, checklists, project rules, and architecture decisions that constrain the solution space.
    .planr/rules.md + ADRs
  4. Scan the Codebase
    Tech stack, source tree, dependency chains, patterns, and related files for full implementation context.
    stack + tree + patterns
// Features

Everything you need.
Nothing you don't.

A complete agile planning toolkit that lives in your terminal and your repo. No accounts, no subscriptions.

  • AI-Powered Planning
    Generate a full agile hierarchy from a one-line brief or a detailed PRD. Epics, features, stories with Gherkin, and task lists — cascaded automatically.
    $planr plan --epic EPIC-001
  • Backlog Capture
    Capture ideas in under a second without breaking flow. AI prioritizes by impact and effort. Promote to tasks or stories when you’re ready.
    $planr backlog add "user profiles"
  • Sprint Planning
    Time-boxed iterations with AI task selection based on velocity, subtask complexity, and feature priority. Velocity charts track progress across sprints.
    $planr sprint create --auto
  • Task Templates
    5 built-in templates for REST endpoints, React components, DB migrations, API integrations, and auth flows. Save your own from any task list.
    $planr template use rest-endpoint
  • Effort Estimation
    AI-powered story points on the Fibonacci scale with hours, complexity, risk factors, and reasoning. Epic rollup aggregates across all tasks.
    $planr estimate TASK-001 --save
  • Quality Guardrails
    Auto-extracted pattern rules from your codebase. Post-generation validation catches file path errors and dependency gaps before you accept AI output.
    5 heuristic detectors
  • GitHub Sync
    Push artifacts to GitHub Issues with type-aware formatting. Bi-directional status sync — pull, push, or interactive conflict resolution.
    $planr github push --epic EPIC-001
  • Export Reports
    Generate consolidated reports in Markdown, JSON, or self-contained HTML with collapsible sections, status badges, and full hierarchy rendering.
    $planr export --format html
  • Smart Rules
    Generates native rule files for each coding agent. Your agent reads the plan, architecture, and codebase patterns before every implementation.
    $planr rules generate
// Agent Support

Works with the agents
you already use

No plugins. No extensions. Just the rules file your agent already reads.

Claude Code
CLAUDE.md
Full context protocol with task parsing, parent chain walking, and codebase scanning.
Cursor
.cursor/rules/*.mdc
6 structured rule files that activate when your agent opens a task for implementation.
Codex
AGENTS.md
Autonomous agent instructions with the same 4-step context-gathering protocol.

Built with itself.

Every feature in OpenPlanr started as a backlog item, moved through the agile hierarchy, and was implemented by AI agents guided by the rules OpenPlanr generates. The tool is its own proof of concept.

Give your AI agent
the full picture.

Open source. MIT licensed. Get started in 30 seconds.

$ npm install -g openplanr && planr init

Requires Node.js 20+

TypeScriptNode.jsCommander.jsHandlebarsZodBiome