Openplanr

OpenPlanr — Agile Planning for Coding Agents

What This Skill Does

OpenPlanr is a CLI that generates and maintains agile planning artifacts — epics, features, user stories, tasks, sprints, and backlog items — as markdown files in a .planr/ directory. This skill teaches Claude how to drive OpenPlanr end-to-end: detecting when planning is needed, installing or verifying the CLI, running the right commands in agent-friendly non-interactive mode, and interpreting the markdown artifacts it produces.

A third planning posture (spec-driven mode) bridges to the planr-pipeline Claude Code plugin for AI-driven feature shipping. See Critical Routing Decision for which surface owns the work in each runtime context.

When to Use

Activate this skill when the user:

• Asks to plan a project, feature, milestone, or sprint
• Wants to break down a PRD, spec, or design document into structured work
• Uses agile vocabulary: "epic", "feature", "user story", "task", "sprint", "backlog", "story points"
• Asks to estimate work ("how long will this take?", "story points for this?")
• Asks to prioritize a list of items
• Asks to generate agent rules (CLAUDE.md, AGENTS.md, .cursor/rules) from planning
• Asks to export a planning report (markdown, HTML, JSON)
• Works in a repo that already contains a .planr/ directory — OpenPlanr owns that directory
• Asks to refine or improve existing planning artifacts
• Asks to sync plans with GitHub Issues or Linear
• Wants spec-driven planning — author specs that decompose into agent-executable tasks ("plan for AI agents", "spec mode", "decompose this spec for execution", "bridge to planr-pipeline")
• Wants to author plans that the planr-pipeline Claude Code plugin can execute directly without translation

When NOT to Use

Do NOT activate this skill when:

• The user wants to write code directly for a task that's already fully specified — implementation alone isn't this skill's job (planning is)
• The user wants project management dashboards (Jira UI, Linear UI, Asana) — OpenPlanr is file-based, not a dashboard tool. It can sync to GitHub Issues or Linear though.
• The user wants to track live work status in a UI — use GitHub Issues via planr github push, Linear via planr linear push, or an external tool.

Critical Routing Decision

OpenPlanr ships across three first-class AI coding agent runtimes (Claude Code, Cursor, Codex) and a bare CLI mode. Pick exactly one path per request based on the runtime context (axis 1) and whether pipeline rules are installed for that runtime (axis 2).

Two-axis decision tree

What runtime are you in?
│
├── Claude Code
│   │
│   └── Is the planr-pipeline plugin installed?
│       │
│       ├── YES → Path A   (canonical — manifest-enforced subagents)
│       │
│       └── NO  → Path B   (drive planr CLI; suggest plugin install at end)
│
├── Cursor
│   │
│   └── Are pipeline rules installed (`.cursor/rules/planr-pipeline.mdc`)?
│       │
│       ├── YES → Path A2  (Cursor adapter — Composer subagent dispatch)
│       │
│       └── NO  → suggest: planr rules generate --target cursor --scope pipeline
│
├── Codex
│   │
│   └── Does AGENTS.md include the OpenPlanr pipeline section?
│       │
│       ├── YES → Path A3  (Codex adapter — persona role-shift)
│       │
│       └── NO  → suggest: planr rules generate --target codex --scope pipeline
│
└── Bare CLI (no AI runtime)
    │
    └── Path C — out of skill scope
        The user runs planr commands themselves; skill is not in the loop.

All three pipeline paths (A, A2, A3) execute the same OpenPlanr Protocol v1.0.0 — same artifacts, same workflow, same .pipeline-shipped marker. Full compatibility matrix: see planr-pipeline/docs/compatibility-matrix.md.

Path A — pipeline-driven (canonical)

Use when: the planr-pipeline plugin is installed in the user's Claude Code session.

The pipeline plugin is self-sufficient. It does NOT require the planr CLI to be installed. Your job is to invoke the pipeline directly with the feature slug — the pipeline scaffolds its own spec shell, runs the designer + specification agents, and ships the code.

# Single command — pipeline scaffolds .planr/specs/SPEC-NNN-{slug}/ if missing,
# then runs decomposition.
/planr-pipeline:plan <slug>

First run (no spec exists): pipeline auto-scaffolds an empty spec shell at .planr/specs/SPEC-NNN-<slug>/SPEC-NNN-<slug>.md and stops with an "edit and re-run" message. Tell the user to fill in the spec body (or open the file for them) and re-invoke /planr-pipeline:plan <slug>.

