From openplanr
Agile planning CLI for coding agents — creates epics, features, user stories, tasks, sprints, and backlog items as markdown artifacts in .planr/. Use when the user asks to plan a project, break down a PRD, write stories, estimate work, manage sprints, prioritize a backlog, or generate agent rule files (CLAUDE.md, AGENTS.md, .cursor/rules). Also use when the repo already contains a .planr/ directory — OpenPlanr owns that directory.
How this skill is triggered — by the user, by Claude, or both
Slash command
/openplanr:openplanrThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
OpenPlanr is a CLI that generates and maintains agile planning artifacts — epics,
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 so you can then implement the planned work.
Activate this skill when the user:
.planr/ directory — OpenPlanr owns that directoryopenplanr-pipeline Claude Code plugin can execute directly without translationDo NOT activate this skill when:
planr github push, Linear via planr linear push, or an external tool.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.
Every interaction follows the same four steps:
references/commands.md for the full catalog).planr/config.json exists (run planr init --yes if not)--yes (or
--no-interactive); never rely on interactive prompts.planr/, read
it, summarize the result, and propose next steps (e.g. "Epic created. Next,
generate features with planr feature create --epic EPIC-001 --yes?")The 10 most common commands. For the full catalog (~40 commands), see
references/commands.md.
| Command | What it does |
|---|---|
planr init --yes | Initialize .planr/ in the current project |
planr plan --yes | Full agile flow: Epic → Features → Stories → Tasks |
planr epic create --file <path> --yes | Generate an epic from a PRD document |
planr feature create --epic EPIC-001 --yes | Generate features under an epic |
planr story create --epic EPIC-001 --yes | Generate stories for every feature under an epic |
planr task create --story US-001 --yes | Generate an implementation task list |
planr refine EPIC-001 --cascade --yes | AI review and improvement, cascading to children |
planr status | Tree view of all planning progress |
planr rules generate --yes | Generate CLAUDE.md / AGENTS.md / .cursor/rules |
planr backlog prioritize --yes | AI-powered backlog prioritization by impact/effort |
planr spec init | Activate spec-driven mode — the third planning posture for AI-agent execution |
planr spec create "<title>" --slug <slug> | Create a self-contained .planr/specs/SPEC-NNN-{slug}/ with stories/, tasks/, design/ subdirs |
planr spec shape <SPEC-id> | Interactive 4-question spec authoring (Context, Functional Reqs, Business Rules, Acceptance) |
planr spec decompose <SPEC-id> | AI-driven generation of User Stories + Tasks; matches openplanr-pipeline schema |
planr spec sync [<SPEC-id>] --dry-run | Validate spec integrity (orphans, missing specId, schema drift); auto-fixes safe issues |
planr spec promote <SPEC-id> | Validate decomposition + print /openplanr-pipeline:plan {slug} handoff |
Rule: Every command that accepts --yes MUST receive it when invoked by an
agent. Interactive prompts hang forever in non-TTY contexts.
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:
--manual mode exits with an error (it requires a human)[auto] prefix for auditabilityAfter 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
├── 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). 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.
See references/workflows.md for full walkthroughs of:
openplanr-pipeline plugin)OpenPlanr supports three planning modes:
The spec-driven mode produces planning artifacts with a richer agent-execution
contract: explicit file Create/Modify/Preserve lists, Type=UI|Tech, agent
assignment, and DoD with build/test commands. The schema matches the
openplanr-pipeline Claude
Code plugin verbatim — both products share one schema, no conversion adapter.
The user's project might benefit from spec-driven mode when:
openplanr-pipeline for code generationActivate spec-driven mode with planr spec init. It is opt-in and additive —
existing agile + QT artifacts are untouched.
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 openplanr-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.
# 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
After planr spec promote SPEC-001 succeeds, the user invokes the pipeline plugin
in Claude Code (not the planr CLI):
/openplanr-pipeline:plan auth # PO Phase: design-spec, decomposition (if not done)
/openplanr-pipeline:review auth # human review of the decomposition
/openplanr-pipeline:ship auth # DEV Phase: code generation, QA, devops, docs
The pipeline plugin reads .planr/specs/ directly when spec mode is active —
no conversion. This is the integration story: planr plans, openplanr-pipeline
ships, schema is shared.
See references/troubleshooting.md for handling:
planr config set-provider anthropicplanr config set-key anthropic--yesplanr syncexamples/plan-from-prd.md — turn a PRD markdown file into a full agile hierarchyexamples/quick-task.md — capture a standalone task list for a one-off fixexamples/sprint-cycle.md — full sprint lifecycle from creation to closeProvides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub openplanr/skills --plugin openplanr