openplanr

Files (8)

• SKILL.md
• plan-from-prd.md · examples/
• quick-task.md · examples/
• sprint-cycle.md · examples/
• artifacts.md · references/
• commands.md · references/
• troubleshooting.md · references/
• workflows.md · references/

SKILL.md (first lines)

# 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](#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>
```

From openplanr/skills, MIT.

More from openplanr/skills