Second run (spec body has real content): pipeline's designer-agent and specification-agent decompose the spec into stories + tasks. Stop and wait for the user to review.

After user approval, ship:

/planr-pipeline:ship <slug>

If the user has dropped PNG mockups for the feature, place them at input/ui/feat-<slug>/*.png (default) or attach via planr spec attach-design if planr CLI is installed. Either path resolves correctly.

No mockups, but it's UI-facing? Instead of shipping backend-only, run /planr-pipeline:design <slug> before /plan to generate a visual design — a prototype (one screen), a walkthrough (multi-screen gallery), or a canvas (Figma-like board) — plus a design-spec.md. That makes decomposition emit a UI task (R2: a design-spec.md OR a PNG ⇒ a UI task). The command asks which format (or pass --format … --from … --yes for headless), and never auto-chains — review the artifact, then run /planr-pipeline:plan <slug>. No spec yet? It asks whether to scaffold one or just explore standalone (design only, into .planr/designs/<slug>/, no tracked spec) — so you can prototype without committing to a spec. (Claude Code only as of planr-pipeline v0.13.0+.)

Exploring a brand asset, not a feature? (logo, brand sheet, og-image, a one-off screen) → /planr-pipeline:design-loop <target> (v0.19.0+): N parallel AI variants on a live localhost comparison board — pin comments on exact regions, rate, remix — then iterate conversationally until approval; taste memory carries preferences across runs. Works with an OpenAI key (image generation) or with none (agent-authored SVG, $0 — often better for logos). The approved output lands in the project's design-system dir.

Polishing a design that already exists? → /planr-pipeline:design-review <slug> (v0.19.0+): serves the generated finalized.html/canvas.html on the live board; each pin maps to its screen and ONLY that screen is regenerated (lint gate stays 0-error); approval syncs design-spec.md + finalized.json. Route here when the user says "fix this part of the design" about an artifact /design produced.

Both stop at approval and never auto-chain into /plan or /ship (R1).

Want to see the whole project, not just read it? → /planr-pipeline:dashboard (v0.21.0+): launches a persistent localhost server with six live, read-only views of .planr/ — Overview · Graph · Board · List · Sprints · Activity — rendered from a typed project graph and kept in sync as files change (≤1s, view-state preserved). It never writes to .planr/. Route here when the user wants to visualize progress; route to /planr-pipeline:status (or planr status) for a terminal/markdown delivery report instead.

Path A invariants:

• Do not call planr spec decompose — duplicates the pipeline's specification-agent
• Do not call planr spec create — the pipeline scaffolds its own shell
• Do not implement tasks yourself in-session — the pipeline's frontend-agent / backend-agent must run

Path A2 — Cursor adapter

Use when: the user is in Cursor with pipeline rules installed at .cursor/rules/planr-pipeline.mdc (generated by planr rules generate --target cursor --scope pipeline).

The Cursor rules tell Composer how to orchestrate the pipeline:

• User says "plan {feature}" → planr-pipeline-plan.mdc activates
• User says "ship {feature}" → planr-pipeline-ship.mdc activates

Subagents are dispatched via Cursor's Composer subagent system using body files at .cursor/rules/agents/{role}.md. Tool restrictions are advisory (prompt-level only on Cursor — see compatibility matrix caveats).

If the user is in Cursor but pipeline rules aren't installed: tell them to run planr rules generate --target cursor --scope pipeline first.

Path A3 — Codex adapter

Use when: the user is in Codex with AGENTS.md containing the OpenPlanr pipeline section (generated by planr rules generate --target codex --scope pipeline).

Codex models the 8 roles as personas the model adopts during specific tasks. No separate subagent processes — persona role-shift happens in-session.

If AGENTS.md doesn't include the pipeline section: tell the user to run planr rules generate --target codex --scope pipeline to add it.

Optional planr CLI helpers in any Path A variant (only if planr CLI is installed; the pipeline does not depend on it):

These are convenience surfaces for ongoing maintenance — they are NOT prerequisites for the core /planr-pipeline:plan → /ship flow.

Path B — skill-driven (no pipeline plugin)

Use when: you're in Claude Code but planr-pipeline is not installed.

Drive planr CLI commands on the user's behalf, then implement the tasks yourself in-session. Suggest the pipeline at the end:

planr init --yes                                # AI auto-enabled
planr spec init
planr spec create "<title>" --slug <slug>
planr spec shape <SPEC-id>                       # interactive 4 questions; reliable in TTY
planr spec decompose <SPEC-id>                   # AI generates US + tasks
planr spec show <SPEC-id>                        # human review the tree

After decomposition, implement the tasks in your session, then tell the user:

For full pipeline orchestration with QA gate, parallel subagents, Docker generation, and CLAUDE.md snapshot — install the planr-pipeline plugin from the marketplace: /plugin marketplace add openplanr/marketplace and /plugin install planr-pipeline@openplanr.

Path C — bare CLI (out of skill scope)

The user runs planr commands themselves at the terminal. You're not invoked. This skill activates only inside Claude Code (Paths A and B).

Pipeline invocation when tasks are populated (Path A)

If you find populated .planr/specs/SPEC-NNN-{slug}/tasks/T-*.md files with type: UI|Tech frontmatter AND the planr-pipeline plugin is installed, invoke /planr-pipeline:ship <slug> to execute them. The pipeline's qa-agent gate, error-report mechanism, and CLAUDE.md snapshot are part of the contract.

The only acceptable bypass: the user explicitly says "do not run the pipeline, implement directly." A generic "continue" or "go" is not explicit consent.

Installation Check

Before running any planr command, verify OpenPlanr is available:

npx openplanr@latest --version

This fetches the latest stable version on first use and caches it. No global install is required. If the user has installed globally (npm i -g openplanr), planr --version works directly — prefer planr over npx openplanr when it's on PATH.

If npx itself is unavailable, instruct the user to install Node.js 20+ first.

planr init defaults

Run planr init --yes (without --no-ai) on the user's behalf. planr auto-detects API keys from the OS keychain, environment variables (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY), or ~/.planrrc. Pass --no-ai only when the user has explicitly opted out of AI features.

Core Workflow

Every interaction follows the same four steps:

1. Detect the planning intent — map the user's request to an OpenPlanr command (see "Key Commands" below, or references/commands.md for the full catalog)
2. Apply the routing decision — Path A (pipeline-driven), Path B (skill-driven), or Path C (out of scope)
3. Run commands non-interactively — ALWAYS pass --yes (or --no-interactive); never rely on interactive prompts
4. Read the generated artifact(s) — locate the output file in .planr/, read it, summarize the result, and propose the next step

Key Commands

The most common commands. For the full catalog (~40 commands), see references/commands.md.

Setup + agile commands

Spec-driven commands

⚠️ Read the Critical Routing Decision before invoking any of these. When the planr-pipeline plugin is installed (Path A), the pipeline scaffolds its own spec shell — planr CLI commands here become optional maintenance helpers, not prerequisites.

Rule: Every command that accepts --yes MUST receive it when invoked by an agent. Interactive prompts hang forever in non-TTY contexts.

Non-Interactive Mode (Required for Agents)

OpenPlanr auto-detects non-TTY environments and falls back to defaults, but you should be explicit anyway. Pass --yes (or its long form --no-interactive) on every invocation.

# CORRECT — agent-friendly
planr epic create --title "User Auth" --yes

# WRONG — will hang in agent execution
planr epic create --title "User Auth"

What --yes does:

• Confirmations return their default (usually "yes")
• Select menus pick the primary option
• --manual mode exits with an error (it requires a human)
• Skipped prompts are logged with [auto] prefix for auditability

Artifact Layout

After running commands, .planr/ contains:

.planr/
├── config.json                  # Project config (AI provider, paths)
├── epics/EPIC-001-*.md          # Epics
├── features/FEAT-001-*.md       # Features
├── stories/
│   ├── US-001-*.md              # User story (role, goal, benefit, acceptance)
│   └── US-001-gherkin.feature   # Gherkin acceptance criteria
├── tasks/TASK-001-*.md          # Implementation task lists (parent: a story or feature)
├── quick/QT-001-*.md            # Standalone task lists (no hierarchy)
├── backlog/BL-001-*.md          # Captured backlog items
├── sprints/SPRINT-001-*.md      # Time-boxed sprints
├── specs/SPEC-001-*/            # Spec-driven mode (third posture)
│   ├── SPEC-001-*.md            # the functional spec
│   ├── design/                  # PNG mockups + design-spec.md
│   ├── stories/US-NNN-*.md      # scoped to this spec
│   └── tasks/T-NNN-*.md         # scoped to this spec, with type/agent frontmatter
├── adrs/ADR-001-*.md            # Architecture decision records (created by user)
├── templates/                   # Custom task templates
└── checklists/agile-checklist.md

