OpenPlanr is a toolkit for spec-driven coding agents. Author plans in markdown, hand them to a Claude Code factory that ships code, tests, infra and docs — with a human checkpoint between.
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.
Node CLI that scaffolds .planr/ markdown artifacts. Three planning postures: agile (epic→feature→story→task), quick task, spec-driven for AI handoff.
Eight-subagent factory. PO Phase decomposes specs & PNGs into tasks; DEV Phase ships code, tests, Docker and docs. Tool-layer enforced rules.
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.
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.
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.
Full SDLC artifacts in markdown. Stories carry Gherkin acceptance criteria, tasks reference parents via frontmatter, ADRs document binding decisions. Sprints, backlog, the lot.
$ 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 selectedA single markdown checklist file under .planr/quick/. AI optionally generates the breakdown from a one-liner. Skip the agile hierarchy entirely.
$ 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 shipAuthor 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.
$ 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 pipelineEach subagent has restrictions enforced in the manifest, not the prompt. The db-agent can run psql but never git; the designer-agent has no shell access at all.
/openplanr-pipeline:plan {feature}/openplanr-pipeline:ship {feature}Filled mint dot = primary tool. Hollow ring = optional support. Dash = not needed. Skills runs whenever you're in Claude Code — it's the always-on playbook. The two AI-orchestrated rows (Spec → AI ships it and Plan-and-ship from a one-liner) are where all three components actively compose.
| Scenario | planr CLI | pipeline | skills |
|---|---|---|---|
| Solo dev fixing one thingOne file, no reviewers, ship today. | |||
| Team running sprintsReal backlog, multiple stakeholders, ADRs. | |||
| Spec → AI agent ships itYou wrote the spec; agent does the implementation. | |||
| PNG mockups → full-stack codeDesigner hands you screens; you want UI + API. | |||
| Greenfield project scopingNew repo, brand-new product, define epics. | |||
| Plan-and-ship from a one-linerOne sentence to Claude → committed PR. |
The full spec-driven loop. Every step writes a real artifact you can read, edit, and commit. The human only intervenes at the review gate — everything else is one keystroke.
Initialise .planr/ and the spec subsystem. Optional: drop PNG mockups into input/ui/ and a stack file at input/tech/stack.md.
$ planr init
$ planr spec initSpec frontmatter + a 4-prompt body: who's the user, what must the system do, business rules, observable outcomes. No vim, no editor mode — single-line answers compose into markdown.
$ planr spec create "User Auth" --slug auth --priority P0
$ planr spec shape SPEC-001AI scans your repo (planr's buildCodebaseContext), reads the spec + stack, generates stories with Gherkin-shaped acceptance plus 1–2 tasks each, every task naming concrete files to create / modify / preserve.
$ planr spec decompose SPEC-001
✓ 3 stories · 5 tasks
✓ written to .planr/specs/SPEC-001-auth/spec decompose)If you skipped planr spec decompose, run the pipeline's PO phase instead — same output, same paths. The pipeline auto-detects spec mode via .planr/config.json.
/openplanr-pipeline:plan auth
✓ designer-agent · spec mode detected
✓ specification-agent · 3 US, 5 tasks
⚠ STOP: human review requiredRead every tasks/T-NNN-*.md. Adjust scope, fix file paths, edit the stack if a dependency changed. The pipeline refuses to proceed without this checkpoint — by design.
# review the tree, edit anything
$ tree .planr/specs/SPEC-001-auth
$ $EDITOR tasks/T-002-jwt-middleware.mdFrontend + backend agents run in parallel by topological group, qa-agent gates the build, devops + doc-gen produce Docker/CI/Docs in parallel. CLAUDE.md snapshot at the end. PR-ready.
/openplanr-pipeline:ship auth
✓ frontend-agent · 2 tasks
✓ backend-agent · 3 tasks
✓ qa-agent · build + tests pass
✓ devops + doc-gen complete
✓ CLAUDE.md refreshed · ready for PRPublic progress in three lanes. Versions are pinned across the four repos in lockstep so the spec contract never drifts.
.planr/specs/ directlyspec initspec-schema moduleplanr github push for spec artifactsoutput/feats/ → .planr/specs/