Every artifact has YAML frontmatter with id, status, and parent links (epicId, featureId, storyId, specId). Follow parent links to build the full context chain when implementing a task. See references/artifacts.md for the full frontmatter schema per artifact type, or visit the canonical reference at openplanr.dev/docs/reference/spec-schema.

Common Workflows

See references/workflows.md for full walkthroughs of:

• PRD → full agile hierarchy (epic → features → stories → tasks)
• Quick task (standalone, no hierarchy)
• Sprint cycle (create → add tasks → track → close)
• Backlog grooming (capture → AI-prioritize → promote)
• Refinement pass (review and improve artifacts with AI)
• Export (markdown / HTML / JSON reports)
• GitHub sync (push artifacts to Issues, bi-directional status)
• Spec-driven workflow (Paths A and B above — bridges to planr-pipeline plugin)

Spec-Driven Mode (third planning posture)

OpenPlanr supports three planning modes:

1. Agile — humans planning for humans (epic → feature → story → task, sprints, story points)
2. QT (Quick Task) — standalone task lists, no hierarchy
3. Spec-driven — humans planning for AI coding agents to execute (the planr-pipeline plugin reads .planr/specs/ verbatim)

The spec-driven mode produces planning artifacts with a richer agent-execution contract: explicit file Create/Modify/Preserve lists, Type: UI|Tech, agent assignment (frontend-agent / backend-agent), and DoD with build/test commands. The schema matches the planr-pipeline Claude Code plugin verbatim — both products share one schema, no conversion adapter.

When to suggest spec-driven mode

The user's project might benefit from spec-driven mode when:

• They use Claude Code, Cursor, or Codex to ship features end-to-end (planning for agents)
• They've installed (or want to install) planr-pipeline for code generation
• Their tasks need explicit file lists / build/test DoD (richer than agile tasks)
• They mention "spec-driven", "decompose for agents", "pipeline", or similar

Activate spec-driven mode with planr spec init. It is opt-in and additive — existing agile + QT artifacts are untouched.

Spec-driven artifact layout

Each spec is a self-contained directory under .planr/specs/:

.planr/specs/SPEC-001-auth-flow/
├── SPEC-001-auth-flow.md            # the functional spec
├── design/                          # PNG mockups + design-spec.md
│   ├── login-screen.png
│   └── design-spec.md               # written by planr-pipeline's designer-agent
├── stories/
│   └── US-001-login.md              # US-NNN scoped to this spec (not project-globally unique)
└── tasks/
    └── T-001-loginform.md           # T-NNN scoped to this spec

ID scoping rule: in spec-driven mode, US-NNN and T-NNN are scoped to their parent SPEC, not project-globally unique. Two specs can each have their own US-001. Disambiguate via path or via specId frontmatter when necessary.

Frontmatter schema (canonical)

When hand-authoring or repairing US/T files, every story and task MUST include:

Story (stories/US-NNN-*.md):

---
id: "US-001"
title: "Story title"
specId: "SPEC-001"
slug: "story-slug"
schemaVersion: "1.0.0"
status: "pending"            # pending | in-progress | done | blocked
priority: "P0"               # P0 | P1 | P2 | P3
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
---

Task (tasks/T-NNN-*.md):

---
id: "T-001"
title: "Task title"
storyId: "US-001"
specId: "SPEC-001"
slug: "task-slug"
schemaVersion: "1.0.0"
type: "UI"                   # UI | Tech (UI → frontend-agent, Tech → backend-agent)
agent: "frontend-agent"      # frontend-agent | backend-agent | (db-agent for migrations)
status: "pending"            # pending | in-progress | done | blocked
rationale: ""                # 1-3 sentences: why this task, why these files (populated by specification-agent)
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
---

The pipeline's specification-agent generates these automatically. If you need to hand-author them (e.g., AI is unavailable), use these templates verbatim.

Cross-runtime resume via task status (planr-pipeline v0.8.0+)

The pipeline's /ship command reads each task's status on entry and partitions the dispatch queue:

This makes a partially-shipped SPEC resumable across sessions, machines, and runtimes — a SPEC half-shipped on Claude Code can finish on Cursor and vice versa.

On Cursor and Codex /ship defaults to DISPATCH_MODE: per-task (one task per invocation) because Composer / persona role-shift is a single continuous session and cumulative context biases the model toward "verification rollup" instead of fresh codegen. On Claude Code the default is multi-task because manifest-isolated subagents give each task a clean context. Override with --all-tasks when you know your runtime supports isolated subagents.

Project memory (planr-pipeline v0.9.0+)

.planr/memory.md is an append-only project memory file with three sections:

• Decisions — architectural choices made during /ship not captured in ADRs (e.g., "Prisma createMany doesn't support nested relations on PG — use $transaction")
• Traps — failure patterns auto-appended when R6 hits iteration 2+. Surfaced to agents before dispatch so they don't repeat mistakes.
• Corrections — human overrides recorded when the PO modifies agent output at the R1 review gate

The orchestrator reads memory on /ship entry and keyword-matches relevant entries into each agent's context. Agents never delete entries; humans prune. Entry format: - [YYYY-MM-DD, <source>] <description>.

Clarification loop (planr-pipeline v0.9.0+)

When the specification-agent encounters genuine ambiguity during /plan (two valid interpretations → different architectures), it emits clarifications.md with structured options instead of guessing. The PO fills in the **Resolved:** fields, then re-runs /plan — the agent reads the answers and decomposes without guessing.

Task rationale (planr-pipeline v0.9.0+)

Each task carries a rationale: frontmatter field (1-3 sentences) explaining why the task exists and why those specific files were chosen. The qa-agent reads rationale during the QA gate to flag implementation drift — a non-blocking warning when the code doesn't match the stated intent.

Spec-driven command sequence (Path B — when no pipeline plugin)

# 1. Activate spec-driven mode (idempotent, additive)
planr spec init

# 2. Author a spec (creates self-contained SPEC-NNN-{slug}/ directory)
planr spec create "Auth flow" --slug auth --priority P0 --milestone v1.0

# 3. (Optional) Attach UI mockups for the pipeline's designer-agent
planr spec attach-design SPEC-001 --files login.png signup.png

# 4a. Author the spec body — pick one:
#     EITHER guided authoring (interactive 4 questions):
planr spec shape SPEC-001
#     OR edit the spec markdown in your $EDITOR directly

# 4b. Decompose into User Stories + Tasks (AI-driven)
planr spec decompose SPEC-001
#     Flags: --force (overwrite existing), --no-code-context (faster),
#            --max-stories <n> (cap output)

# 5. Review the decomposition
planr spec show SPEC-001
planr spec status

# 5b. Validate integrity if needed (orphans, missing specId, schema drift)
planr spec sync SPEC-001        # or `planr spec sync` for all specs

# 6. Promote (validates completeness; prints pipeline handoff)
planr spec promote SPEC-001

Pipeline bridge

When the planr-pipeline plugin is installed, follow Path A in the Critical Routing Decision section. The pipeline scaffolds the spec shell, decomposes, and ships — planr CLI is optional. Both products share the v1.0.0 spec schema verbatim.

When NOT to use spec-driven mode

• The user is doing pure human planning (agile mode is the right call)
• The user wants story points / sprint velocity / burndown (agile concepts; spec mode focuses on agent-execution contracts instead)
• The user's project doesn't (and won't) use a Claude Code plugin for code generation

Troubleshooting

See references/troubleshooting.md for handling:

• "AI provider not configured" → planr config set-provider anthropic
• "API key missing" → planr config set-key anthropic
• "AI is not configured" during planr spec decompose → configure AI as above, or hand-author from the schema reference
• Hangs in agent execution → you forgot --yes
• Broken parent links → planr sync (or planr spec sync for spec-driven mode)
• Import errors on older Node → upgrade to Node 20+

Examples

• examples/plan-from-prd.md — turn a PRD markdown file into a full agile hierarchy
• examples/quick-task.md — capture a standalone task list for a one-off fix
• examples/sprint-cycle.md — full sprint lifecycle from creation to close

Source: openplanr/skills — distributed by TomeVault.