# OpenPlanr docs > Every page listed in llms.txt, as Markdown, built from openplanr 2.2641.1. --- title: OpenPlanr overview description: What OpenPlanr is, how its plan, design, build, review, and operate loop works, and where to start in Claude Code, Codex, or Cursor. url: https://openplanr.dev/docs/get-started updated: 2026-10-06 related: - https://openplanr.dev/docs/get-started/install.md - https://openplanr.dev/docs/get-started/agent-setup.md - https://openplanr.dev/docs/get-started/first-spec.md --- # OpenPlanr overview OpenPlanr is the shared delivery loop for product teams and their AI agents. You plan, design, build, review, and operate from durable context in your repository, with 25+ skills for Claude Code, Codex, and Cursor, plus the deterministic `openplanr` CLI. ## What it is - **Skills, not a second model.** Every skill runs inside the coding agent you already use. Skills and the openplanr CLI add no model calls or telemetry; the optional design engine calls OpenAI only when you select its OpenAI provider and supply your own key. - **Plans are files.** Specifications, user stories, tasks, and provenance live under `.planr/` in your repository, reviewed and versioned like code. See [Plans are files](https://openplanr.dev/docs/get-started/plans-are-files.md). - **A deterministic CLI.** `openplanr` stores and validates planning files, renders diagrams and reports, installs the skills into each agent, diagnoses installations, and syncs with GitHub Issues and Linear. - **Open source under MIT.** One repository, published as 3 npm packages: `openplanr` (the CLI and host packages), `planr-pipeline` (the delivery pipeline), and `@openplanr/protocol` (schemas and registries). OpenPlanr is not a hosted project tracker and does not replace your issue tracker. It closes the loop: your agent reads the plan before it changes code, and what it ships flows back as evidence for the next review. ## How it works Reasoning stays in your agent. The CLI never calls a model; it validates what the agent wrote, renders it, and keeps trackers in step. Every step is a skill your agent selects from its description, or one you invoke by name: | Stage | What you get | Guide | | --- | --- | --- | | Plan | A spec with measurable acceptance criteria, then user stories and tasks with exact file scope | [Plan a feature](https://openplanr.dev/docs/guides/plan.md) | | Design | One design direction in a review studio, and a design spec that Plan reads | [Design before you build](https://openplanr.dev/docs/guides/design.md) | | Build | One task at a time, verified and small enough to review as one pull request | [Build one task at a time](https://openplanr.dev/docs/guides/build.md) | | Review | A plan review before building, browser QA after it, and a readiness check before merge | [Review before it lands](https://openplanr.dev/docs/guides/review.md) | | Operate | Delivery status from the plan, and leadership reviews that end in decisions | [Track delivery and run operating reviews](https://openplanr.dev/docs/guides/operate.md) | Plan and ship stay separate steps that you invoke. The agent never chains them on its own. ## Start here 1. [Install and set up OpenPlanr](https://openplanr.dev/docs/get-started/install.md): the CLI, the skills for your agent, and the planning folder in your project. To let your agent do it for you, see [Set up from your agent](https://openplanr.dev/docs/get-started/agent-setup.md). 2. [Write your first spec](https://openplanr.dev/docs/get-started/first-spec.md). 3. Read the page for your agent: [Claude Code](https://openplanr.dev/docs/hosts/claude-code.md), [Codex](https://openplanr.dev/docs/hosts/codex.md), or [Cursor](https://openplanr.dev/docs/hosts/cursor.md). 4. Copy a prompt from the [prompt library](https://openplanr.dev/docs/prompts.md), starting with the ones marked Start here. --- title: Install and set up OpenPlanr description: This guide takes you from an empty terminal to your first specification written by your coding agent. It takes about five minutes. url: https://openplanr.dev/docs/get-started/install updated: 2026-10-06 related: - https://openplanr.dev/docs/get-started.md - https://openplanr.dev/docs/get-started/agent-setup.md - https://openplanr.dev/docs/get-started/first-spec.md --- # Install and set up OpenPlanr This guide takes you from an empty terminal to your first specification written by your coding agent. It takes about five minutes. ## Requirements - a supported Node.js version (see [package metadata](https://github.com/openplanr/OpenPlanr/blob/4d4fb273180f65c6c648e6babd4b9c6ae8465ff2/packages/cli/package.json)) and npm. - One coding agent: Claude Code, Codex, or Cursor. - A project under Git, or a directory you are willing to initialize. ## 1. Install the CLI ```bash npm install -g openplanr openplanr --version ``` The package installs two equivalent commands: `openplanr` and its short alias `opr`. Alternatives: ```bash npx openplanr@latest setup # no global install curl -fsSL https://openplanr.dev/install.sh | sh # macOS and Linux irm https://openplanr.dev/install.ps1 | iex # Windows PowerShell ``` The installers require Node.js and never install or upgrade it silently. ## 2. Install the skills into your coding agent `openplanr setup` detects the agents on the machine, shows exactly what it will write, and installs the skills for the host and scope you choose. Preview first: ```bash openplanr setup --runtime claude --scope user --dry-run openplanr setup --runtime claude --scope user ``` | Host | Command | What it writes | | --- | --- | --- | | Claude Code | `openplanr setup --runtime claude --scope user` | A generated local marketplace and the unified `planr` plugin, registered with Claude Code | | Codex | `openplanr setup --runtime codex --scope user --skill-mode unified-plugin` | The unified `planr` plugin, registered through Codex's plugin marketplace | | Cursor | `openplanr setup --runtime cursor --scope project` | Thin `.mdc` discovery rules under `.cursor/rules/openplanr/` | | Everything | `openplanr setup --runtime all --scope both` | All of the above | User scope installs once per machine and is the default; project scope installs into the current repository and is required for Cursor. Codex can also install each skill separately (`--skill-mode direct`, invoked by bare name such as `$spec`) or as project rules (`--skill-mode project-rule`). Project writes need a Git worktree or an initialized `.planr/` project; setup never treats your home directory as a project. Existing files are backed up byte for byte under `~/.planr/backups/`, and only OpenPlanr-managed marker blocks are ever replaced. Direct and project skill entries read an exact cached package under `~/.planr/runtime/packages/`; they do not copy the runtime's schemas and scripts into your repository. `PLANR_HOME` relocates that cache and OpenPlanr state; `CODEX_HOME` selects the native Codex profile independently. Both scope reuses user discovery with project policy rather than installing the same Claude or Codex skills twice. Regenerate local loaders on each machine instead of committing their absolute cache paths. In Claude Code you can install the same plugin from the public OpenPlanr marketplace instead of `openplanr setup --runtime claude`. Use one path, not both: ```text /plugin marketplace add openplanr/marketplace /plugin install planr@openplanr ``` Several skills call the `openplanr` CLI, so keep the CLI from step 1 installed. Restart the coding agent after setup so it loads the new skills. ## 3. Initialize the project ```bash cd your-project openplanr init ``` `openplanr init` creates `.planr/config.json`, the artifact directories (`epics/`, `features/`, `stories/`, `tasks/`, `quick/`, `backlog/`, `sprints/`, `adrs/`, `checklists/`, `diagrams/`), an agile checklist, and an estimation guide. Commit `.planr/` with your code. To let the agent see every skill and when to use it, generate the host guidance: ```bash openplanr rules generate --target claude # or codex, cursor, all ``` This adds an `## OpenPlanr capabilities` section to `CLAUDE.md` or `AGENTS.md` between managed markers; your own content outside the markers is left alone. ## 4. Write the first specification Open the project in your coding agent and invoke the spec skill: ```text /spec "Add passwordless sign-in for existing accounts" # Claude Code $spec "Add passwordless sign-in for existing accounts" # Codex ``` In Cursor, mention the `planr-spec` rule in Composer and describe the change. The skill reads the repository, asks only the questions that change the outcome, and writes `.planr/specs/SPEC-001-/SPEC-001-.md`. Then: | Step | Skill | Result | | --- | --- | --- | | Plan | `plan` | User stories and tasks under the specification, with acceptance criteria and file-level change lists | | Review the plan | `plan-review` | Product, engineering, design, and developer-experience findings | | Implement | `ship` | One task implemented in the repository, verified, and recorded in `.planr/provenance.jsonl` | | Check status | `status` or `openplanr status --md` | Every specification, story, and task by status | Plan and ship are separate steps. The agent never chains them on its own. ## 5. Keep it healthy ```bash openplanr doctor # installation, adapters, and project health openplanr doctor --fix # preview and repair owned installation drift openplanr sync # validate and repair cross-references between artifacts openplanr upgrade status # compare the installed CLI and plugin with the published set ``` `openplanr runtime update codex` refreshes only that agent and keeps its saved scope and discovery mode. Repairs preserve user edits, other agents, native profiles and retained runs. Cursor integration requires a valid project; user scope is not a supported recovery alternative. When a skill misbehaves, start with `openplanr doctor --json` and the [troubleshooting guide](https://openplanr.dev/docs/get-started/troubleshooting.md). ## Undo ```bash openplanr runtime rollback # restore the last pre-setup state for every managed adapter openplanr runtime remove claude # remove one host's OpenPlanr-owned files (hashes must still match) npm uninstall -g openplanr ``` Removal deletes only files OpenPlanr wrote and still recognizes; modified or unknown files are reported and left in place. Delete `.planr/` from a project by hand if you no longer want the planning files. ## Next - [Skill catalog](https://openplanr.dev/docs/skills): every skill, its triggers, and what it defers. - [CLI reference](https://openplanr.dev/docs/cli): every command and option. - [Diagrams](https://github.com/openplanr/OpenPlanr/blob/4d4fb273180f65c6c648e6babd4b9c6ae8465ff2/docs/diagrams/authoring.md): render and verify diagrams offline. - [Host matrix](https://openplanr.dev/docs/hosts.md): what differs between Claude Code, Codex, and Cursor. Tried it on a real feature? Tell us what you'd change in the [beta discussion](https://github.com/openplanr/OpenPlanr/discussions/324). --- title: Set up from your agent description: Ask Claude Code, Codex, or Cursor to install OpenPlanr from a guide written for agents. It previews every change and asks before applying it. url: https://openplanr.dev/docs/get-started/agent-setup updated: 2026-10-06 related: - https://openplanr.dev/docs/get-started.md - https://openplanr.dev/docs/get-started/install.md - https://openplanr.dev/docs/get-started/first-spec.md --- # Set up from your agent OpenPlanr publishes a setup guide written for coding agents at [openplanr.dev/setup.md](https://openplanr.dev/setup.md). Give it to the agent you already use, and the agent installs OpenPlanr in your repository step by step, asking you before it installs or changes anything. ## Ask your agent Open your repository in Claude Code, Codex, or Cursor, and ask the agent to set up OpenPlanr in this repository by following `https://openplanr.dev/setup.md`. If you are a coding agent and the user asked you to set up OpenPlanr, fetch https://openplanr.dev/setup.md and follow its steps in order. Ask the user only where a step says to. ## What the agent does 1. Checks that Node.js and Git are installed and recent enough. If either is missing or too old, it stops and tells you which one to install or upgrade. 2. Asks once whether to install the OpenPlanr CLI globally with npm. If you say no, it runs the CLI through npx instead. 3. Previews the setup for the coding agents on your machine and shows you which agents it covers, where files go, and what it adds, updates, or removes. Cursor installs per project, so the guide previews a separate project setup for it. 4. Asks once before applying the setup. If you say no, it stops and confirms that nothing changed. 5. Initializes the planning folder, `.planr/`, where specs, stories, and tasks live as files you review and version like code. 6. Runs a health check and reports the result. For a warning, it shows the suggested fix and asks before applying it. 7. Asks which feature you want to build next, tells you to restart the agent so it loads the new skills, and gives you the exact first command for your agent. ## What the agent does not do - Write anywhere other than your repository and the coding agent's own skill folders. - Ask for, read, or store secrets. - Guess a workaround when a command fails. It shows the exact error and stops. ## After the restart Start with `/spec` (Claude Code), `$spec` (Codex) or `@planr-spec` (Cursor) and the feature you named. In Codex, the guide installs each skill under its own name, and each skill also carries a display name, such as OpenPlanr Spec. Prefer to run each command yourself? Follow [Install and set up OpenPlanr](https://openplanr.dev/docs/get-started/install.md), then [write your first spec](https://openplanr.dev/docs/get-started/first-spec.md). --- title: Write your first spec description: Turn one feature into a specification your agent and your reviewers can check the work against, saved as a file in your repository. url: https://openplanr.dev/docs/get-started/first-spec updated: 2026-10-06 related: - https://openplanr.dev/docs/get-started/install.md - https://openplanr.dev/docs/get-started/agent-setup.md - https://openplanr.dev/docs/get-started/plans-are-files.md --- # Write your first spec A spec is the first file in the loop. It says what you want to change, why, and how anyone can tell the change is done, before your agent plans or builds anything. Before you start, install the CLI, set up the skills for your agent, and initialize the project. [Install and set up OpenPlanr](https://openplanr.dev/docs/get-started/install.md) covers all three, or [let your agent do it](https://openplanr.dev/docs/get-started/agent-setup.md). Restart the agent after setup so it loads the new skills. ## Ask for the spec Open the project in your agent and invoke `/spec` (Claude Code), `$spec` (Codex) or `@planr-spec` (Cursor) with the change you want and the problem it solves. For example: > Add passwordless sign-in for existing accounts. Users drop off at the password step. The [Turn a rough idea into a spec](https://openplanr.dev/docs/prompts/spec-from-idea.md) prompt has this example ready to edit and copy for your agent. ## What the skill does - It reads your request, the repository instructions, ADRs, product docs, existing plans, the relevant code and tests, and current behavior. Anything the repository already answers, it infers. - When a missing decision would change the scope or the behavior, it asks you: at most 3 short questions at a time, with the recommended option first. - It writes one specification. Requirements and acceptance criteria are observable, each criterion has a stable ID, and non-goals go under out-of-scope boundaries. - It validates the file before it returns. ## What you get The spec is saved in your repository: ```text .planr/specs/SPEC-001-/SPEC-001-.md ``` Its sections follow the specification contract the skill ships with: Context & Goal, Audience, Outcome & Measurement, Functional Requirements, Business Rules, Constraints, Evidence Expectations, Failure Modes, Rollback, Scope Boundaries, Acceptance Criteria, Declared Risk Specialists, and Notes for Decomposition. The reply leads with what is ready and links the saved file. It lists the decisions the skill made and the checks it ran, names any open question that still changes the product, and ends with the exact command to plan the spec next. ## Review it, then plan Read the spec the way you would read code, and commit `.planr/` with your project. When the spec says what you mean, break it into stories and tasks with `/planr:plan` (Claude Code), `$plan` (Codex) or `@planr-plan` (Cursor). Plan and ship are separate steps, and the agent never chains them on its own. Next: [Plan a feature](https://openplanr.dev/docs/guides/plan.md), or copy [Break a spec into stories and tasks](https://openplanr.dev/docs/prompts/plan-a-spec.md). --- title: Plans are files description: OpenPlanr keeps specs, stories, and tasks as files in your repository, so Claude Code, Codex, and Cursor read the same plan in every session. url: https://openplanr.dev/docs/get-started/plans-are-files updated: 2026-10-06 related: - https://openplanr.dev/docs/get-started/agent-setup.md - https://openplanr.dev/docs/get-started/first-spec.md - https://openplanr.dev/docs/get-started/troubleshooting.md --- # Plans are files OpenPlanr keeps the plan in your repository. Specifications, user stories, tasks, and provenance live under `.planr/`, reviewed and versioned like code. A plan that exists only in a chat is gone when the session ends. A plan in the repository is there for the next session, the next teammate, and the next agent, and every change to it shows up in a diff. ## What the folder holds Initializing a project creates the planning folder. This is the listing of an empty project after [`openplanr init`](https://openplanr.dev/docs/cli/init.md): ```text .planr .planr/ESTIMATION.md .planr/adrs .planr/backlog .planr/checklists .planr/checklists/AGILE-DEVELOPMENT-GUIDE.md .planr/config.json .planr/diagrams .planr/epics .planr/features .planr/quick .planr/specs .planr/sprints .planr/stories .planr/tasks ``` Each spec gets its own folder under `.planr/specs/`, with the stories and tasks planned from it: ```text .planr/specs/SPEC-NNN-/ SPEC-NNN-.md stories/US-NNN-.md stories/US-NNN-gherkin.feature tasks/T-NNN-.md ``` ## What a task carries Every story keeps its acceptance criteria with stable IDs, starting at AC-001. Every task carries the context an agent needs to build it and a reviewer needs to check it: | Field | What it holds | | --- | --- | | `rationale` | Why the task exists | | `dependsOn` | Tasks whose output this task consumes | | `preserve` | Files the task must leave unchanged | | `reviewRisks` | What a reviewer should watch for, set from evidence in the repository | | `browserSurfaces` | Browser surfaces the change touches, which pick the browser checks | | `acceptanceRefs` | The acceptance criteria the task delivers | The task body lists the files to create, modify, and preserve, then the technical spec, the test requirements, and the Definition of Done. Every acceptance criterion is referenced by at least one task, and that task's test requirements name the same ID with a check you can observe. ## How your agent uses the files - `/spec` (Claude Code), `$spec` (Codex) or `@planr-spec` (Cursor) writes the spec, and `/planr:plan` (Claude Code), `$plan` (Codex) or `@planr-plan` (Cursor) writes the stories and tasks. - `/ship` (Claude Code), `$ship` (Codex) or `@planr-ship` (Cursor) reads the task, its story, its acceptance criteria, and the spec before it changes code. - `/planr:status` (Claude Code), `$status` (Codex) or `@planr-status` (Cursor) reads the files to report what is done, blocked, and next, without changing them. - The `openplanr` CLI validates the planning files offline, never with a model, and [`openplanr sync`](https://openplanr.dev/docs/cli/sync.md) repairs cross-references between them. ## Review the plan like code Commit `.planr/` with your code. A change to the plan then arrives as a diff in the same pull request flow as everything else, where your team can review it before an agent builds from it. ## Keep trackers in step The CLI syncs planning files with GitHub Issues and Linear, so the plan in the repository and the tracker your team uses stay aligned. See the [`openplanr github`](https://openplanr.dev/docs/cli/github.md) and [`openplanr linear`](https://openplanr.dev/docs/cli/linear.md) references. --- title: Troubleshooting description: Common issues and how to resolve them. url: https://openplanr.dev/docs/get-started/troubleshooting updated: 2026-10-06 related: - https://openplanr.dev/docs/get-started/agent-setup.md - https://openplanr.dev/docs/get-started/first-spec.md - https://openplanr.dev/docs/get-started/plans-are-files.md --- # Troubleshooting Common issues and how to resolve them. Start with the unified health check: ```bash openplanr doctor --json openplanr setup --dry-run ``` `doctor --fix` preserves each managed coding agent's saved installation scope and Codex discovery choice. It previews generated-file repairs, managed native plugin operations and stale OpenPlanr daemon state, then asks once before applying them. File changes are grouped by agent; `--verbose` shows every path and `--json` saves the exact repair preview, whether it was applied, and whether a host restart is needed. Use `--yes` only after reviewing the proposed repairs. Repairs use the plugin bundled with the running CLI, without upgrading the CLI or changing credentials. Doctor also compares the cached plugin payload with the bundled files, so a current version with missing skills still needs repair. Native plugin commands remove stale managed registrations, including an old enabled identity omitted from the current marketplace listing. Unrelated registrations and modified owned files require explicit resolution. Restart the affected agent after a plugin change; doctor checks registration and owned assets, so it cannot prove that an already-open host has reloaded its live skill list. Failed native plugin inspection blocks setup and repair before managed files change; resolve the reported configuration or CLI problem, then retry. A healthy second repair makes no changes. Daemon cleanup rechecks health and never kills a process. CLI package upgrades and provenance recovery remain separate actions. An unavailable runtime is informational unless setup or the project lock actually selected it. A selected runtime that disappears remains a warning. ## Runtime setup and migration - `E_NODE_VERSION`: install a supported Node.js version (see [package metadata](https://github.com/openplanr/OpenPlanr/blob/4d4fb273180f65c6c648e6babd4b9c6ae8465ff2/packages/cli/package.json)); the installer never changes Node. - `E_PROJECT_CONTEXT_REQUIRED`: change into a Git or initialized OpenPlanr project before selecting project scope. Use `--scope user` only for an integration that supports it; Cursor requires a valid project. - `E_RUNTIME_AMBIGUOUS`: pass `--runtime` or set a project default. - `E_LOCK_INCOMPATIBLE`: run the exact `openplanr runtime update ...` command shown. - `E_MIGRATION_CONFLICT`: a managed file changed after setup; preview, preserve the edit, or use `openplanr runtime rollback`. - `E_CLAUDE_PLUGIN_INSPECTION_FAILED`: update Claude Code so its plugin manager is available, then rerun `openplanr setup --runtime claude --scope user`. - `E_CLAUDE_PLUGIN_UPDATE_FAILED`: verify GitHub/marketplace connectivity, run `openplanr runtime update claude --scope user`, and restart Claude Code. - `E_PROVENANCE_WRITE`: repair permissions, then append an explicit recovery event; doctor never invents history silently. If doctor reports `runtime-claude-plugins`, the installed plugin version or manifest identity does not match the compatible release. Run: ```bash openplanr runtime update claude --scope user ``` Review and confirm the listed marketplace and plugin operations, then restart Claude Code. Setup serves the unified `planr` plugin from a generated local marketplace (`openplanr-local`). Older `openplanr` or `planr-pipeline` plugins from the public marketplace are reported as legacy and never removed silently; confirm the OpenPlanr plugin works, then remove them from Claude Code. Setup backups live under `~/.planr/backups///`. Machine state and paths live under `~/.planr/runtime/state.json`; the committed project lock contains only versions and compatibility capabilities. If an older installer created `~/CLAUDE.md`, `~/AGENTS.md`, Cursor rules, or a home-directory runtime lock, `openplanr doctor` reports `home-project-install`. Run `openplanr doctor --fix` to preview removal. Only recorded OpenPlanr-owned bytes are removed; user-scope adapters and hand-written content are retained. --- ## Skills ### A skill is not found in the host Confirm setup targeted that host and scope (`openplanr doctor --json` lists every managed installation), then restart the host so it reloads its skills. Codex uses one install mode at a time; preview with `openplanr setup --runtime codex --dry-run` before switching modes. ### A skill asks for an API key or runs a planning command That is an old projection. Current skills reason inside the coding agent and call only deterministic `openplanr` utilities. Run `openplanr setup` again, restart the host, and check `openplanr upgrade status`. ### The agent does not pick the right skill Generate the host guidance so the agent sees every skill and its triggers: ```bash openplanr rules generate --target claude # or codex, cursor, all ``` Then ask for `/openplanr` (Claude Code) or `$openplanr` (Codex), which routes a request to the best skill. ## "No .planr/config.json found" Initialize OpenPlanr in the project first: ```bash openplanr init ``` If you're running from a subdirectory, use `--project-dir`: ```bash openplanr status --project-dir /path/to/project ``` --- ## Artifact review issues ### `E_PIPELINE_NOT_INSTALLED` Artifact review is part of the full distribution. A planning-only install made with `--minimal` omits it. Install the full package and verify again: ```bash npm install -g openplanr@latest openplanr doctor ``` ### `E_ARTIFACT_STALE_REVIEW` The returned review targets a different artifact digest. Do not merge it silently. If the older feedback is still useful, rerun the import with `--allow-stale`, inspect the preview, and confirm. CI must also pass `--yes`. ### A remote or SSH browser cannot reach the local review `openplanr artifact` intentionally binds to `127.0.0.1`. Use `--no-open --json`, then forward the printed port over SSH. Do not bind the review server publicly. ### An artifact dependency is rejected The bundler resolves local dependencies below `--root` (the artifact's directory by default) and vendors supported public HTTPS dependencies automatically. It still rejects forms, path traversal, symlink escapes, private or non-HTTPS hosts, unsupported resources, and unresolved dependencies. Use `--root` when the artifact intentionally depends on a larger local asset tree. See [Artifact review and private sharing](https://openplanr.dev/docs/guides/artifact-review.md) for the complete privacy and sharing model. --- ## Cross-reference issues ### Links point to wrong files If artifacts were renamed or moved manually, cross-references may break. Run: ```bash openplanr sync --dry-run # preview what would change openplanr sync # fix broken links ``` ### "Stale link" warnings A parent artifact links to a child that no longer exists on disk. `openplanr sync` removes these automatically. ### "Missing link" warnings A child artifact references a parent, but the parent doesn't list the child. `openplanr sync` adds the missing link. --- ## Template issues ### Custom templates not loading Make sure `templateOverrides` in `.planr/config.json` points to the correct directory: ```json { "templateOverrides": "./my-templates" } ``` The override directory must mirror the default template structure (e.g., `my-templates/epics/epic.md.hbs`). Only files that exist in the override directory will be used — all others fall back to defaults. --- ## GitHub integration issues ### "GitHub CLI (gh) is not installed" The `openplanr github` commands require the GitHub CLI. Install it: ```bash # macOS brew install gh # Other platforms: https://cli.github.com/ ``` ### "Not authenticated with GitHub" You need to log in with `gh`: ```bash gh auth login ``` ### "No GitHub remote found" Your repository doesn't have a GitHub remote configured. Add one: ```bash git remote add origin https://github.com/your-org/your-repo.git ``` ### "Could not resolve to an issue" The linked GitHub issue was deleted. The CLI creates a new issue on the next push. If you see this error during sync, re-push the artifact: ```bash openplanr github push EPIC-001 ``` ### Push creates duplicate issues Each artifact stores its linked issue number in frontmatter (`githubIssue: 123`). If you manually delete this field, a new issue will be created on the next push. Don't edit `githubIssue` fields manually. --- ## Working from a source checkout Build and test failures inside the repository are covered by the contributor guide, [Working from a checkout](https://github.com/openplanr/OpenPlanr/blob/main/docs/contributing/dogfooding.md). --- ## Still stuck? Ask in [Discussions](https://github.com/openplanr/OpenPlanr/discussions) or open an issue through the [issue forms](https://github.com/openplanr/OpenPlanr/issues/new/choose) with: - the command or skill invocation and the full output - `openplanr --version` and `openplanr doctor --json` (doctor redacts secrets; check anyway) - the host and its version, your operating system, and `node --version` ## Thin skill installation recovery Direct and project discovery entries refer to an exact runtime package in the selected `PLANR_HOME` (default `~/.planr`). Keep that cache available when working offline, and regenerate local entries with setup when moving machines or changing homes. Native plugin packages and downloaded standalone skills remain complete. Run `openplanr doctor --json` to distinguish discovery metadata drift from a missing or changed package closure. `openplanr doctor --fix` uses the same preview, backup, ownership checks and transaction as setup. It preserves the saved scope and Codex mode. `openplanr runtime update ` updates only that agent. A partially copied exact cache can resume from the installed CLI. Modified cache bytes, edited discovery entries and unknown files are preserved as conflicts; inspect them instead of deleting the cache or relaxing ownership checks. Retained packages are not cleaned up during repair. If a concurrent edit prevents rollback, the edit and migration backup remain available and the error names the affected paths. --- title: Skill host matrix description: OpenPlanr compiles one canonical skill graph into semantically equivalent, host-native projections. Generated files are outputs, not alternate sources. url: https://openplanr.dev/docs/hosts updated: 2026-10-06 related: - https://openplanr.dev/docs/hosts/claude-code.md - https://openplanr.dev/docs/hosts/codex.md - https://openplanr.dev/docs/hosts/cursor.md --- # Skill host matrix OpenPlanr compiles one canonical skill graph into semantically equivalent, host-native projections. Generated files are outputs, not alternate sources. | Capability | Claude Code | Codex | Cursor | Pipeline compatibility | |---|---|---|---|---| | Primary unit | Claude skill/plugin | Codex plugin skill | `.mdc` rule | packed skill asset | | Explicit invocation | `/*` | `$*` in the plugin; the bare skill name (`$spec`) in direct mode | Composer mention of the `planr-*` rule | adapter dispatch | | Automatic matching | description metadata | description metadata with implicit invocation | rule description | registry routing | | Structured questions | native question when available | native composer question when available | Composer chat | terminal/headless resolver | | On-demand content | relative packaged references | relative packaged references | generated rule references | package-relative references | | UI metadata | plugin manifest | `.codex-plugin/plugin.json` and `agents/openai.yaml` | rule frontmatter | adapter manifest | | Recommended install | OpenPlanr plugin | OpenPlanr plugin | Project rules | Installed CLI package | Host profiles may change supported syntax, invocation wording, metadata, and question surfaces. They may not change the OpenPlanr context, workflow, output contract, or error semantics. Vendor-specific paths, commands, variables, and model-selection instructions are rejected outside their owning projection. Every projection must be readable without this source repository. The release verifier opens each entrypoint, links every support file, checks native metadata, and compares installed bytes with the deterministic release manifest. --- title: OpenPlanr in Claude Code description: Install OpenPlanr's skills as a Claude Code plugin, invoke them as slash commands, and let Claude see every skill from CLAUDE.md. url: https://openplanr.dev/docs/hosts/claude-code updated: 2026-10-06 related: - https://openplanr.dev/docs/hosts.md - https://openplanr.dev/docs/hosts/codex.md - https://openplanr.dev/docs/hosts/cursor.md --- # OpenPlanr in Claude Code In Claude Code, OpenPlanr's skills arrive as one plugin named `planr`. Every skill runs inside Claude Code. Skills and the openplanr CLI add no model calls or telemetry. ## Install Run the setup step from [Install and set up OpenPlanr](https://openplanr.dev/docs/get-started/install.md) and choose Claude Code. Setup shows exactly what it will write before it writes anything. It installs the plugin at user scope by default, once per machine; project scope installs it into the current repository instead. Restart Claude Code after setup so it loads the new skills. Several skills call the `openplanr` CLI, so keep the CLI installed. ## Invoke a skill Type a slash and the skill's name. Claude Code also picks a skill on its own when your request matches the skill's description, and when a skill needs a decision from you, it asks with Claude Code's native question prompt where one is available. Plan, Design, Status, and Doctor keep the plugin's `planr:` prefix, because Claude Code has built-in commands with the same names. A bare name runs a plugin skill only when no other command already uses it, so if a bare command runs something else on your machine, add the prefix. Set Commands for to Claude Code, in the page header or in the navigation menu on a phone, and every skill command in these docs shows its Claude Code form, with the prefixed form in the note under it. ## Let Claude see every skill Generate the guidance so Claude knows every skill and when to reach for it: ```bash openplanr rules generate --target claude ``` This adds an `## OpenPlanr capabilities` section to `CLAUDE.md` between managed markers. Your own content outside the markers is left alone. ## When something goes wrong - **A skill is missing.** Run `openplanr doctor --json`, which lists every managed installation. Confirm that setup targeted Claude Code with the scope you expect, then restart Claude Code. - **Setup cannot inspect plugins** (`E_CLAUDE_PLUGIN_INSPECTION_FAILED`). Update Claude Code so its plugin manager is available, then run setup again. - **Doctor reports `runtime-claude-plugins`.** The installed plugin does not match the compatible release. Run `openplanr runtime update claude --scope user`, review the listed operations, and restart Claude Code. - **You want to remove it.** `openplanr runtime remove claude` deletes only the files OpenPlanr wrote and still recognizes. Modified or unknown files are reported and left in place. More fixes are in [Troubleshooting](https://openplanr.dev/docs/get-started/troubleshooting.md), and [the host matrix](https://openplanr.dev/docs/hosts.md) shows what differs between agents. --- title: OpenPlanr in Codex description: Install OpenPlanr's skills in Codex as one plugin, as individual skills, or as project rules, and invoke them with a dollar sign. url: https://openplanr.dev/docs/hosts/codex updated: 2026-10-06 related: - https://openplanr.dev/docs/hosts.md - https://openplanr.dev/docs/hosts/claude-code.md - https://openplanr.dev/docs/hosts/cursor.md --- # OpenPlanr in Codex In Codex, OpenPlanr's skills run inside your Codex session. Skills and the openplanr CLI add no model calls or telemetry. ## Install Run the setup step from [Install and set up OpenPlanr](https://openplanr.dev/docs/get-started/install.md) and choose Codex. Setup shows exactly what it will write before it writes anything. User scope installs once per machine and is the default; project scope installs into the current repository. `CODEX_HOME` selects the Codex profile that setup writes to. Codex supports 3 install modes, chosen with setup's `--skill-mode` option: - **One plugin** (`unified-plugin`): the `planr` plugin, with every skill in it. - **Individual skills** (`direct`): each skill installed on its own and invoked by its bare name. - **Project rules** (`project-rule`): the skills installed as rules in the current repository. Codex uses one install mode at a time. Preview a switch with a dry run before you change modes; setup's `--replace-managed` option replaces only OpenPlanr's own discovery files when you switch. Restart Codex after setup so it loads the new skills. ## Invoke a skill Type a dollar sign and the skill's name. With the plugin installed, add the plugin's `planr:` prefix after the dollar sign. Codex can also invoke a skill on its own when your request matches the skill's description. When a skill needs a decision from you, it asks with Codex's native question prompt where one is available. Each skill also carries a display name for Codex, such as OpenPlanr Spec. Set Commands for to Codex, in the page header or in the navigation menu on a phone, and every skill command in these docs shows its Codex form, with the plugin form in the note under it. ## Let Codex see every skill Generate the guidance so Codex knows every skill and when to reach for it: ```bash openplanr rules generate --target codex ``` This adds an `## OpenPlanr capabilities` section to `AGENTS.md` between managed markers. Your own content outside the markers is left alone. ## When something goes wrong - **A skill is missing.** Run `openplanr doctor --json`, which lists every managed installation. Confirm that setup targeted Codex with the scope and mode you expect, then restart Codex. - **Update only Codex.** `openplanr runtime update codex` refreshes Codex alone and keeps its saved scope and discovery mode. - **Undo setup.** `openplanr runtime rollback` restores the last pre-setup state for every managed agent. More fixes are in [Troubleshooting](https://openplanr.dev/docs/get-started/troubleshooting.md), and [the host matrix](https://openplanr.dev/docs/hosts.md) shows what differs between agents. --- title: OpenPlanr in Cursor description: Install OpenPlanr's skills as Cursor project rules, and use a skill by mentioning its rule in chat. url: https://openplanr.dev/docs/hosts/cursor updated: 2026-10-06 related: - https://openplanr.dev/docs/hosts.md - https://openplanr.dev/docs/hosts/claude-code.md - https://openplanr.dev/docs/hosts/codex.md --- # OpenPlanr in Cursor In Cursor, OpenPlanr's skills arrive as project rules. You use a skill by mentioning its rule in chat, and Cursor can also apply a rule when your request matches the rule's description. Skills and the openplanr CLI add no model calls or telemetry. ## Install Cursor installs per project, so run the setup step from [Install and set up OpenPlanr](https://openplanr.dev/docs/get-started/install.md) inside your repository and choose Cursor with project scope. Setup shows exactly what it will write before it writes anything, then adds thin `.mdc` discovery rules under `.cursor/rules/openplanr/`. The repository must be a Git repository or an initialized OpenPlanr project. User scope is not supported for Cursor. Restart Cursor after setup so it loads the new rules. ## Use a skill Mention the skill's rule in chat with your request. Each rule is named after its skill with a `planr-` prefix, and you mention it with an @ sign. When a skill needs a decision from you, it asks in the chat. Set Commands for to Cursor, in the page header or in the navigation menu on a phone, and every skill command in these docs shows the rule to mention in Cursor. ## Let Cursor see every skill Generate OpenPlanr's rule files for Cursor: ```bash openplanr rules generate --target cursor ``` This writes OpenPlanr's `.mdc` rule files into `.cursor/rules/`. ## When something goes wrong - **`E_PROJECT_CONTEXT_REQUIRED`.** Change into a Git repository or an initialized OpenPlanr project before you set up Cursor. - **A rule is missing.** Run `openplanr doctor --json`, which lists every managed installation, then restart Cursor. - **You want to remove it.** `openplanr runtime remove cursor` deletes only the files OpenPlanr wrote and still recognizes. Modified or unknown files are reported and left in place. More fixes are in [Troubleshooting](https://openplanr.dev/docs/get-started/troubleshooting.md), and [the host matrix](https://openplanr.dev/docs/hosts.md) shows what differs between agents. --- title: OpenPlanr Artifact description: Open, share, import, or export an OpenPlanr diagram, design, or HTML artifact review. Use when feedback must move between a local artifact and its review board. url: https://openplanr.dev/docs/skills/artifact updated: 2026-10-06 related: [] --- # OpenPlanr Artifact Skill family: Artifact reviews. Open, share, import, or export an OpenPlanr diagram, design, or HTML artifact review. Use when feedback must move between a local artifact and its review board. ## Run it - Claude Code: `/artifact`. If /artifact runs another command, use /planr:artifact. - Codex: `$artifact`. With the OpenPlanr plugin for Codex, use $planr:artifact. - Cursor: `@planr-artifact`. Cursor applies the planr-artifact rule when you mention it in chat. ## Use it to - Open or share an HTML artifact review - Import artifact feedback and export the reviewed artifact ## Not for - Review source code changes - Create a product interface design --- title: OpenPlanr Browser QA description: Run practical browser-backed QA against real routes, forms, viewports, accessibility, console, and network behavior. url: https://openplanr.dev/docs/skills/browser-qa updated: 2026-10-06 related: [] --- # OpenPlanr Browser QA Skill family: Review and QA. Exercise the running app in a real browser, from routes and forms to phone sizes, accessibility, the console, and the network. It reports what it found and leaves the fixes to you. Run practical browser-backed QA against real routes, forms, viewports, accessibility, console, and network behavior. Use for UI, authentication, session, navigation, or browser-network changes. ## Run it - Claude Code: `/browser-qa`. If /browser-qa runs another command, use /planr:browser-qa. - Codex: `$browser-qa`. With the OpenPlanr plugin for Codex, use $planr:browser-qa. - Cursor: `@planr-browser-qa`. Cursor applies the planr-browser-qa rule when you mention it in chat. ## Use it to - Test this page or application in a real browser - Check routes, forms, mobile viewports, accessibility, console, and network behavior ## Not for - Run backend unit tests only - Review a plan without exercising a browser ## Example prompt Claude Code: ```text /browser-qa the sign-in flow on /login at phone and desktop sizes, including the expired-link error ``` If /browser-qa runs another command, use /planr:browser-qa. Codex: ```text $browser-qa the sign-in flow on /login at phone and desktop sizes, including the expired-link error ``` With the OpenPlanr plugin for Codex, use $planr:browser-qa. Cursor: ```text @planr-browser-qa the sign-in flow on /login at phone and desktop sizes, including the expired-link error ``` Cursor applies the planr-browser-qa rule when you mention it in chat. Browser QA infers the routes, journeys, and sizes from your request and the repository, then starts or reuses the project's local runtime. It checks navigation, forms, responsive layout, keyboard access, visible focus, accessible names, console errors, failed requests, and the loading and error states the change touches. It never stores credentials, cookies, or session secrets. The reply gives the outcome (pass, issues found, or blocked), the coverage it exercised, and reproducible findings with the page and the expected behavior. A check it could not run is reported as unverified, never as a pass. See [Review before it lands](https://openplanr.dev/docs/guides/review.md). --- title: OpenPlanr CEO Review description: Produce a grounded strategy and finance review for an Operate cycle. Use when direction, runway, margin, investment, or cost of delay needs a CEO lens. url: https://openplanr.dev/docs/skills/ceo-review updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/cmo-review.md - https://openplanr.dev/docs/skills/coo-review.md - https://openplanr.dev/docs/skills/cpo-review.md --- # OpenPlanr CEO Review Skill family: Operate advisors. Produce a grounded strategy and finance review for an Operate cycle. Use when direction, runway, margin, investment, or cost of delay needs a CEO lens. ## Run it - Claude Code: `/ceo-review`. If /ceo-review runs another command, use /planr:ceo-review. - Codex: `$ceo-review`. With the OpenPlanr plugin for Codex, use $planr:ceo-review. - Cursor: `@planr-ceo-review`. Cursor applies the planr-ceo-review rule when you mention it in chat. ## Use it to - Run a CEO strategy and finance review - Assess direction, runway, margin, investment, or cost of delay ## Not for - Review implementation details - Assess only product usability --- title: OpenPlanr Chair Review description: Synthesize an Operate cycle into a prioritized decision queue and action plan. Use after specialist reviews when leadership needs one coherent brief. url: https://openplanr.dev/docs/skills/chair-review updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/challenger-review.md --- # OpenPlanr Chair Review Skill family: Operate synthesis. Synthesize an Operate cycle into a prioritized decision queue and action plan. Use after specialist reviews when leadership needs one coherent brief. ## Run it - Claude Code: `/chair-review`. If /chair-review runs another command, use /planr:chair-review. - Codex: `$chair-review`. With the OpenPlanr plugin for Codex, use $planr:chair-review. - Cursor: `@planr-chair-review`. Cursor applies the planr-chair-review rule when you mention it in chat. ## Use it to - Synthesize executive reviews into a decision queue - Turn operating-review findings into prioritized decisions and actions ## Not for - Produce an independent specialist review - Implement the recommended actions --- title: OpenPlanr Challenger Review description: Challenge an Operate cycle's claims, alternatives, downside, and confidence. Use when assumptions or executive consensus need an independent stress test. url: https://openplanr.dev/docs/skills/challenger-review updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/chair-review.md --- # OpenPlanr Challenger Review Skill family: Operate synthesis. Challenge an Operate cycle's claims, alternatives, downside, and confidence. Use when assumptions or executive consensus need an independent stress test. ## Run it - Claude Code: `/challenger-review`. If /challenger-review runs another command, use /planr:challenger-review. - Codex: `$challenger-review`. With the OpenPlanr plugin for Codex, use $planr:challenger-review. - Cursor: `@planr-challenger-review`. Cursor applies the planr-challenger-review rule when you mention it in chat. ## Use it to - Challenge operating-review assumptions and downside - Test material claims, alternatives, confidence, and dissent ## Not for - Summarize reviews without challenging them - Implement a proposed decision --- title: OpenPlanr CMO Review description: Produce a grounded market and growth review for an Operate cycle. Use when acquisition, positioning, demand, retention, or missing measurement needs a CMO lens. url: https://openplanr.dev/docs/skills/cmo-review updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/ceo-review.md - https://openplanr.dev/docs/skills/coo-review.md - https://openplanr.dev/docs/skills/cpo-review.md --- # OpenPlanr CMO Review Skill family: Operate advisors. Produce a grounded market and growth review for an Operate cycle. Use when acquisition, positioning, demand, retention, or missing measurement needs a CMO lens. ## Run it - Claude Code: `/cmo-review`. If /cmo-review runs another command, use /planr:cmo-review. - Codex: `$cmo-review`. With the OpenPlanr plugin for Codex, use $planr:cmo-review. - Cursor: `@planr-cmo-review`. Cursor applies the planr-cmo-review rule when you mention it in chat. ## Use it to - Run a market and growth review - Assess acquisition, positioning, demand, channels, or growth measurement ## Not for - Review backend architecture - Assess internal delivery mechanics only --- title: OpenPlanr COO Review description: Produce a grounded operations and customer-health review for an Operate cycle. url: https://openplanr.dev/docs/skills/coo-review updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/ceo-review.md - https://openplanr.dev/docs/skills/cmo-review.md - https://openplanr.dev/docs/skills/cpo-review.md --- # OpenPlanr COO Review Skill family: Operate advisors. Produce a grounded operations and customer-health review for an Operate cycle. Use when readiness, service delivery, capacity, or customer health needs a COO lens. ## Run it - Claude Code: `/coo-review`. If /coo-review runs another command, use /planr:coo-review. - Codex: `$coo-review`. With the OpenPlanr plugin for Codex, use $planr:coo-review. - Cursor: `@planr-coo-review`. Cursor applies the planr-coo-review rule when you mention it in chat. ## Use it to - Run an operations and customer-health review - Assess readiness, support, reliability, process, or customer operations ## Not for - Review company strategy only - Design a product interface --- title: OpenPlanr CPO Review description: Produce a grounded product and activation review for an Operate cycle. Use when customer value, activation, prioritization, or adoption needs a CPO lens. url: https://openplanr.dev/docs/skills/cpo-review updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/cmo-review.md - https://openplanr.dev/docs/skills/coo-review.md - https://openplanr.dev/docs/skills/cto-review.md --- # OpenPlanr CPO Review Skill family: Operate advisors. Produce a grounded product and activation review for an Operate cycle. Use when customer value, activation, prioritization, or adoption needs a CPO lens. ## Run it - Claude Code: `/cpo-review`. If /cpo-review runs another command, use /planr:cpo-review. - Codex: `$cpo-review`. With the OpenPlanr plugin for Codex, use $planr:cpo-review. - Cursor: `@planr-cpo-review`. Cursor applies the planr-cpo-review rule when you mention it in chat. ## Use it to - Run a product and activation review - Assess customer value, adoption, activation, retention, or product outcomes ## Not for - Review infrastructure only - Assess financial runway only --- title: OpenPlanr CTO Review description: Produce a grounded technology and delivery-risk review for an Operate cycle. Use when architecture, reliability, security, or execution risk needs a CTO lens. url: https://openplanr.dev/docs/skills/cto-review updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/cmo-review.md - https://openplanr.dev/docs/skills/coo-review.md - https://openplanr.dev/docs/skills/cpo-review.md --- # OpenPlanr CTO Review Skill family: Operate advisors. Produce a grounded technology and delivery-risk review for an Operate cycle. Use when architecture, reliability, security, or execution risk needs a CTO lens. ## Run it - Claude Code: `/cto-review`. If /cto-review runs another command, use /planr:cto-review. - Codex: `$cto-review`. With the OpenPlanr plugin for Codex, use $planr:cto-review. - Cursor: `@planr-cto-review`. Cursor applies the planr-cto-review rule when you mention it in chat. ## Use it to - Run a technology and delivery-risk review - Assess architecture, security, reliability, technical debt, or delivery risk ## Not for - Review marketing channels - Assess financial runway only --- title: OpenPlanr Dashboard description: Start or inspect the loopback-only OpenPlanr planning dashboard. Use when the user wants to view local planning or Operate state in the browser. url: https://openplanr.dev/docs/skills/dashboard updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/openplanr.md - https://openplanr.dev/docs/skills/status.md - https://openplanr.dev/docs/skills/sync.md --- # OpenPlanr Dashboard Skill family: Status, routing and sync. Start or inspect the loopback-only OpenPlanr planning dashboard. Use when the user wants to view local planning or Operate state in the browser. ## Run it - Claude Code: `/dashboard`. If /dashboard runs another command, use /planr:dashboard. - Codex: `$dashboard`. With the OpenPlanr plugin for Codex, use $planr:dashboard. - Cursor: `@planr-dashboard`. Cursor applies the planr-dashboard rule when you mention it in chat. ## Use it to - Open or inspect the local OpenPlanr dashboard - Show planning and Operate workspaces visually ## Not for - Return a short text delivery status - Create a product dashboard design --- title: OpenPlanr Delegate description: Coordinate an explicitly requested implementation with Claude Code, Codex or Cursor, then independently review and integrate its observed changes. url: https://openplanr.dev/docs/skills/delegate updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/ship.md --- # OpenPlanr Delegate Skill family: Implement. Hand an implementation you explicitly assign to another coding agent's CLI, then review, verify, and integrate what it changed. Accepted work arrives as an uncommitted diff in your checkout. Coordinate an explicitly requested implementation with Claude Code, Codex or Cursor, then independently review and integrate its observed changes. Use when the user asks another coding agent to implement. ## Run it - Claude Code: `/delegate`. If /delegate runs another command, use /planr:delegate. - Codex: `$delegate`. With the OpenPlanr plugin for Codex, use $planr:delegate. - Cursor: `@planr-delegate`. Cursor applies the planr-delegate rule when you mention it in chat. ## Use it to - Delegate implementation to another coding agent - Ask a second coding agent to implement while I orchestrate - Use planr-delegate for this task - Have Codex implement this task - Use Codex to implement this - Have Claude Code implement this task - Ask another coding agent to implement this task - Use another coding agent to build this change ## Not for - Active host implementation - Ship this change without delegation - Review existing code - Review this code using Codex - Parallel agents - Fix the delegate runner in the active agent ## Example prompt Claude Code: ```text /delegate Ask another coding agent to implement T-003, then review and verify its changes before you integrate them. ``` If /delegate runs another command, use /planr:delegate. Codex: ```text $delegate Ask another coding agent to implement T-003, then review and verify its changes before you integrate them. ``` With the OpenPlanr plugin for Codex, use $planr:delegate. Cursor: ```text @planr-delegate Ask another coding agent to implement T-003, then review and verify its changes before you integrate them. ``` Cursor applies the planr-delegate rule when you mention it in chat. Delegate works through the native CLI you already have installed and signed in. The other agent investigates, implements, builds, tests, and corrects in its own worktree. Your current agent keeps the scope and the context, reviews the observed changes independently, runs its own checks, and integrates only what it accepts. Before it dispatches, it shows you the engine, the model selection, the routing, the working directory, and the context it will send. Committing, landing, and deploying stay separate decisions, and ordinary implementation stays with Ship. See [Delegate implementation through a native coding CLI](https://openplanr.dev/docs/guides/delegation.md). --- title: OpenPlanr Design description: Design a polished product interface through adaptive consultation, a shared canvas/prototype/walkthrough studio, and an implementation-ready specification. url: https://openplanr.dev/docs/skills/design updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/design-loop.md - https://openplanr.dev/docs/skills/design-review.md --- # OpenPlanr Design Skill family: Design. Design one product direction in a review studio you can view as a canvas, a prototype, and a walkthrough. It ends with a 10-section design spec that Plan reads. Design a polished product interface through adaptive consultation, a shared canvas/prototype/walkthrough studio, and an implementation-ready specification. Use for a new design or an existing interface that needs a coherent direction. ## Run it - Claude Code: `/planr:design` - Codex: `$design`. With the OpenPlanr plugin for Codex, use $planr:design. - Cursor: `@planr-design`. Cursor applies the planr-design rule when you mention it in chat. ## Use it to - Create an initial product design direction - Start the OpenPlanr design workflow for a feature ## Not for - Review an existing completed design - Explore several competing design variants ## Example prompt Claude Code: ```text /planr:design the onboarding checklist for new accounts on desktop and phone, with empty and error states ``` Codex: ```text $design the onboarding checklist for new accounts on desktop and phone, with empty and error states ``` With the OpenPlanr plugin for Codex, use $planr:design. Cursor: ```text @planr-design the onboarding checklist for new accounts on desktop and phone, with empty and error states ``` Cursor applies the planr-design rule when you mention it in chat. ## Output `.planr/specs/SPEC-001-/design/design-spec.md`: ```text ## 1. Color Palette ## 2. Typography ## 3. Spacing & Layout ## 4. Components Inventory ## 5. Navigation & Layout Patterns ## 6. Iconography ## 7. Motion & Interaction Hints ## 8. Component Overrides ## 9. Screen Inventory ## 10. Open Questions ``` The skill reads your brief, the app shell, components, tokens, and reference screens, and reuses your app's design system when one exists. It builds one design document with stable screens. Canvas, Prototype, and Walkthrough are views of that document, so switching views never regenerates the screens. It checks the screens in a browser at the declared sizes, or returns the design as unverified when it cannot. Design stops at the handoff: planning, building, sharing a review link, and deploying are separate steps you start yourself. See [Design before you build](https://openplanr.dev/docs/guides/design.md). --- title: OpenPlanr Design Loop description: Compare three materially different product design directions in a live review studio, collect pins and ratings, and develop the selected direction. url: https://openplanr.dev/docs/skills/design-loop updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/design.md - https://openplanr.dev/docs/skills/design-review.md --- # OpenPlanr Design Loop Skill family: Design. Compare three materially different product design directions in a live review studio, collect pins and ratings, and develop the selected direction. Use for visual alternatives, comparison or a remix. ## Run it - Claude Code: `/design-loop`. If /design-loop runs another command, use /planr:design-loop. - Codex: `$design-loop`. With the OpenPlanr plugin for Codex, use $planr:design-loop. - Cursor: `@planr-design-loop`. Cursor applies the planr-design-loop rule when you mention it in chat. ## Use it to - Explore multiple design directions or variants - Iterate a design using pinned board feedback ## Not for - Create only one initial design - Review an existing design without generating variants --- title: OpenPlanr Design Review description: Review and revise an existing product design using stable board pins and scoped browser-verified changes. url: https://openplanr.dev/docs/skills/design-review updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/design.md - https://openplanr.dev/docs/skills/design-loop.md --- # OpenPlanr Design Review Skill family: Design. Review and revise an existing product design using stable board pins and scoped browser-verified changes. Use for focused improvements while preserving unrelated screens and feedback. ## Run it - Claude Code: `/design-review`. If /design-review runs another command, use /planr:design-review. - Codex: `$design-review`. With the OpenPlanr plugin for Codex, use $planr:design-review. - Cursor: `@planr-design-review`. Cursor applies the planr-design-review rule when you mention it in chat. ## Use it to - Review or critique an existing OpenPlanr design - Apply pinned feedback to affected design regions ## Not for - Create an initial design from scratch - Implement backend code --- title: OpenPlanr Diagram description: Create, edit, inspect, verify, or rerender professional offline diagrams. url: https://openplanr.dev/docs/skills/diagram updated: 2026-10-06 related: [] --- # OpenPlanr Diagram Skill family: Diagrams. Create, edit, inspect, verify, or rerender professional offline diagrams. Use for architecture, process, sequence, data, state, or relationship visuals from intent or source. ## Run it - Claude Code: `/diagram`. If /diagram runs another command, use /planr:diagram. - Codex: `$diagram`. With the OpenPlanr plugin for Codex, use $planr:diagram. - Cursor: `@planr-diagram`. Cursor applies the planr-diagram rule when you mention it in chat. ## Use it to - Create a professional diagram from English intent or Mermaid - Inspect, verify, preview, or rerender an OpenPlanr diagram set ## Not for - Create a product interface design - Open a generic artifact that is not a diagram --- title: OpenPlanr Doctor description: Diagnose OpenPlanr CLI, pipeline, runtime-adapter, installation, and lock health. url: https://openplanr.dev/docs/skills/doctor updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/investigate.md --- # OpenPlanr Doctor Skill family: Setup and diagnostics. Diagnose OpenPlanr CLI, pipeline, runtime-adapter, installation, and lock health. Use when setup, discovery, versions, generated assets, or runtime behavior seems wrong. ## Run it - Claude Code: `/planr:doctor` - Codex: `$doctor`. With the OpenPlanr plugin for Codex, use $planr:doctor. - Cursor: `@planr-doctor`. Cursor applies the planr-doctor rule when you mention it in chat. ## Use it to - Diagnose OpenPlanr installation, runtime, adapter, version, or lock health - Check why openplanr setup or upgrade is unhealthy ## Not for - Diagnose an application bug - Implement a feature --- title: OpenPlanr Investigate description: Diagnose a bug, regression, error, or unexplained behavior and optionally implement a bounded fix. url: https://openplanr.dev/docs/skills/investigate updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/doctor.md --- # OpenPlanr Investigate Skill family: Setup and diagnostics. Diagnose a bug, regression, error, or unexplained behavior and optionally implement a bounded fix. Use for root-cause investigation, not planned feature delivery. ## Run it - Claude Code: `/investigate`. If /investigate runs another command, use /planr:investigate. - Codex: `$investigate`. With the OpenPlanr plugin for Codex, use $planr:investigate. - Cursor: `@planr-investigate`. Cursor applies the planr-investigate rule when you mention it in chat. ## Use it to - Investigate a bug, regression, error, or unexplained behavior - Reproduce a defect, establish its root cause, or apply a bounded fix - Investigate why this fails ## Not for - Plan a new feature - Run a broad product review --- title: OpenPlanr Land description: Assess release readiness and prepare or inspect an OpenPlanr landing sequence. url: https://openplanr.dev/docs/skills/land updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/release.md --- # OpenPlanr Land Skill family: Land and release. Check whether reviewed work is ready to merge, publish, or deploy, and get the landing sequence in order. Land prepares the steps and never runs them. Assess release readiness and prepare or inspect an OpenPlanr landing sequence. Use after implementation and checks are complete, before merge, publication, or deployment. ## Run it - Claude Code: `/land`. If /land runs another command, use /planr:land. - Codex: `$land`. With the OpenPlanr plugin for Codex, use $planr:land. - Cursor: `@planr-land`. Cursor applies the planr-land rule when you mention it in chat. ## Use it to - Prepare or inspect a landing and release plan - Check whether reviewed work is ready to land without deploying it ## Not for - Build a new application feature - Deploy or publish immediately ## Example prompt Claude Code: ```text /land the sign-in work on this branch ``` If /land runs another command, use /planr:land. Codex: ```text $land the sign-in work on this branch ``` With the OpenPlanr plugin for Codex, use $planr:land. Cursor: ```text @planr-land the sign-in work on this branch ``` Cursor applies the planr-land rule when you mention it in chat. Use Land after implementation and checks are complete. It reads the current branch, the worktree, the requested target, the checks that already ran, and the release constraints in the repository. It uses `openplanr land` only when that adds useful local state. The reply gives readiness (ready, conditional, or blocked), the blockers, the ordered landing sequence with its preconditions, recovery guidance for the first meaningful failure, and one next action. Merging, publishing, and deploying stay with you. See [Review before it lands](https://openplanr.dev/docs/guides/review.md). --- title: OpenPlanr Router description: Route a planning, specification, delivery, delegation, design, review, diagram, release, or operating request to the best OpenPlanr skill. url: https://openplanr.dev/docs/skills/openplanr updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/dashboard.md - https://openplanr.dev/docs/skills/status.md - https://openplanr.dev/docs/skills/sync.md --- # OpenPlanr Router Skill family: Status, routing and sync. Route a planning, specification, delivery, delegation, design, review, diagram, release, or operating request to the best OpenPlanr skill. Use when the right skill is unclear or the request spans several. ## Run it - Claude Code: `/openplanr`. If /openplanr runs another command, use /planr:openplanr. - Codex: `$openplanr`. With the OpenPlanr plugin for Codex, use $planr:openplanr. - Cursor: `@planr-openplanr`. Cursor applies the planr-openplanr rule when you mention it in chat. ## Use it to - Choose which OpenPlanr skill should handle a request - Route a mixed or unclear planning, delivery, design, or operating request ## Not for - Perform the routed work itself - Answer a question unrelated to OpenPlanr workflows --- title: OpenPlanr Operate description: Run a focused operating review across seven executive lenses and produce a decision and action brief. url: https://openplanr.dev/docs/skills/operate updated: 2026-10-06 related: [] --- # OpenPlanr Operate Skill family: Operate. Run one operating review across 7 executive lenses and get a board report with decisions, actions, risks, and gaps. Run a focused operating review across seven executive lenses and produce a decision and action brief. Use for periodic product or company-level leadership review. ## Run it - Claude Code: `/operate`. If /operate runs another command, use /planr:operate. - Codex: `$operate`. With the OpenPlanr plugin for Codex, use $planr:operate. - Cursor: `@planr-operate`. Cursor applies the planr-operate rule when you mention it in chat. ## Use it to - Run an executive operating review across product, technology, growth, operations, and strategy - Produce a decision and action brief for the product or company ## Not for - Review only a code diff - Implement the resulting actions ## Example prompt Claude Code: ```text /operate activation, runway, and delivery risk this month ``` If /operate runs another command, use /planr:operate. Codex: ```text $operate activation, runway, and delivery risk this month ``` With the OpenPlanr plugin for Codex, use $planr:operate. Cursor: ```text @planr-operate activation, runway, and delivery risk this month ``` Cursor applies the planr-operate rule when you mention it in chat. ## Output `.planr/operate/-/board-report.md`: ```text > **Contract:** operate-review-quality-contract@2.0.0 ## Scope ## Executive summary ## Decision queue ## Action plan ## Risks and dissent ## Decision-changing gaps ## Review coverage ## Issues ``` Operate writes one shared brief, then runs 5 advisor lenses: strategy and finance, technology and delivery risk, product and activation, growth and market, and operations and customer health. A challenger tests the claims that could change a decision, and a chair turns the notes into one decision queue and action plan. Each review gets its own folder, and a new review never overwrites an earlier one. The board report holds at most 5 decisions, 7 actions, and 5 decision-changing gaps. See [Track delivery and run operating reviews](https://openplanr.dev/docs/guides/operate.md). --- title: OpenPlanr Plan description: Turn a Protocol-compatible specification or product intent into schema-compatible OpenPlanr stories and implementation tasks. url: https://openplanr.dev/docs/skills/plan updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/plan-review.md - https://openplanr.dev/docs/skills/spec.md - https://openplanr.dev/docs/skills/sprint.md --- # OpenPlanr Plan Skill family: Plan and specify. Break a specification or a clear request into user stories and tasks, each task with its files, its dependencies, and the checks that prove it is done. Plan stops at the handoff and never starts building. Turn a Protocol-compatible specification or product intent into schema-compatible OpenPlanr stories and implementation tasks. Use for planning and decomposition, not implementation. ## Run it - Claude Code: `/planr:plan` - Codex: `$plan`. With the OpenPlanr plugin for Codex, use $planr:plan. - Cursor: `@planr-plan`. Cursor applies the planr-plan rule when you mention it in chat. ## Use it to - Decompose a specification into user stories and implementation tasks - Create an implementation plan from product intent ## Not for - Implement the plan - Review an already written plan ## Example prompt Claude Code: ```text /planr:plan SPEC-001 ``` Codex: ```text $plan SPEC-001 ``` With the OpenPlanr plugin for Codex, use $planr:plan. Cursor: ```text @planr-plan SPEC-001 ``` Cursor applies the planr-plan rule when you mention it in chat. ## Output `.planr/specs/SPEC-001-/tasks/T-001-.md`: ```text --- id: "T-001" storyId: "US-001" specId: "SPEC-001" schemaVersion: "1.7.0" type: "Tech" rationale: "" dependsOn: [] preserve: [] reviewRisks: [] browserSurfaces: [] acceptanceRefs: ["AC-001"] --- ## Objective ## Files ### Create ### Modify ### Preserve (do not touch) ## Technical Spec ## Test Requirements ## Definition of Done ``` Plan reads the spec, the repository instructions, the relevant code and tests, and any approved design, then writes stories and tasks next to the spec. Every story gets acceptance criteria with stable IDs, and every criterion maps to a task that names it again in its test requirements. A story never gets more than 2 tasks: one Tech task, or one UI task and one Tech task when it has a design surface. It validates the frontmatter and the acceptance coverage, then hands you the next ready task and the exact command to build it. See [Plan a feature](https://openplanr.dev/docs/guides/plan.md). --- title: OpenPlanr Plan Review description: Review an OpenPlanr plan for product, engineering, design, and developer-experience problems. Use after planning and before implementation to improve the plan. url: https://openplanr.dev/docs/skills/plan-review updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/plan.md - https://openplanr.dev/docs/skills/spec.md - https://openplanr.dev/docs/skills/sprint.md --- # OpenPlanr Plan Review Skill family: Plan and specify. Review a plan for product, engineering, design, and developer-experience problems after planning and before anyone builds. You get one verdict and concrete corrections. Review an OpenPlanr plan for product, engineering, design, and developer-experience problems. Use after planning and before implementation to improve the plan. ## Run it - Claude Code: `/plan-review`. If /plan-review runs another command, use /planr:plan-review. - Codex: `$plan-review`. With the OpenPlanr plugin for Codex, use $planr:plan-review. - Cursor: `@planr-plan-review`. Cursor applies the planr-plan-review rule when you mention it in chat. ## Use it to - Review an implementation plan for product, engineering, design, and developer-experience problems - Challenge a plan before implementation ## Not for - Implement the plan - Write a new specification from vague intent ## Example prompt Claude Code: ```text /plan-review SPEC-001 ``` If /plan-review runs another command, use /planr:plan-review. Codex: ```text $plan-review SPEC-001 ``` With the OpenPlanr plugin for Codex, use $planr:plan-review. Cursor: ```text @planr-plan-review SPEC-001 ``` Cursor applies the planr-plan-review rule when you mention it in chat. The review checks that the outcome is clear and measurable, then looks at scope, sequencing, ownership, architecture, migration, security, operability, testing, and rollback in proportion to the change, plus the first-run and everyday developer experience. It uses only the lenses the work needs. It leads with one verdict: ready, ready with improvements, or needs revision. Then come the issues that must be fixed, the improvements worth making, the open decisions with a recommended default, and the smallest next step, each finding tied to the plan section it affects. See [Review before it lands](https://openplanr.dev/docs/guides/review.md). --- title: OpenPlanr Release description: Choose and maintain a product's versioning scheme, classify shipped changes, and write user-facing changelogs or release notes. url: https://openplanr.dev/docs/skills/release updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/land.md --- # OpenPlanr Release Skill family: Land and release. Pick the next version from what changed for users, and write release notes people can read. Release prepares everything locally and publishes only when you ask. Choose and maintain a product's versioning scheme, classify shipped changes, and write user-facing changelogs or release notes. Use for SemVer or CalVer decisions, version bumps, release cadence, and preparing a versioned release after landing. ## Run it - Claude Code: `/release`. If /release runs another command, use /planr:release. - Codex: `$release`. With the OpenPlanr plugin for Codex, use $planr:release. - Cursor: `@planr-release`. Cursor applies the planr-release rule when you mention it in chat. ## Use it to - Choose the next SemVer or CalVer version and write user-facing release notes - Set up or maintain a changelog, versioning scheme, and release cadence ## Not for - Check whether unmerged work is ready to land without choosing a version - Implement product code before release preparation ## Use instead - [OpenPlanr Land](https://openplanr.dev/docs/skills/land.md) - [OpenPlanr Ship](https://openplanr.dev/docs/skills/ship.md) ## Example prompt Claude Code: ```text /release Write user-facing release notes for everything since the last tag and update the changelog. ``` If /release runs another command, use /planr:release. Codex: ```text $release Write user-facing release notes for everything since the last tag and update the changelog. ``` With the OpenPlanr plugin for Codex, use $planr:release. Cursor: ```text @planr-release Write user-facing release notes for everything since the last tag and update the changelog. ``` Cursor applies the planr-release rule when you mention it in chat. ## Output `CHANGELOG.md`: ```text ## [Unreleased] ## [1.4.0] - 2026-09-08 ### Removed - Entry, with the migration step inline. ### Added - Entry. ### Changed - Entry. ### Fixed - Entry. ``` Release classifies every change by one question: does a user have to do, know, or expect something different now? That classification drives the version bump and the notes. A CLI or library that others install and pin follows SemVer strictly, and the scheme you agree on is saved in `.release/profile.md`, so later releases follow it instead of deciding again. The notes lead with what users can now do, describe fixes by the symptom users saw, and leave internal work out. Release prepends the new section to `CHANGELOG.md`, bumps versions with your repository's release tool, and stops there: pushing tags, publishing packages, and deploying happen only when you ask. --- title: OpenPlanr Ship description: Implement an OpenPlanr plan, specification, task, or clearly stated request end to end in the current repository. url: https://openplanr.dev/docs/skills/ship updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/delegate.md --- # OpenPlanr Ship Skill family: Implement. Build one task, or a clearly stated change, end to end in your repository, then run the checks the repository defines. Ship keeps the work local and does not publish or deploy it. Implement an OpenPlanr plan, specification, task, or clearly stated request end to end in the current repository. Use when the user asks to build, implement, fix, finish, or ship local work. ## Run it - Claude Code: `/ship`. If /ship runs another command, use /planr:ship. - Codex: `$ship`. With the OpenPlanr plugin for Codex, use $planr:ship. - Cursor: `@planr-ship`. Cursor applies the planr-ship rule when you mention it in chat. ## Use it to - Implement a plan, specification, task, fix, or clearly stated local request - Build and verify the requested repository change - Ship this - Ship task - Implement this task - Implement this plan with parallel coding agents - Use native parallel agents to implement this task - Fix the delegate runner in the active agent ## Not for - Only plan the work - Prepare a release without changing code - Have Codex implement this task - Use Codex to implement this - Have Claude Code implement this task - Ask another coding agent to implement this task - Use another coding agent to build this change ## Use instead - [OpenPlanr Land](https://openplanr.dev/docs/skills/land.md) ## Example prompt Claude Code: ```text /ship T-001 ``` If /ship runs another command, use /planr:ship. Codex: ```text $ship T-001 ``` With the OpenPlanr plugin for Codex, use $planr:ship. Cursor: ```text @planr-ship T-001 ``` Cursor applies the planr-ship rule when you mention it in chat. Ship reads the task completely, then its story, the acceptance criteria, the Gherkin file when there is one, and the spec. It treats the task's Create and Modify lists as the expected surface, adds companion files when correctness needs them, and leaves the Preserve list unchanged. It finds checks in the task's test requirements, the repository instructions, the package scripts, and the CI configuration, runs them, and fixes failures its own change caused. The reply gives the outcome (completed, partial, or blocked), the task, the files changed, each check with its result, and any open issue. See [Build one task at a time](https://openplanr.dev/docs/guides/build.md). --- title: OpenPlanr Spec description: Shape vague product or engineering intent into a clear, measurable Protocol-compatible specification grounded in the current repository. url: https://openplanr.dev/docs/skills/spec updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/plan.md - https://openplanr.dev/docs/skills/plan-review.md - https://openplanr.dev/docs/skills/sprint.md --- # OpenPlanr Spec Skill family: Plan and specify. Turn a vague product or engineering idea into a clear, measurable specification grounded in your repository, before anyone plans or builds. Shape vague product or engineering intent into a clear, measurable Protocol-compatible specification grounded in the current repository. Use when requirements need clarification before planning or implementation. ## Run it - Claude Code: `/spec`. If /spec runs another command, use /planr:spec. - Codex: `$spec`. With the OpenPlanr plugin for Codex, use $planr:spec. - Cursor: `@planr-spec`. Cursor applies the planr-spec rule when you mention it in chat. ## Use it to - Turn vague product or engineering intent into a precise specification - Clarify requirements and acceptance criteria before planning ## Not for - Implement an existing specification - Return project status ## Example prompt Claude Code: ```text /spec add passwordless sign-in for existing accounts. Users drop off at the password step. ``` If /spec runs another command, use /planr:spec. Codex: ```text $spec add passwordless sign-in for existing accounts. Users drop off at the password step. ``` With the OpenPlanr plugin for Codex, use $planr:spec. Cursor: ```text @planr-spec add passwordless sign-in for existing accounts. Users drop off at the password step. ``` Cursor applies the planr-spec rule when you mention it in chat. ## Output `.planr/specs/SPEC-001-/SPEC-001-.md`: ```text --- id: "SPEC-001" title: "" slug: "<slug>" schemaVersion: "1.7.0" --- ## Context & Goal ## Audience ## Outcome & Measurement ## Functional Requirements ## Business Rules ## Constraints ## Evidence Expectations ## Failure Modes ## Rollback ## Scope Boundaries ## Acceptance Criteria ## Declared Risk Specialists ## Notes for Decomposition ``` The skill reads your request, the repository instructions, existing plans, and the relevant code and tests. When a missing decision would change the scope or the behavior, it asks you, at most 3 short questions at a time, with the recommended option first. Then it writes one specification whose requirements and acceptance criteria are observable, each criterion with a stable ID. The sections follow the specification contract the skill ships with. The reply links the saved file and ends with the exact command to plan the spec next. Walk through it in [Write your first spec](https://openplanr.dev/docs/get-started/first-spec.md). --- title: OpenPlanr Sprint description: Refine every open backlog item against the code and the calendar, refute the picks, and select a sprint that fits capacity and the release cut. url: https://openplanr.dev/docs/skills/sprint updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/plan.md - https://openplanr.dev/docs/skills/plan-review.md - https://openplanr.dev/docs/skills/spec.md --- # OpenPlanr Sprint Skill family: Plan and specify. Refine every open backlog item against the code and the calendar, refute the picks, and select a sprint that fits capacity and the release cut. Use before a cut or sprint; not for decomposing one specification or reporting status. ## Run it - Claude Code: `/sprint`. If /sprint runs another command, use /planr:sprint. - Codex: `$sprint`. With the OpenPlanr plugin for Codex, use $planr:sprint. - Cursor: `@planr-sprint`. Cursor applies the planr-sprint rule when you mention it in chat. ## Use it to - Refine the open backlog and select what fits the next sprint or release cut - Judge which backlog items are stale, blocked, or ready and fit the sprint to capacity - Decide which open backlog items move to in progress before the release cut and which are dead ## Not for - Decompose one specification into stories and tasks - Report delivery status without judging or selecting work --- title: OpenPlanr Status description: Inspect project delivery or one feature's pipeline status without changing state. Use when the user asks what is done, pending, blocked, or next. url: https://openplanr.dev/docs/skills/status updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/dashboard.md - https://openplanr.dev/docs/skills/openplanr.md - https://openplanr.dev/docs/skills/sync.md --- # OpenPlanr Status Skill family: Status, routing and sync. See what is done, pending, blocked, and next from the plan in your repository, without changing anything. Inspect project delivery or one feature's pipeline status without changing state. Use when the user asks what is done, pending, blocked, or next. ## Run it - Claude Code: `/planr:status` - Codex: `$status`. With the OpenPlanr plugin for Codex, use $planr:status. - Cursor: `@planr-status`. Cursor applies the planr-status rule when you mention it in chat. ## Use it to - Report current OpenPlanr delivery status or outstanding work - Show progress for one feature or the whole project ## Not for - Open the visual dashboard - Modify planning state ## Example prompt Claude Code: ```text /planr:status ``` Codex: ```text $status ``` With the OpenPlanr plugin for Codex, use $planr:status. Cursor: ```text @planr-status ``` Cursor applies the planr-status rule when you mention it in chat. Status reads the planning files, task statuses, dependency graph, current branch, and runtime markers directly. It reports counts, ready and blocked work, dependency problems, and the most useful next action, for the whole project or one feature. It never repairs files, starts Plan or Ship, or changes a status. It works from local files, queries GitHub or Linear only when you ask for live remote state, and says which data it inspected and how fresh it is. See [Track delivery and run operating reviews](https://openplanr.dev/docs/guides/operate.md). --- title: OpenPlanr Sync description: Audit OpenPlanr planning artifacts for graph and protocol drift. Use when statuses, references, schemas, or generated planning views may be inconsistent. url: https://openplanr.dev/docs/skills/sync updated: 2026-10-06 related: - https://openplanr.dev/docs/skills/dashboard.md - https://openplanr.dev/docs/skills/openplanr.md - https://openplanr.dev/docs/skills/status.md --- # OpenPlanr Sync Skill family: Status, routing and sync. Audit OpenPlanr planning artifacts for graph and protocol drift. Use when statuses, references, schemas, or generated planning views may be inconsistent. ## Run it - Claude Code: `/sync`. If /sync runs another command, use /planr:sync. - Codex: `$sync`. With the OpenPlanr plugin for Codex, use $planr:sync. - Cursor: `@planr-sync`. Cursor applies the planr-sync rule when you mention it in chat. ## Use it to - Audit planning artifacts for graph, schema, or protocol drift - Check whether stories, tasks, and generated planning state are synchronized ## Not for - Synchronize external cloud data - Implement feature code --- title: Guides description: Step-by-step guides for each stage of the OpenPlanr loop, from the first spec to the operating review. url: https://openplanr.dev/docs/guides updated: 2026-10-06 related: [] --- # Guides Plan. Design. Build. Review. Operate. Each stage of the loop has a guide that shows which skills to use, what each one writes, and where to go next. ## The loop - [Plan a feature](https://openplanr.dev/docs/guides/plan.md): turn an idea into a spec, then into stories and tasks your agent can build. - [Design before you build](https://openplanr.dev/docs/guides/design.md): design the screens in a review studio and hand Plan a design spec. - [Build one task at a time](https://openplanr.dev/docs/guides/build.md): ship one task per change, or hand a task to another coding agent. - [Review before it lands](https://openplanr.dev/docs/guides/review.md): review the plan, test the running app, and check readiness before merge. - [Track delivery and run operating reviews](https://openplanr.dev/docs/guides/operate.md): see what is done and blocked, and turn reviews into decisions. ## Planning for coding agents - [Plan mode or a written plan?](https://openplanr.dev/docs/guides/plan-mode-vs-written-plan.md): when your agent's plan mode is enough, and when a plan in the repository pays off. - [User stories your coding agent can build and check](https://openplanr.dev/docs/guides/user-stories-for-coding-agents.md): acceptance criteria and tasks an agent can verify. ## More guides - [Delegate implementation through a native coding CLI](https://openplanr.dev/docs/guides/delegation.md) - [Artifact review and private sharing](https://openplanr.dev/docs/guides/artifact-review.md) --- title: Plan a feature description: Turn an idea into a measurable spec, break it into stories and tasks your agent can build, and pick what fits the next release cut. url: https://openplanr.dev/docs/guides/plan updated: 2026-10-06 related: - https://openplanr.dev/docs/guides/plan-mode-vs-written-plan.md - https://openplanr.dev/docs/guides/user-stories-for-coding-agents.md --- # Plan a feature Planning in OpenPlanr happens in 3 steps: a spec that says what and why, a plan of stories and tasks that says how, and a sprint that says what fits next. Each step writes files under `.planr/` that you review like code. ## 1. Write the spec Invoke `/spec` (Claude Code), `$spec` (Codex) or `@planr-spec` (Cursor) with the change you want and the problem it solves. The skill reads your repository first and asks only about decisions that would change the scope, at most 3 short questions at a time. It writes one specification with observable requirements and acceptance criteria, each with a stable ID. The walkthrough is in [Write your first spec](https://openplanr.dev/docs/get-started/first-spec.md). ## 2. Break it into stories and tasks Invoke `/planr:plan` (Claude Code), `$plan` (Codex) or `@planr-plan` (Cursor) with the spec ID. Plan reads the spec, the repository instructions, the relevant code and tests, and any design handoff, then writes stories and tasks next to the spec: - Every story gets acceptance criteria with stable IDs, starting at AC-001. - A story gets one Tech task, or one UI task and one Tech task when it has a design surface. It never gets more than 2. - Every task names the files to create, modify, and preserve, the checks that prove it is done, and the acceptance IDs it delivers. - A task depends on another only when it consumes that task's output. File overlap and numbering never create a dependency. Plan validates the frontmatter and the acceptance coverage, then stops. It hands you the next ready task and the exact command to build it, and it never starts building on its own. When the request is already clear, you can skip the spec: Plan also accepts a clear product request and reads the repository for the rest. ## 3. Pick what fits the next cut Invoke `/sprint` (Claude Code), `$sprint` (Codex) or `@planr-sprint` (Cursor) before a sprint or a release cut. Sprint reads every open backlog item in full, checks the code each item names before believing its claim, and sorts what is stale, blocked, or ready. Then it fits the surviving items to your capacity and the next cut, tests its picks, and writes the sprint. Ask for a refine-only run to get the refinement without a sprint. Any run can be repeated and compared with the previous one. ## Keep the plan consistent When stories, tasks, and statuses may have drifted apart, invoke `/sync` (Claude Code), `$sync` (Codex) or `@planr-sync` (Cursor). It audits read-only by default and repairs only when you ask. From the terminal, `openplanr sync --dry-run` previews the cross-reference fixes and `openplanr sync` applies them. ## Prompts for this stage - [Turn a rough idea into a spec](https://openplanr.dev/docs/prompts/spec-from-idea.md) - [Pin down acceptance criteria before planning](https://openplanr.dev/docs/prompts/clarify-acceptance-criteria.md) - [Break a spec into stories and tasks](https://openplanr.dev/docs/prompts/plan-a-spec.md) - [Plan straight from a clear request](https://openplanr.dev/docs/prompts/plan-from-intent.md) - [Pick the next sprint against the real code](https://openplanr.dev/docs/prompts/pick-the-sprint.md) - [Refine the backlog without picking a sprint](https://openplanr.dev/docs/prompts/refine-the-backlog.md) - [Audit the plan for drift](https://openplanr.dev/docs/prompts/audit-plan-drift.md) Next: [Design before you build](https://openplanr.dev/docs/guides/design.md) when the work has screens, or [Build one task at a time](https://openplanr.dev/docs/guides/build.md). --- title: Plan mode or a written plan? description: Claude Code, Codex, and Cursor each have a plan mode for the change in front of you. When a written plan in your repository pays off, and how to use both. url: https://openplanr.dev/docs/guides/plan-mode-vs-written-plan updated: 2026-10-06 related: - https://openplanr.dev/docs/guides/plan.md - https://openplanr.dev/docs/guides/user-stories-for-coding-agents.md --- # Plan mode or a written plan? Plan mode is the right tool for a change you finish in one session. When the work spans several sessions, several people, or several pull requests, a written plan in your repository pays off. Most teams use both. ## What plan mode does Claude Code, Codex, and Cursor each have a plan mode: the agent researches the change and proposes a plan before it edits anything. - **Claude Code.** Press Shift+Tab until the status bar shows plan mode, or start a session with `claude --permission-mode plan`. Claude reads files and proposes a plan, but makes no edits until you approve it. Plan files go to `~/.claude/plans` by default; the `plansDirectory` setting keeps them inside the project instead. - **Codex.** In the Codex CLI, a slash command switches the chat into plan mode, and Codex proposes an execution plan before implementation work starts. - **Cursor.** Press Shift+Tab in the chat input, or use the mode picker. The agent researches your codebase, asks clarifying questions, and writes a plan you can edit before you build. Plans are saved in your home directory until you choose Save to workspace. For a bug fix, a small refactor, or a change you will finish before you close the session, plan mode is enough. ## Where a written plan helps Plan mode writes a plan for the change in front of you. A written plan in OpenPlanr is a set of files with a fixed shape, kept in your repository and read by every later step: - **A spec with acceptance criteria.** Each criterion is observable and has a stable ID, such as AC-001. - **Stories and tasks with their context.** Every task names its files to create, modify, and preserve, the tasks it depends on, its rationale, the risks a reviewer should watch, and the acceptance IDs it delivers. - **Files in your repository.** Specifications, stories, tasks, and provenance live under `.planr/`, reviewed and versioned like code, so the next session and the next teammate start from the same plan. - **A separate build step.** Plan stops after writing the plan. Ship later reads the task, its story, its acceptance criteria, and the spec before it changes code, one task at a time. - **Checks without a model.** The `openplanr` CLI validates the planning files offline. ## Choosing between them | Situation | Use | | --- | --- | | A change you finish in one session | Plan mode | | Work that spans several sessions or days | A written plan | | Several people or agents build parts of it | A written plan | | More than one pull request | A written plan | | The plan itself needs review before anyone builds | A written plan, reviewed as a diff | ## Using both Start a feature with a written plan, then use plan mode inside a single task when the change needs a closer look before your agent edits code. If you already have a plan from plan mode, you can hand it to `/planr:plan` (Claude Code), `$plan` (Codex) or `@planr-plan` (Cursor) as the request. Plan accepts a specification or a clear product request, reads the repository, and writes the stories and tasks. For a vague idea, start with `/spec` (Claude Code), `$spec` (Codex) or `@planr-spec` (Cursor) instead. Next: [Plan a feature](https://openplanr.dev/docs/guides/plan.md), or [Plans are files](https://openplanr.dev/docs/get-started/plans-are-files.md) for what the folder holds. --- title: User stories your coding agent can build and check description: How to write user stories, acceptance criteria, and tasks a coding agent can build from and verify, with a template in OpenPlanr's format. url: https://openplanr.dev/docs/guides/user-stories-for-coding-agents updated: 2026-10-06 related: - https://openplanr.dev/docs/guides/plan.md - https://openplanr.dev/docs/guides/plan-mode-vs-written-plan.md --- # User stories your coding agent can build and check A coding agent reads a story literally. Where the story leaves a gap, the agent fills it with a guess. This guide covers the parts of a story and a task that an agent can build from and a reviewer can check against, in the shape OpenPlanr's planning skills write them. ## Why stories written for people fall short A story written for a team leans on context the team already shares: the planning conversation, the design someone has in mind, the files everyone knows to leave alone. An agent has none of that unless the story or the task states it. A criterion such as "handles errors well" leaves the agent to decide what done means. ## Write acceptance criteria an agent can check Make each criterion observable: something a test, a browser check, or a reviewer can confirm without asking what you meant. The Given, When, Then form keeps it concrete: > Given an existing account, when the user requests a sign-in link, then an email with a single-use link arrives. Give each criterion a stable ID, starting at AC-001, and keep one behavior per criterion, so a task can point at exactly the criteria it delivers. ## Give every task its context A task is where an agent starts work, so it carries what the agent and the reviewer need: - **Files.** What to create, what to modify, and what to preserve. The Preserve list protects files the change must not touch. - **Dependencies.** The tasks whose output this one consumes, and only those. Overlapping files and numbering are not dependencies. - **Rationale.** Why the task exists. - **Review risks.** The risk areas a reviewer should check: security, performance, migration, API contract, or data integrity. - **Acceptance references.** The criteria the task delivers. The task's test requirements name each one again with an observable check. Keep stories small. OpenPlanr's planning skill gives a story one Tech task, or one UI task and one Tech task when it has a design surface, and never more than 2. ## A template you can copy This story and task follow the files `/planr:plan` (Claude Code), `$plan` (Codex) or `@planr-plan` (Cursor) writes. Replace the parts in angle brackets. ```markdown --- id: "US-001" title: "<what the user can do>" specId: "SPEC-001" slug: "<story-slug>" schemaVersion: "1.7.0" status: "pending" created: "<YYYY-MM-DD>" updated: "<YYYY-MM-DD>" acceptanceCriteria: - id: "AC-001" statement: "Given <context>, when <action>, then <observable outcome>." --- ## User Story As a <role>, I want <action>, so that <benefit>. ## Scope <what this story covers> ## Acceptance Criteria - **AC-001:** Given <context>, when <action>, then <observable outcome>. ## Task Breakdown - T-001: <task title> ## Dependencies <stories or tasks this one waits on, or none> ## Notes <anything the agent needs that the criteria do not say> ``` ```markdown --- id: "T-001" title: "<task title>" storyId: "US-001" specId: "SPEC-001" slug: "<task-slug>" schemaVersion: "1.7.0" type: "Tech" agent: "backend-agent" status: "pending" created: "<YYYY-MM-DD>" updated: "<YYYY-MM-DD>" rationale: "<why this task exists>" dependsOn: [] preserve: - { repositoryKey: "<repository>", path: "<file to leave unchanged>" } reviewRisks: [] browserSurfaces: [] acceptanceRefs: ["AC-001"] --- ## Objective <what this task accomplishes> ## Files ### Create - <path> ### Modify - <path> ### Preserve (do not touch) - <file to leave unchanged> ## Technical Spec <libraries, patterns, and integration points> ## Test Requirements - **AC-001:** <the observable check that proves it> ## Definition of Done - [ ] <the checks that must pass> ``` ## A checklist before an agent builds - Each criterion is observable and has a stable ID. - No criterion is left without a task that delivers it. - Tasks list the files to create, modify, and preserve. - A dependency points at a task whose output this task consumes, never at a file overlap. - Test requirements name the criteria the task delivers, each with a check. - The Definition of Done names the checks that must pass. ## From a PRD to tasks If you start from a PRD, turn it into a spec first with `/spec` (Claude Code), `$spec` (Codex) or `@planr-spec` (Cursor). The skill shapes vague intent into measurable requirements and asks only about decisions that change the scope. Then run `/planr:plan` (Claude Code), `$plan` (Codex) or `@planr-plan` (Cursor) on the spec to get stories and tasks in the shape above. When a request is already clear and small, Plan can work from it directly. ## Let your agent write them `/planr:plan` (Claude Code), `$plan` (Codex) or `@planr-plan` (Cursor) writes stories and tasks in this shape, validates the frontmatter and the acceptance coverage, and stops before any code is written. Review them like code before anyone builds. Next: [Plan a feature](https://openplanr.dev/docs/guides/plan.md). --- title: Design before you build description: Design the screens in a review studio you can click through, compare directions, apply pinned feedback, and hand Plan a design spec. url: https://openplanr.dev/docs/guides/design updated: 2026-10-06 related: [] --- # Design before you build When the work has screens, design them before an agent builds them. OpenPlanr's design skills run in your coding agent, produce editable source in your repository, and end with a design spec that Plan reads when it splits the UI work. ## Start one direction Invoke `/planr:design` (Claude Code), `$design` (Codex) or `@planr-design` (Cursor) with the screens, the sizes, and the states you need. The skill reads your brief, the app shell, components, tokens, and reference screens, and asks only the questions that change the outcome. It reuses your app's design system when one exists. It builds one design document with stable screens. Canvas, Prototype, and Walkthrough are 3 views of that same document, so switching views never regenerates the screens. The skill checks the screens in a browser at the declared sizes and exercises the main journey; without a browser it returns the design as unverified. Design stops when the handoff is ready. Planning, building, sharing a review link, and deploying are separate steps you start yourself. ## Compare 3 directions When you want alternatives, invoke `/design-loop` (Claude Code), `$design-loop` (Codex) or `@planr-design-loop` (Cursor). It builds 3 materially different directions for the same journey in a live review studio, using the same screens and frames for each. You pin and rate them on the board, then it develops the direction you select. Until you select one, it reports the comparison as awaiting selection. ## Apply pinned feedback To revise an existing design, invoke `/design-review` (Claude Code), `$design-review` (Codex) or `@planr-design-review` (Cursor). It maps each pin to a stable screen and anchor, changes only the targeted source, and keeps unrelated screens, feedback, and layout as they were. It resolves a pin only after the change is rendered and checked, and reports pins it cannot place as unresolved. ## What Plan receives In a spec-driven project, the design lives next to the spec: ```text .planr/specs/SPEC-NNN-<slug>/design/ design-spec.md ``` The design spec has 10 sections: color palette, typography, spacing and layout, components inventory, navigation and layout patterns, iconography, motion and interaction hints, component overrides, screen inventory, and open questions. Plan reads the design document, the selected direction, and this spec, and checks that they describe the same direction before it writes UI tasks. Screen IDs, component recipes, responsive frames, and flows become context for those tasks. ## Prompts for this stage - [Design the screens before anyone builds them](https://openplanr.dev/docs/prompts/design-before-build.md) - [Compare 3 design directions](https://openplanr.dev/docs/prompts/compare-design-directions.md) - [Apply pinned design feedback](https://openplanr.dev/docs/prompts/apply-pinned-feedback.md) - [Plan UI work from a finished design](https://openplanr.dev/docs/prompts/plan-ui-from-design.md) Next: [Build one task at a time](https://openplanr.dev/docs/guides/build.md). --- title: Build one task at a time description: Ship one planned task per change, verified and small enough to review as one pull request, or hand a task to another coding agent. url: https://openplanr.dev/docs/guides/build updated: 2026-10-06 related: - https://openplanr.dev/docs/guides/delegation.md --- # Build one task at a time Build one task at a time. Each change stays small enough to review as one pull request, and it is checked against the plan it came from. ## Ship a task Invoke `/ship` (Claude Code), `$ship` (Codex) or `@planr-ship` (Cursor) with a task ID. Before it changes code, Ship reads the task completely, then follows it to the parent story, the acceptance criteria, the Gherkin file when there is one, and the spec. It also reads the repository instructions, the relevant code and tests, and the interfaces that the task's dependencies produced. The task's Create and Modify lists describe where the change should land. Ship adds companion files when correctness needs them, leaves the Preserve list unchanged, and keeps unrelated changes in your working tree. When your agent supports sub-agents, Ship can hand frontend, backend, database, QA, DevOps, and documentation work to role agents inside the same session. Otherwise it works through those roles itself. ## How Ship checks its work Ship looks for checks in this order: the task's test requirements, the repository instructions, the package scripts, then CI and pre-commit configuration. It runs focused checks while it works and regression checks at the end, and it fixes failures its own change caused. It reports 5 things: the outcome (completed, partial, or blocked), the task, the files it changed, each check with passed, failed, or not run, and any open issue. Work it could not verify is labeled unverified. Ship keeps the work local and does not publish or deploy it. Getting the change ready to merge belongs to `/land` (Claude Code), `$land` (Codex) or `@planr-land` (Cursor). ## Ship a direct request For a small, clear change, you can skip the plan and give Ship the request itself. The request and the repository are enough context, and missing planning files do not block it. ## Hand a task to another agent When you explicitly want another coding agent to build a task, invoke `/delegate` (Claude Code), `$delegate` (Codex) or `@planr-delegate` (Cursor). The other agent's CLI investigates, implements, and tests in its own worktree. Your current agent keeps the scope, reviews the observed changes, runs its own checks, and applies accepted changes as an uncommitted diff in your checkout. Committing, merging, and deploying stay separate decisions. The full workflow is in [Delegate implementation through a native coding CLI](https://openplanr.dev/docs/guides/delegation.md). ## When something breaks For a bug, start with `/investigate` (Claude Code), `$investigate` (Codex) or `@planr-investigate` (Cursor) instead of Ship. It reproduces the failure, tests competing causes, and changes code only when you ask for a fix. ## Prompts for this stage - [Ship one task, then stop](https://openplanr.dev/docs/prompts/ship-one-task.md) - [Ship a task without touching protected files](https://openplanr.dev/docs/prompts/ship-within-preserve.md) - [Ship a small fix without a plan](https://openplanr.dev/docs/prompts/ship-a-direct-fix.md) - [Hand a task to another coding agent](https://openplanr.dev/docs/prompts/delegate-to-another-agent.md) - [Find the root cause before you fix it](https://openplanr.dev/docs/prompts/investigate-first.md) Next: [Review before it lands](https://openplanr.dev/docs/guides/review.md). --- title: Delegate implementation through a native coding CLI description: planr-delegate coordinates an explicitly requested implementation with Claude Code, Codex or Cursor. url: https://openplanr.dev/docs/guides/delegation updated: 2026-10-06 related: - https://openplanr.dev/docs/guides/build.md --- # Delegate implementation through a native coding CLI `planr-delegate` coordinates an explicitly requested implementation with Claude Code, Codex or Cursor. The installed native harness owns investigation, tools, permissions, sandboxing, configuration, build/test and correction. OpenPlanr supplies complete context, tracks the exact run/session, independently reviews and verifies the candidate, and safely integrates accepted changes into the user's checkout. Use normal signed-in CLI authentication. Fresh native runs need no named enrollment or renewal. Choose an engine explicitly, reuse a saved choice or use the sole available CLI. Optional profiles pin a model or alternate existing configuration. Hosted and local models use the same workflow; local compatibility probes are diagnostic. Before dispatch, review the engine/model selection, known provider or native-managed routing, trusted configuration, context inventory and owned working directory. Pinned destinations must match inspected routing. Conflicting environment and configuration sources block dispatch with their source names and safe origins; OpenPlanr does not silently reset native routing. Local probes use bounded, authenticated model metadata reads. They do not generate completions or load models, and their latency is not an estimate of task duration. Trusted native hooks/plugins/MCP can execute or contact additional services. OpenPlanr does not claim to sandbox those operations. Scope limits accepted changes. The readable capsule retains required ignored planning files and binding repository instructions. A short brief and ordered index avoid duplicating complete files in prompts. Continue the exact recorded session with new findings; unchanged context does not need repeated delivery. Plain native completion is accepted without a formatting-only correction. Permission denials remain actionable and are never worked around by silently weakening policy or changing providers. Prepare required dependencies/build outputs once in the owned worktree. Parent verification uses structured executable/argument arrays and normally reuses that prepared tree. Reviewable changes made by verification invalidate the previous review. A stale prepared tree requires a fresh actual candidate only when necessary. Failures remain blocked; baseline comparisons are explicit diagnostics. Review-only acceptance is explicitly unverified and requires a reason. Integration retains the checkout lock, scope/Preserve checks, reviewed patch identity, destination compare-and-swap and recovery journal. Concurrent user edits are preserved. Accepted changes remain an uncommitted local diff. Successful integration removes only its owned worktree unless retained, keeping context, patch, evidence, report and native session reference. Failed/interrupted worktrees remain inspectable. Status reports live elapsed time and observed native tool activity when the harness provides it. This is activity evidence, not proof that every reported file was read or every proposed change was verified. Errors include recognized native reasons, HTTP status and the inspected destination without exposing raw output or credentials. Use the runner's explicit `abandon` action for a prepared or blocked run that has never executed. It checks ownership, the initial checkout and all surrounding resources before cleanup. Modified or unknown files, ignored dependencies, existing sessions and recovery work prevent removal. The record and evidence remain available. Private v2 records describe this behavior. Existing profiles are unchanged and retained runs use their original pinned helpers. Generic adapters remain experimental under their existing versioned protocol. Ordinary `planr-ship` and frozen public contracts remain unchanged; there are no public delegation CLI commands. See the canonical [skill](https://github.com/openplanr/OpenPlanr/blob/4d4fb273180f65c6c648e6babd4b9c6ae8465ff2/skills/planr-delegate/SKILL.md), [onboarding](https://github.com/openplanr/OpenPlanr/blob/4d4fb273180f65c6c648e6babd4b9c6ae8465ff2/skills/planr-delegate/references/operator-guide.md) and [verification contract](https://github.com/openplanr/OpenPlanr/blob/4d4fb273180f65c6c648e6babd4b9c6ae8465ff2/skills/planr-delegate/references/integration-review.md). Live configurations are verified individually; unavailable or quota-blocked journeys are reported as such. Merge, publication and deployment require separate release decisions. --- title: Review before it lands description: Review the plan before anyone builds it, test the running app in a real browser, check readiness before merge, and write the release notes. url: https://openplanr.dev/docs/guides/review updated: 2026-10-06 related: - https://openplanr.dev/docs/guides/artifact-review.md --- # Review before it lands Review happens at 3 points: on the plan before anyone builds it, on the running app after a change, and on the branch before it merges. Each review skill reports what it checked and leaves the decisions and the merge to you. ## Review the plan Invoke `/plan-review` (Claude Code), `$plan-review` (Codex) or `@planr-plan-review` (Cursor) after planning and before implementation. It checks that the outcome is clear and measurable, then looks at scope, sequencing, ownership, architecture, migration, security, operability, testing, and rollback in proportion to the change. It also checks the first-run and everyday developer experience: setup, diagnostics, defaults, and recovery. It leads with one verdict: ready, ready with improvements, or needs revision. Then it lists what must be fixed, the improvements worth making, the open decisions with a recommended default, and the smallest next step. Each finding names the plan section it affects. ## Test the running app Invoke `/browser-qa` (Claude Code), `$browser-qa` (Codex) or `@planr-browser-qa` (Cursor) after a change to a page, a form, sign-in, or navigation. It starts or reuses your local app and exercises the route in a real browser: navigation, forms, responsive layout, keyboard access, visible focus, accessible names, console errors, failed requests, and loading and error states. Browser QA only reports. It lists reproducible findings with the page and the expected behavior, and you rerun it after the fix. A check it could not run is reported as unverified, and a passing subset never stands in for the whole app. ## Check readiness before merge Invoke `/land` (Claude Code), `$land` (Codex) or `@planr-land` (Cursor) after implementation and checks are complete. It reads the branch, the worktree, the checks that already ran, and the release constraints, then answers ready, conditional, or blocked. You get the blockers, the ordered landing sequence with its preconditions, recovery guidance for the first failure, and one next action. Land prepares the sequence; it never merges, publishes, or deploys. ## Release what landed After landing, `/release` (Claude Code), `$release` (Codex) or `@planr-release` (Cursor) picks the next version from what changed for users and writes the release notes. It prepares the changelog and the version bump locally. Pushing tags, publishing packages, and deploying happen only when you ask. ## Review an HTML artifact To collect comments on a prototype or any HTML file, open it with `openplanr artifact`. Reviewers can comment, pin, reply in threads, and approve or request changes. See [Artifact review and private sharing](https://openplanr.dev/docs/guides/artifact-review.md). ## Prompts for this stage - [Review a plan before anyone builds it](https://openplanr.dev/docs/prompts/review-the-plan.md) - [Check a plan's first-run developer experience](https://openplanr.dev/docs/prompts/review-plan-developer-experience.md) - [Check migration and rollback before you build](https://openplanr.dev/docs/prompts/review-plan-rollback.md) - [Test the change in a real browser](https://openplanr.dev/docs/prompts/browser-qa-flow.md) - [Check a page for accessibility and console errors](https://openplanr.dev/docs/prompts/check-page-accessibility.md) - [Check a branch is ready to land](https://openplanr.dev/docs/prompts/ready-to-land.md) - [Prepare the merge and deploy steps](https://openplanr.dev/docs/prompts/prepare-landing-sequence.md) - [Write release notes users can read](https://openplanr.dev/docs/prompts/write-release-notes.md) Next: [Track delivery and run operating reviews](https://openplanr.dev/docs/guides/operate.md). --- title: Artifact review and private sharing description: openplanr artifact opens native diagrams, authored designs, and HTML artifacts for local review or explicit encrypted sharing. url: https://openplanr.dev/docs/guides/artifact-review updated: 2026-10-06 related: - https://openplanr.dev/docs/guides/review.md --- # Artifact review and private sharing `openplanr artifact` opens native diagrams, authored designs, and HTML artifacts for local review or explicit encrypted sharing. Generic HTML sessions support comments, pins, threads, and Approve or Request changes decisions. JavaScript inside the artifact remains interactive in an opaque-origin, network-blocked sandbox. Generic artifacts open in `document` presentation by default: the complete artifact is the edge-to-edge page with a compact floating comments rail. The prior zoomable artboard is still available as `canvas` presentation and remains the default for design boards and multi-variant workflows. ## Local review ```bash openplanr artifact ./artifact.html openplanr artifact open /absolute/path/to/artifact.html --theme auto openplanr artifact open ./artifact.html --presentation canvas openplanr artifact export <session-id> --format markdown --output review.md ``` The bundler packages local CSS, scripts, modules, images, SVG, fonts, `srcset`, and CSS `url()` references. With no `--root`, the artifact's own directory is the dependency root, so absolute files from Downloads or another project work without extra flags. It also vendors safe public HTTPS dependency graphs (such as Google Fonts, CDN stylesheets, scripts, images, and fonts) into the immutable artifact before review or sharing. Forms, traversal, symlink escapes, unsafe or unavailable remote assets, and unresolved dependencies remain rejected. Use `--no-open --json` for remote or SSH sessions, then forward the printed loopback port explicitly. `--presentation auto|document|canvas` is available on `open` and `share`. `auto` resolves one generic artifact to `document`; explicit overrides win. Document feedback starts closed and opens as an overlay without resizing the artifact. JSON output includes the resolved presentation. The complete local HTML/CSS/JavaScript graph is bundled into immutable bytes before review or sharing. The viewer does not fetch the original project after sharing. It loads those bytes through an invisible Blob iframe with `sandbox="allow-scripts"`; it never injects artifact HTML into OpenPlanr or executes it under the `share.openplanr.dev` origin. A bounded authenticated layout bridge provides natural outer-page scrolling and full-document pins. This is private artifact review, not standalone website hosting. Publishing a top-level website would require a separate isolated artifact origin and is not part of this command. ## Native diagram sharing ```bash openplanr artifact open ./diagrams/handover/handover.manifest.json openplanr artifact share ./diagrams/handover/handover.manifest.json --yes --no-open openplanr artifact publish ./diagrams/handover/handover.manifest.json --yes openplanr artifact sync ./diagrams/handover/handover.manifest.json ``` An authored `diagrams/<slug>/<slug>.planr-diagram-bundle.json` is also accepted. Sharing publishes the selected diagram's native scene without converting its format or rerunning layout. The creation preview shows its title, source revision, publication contents, destination and retention. Original source bytes, local paths and private provenance are excluded. Each diagram has a stable `/diagram/<id>` URL and a separate reviewer access token. Use the local studio's **Share diagram** dialog to copy them separately. Owner custody is kept privately outside the repository. Ordinary command output contains no tokens or signing keys; `--secret-output` explicitly exports recovery to a new private file. Reviews last until revoked or deleted and remain available while the owner's laptop is offline. Local edits remain unpublished until **Publish revision** or `artifact publish`. Comments are tied to their published revision and element or scene position. Earlier revisions stay readable but accept no new comments. Synchronization imports feedback into the local ledger without modifying diagram content. Reviewers can use outline/search, inspection, pan/zoom, Fit, Present, Discussion, Revisions, and SVG/PNG or feedback export. The native shell loads its packaged font before reporting readiness and preserves wide diagrams without an HTML wrapper viewport. An incompatible installed runtime or hosted service produces a compatibility error. There is no automatic HTML fallback. To share an HTML snapshot, export HTML first and explicitly use the generic snapshot route. ## Private links ```bash openplanr artifact share ./artifact.html --secret-output ./room.private.json openplanr artifact share ./artifact.html --presentation document --secret-output ./room.private.json openplanr artifact share ./artifact.html --snapshot --short --ttl 7d --yes ``` By default, sharing creates one stable encrypted live review room. The normal review URL lets anyone with the link view and comment. A distinct owner-verdict URL plus the matching private P-256 signer can approve or request changes. The management URL can only pause/reopen comments or delete the room. The required `--secret-output` path is reserved exclusively, then an exact recovery bundle containing all three URLs and the owner signer is made durable at mode 0600 before the first room request. A lost response is retried once with the same prepared room identity, ciphertext, and capabilities, so it cannot create a duplicate or rotate the recovery URLs. A validated no-effect rejection revokes the bundle; an ambiguous outcome preserves it and returns a bounded, path-free recovery error. New feedback synchronizes to other open review tabs immediately. The artifact itself remains immutable and the service never receives the private signer. Use `--snapshot` for the immutable sharing model. Artifacts whose encoded fragments are 8,000 characters or less use `https://share.openplanr.dev/#v1.<payload>`. The browser fragment is not sent in the HTTP request, so the host receives no artifact content. Fragment links are encoded, not encrypted: anyone who receives the URL can read the review. Larger artifacts require an explicit encrypted short-link upload. OpenPlanr compresses the envelope, encrypts it with AES-256-GCM, uploads ciphertext, and puts the key only after `#k=` in the URL. The service sees request metadata and ciphertext, never plaintext or the key. Links are immutable and expire after 1, 7, or 30 days. Save the one-time deletion token when it is displayed. ## Return and import feedback Live-room feedback stays in its encrypted room until expiry or deletion. Import the room URL at any point to merge its latest full feedback state locally. For snapshot sharing, a reviewer still returns a new immutable review URL. Import one or more room or snapshot URLs non-destructively: ```bash openplanr artifact import "<review-url>" "<second-review-url>" ``` Changed-artifact feedback is rejected with `E_ARTIFACT_STALE_REVIEW`. To retain it for audit, rerun with `--allow-stale`, inspect the digest and feedback-count preview, and confirm. Automation must use `--allow-stale --yes`. Generic review state is stored in `.planr/artifacts/<artifact-id>/` inside a valid project and under `~/.planr/artifacts/` elsewhere. Design-board reviews continue to merge into the adjacent `feedback.json` contract. ## Minimal installs, offline use, and self-hosting A planning-only installation returns `E_PIPELINE_NOT_INSTALLED`; install the full distribution with `npm install -g openplanr@latest`. Local review and export work offline after installation. Creating or opening a remote review link requires network access. The shell assets and Protocol v1.1 schemas are shipped by `planr-pipeline`. Self-hosters can point `OPENPLANR_SHARE_BASE` at their own HTTPS origin serving the static viewer and share Worker. --- title: Track delivery and run operating reviews description: See what is done, blocked, and next from the plan in your repository, and run leadership reviews that end in a decision queue. url: https://openplanr.dev/docs/guides/operate updated: 2026-10-06 related: [] --- # Track delivery and run operating reviews Operating the work means knowing where delivery stands today and stepping back on a regular rhythm to decide what to do next. OpenPlanr reads both from the files in your repository. ## Check delivery status Invoke `/planr:status` (Claude Code), `$status` (Codex) or `@planr-status` (Cursor) to see what is done, pending, blocked, and next, for the whole project or one feature. Status reads the planning files, task statuses, dependency graph, and current branch, and changes nothing. It reports counts, ready and blocked work, dependency problems, and the most useful next action. It works from local files and queries GitHub or Linear only when you ask for live remote state. The report says which data it inspected and how fresh it is. From the terminal, `openplanr status --md` prints the whole-project delivery report as paste-ready Markdown: every spec, backlog item, and quick task by status. ## See the plan on a board Invoke `/dashboard` (Claude Code), `$dashboard` (Codex) or `@planr-dashboard` (Cursor) to start the local planning dashboard. It binds only to your machine's loopback address, reuses a compatible server that is already running, and opens a browser only when you ask. ## Run an operating review Invoke `/operate` (Claude Code), `$operate` (Codex) or `@planr-operate` (Cursor) for a periodic leadership review of a product or the business as a whole. It writes one shared brief, then runs 5 advisor lenses: | Lens | Skill | | --- | --- | | Strategy and finance | [ceo-review](https://openplanr.dev/docs/skills/ceo-review.md) | | Technology and delivery risk | [cto-review](https://openplanr.dev/docs/skills/cto-review.md) | | Product and activation | [cpo-review](https://openplanr.dev/docs/skills/cpo-review.md) | | Growth and market | [cmo-review](https://openplanr.dev/docs/skills/cmo-review.md) | | Operations and customer health | [coo-review](https://openplanr.dev/docs/skills/coo-review.md) | A challenger then tests only the claims that could change a decision, and a chair turns the notes into one brief. Those are the 7 lenses. Each review gets its own folder, and a new review never overwrites an earlier one: ```text .planr/operate/<date>-<slug>/ cycle.md brief.md <lens notes>.md board-report.md ``` The board report holds the scope, an executive summary, a decision queue of at most 5 decisions, an action plan of at most 7 actions, the risks and dissent, the gaps that could change a decision, and the review coverage. Each decision carries a recommendation, a credible alternative, a confidence level, a first step, and a condition to revisit it. ## Prompts for this stage - [Ask what is done, blocked, and next](https://openplanr.dev/docs/prompts/status-check.md) - [Find what is blocked and why](https://openplanr.dev/docs/prompts/find-what-is-blocked.md) - [See the plan on a local board](https://openplanr.dev/docs/prompts/open-the-dashboard.md) - [Run a monthly operating review](https://openplanr.dev/docs/prompts/operate-review.md) - [Stress-test an operating review](https://openplanr.dev/docs/prompts/challenge-the-operating-review.md) - [Get the technology and delivery-risk view](https://openplanr.dev/docs/prompts/technology-risk-review.md) - [Turn review findings into decisions](https://openplanr.dev/docs/prompts/turn-findings-into-decisions.md) --- title: Turn a rough idea into a spec description: Start every feature with a specification your agent can check its work against. url: https://openplanr.dev/docs/prompts/spec-from-idea updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/clarify-acceptance-criteria.md - https://openplanr.dev/docs/prompts/audit-plan-drift.md - https://openplanr.dev/docs/prompts/pick-the-sprint.md --- # Turn a rough idea into a spec Start every feature with a specification your agent can check its work against. ## Prompt Claude Code: ```text /spec add passwordless sign-in for existing accounts. Users drop off at the password step. ``` If /spec runs another command, use /planr:spec. Codex: ```text $spec add passwordless sign-in for existing accounts. Users drop off at the password step. ``` With the OpenPlanr plugin for Codex, use $planr:spec. Cursor: ```text @planr-spec add passwordless sign-in for existing accounts. Users drop off at the password step. ``` Cursor applies the planr-spec rule when you mention it in chat. Parts to fill in, shown with their example text: - The change you want: add passwordless sign-in for existing accounts - The problem it solves: Users drop off at the password step. ## Why this works Name the change and the problem it solves. The skill reads your repository for the rest, and when a missing decision would change the scope, it asks at most 3 short questions at a time. Requirements and acceptance criteria come out observable, so the work can be checked against them. ## Make it stick [Write your first spec](https://openplanr.dev/docs/get-started/first-spec.md) --- title: Break a spec into stories and tasks description: Get user stories and tasks with acceptance criteria and file-level changes. url: https://openplanr.dev/docs/prompts/plan-a-spec updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/plan-from-intent.md - https://openplanr.dev/docs/prompts/plan-ui-from-design.md - https://openplanr.dev/docs/prompts/audit-plan-drift.md --- # Break a spec into stories and tasks Get user stories and tasks with acceptance criteria and file-level changes. ## Prompt Claude Code: ```text /planr:plan SPEC-001 ``` Codex: ```text $plan SPEC-001 ``` With the OpenPlanr plugin for Codex, use $planr:plan. Cursor: ```text @planr-plan SPEC-001 ``` Cursor applies the planr-plan rule when you mention it in chat. Parts to fill in, shown with their example text: - The spec to plan: SPEC-001 ## Why this works Plan reads the saved spec, so every story keeps its acceptance criteria and every task names its files, its dependencies, and the checks that prove it is done. It stops after the plan and never starts building on its own. ## Make it stick [Plan a feature](https://openplanr.dev/docs/guides/plan.md) --- title: Ship one task, then stop description: Build one task end to end and keep the change small enough to review. url: https://openplanr.dev/docs/prompts/ship-one-task updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/ship-a-direct-fix.md - https://openplanr.dev/docs/prompts/ship-within-preserve.md - https://openplanr.dev/docs/prompts/delegate-to-another-agent.md --- # Ship one task, then stop Build one task end to end and keep the change small enough to review. ## Prompt Claude Code: ```text /ship T-001 ``` If /ship runs another command, use /planr:ship. Codex: ```text $ship T-001 ``` With the OpenPlanr plugin for Codex, use $planr:ship. Cursor: ```text @planr-ship T-001 ``` Cursor applies the planr-ship rule when you mention it in chat. Parts to fill in, shown with their example text: - The task to build: T-001 ## Why this works Ship reads the task, its story, its acceptance criteria, and the spec before it changes code, then runs the checks the repository defines. One task at a time keeps each change small enough to review as one pull request. ## Make it stick [Build one task at a time](https://openplanr.dev/docs/guides/build.md) --- title: Ask what is done, blocked, and next description: Read delivery status from the plan in your repo without changing anything. url: https://openplanr.dev/docs/prompts/status-check updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/find-what-is-blocked.md - https://openplanr.dev/docs/prompts/open-the-dashboard.md - https://openplanr.dev/docs/prompts/route-a-mixed-request.md --- # Ask what is done, blocked, and next Read delivery status from the plan in your repo without changing anything. ## Prompt Claude Code: ```text /planr:status ``` Codex: ```text $status ``` With the OpenPlanr plugin for Codex, use $planr:status. Cursor: ```text @planr-status ``` Cursor applies the planr-status rule when you mention it in chat. ## Why this works Status reads your planning files, task statuses, and dependency graph without changing them, then reports ready and blocked work and the most useful next action. It is read-only, so ask as often as you like. ## Make it stick [Plans are files](https://openplanr.dev/docs/get-started/plans-are-files.md) --- title: Design the screens before anyone builds them description: One design direction in a studio you can click through, plus a design spec Plan can read. url: https://openplanr.dev/docs/prompts/design-before-build updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/apply-pinned-feedback.md - https://openplanr.dev/docs/prompts/compare-design-directions.md - https://openplanr.dev/docs/prompts/plan-ui-from-design.md --- # Design the screens before anyone builds them One design direction in a studio you can click through, plus a design spec Plan can read. ## Prompt Claude Code: ```text /planr:design the onboarding checklist for new accounts on desktop and phone, with empty and error states ``` Codex: ```text $design the onboarding checklist for new accounts on desktop and phone, with empty and error states ``` With the OpenPlanr plugin for Codex, use $planr:design. Cursor: ```text @planr-design the onboarding checklist for new accounts on desktop and phone, with empty and error states ``` Cursor applies the planr-design rule when you mention it in chat. Parts to fill in, shown with their example text: - The screens to design: the onboarding checklist for new accounts ## Why this works Name the screens, the sizes, and the states. Design builds one direction you can review as a canvas, a prototype, and a walkthrough, then writes a 10-section design spec that Plan reads before it splits the UI work. ## Make it stick [Design before you build](https://openplanr.dev/docs/guides/design.md) --- title: Apply pinned design feedback description: Revise only the screens your review pins point at, and keep everything else as it was. url: https://openplanr.dev/docs/prompts/apply-pinned-feedback updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/review-an-html-artifact.md - https://openplanr.dev/docs/prompts/audit-plan-drift.md - https://openplanr.dev/docs/prompts/browser-qa-flow.md --- # Apply pinned design feedback Revise only the screens your review pins point at, and keep everything else as it was. ## Prompt Claude Code: ```text /design-review Apply the pinned feedback on the settings screens and leave the other screens unchanged. ``` If /design-review runs another command, use /planr:design-review. Codex: ```text $design-review Apply the pinned feedback on the settings screens and leave the other screens unchanged. ``` With the OpenPlanr plugin for Codex, use $planr:design-review. Cursor: ```text @planr-design-review Apply the pinned feedback on the settings screens and leave the other screens unchanged. ``` Cursor applies the planr-design-review rule when you mention it in chat. Parts to fill in, shown with their example text: - The screens with feedback: the settings screens ## Why this works Design Review maps each pin to a stable screen and anchor, changes only the targeted source, and checks the revised screens in a browser before it resolves a pin. Pins it cannot place are reported as unresolved, not attached somewhere else. ## Make it stick [Design before you build](https://openplanr.dev/docs/guides/design.md) --- title: Audit the plan for drift description: Check that stories, tasks, statuses, and references in the planning folder still agree. url: https://openplanr.dev/docs/prompts/audit-plan-drift updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/review-the-plan.md - https://openplanr.dev/docs/prompts/apply-pinned-feedback.md - https://openplanr.dev/docs/prompts/browser-qa-flow.md --- # Audit the plan for drift Check that stories, tasks, statuses, and references in the planning folder still agree. ## Prompt Claude Code: ```text /sync Check whether the stories, tasks, and statuses under .planr/ still agree. Report what is out of step before changing anything. ``` If /sync runs another command, use /planr:sync. Codex: ```text $sync Check whether the stories, tasks, and statuses under .planr/ still agree. Report what is out of step before changing anything. ``` With the OpenPlanr plugin for Codex, use $planr:sync. Cursor: ```text @planr-sync Check whether the stories, tasks, and statuses under .planr/ still agree. Report what is out of step before changing anything. ``` Cursor applies the planr-sync rule when you mention it in chat. ## Why this works Sync audits read-only by default. It applies local repairs only when you ask for reconciliation, and it pushes to GitHub or Linear only when you ask for external sync. ## Make it stick [Plans are files](https://openplanr.dev/docs/get-started/plans-are-files.md) --- title: Check a branch is ready to land description: Assess release readiness without merging, publishing, or deploying anything. url: https://openplanr.dev/docs/prompts/ready-to-land updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/prepare-landing-sequence.md - https://openplanr.dev/docs/prompts/review-plan-rollback.md - https://openplanr.dev/docs/prompts/apply-pinned-feedback.md --- # Check a branch is ready to land Assess release readiness without merging, publishing, or deploying anything. ## Prompt Claude Code: ```text /land the sign-in work on this branch ``` If /land runs another command, use /planr:land. Codex: ```text $land the sign-in work on this branch ``` With the OpenPlanr plugin for Codex, use $planr:land. Cursor: ```text @planr-land the sign-in work on this branch ``` Cursor applies the planr-land rule when you mention it in chat. Parts to fill in, shown with their example text: - The work to check: the sign-in work on this branch ## Why this works Land reads the branch, the worktree, and the checks that already ran, then answers ready, conditional, or blocked, with the blockers, the landing sequence, and a recovery step. It prepares the commands but does not merge, publish, or deploy. ## Make it stick [Review before it lands](https://openplanr.dev/docs/guides/review.md) --- title: Check a page for accessibility and console errors description: Keyboard access, focus, accessible names, console errors, and failed requests on one page. url: https://openplanr.dev/docs/prompts/check-page-accessibility updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/browser-qa-flow.md - https://openplanr.dev/docs/prompts/apply-pinned-feedback.md - https://openplanr.dev/docs/prompts/audit-plan-drift.md --- # Check a page for accessibility and console errors Keyboard access, focus, accessible names, console errors, and failed requests on one page. ## Prompt Claude Code: ```text /browser-qa Check the pricing page for keyboard access, visible focus, accessible names, console errors, and failed network requests. ``` If /browser-qa runs another command, use /planr:browser-qa. Codex: ```text $browser-qa Check the pricing page for keyboard access, visible focus, accessible names, console errors, and failed network requests. ``` With the OpenPlanr plugin for Codex, use $planr:browser-qa. Cursor: ```text @planr-browser-qa Check the pricing page for keyboard access, visible focus, accessible names, console errors, and failed network requests. ``` Cursor applies the planr-browser-qa rule when you mention it in chat. Parts to fill in, shown with their example text: - The page: the pricing page ## Why this works Browser QA checks navigation, forms, responsive layout, keyboard access, visible focus, accessible names, console errors, and failed requests in a real browser. Checks it could not run are reported as unverified, never as a pass. ## Make it stick [Review before it lands](https://openplanr.dev/docs/guides/review.md) --- title: Check a plan's first-run developer experience description: Ask the plan review to focus on setup, defaults, error messages, and recovery. url: https://openplanr.dev/docs/prompts/review-plan-developer-experience updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/review-plan-rollback.md - https://openplanr.dev/docs/prompts/review-the-plan.md - https://openplanr.dev/docs/prompts/apply-pinned-feedback.md --- # Check a plan's first-run developer experience Ask the plan review to focus on setup, defaults, error messages, and recovery. ## Prompt Claude Code: ```text /plan-review SPEC-001. Focus on the first-run developer experience: setup, defaults, error messages, and recovery. ``` If /plan-review runs another command, use /planr:plan-review. Codex: ```text $plan-review SPEC-001. Focus on the first-run developer experience: setup, defaults, error messages, and recovery. ``` With the OpenPlanr plugin for Codex, use $planr:plan-review. Cursor: ```text @planr-plan-review SPEC-001. Focus on the first-run developer experience: setup, defaults, error messages, and recovery. ``` Cursor applies the planr-plan-review rule when you mention it in chat. Parts to fill in, shown with their example text: - The plan to review: SPEC-001 ## Why this works Plan Review covers the first-run and everyday developer experience, including setup, diagnostics, defaults, and recovery. It uses only the review lenses the work needs, so naming the focus keeps the findings on the part you care about. ## Make it stick [Review before it lands](https://openplanr.dev/docs/guides/review.md) --- title: Check migration and rollback before you build description: Have the plan reviewed for migration, security, operability, and rollback risk. url: https://openplanr.dev/docs/prompts/review-plan-rollback updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/review-plan-developer-experience.md - https://openplanr.dev/docs/prompts/review-the-plan.md - https://openplanr.dev/docs/prompts/ready-to-land.md --- # Check migration and rollback before you build Have the plan reviewed for migration, security, operability, and rollback risk. ## Prompt Claude Code: ```text /plan-review SPEC-001. Check the migration, security, and rollback plan before we build. ``` If /plan-review runs another command, use /planr:plan-review. Codex: ```text $plan-review SPEC-001. Check the migration, security, and rollback plan before we build. ``` With the OpenPlanr plugin for Codex, use $planr:plan-review. Cursor: ```text @planr-plan-review SPEC-001. Check the migration, security, and rollback plan before we build. ``` Cursor applies the planr-plan-review rule when you mention it in chat. Parts to fill in, shown with their example text: - The plan to review: SPEC-001 ## Why this works Plan Review checks scope, sequencing, architecture, migration, security, operability, testing, and rollback in proportion to the change. Any must-fix issue turns the verdict to needs revision and names the plan section and the change that would resolve it. ## Make it stick [Review before it lands](https://openplanr.dev/docs/guides/review.md) --- title: Choose the next version number description: Decide major, minor, or patch from what changed for users, not from the size of the diff. url: https://openplanr.dev/docs/prompts/choose-next-version updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/write-release-notes.md - https://openplanr.dev/docs/prompts/prepare-landing-sequence.md - https://openplanr.dev/docs/prompts/ready-to-land.md --- # Choose the next version number Decide major, minor, or patch from what changed for users, not from the size of the diff. ## Prompt Claude Code: ```text /release Choose the next version for this CLI and explain whether it is a major, minor, or patch release. ``` If /release runs another command, use /planr:release. Codex: ```text $release Choose the next version for this CLI and explain whether it is a major, minor, or patch release. ``` With the OpenPlanr plugin for Codex, use $planr:release. Cursor: ```text @planr-release Choose the next version for this CLI and explain whether it is a major, minor, or patch release. ``` Cursor applies the planr-release rule when you mention it in chat. Parts to fill in, shown with their example text: - The product: this CLI ## Why this works Release picks the bump from how each change affects users. A CLI or library that others install and pin follows SemVer strictly, and the chosen scheme goes into a release profile so later releases follow it instead of deciding again. ## Make it stick [OpenPlanr Release](https://openplanr.dev/docs/skills/release.md) --- title: Compare 3 design directions description: See 3 materially different directions side by side, rate them, and develop the one you pick. url: https://openplanr.dev/docs/prompts/compare-design-directions updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/apply-pinned-feedback.md - https://openplanr.dev/docs/prompts/design-before-build.md - https://openplanr.dev/docs/prompts/plan-ui-from-design.md --- # Compare 3 design directions See 3 materially different directions side by side, rate them, and develop the one you pick. ## Prompt Claude Code: ```text /design-loop Compare 3 directions for the dashboard home on desktop and phone. ``` If /design-loop runs another command, use /planr:design-loop. Codex: ```text $design-loop Compare 3 directions for the dashboard home on desktop and phone. ``` With the OpenPlanr plugin for Codex, use $planr:design-loop. Cursor: ```text @planr-design-loop Compare 3 directions for the dashboard home on desktop and phone. ``` Cursor applies the planr-design-loop rule when you mention it in chat. Parts to fill in, shown with their example text: - The screens: the dashboard home on desktop and phone ## Why this works Design Loop builds 3 materially different directions for the same journey in a live review studio. You pin and rate them on the board, and it develops the direction you select. Until you select one, it reports the comparison as awaiting selection. ## Make it stick [Design before you build](https://openplanr.dev/docs/guides/design.md) --- title: Diagnose a failure without changing code description: Get the root cause and the evidence for it, with no edits until you decide on a fix. url: https://openplanr.dev/docs/prompts/diagnose-without-fixing updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/investigate-first.md - https://openplanr.dev/docs/prompts/track-down-a-flaky-test.md - https://openplanr.dev/docs/prompts/diagnose-setup.md --- # Diagnose a failure without changing code Get the root cause and the evidence for it, with no edits until you decide on a fix. ## Prompt Claude Code: ```text /investigate Why does checkout fail for carts with a discount code? Find the cause, but don't change any code yet. ``` If /investigate runs another command, use /planr:investigate. Codex: ```text $investigate Why does checkout fail for carts with a discount code? Find the cause, but don't change any code yet. ``` With the OpenPlanr plugin for Codex, use $planr:investigate. Cursor: ```text @planr-investigate Why does checkout fail for carts with a discount code? Find the cause, but don't change any code yet. ``` Cursor applies the planr-investigate rule when you mention it in chat. Parts to fill in, shown with their example text: - The failure: checkout fail for carts with a discount code ## Why this works Without a request to fix, Investigate stays diagnostic. It reports the established cause or the strongest remaining hypotheses, the checks it ran, and what is still uncertain. ## Make it stick [OpenPlanr Investigate](https://openplanr.dev/docs/skills/investigate.md) --- title: Draw the request flow as a diagram description: Get SVG, PNG, and an accessible HTML version from one canonical document. url: https://openplanr.dev/docs/prompts/diagram-the-flow updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/write-release-notes.md --- # Draw the request flow as a diagram Get SVG, PNG, and an accessible HTML version from one canonical document. ## Prompt Claude Code: ```text /diagram the request flow from the web app to the API and the queue as an architecture diagram ``` If /diagram runs another command, use /planr:diagram. Codex: ```text $diagram the request flow from the web app to the API and the queue as an architecture diagram ``` With the OpenPlanr plugin for Codex, use $planr:diagram. Cursor: ```text @planr-diagram the request flow from the web app to the API and the queue as an architecture diagram ``` Cursor applies the planr-diagram rule when you mention it in chat. Parts to fill in, shown with their example text: - What to draw: the request flow from the web app to the API and the queue ## Why this works Name the kind of diagram you want. The skill turns your description into one canonical document, and the offline engine lays it out and renders SVG, PNG, and accessible HTML from it, with a manifest that binds the set. ## Make it stick [OpenPlanr Diagram](https://openplanr.dev/docs/skills/diagram.md) --- title: Find out why a skill is missing description: Diagnose the OpenPlanr installation and preview any repair before it touches a file. url: https://openplanr.dev/docs/prompts/diagnose-setup updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/diagnose-without-fixing.md - https://openplanr.dev/docs/prompts/investigate-first.md - https://openplanr.dev/docs/prompts/ship-a-direct-fix.md --- # Find out why a skill is missing Diagnose the OpenPlanr installation and preview any repair before it touches a file. ## Prompt Claude Code: ```text /planr:doctor The spec skill does not show up after setup. Find the cause and preview any repair before applying it. ``` Codex: ```text $doctor The spec skill does not show up after setup. Find the cause and preview any repair before applying it. ``` With the OpenPlanr plugin for Codex, use $planr:doctor. Cursor: ```text @planr-doctor The spec skill does not show up after setup. Find the cause and preview any repair before applying it. ``` Cursor applies the planr-doctor rule when you mention it in chat. Parts to fill in, shown with their example text: - What looks wrong: The spec skill does not show up after setup ## Why this works Doctor checks the CLI, the pipeline, the agent adapters, the installation, and the lock, and previews every repair. Installing packages, changing versions, and deleting files always wait for your confirmation. ## Make it stick [Troubleshooting](https://openplanr.dev/docs/get-started/troubleshooting.md) --- title: Find the root cause before you fix it description: Reproduce the defect, establish why it happens, then apply a bounded fix. url: https://openplanr.dev/docs/prompts/investigate-first updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/diagnose-without-fixing.md - https://openplanr.dev/docs/prompts/track-down-a-flaky-test.md - https://openplanr.dev/docs/prompts/diagnose-setup.md --- # Find the root cause before you fix it Reproduce the defect, establish why it happens, then apply a bounded fix. ## Prompt Claude Code: ```text /investigate sign-in links expire after 30 seconds instead of 15 minutes. Reproduce it first, then fix it with a test. ``` If /investigate runs another command, use /planr:investigate. Codex: ```text $investigate sign-in links expire after 30 seconds instead of 15 minutes. Reproduce it first, then fix it with a test. ``` With the OpenPlanr plugin for Codex, use $planr:investigate. Cursor: ```text @planr-investigate sign-in links expire after 30 seconds instead of 15 minutes. Reproduce it first, then fix it with a test. ``` Cursor applies the planr-investigate rule when you mention it in chat. Parts to fill in, shown with their example text: - The bug you see: sign-in links expire after 30 seconds instead of 15 minutes ## Why this works Investigate starts from the smallest reproducible case and tests competing causes before it names one. It changes code only when you ask for a fix, and then runs focused regression checks. ## Make it stick [OpenPlanr Investigate](https://openplanr.dev/docs/skills/investigate.md) --- title: Find what is blocked and why description: List blocked work, the dependency behind each block, and the most useful next step. url: https://openplanr.dev/docs/prompts/find-what-is-blocked updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/status-check.md - https://openplanr.dev/docs/prompts/open-the-dashboard.md - https://openplanr.dev/docs/prompts/route-a-mixed-request.md --- # Find what is blocked and why List blocked work, the dependency behind each block, and the most useful next step. ## Prompt Claude Code: ```text /planr:status SPEC-001. What is blocked, what is it waiting on, and what should happen next? ``` Codex: ```text $status SPEC-001. What is blocked, what is it waiting on, and what should happen next? ``` With the OpenPlanr plugin for Codex, use $planr:status. Cursor: ```text @planr-status SPEC-001. What is blocked, what is it waiting on, and what should happen next? ``` Cursor applies the planr-status rule when you mention it in chat. Parts to fill in, shown with their example text: - The spec or feature: SPEC-001 ## Why this works Status reports counts, ready and blocked work, dependency problems, and the most useful next action, for the whole project or one feature. It reads local files by default and queries GitHub or Linear only when you ask for live remote state. ## Make it stick [Plans are files](https://openplanr.dev/docs/get-started/plans-are-files.md) --- title: Get the technology and delivery-risk view description: One CTO lens on architecture, security, reliability, and delivery risk in an Operate cycle. url: https://openplanr.dev/docs/prompts/technology-risk-review updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/challenge-the-operating-review.md - https://openplanr.dev/docs/prompts/operate-review.md - https://openplanr.dev/docs/prompts/turn-findings-into-decisions.md --- # Get the technology and delivery-risk view One CTO lens on architecture, security, reliability, and delivery risk in an Operate cycle. ## Prompt Claude Code: ```text /cto-review Review technology and delivery risk in the current operating review, focusing on the payments migration. ``` If /cto-review runs another command, use /planr:cto-review. Codex: ```text $cto-review Review technology and delivery risk in the current operating review, focusing on the payments migration. ``` With the OpenPlanr plugin for Codex, use $planr:cto-review. Cursor: ```text @planr-cto-review Review technology and delivery risk in the current operating review, focusing on the payments migration. ``` Cursor applies the planr-cto-review rule when you mention it in chat. Parts to fill in, shown with their example text: - The Operate cycle: the current operating review - The area to focus on: the payments migration ## Why this works The CTO lens is read-only. Each risk it raises names likelihood, impact, exposure, and reversibility, and keeps observed failures apart from inferred future risk. It does not present architectural preference or generic technical debt as business risk. ## Make it stick [Track delivery and run operating reviews](https://openplanr.dev/docs/guides/operate.md) --- title: Hand a task to another coding agent description: Let a second agent build the task while your current agent reviews and verifies the result. url: https://openplanr.dev/docs/prompts/delegate-to-another-agent updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/ship-a-direct-fix.md - https://openplanr.dev/docs/prompts/ship-one-task.md - https://openplanr.dev/docs/prompts/ship-within-preserve.md --- # Hand a task to another coding agent Let a second agent build the task while your current agent reviews and verifies the result. ## Prompt Claude Code: ```text /delegate Ask another coding agent to implement T-003, then review and verify its changes before you integrate them. ``` If /delegate runs another command, use /planr:delegate. Codex: ```text $delegate Ask another coding agent to implement T-003, then review and verify its changes before you integrate them. ``` With the OpenPlanr plugin for Codex, use $planr:delegate. Cursor: ```text @planr-delegate Ask another coding agent to implement T-003, then review and verify its changes before you integrate them. ``` Cursor applies the planr-delegate rule when you mention it in chat. Parts to fill in, shown with their example text: - The agent that builds it: another coding agent - The task: T-003 ## Why this works Delegate is for work you explicitly hand to another agent's CLI. That agent builds and tests in its own worktree; your current agent reviews the observed changes, runs its own checks, and applies accepted changes as an uncommitted diff. ## Make it stick [Delegate implementation through a native coding CLI](https://openplanr.dev/docs/guides/delegation.md) --- title: Not sure which skill? Ask the router description: Describe what you want and let the router pick the skill, say why, and start it. url: https://openplanr.dev/docs/prompts/route-a-mixed-request updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/find-what-is-blocked.md - https://openplanr.dev/docs/prompts/open-the-dashboard.md - https://openplanr.dev/docs/prompts/status-check.md --- # Not sure which skill? Ask the router Describe what you want and let the router pick the skill, say why, and start it. ## Prompt Claude Code: ```text /openplanr I have a rough feature idea and a release on Friday. Where do I start? ``` If /openplanr runs another command, use /planr:openplanr. Codex: ```text $openplanr I have a rough feature idea and a release on Friday. Where do I start? ``` With the OpenPlanr plugin for Codex, use $planr:openplanr. Cursor: ```text @planr-openplanr I have a rough feature idea and a release on Friday. Where do I start? ``` Cursor applies the planr-openplanr rule when you mention it in chat. Parts to fill in, shown with their example text: - Your request: I have a rough feature idea and a release on Friday. Where do I start? ## Why this works The router names the skill that owns your request and why, in one line, then invokes it. When a request spans several steps, it starts with the earliest in the order spec, plan, plan review, ship, land, release, and names the rest. ## Make it stick [OpenPlanr Router](https://openplanr.dev/docs/skills/openplanr.md) --- title: Pick the next sprint against the real code description: Refine the open backlog and select what fits capacity and the release cut. url: https://openplanr.dev/docs/prompts/pick-the-sprint updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/refine-the-backlog.md - https://openplanr.dev/docs/prompts/audit-plan-drift.md - https://openplanr.dev/docs/prompts/clarify-acceptance-criteria.md --- # Pick the next sprint against the real code Refine the open backlog and select what fits capacity and the release cut. ## Prompt Claude Code: ```text /sprint two weeks, two engineers, release cut on the 23rd ``` If /sprint runs another command, use /planr:sprint. Codex: ```text $sprint two weeks, two engineers, release cut on the 23rd ``` With the OpenPlanr plugin for Codex, use $planr:sprint. Cursor: ```text @planr-sprint two weeks, two engineers, release cut on the 23rd ``` Cursor applies the planr-sprint rule when you mention it in chat. Parts to fill in, shown with their example text: - Capacity and the release cut: two weeks, two engineers, release cut on the 23rd ## Why this works Sprint reads every open item against the code and the calendar, tests its picks, and fits the survivors to your capacity and the next cut. Putting capacity in the prompt saves a question: the skill asks only for what the repository cannot answer. ## Make it stick [Plan a feature](https://openplanr.dev/docs/guides/plan.md) --- title: Pin down acceptance criteria before planning description: Turn loose requirements into observable criteria with stable IDs before anyone plans the work. url: https://openplanr.dev/docs/prompts/clarify-acceptance-criteria updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/spec-from-idea.md - https://openplanr.dev/docs/prompts/audit-plan-drift.md - https://openplanr.dev/docs/prompts/pick-the-sprint.md --- # Pin down acceptance criteria before planning Turn loose requirements into observable criteria with stable IDs before anyone plans the work. ## Prompt Claude Code: ```text /spec Clarify the requirements and acceptance criteria for team invitations by email before we plan it. ``` If /spec runs another command, use /planr:spec. Codex: ```text $spec Clarify the requirements and acceptance criteria for team invitations by email before we plan it. ``` With the OpenPlanr plugin for Codex, use $planr:spec. Cursor: ```text @planr-spec Clarify the requirements and acceptance criteria for team invitations by email before we plan it. ``` Cursor applies the planr-spec rule when you mention it in chat. Parts to fill in, shown with their example text: - The feature: team invitations by email ## Why this works Spec writes requirements and acceptance criteria that can be observed, each criterion with a stable AC-NNN ID. Plan later maps every ID to a task and to a check in that task's test requirements. ## Make it stick [Write your first spec](https://openplanr.dev/docs/get-started/first-spec.md) --- title: Plan straight from a clear request description: When the request is already clear, skip the spec and get stories and tasks from it. url: https://openplanr.dev/docs/prompts/plan-from-intent updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/plan-a-spec.md - https://openplanr.dev/docs/prompts/plan-ui-from-design.md - https://openplanr.dev/docs/prompts/audit-plan-drift.md --- # Plan straight from a clear request When the request is already clear, skip the spec and get stories and tasks from it. ## Prompt Claude Code: ```text /planr:plan Create an implementation plan for a CSV export button on the monthly report page. ``` Codex: ```text $plan Create an implementation plan for a CSV export button on the monthly report page. ``` With the OpenPlanr plugin for Codex, use $planr:plan. Cursor: ```text @planr-plan Create an implementation plan for a CSV export button on the monthly report page. ``` Cursor applies the planr-plan rule when you mention it in chat. Parts to fill in, shown with their example text: - The request: a CSV export button on the monthly report page ## Why this works Plan accepts a specification or a clear product request. Start with Spec when the scope is still vague; when it is already clear, Plan reads the repository and writes the stories and tasks directly. ## Make it stick [Plan a feature](https://openplanr.dev/docs/guides/plan.md) --- title: Plan UI work from a finished design description: Turn a design and its design spec into UI tasks that carry the screens, states, and frames. url: https://openplanr.dev/docs/prompts/plan-ui-from-design updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/plan-a-spec.md - https://openplanr.dev/docs/prompts/plan-from-intent.md - https://openplanr.dev/docs/prompts/apply-pinned-feedback.md --- # Plan UI work from a finished design Turn a design and its design spec into UI tasks that carry the screens, states, and frames. ## Prompt Claude Code: ```text /planr:plan SPEC-001. Use the selected design direction and its design spec for the UI tasks. ``` Codex: ```text $plan SPEC-001. Use the selected design direction and its design spec for the UI tasks. ``` With the OpenPlanr plugin for Codex, use $planr:plan. Cursor: ```text @planr-plan SPEC-001. Use the selected design direction and its design spec for the UI tasks. ``` Cursor applies the planr-plan rule when you mention it in chat. Parts to fill in, shown with their example text: - The spec with a design: SPEC-001 ## Why this works Plan reads the design document, the selected direction, and the 10-section design spec, and checks that they describe the same direction before it splits the UI work. Screen IDs, component recipes, responsive frames, and flows become task context. ## Make it stick [Design before you build](https://openplanr.dev/docs/guides/design.md) --- title: Prepare the merge and deploy steps description: Get the ordered landing commands, their preconditions, and the recovery step for the first failure. url: https://openplanr.dev/docs/prompts/prepare-landing-sequence updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/ready-to-land.md - https://openplanr.dev/docs/prompts/choose-next-version.md - https://openplanr.dev/docs/prompts/review-plan-rollback.md --- # Prepare the merge and deploy steps Get the ordered landing commands, their preconditions, and the recovery step for the first failure. ## Prompt Claude Code: ```text /land Prepare the landing sequence for the billing changes on this branch, with the recovery step if the deploy fails. ``` If /land runs another command, use /planr:land. Codex: ```text $land Prepare the landing sequence for the billing changes on this branch, with the recovery step if the deploy fails. ``` With the OpenPlanr plugin for Codex, use $planr:land. Cursor: ```text @planr-land Prepare the landing sequence for the billing changes on this branch, with the recovery step if the deploy fails. ``` Cursor applies the planr-land rule when you mention it in chat. Parts to fill in, shown with their example text: - The work to land: the billing changes on this branch ## Why this works Land returns readiness, blockers, the ordered landing sequence with its preconditions, recovery guidance for the first meaningful failure, and one next action. The commands are prepared for you to run, not run by the skill. ## Make it stick [Review before it lands](https://openplanr.dev/docs/guides/review.md) --- title: Refine the backlog without picking a sprint description: Sort open items into stale, blocked, and ready against the current code, with no sprint yet. url: https://openplanr.dev/docs/prompts/refine-the-backlog updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/pick-the-sprint.md - https://openplanr.dev/docs/prompts/audit-plan-drift.md - https://openplanr.dev/docs/prompts/clarify-acceptance-criteria.md --- # Refine the backlog without picking a sprint Sort open items into stale, blocked, and ready against the current code, with no sprint yet. ## Prompt Claude Code: ```text /sprint Refine the open backlog only: mark what is stale, blocked, or ready, and don't create a sprint yet. ``` If /sprint runs another command, use /planr:sprint. Codex: ```text $sprint Refine the open backlog only: mark what is stale, blocked, or ready, and don't create a sprint yet. ``` With the OpenPlanr plugin for Codex, use $planr:sprint. Cursor: ```text @planr-sprint Refine the open backlog only: mark what is stale, blocked, or ready, and don't create a sprint yet. ``` Cursor applies the planr-sprint rule when you mention it in chat. ## Why this works Sprint reads each open item in full and checks the code it names before believing its claim. A refine-only run writes the refinement note without creating a sprint, and any run can be repeated and compared with the last one. ## Make it stick [Plan a feature](https://openplanr.dev/docs/guides/plan.md) --- title: Review a plan before anyone builds it description: Catch product, engineering, design, and developer-experience problems before implementation starts. url: https://openplanr.dev/docs/prompts/review-the-plan updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/review-plan-developer-experience.md - https://openplanr.dev/docs/prompts/review-plan-rollback.md - https://openplanr.dev/docs/prompts/audit-plan-drift.md --- # Review a plan before anyone builds it Catch product, engineering, design, and developer-experience problems before implementation starts. ## Prompt Claude Code: ```text /plan-review SPEC-001 ``` If /plan-review runs another command, use /planr:plan-review. Codex: ```text $plan-review SPEC-001 ``` With the OpenPlanr plugin for Codex, use $planr:plan-review. Cursor: ```text @planr-plan-review SPEC-001 ``` Cursor applies the planr-plan-review rule when you mention it in chat. Parts to fill in, shown with their example text: - The plan to review: SPEC-001 ## Why this works Plan Review runs after Plan and before Ship. It returns one verdict (ready, ready with improvements, or needs revision) and, for each material issue, names the plan section and the change that would fix it. ## Make it stick [Review before it lands](https://openplanr.dev/docs/guides/review.md) --- title: Review an HTML prototype with pinned comments description: Open a local HTML file for review with comments, pins, threads, and an approve or request-changes decision. url: https://openplanr.dev/docs/prompts/review-an-html-artifact updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/apply-pinned-feedback.md - https://openplanr.dev/docs/prompts/audit-plan-drift.md - https://openplanr.dev/docs/prompts/browser-qa-flow.md --- # Review an HTML prototype with pinned comments Open a local HTML file for review with comments, pins, threads, and an approve or request-changes decision. ## Prompt Claude Code: ```text /artifact Open ./prototype.html for review so I can pin comments on it. ``` If /artifact runs another command, use /planr:artifact. Codex: ```text $artifact Open ./prototype.html for review so I can pin comments on it. ``` With the OpenPlanr plugin for Codex, use $planr:artifact. Cursor: ```text @planr-artifact Open ./prototype.html for review so I can pin comments on it. ``` Cursor applies the planr-artifact rule when you mention it in chat. Parts to fill in, shown with their example text: - The HTML file: ./prototype.html ## Why this works The artifact is bundled into immutable bytes and runs in a sandboxed, network-blocked frame, so its scripts stay interactive without running as part of the review page. You can export the feedback as Markdown. ## Make it stick [Artifact review and private sharing](https://openplanr.dev/docs/guides/artifact-review.md) --- title: Run a monthly operating review description: 7 executive lenses, one decision and action brief. url: https://openplanr.dev/docs/prompts/operate-review updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/challenge-the-operating-review.md - https://openplanr.dev/docs/prompts/technology-risk-review.md - https://openplanr.dev/docs/prompts/turn-findings-into-decisions.md --- # Run a monthly operating review 7 executive lenses, one decision and action brief. ## Prompt Claude Code: ```text /operate activation, runway, and delivery risk this month ``` If /operate runs another command, use /planr:operate. Codex: ```text $operate activation, runway, and delivery risk this month ``` With the OpenPlanr plugin for Codex, use $planr:operate. Cursor: ```text @planr-operate activation, runway, and delivery risk this month ``` Cursor applies the planr-operate rule when you mention it in chat. Parts to fill in, shown with their example text: - What the review should cover: activation, runway, and delivery risk this month ## Why this works Operate builds one shared brief, runs the strategy, technology, product, growth, and operations reviews, has a challenger test the material claims, and ends with a board report: a prioritized decision queue and an action plan. ## Make it stick [Track delivery and run operating reviews](https://openplanr.dev/docs/guides/operate.md) --- title: See the plan on a local board description: Start the local planning dashboard for this repository and open it in your browser. url: https://openplanr.dev/docs/prompts/open-the-dashboard updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/find-what-is-blocked.md - https://openplanr.dev/docs/prompts/route-a-mixed-request.md - https://openplanr.dev/docs/prompts/status-check.md --- # See the plan on a local board Start the local planning dashboard for this repository and open it in your browser. ## Prompt Claude Code: ```text /dashboard Start the dashboard for this repository and open it in my browser. ``` If /dashboard runs another command, use /planr:dashboard. Codex: ```text $dashboard Start the dashboard for this repository and open it in my browser. ``` With the OpenPlanr plugin for Codex, use $planr:dashboard. Cursor: ```text @planr-dashboard Start the dashboard for this repository and open it in my browser. ``` Cursor applies the planr-dashboard rule when you mention it in chat. ## Why this works The dashboard binds only to your machine's loopback address and reuses a compatible server that is already running. It opens a browser only when you ask, which is why the prompt says so. ## Make it stick [OpenPlanr Dashboard](https://openplanr.dev/docs/skills/dashboard.md) --- title: Ship a small fix without a plan description: For a clear, local change, ask Ship directly; missing planning files do not block it. url: https://openplanr.dev/docs/prompts/ship-a-direct-fix updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/ship-one-task.md - https://openplanr.dev/docs/prompts/ship-within-preserve.md - https://openplanr.dev/docs/prompts/delegate-to-another-agent.md --- # Ship a small fix without a plan For a clear, local change, ask Ship directly; missing planning files do not block it. ## Prompt Claude Code: ```text /ship Fix the invoice date so it uses the account's locale ``` If /ship runs another command, use /planr:ship. Codex: ```text $ship Fix the invoice date so it uses the account's locale ``` With the OpenPlanr plugin for Codex, use $planr:ship. Cursor: ```text @planr-ship Fix the invoice date so it uses the account's locale ``` Cursor applies the planr-ship rule when you mention it in chat. Parts to fill in, shown with their example text: - The change: Fix the invoice date so it uses the account's locale ## Why this works Ship works from a task or from a clearly stated request. For a direct request, the request plus the repository is enough context, and it still finds and runs the repository's checks before it reports. ## Make it stick [Build one task at a time](https://openplanr.dev/docs/guides/build.md) --- title: Ship a task without touching protected files description: Build the task while every file on its Preserve list stays unchanged. url: https://openplanr.dev/docs/prompts/ship-within-preserve updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/ship-a-direct-fix.md - https://openplanr.dev/docs/prompts/ship-one-task.md - https://openplanr.dev/docs/prompts/delegate-to-another-agent.md --- # Ship a task without touching protected files Build the task while every file on its Preserve list stays unchanged. ## Prompt Claude Code: ```text /ship T-002. Leave every file on its Preserve list unchanged. ``` If /ship runs another command, use /planr:ship. Codex: ```text $ship T-002. Leave every file on its Preserve list unchanged. ``` With the OpenPlanr plugin for Codex, use $planr:ship. Cursor: ```text @planr-ship T-002. Leave every file on its Preserve list unchanged. ``` Cursor applies the planr-ship rule when you mention it in chat. Parts to fill in, shown with their example text: - The task to build: T-002 ## Why this works Every task lists files to create, files to modify, and files to preserve. Ship treats Create and Modify as the expected surface, adds companion files when correctness needs them, and leaves Preserve entries unchanged. ## Make it stick [Build one task at a time](https://openplanr.dev/docs/guides/build.md) --- title: Stress-test an operating review description: Have the challenger test the review's claims, alternatives, downside, and confidence. url: https://openplanr.dev/docs/prompts/challenge-the-operating-review updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/operate-review.md - https://openplanr.dev/docs/prompts/technology-risk-review.md - https://openplanr.dev/docs/prompts/turn-findings-into-decisions.md --- # Stress-test an operating review Have the challenger test the review's claims, alternatives, downside, and confidence. ## Prompt Claude Code: ```text /challenger-review Challenge the claims, alternatives, and downside in this month's operating review. ``` If /challenger-review runs another command, use /planr:challenger-review. Codex: ```text $challenger-review Challenge the claims, alternatives, and downside in this month's operating review. ``` With the OpenPlanr plugin for Codex, use $planr:challenger-review. Cursor: ```text @planr-challenger-review Challenge the claims, alternatives, and downside in this month's operating review. ``` Cursor applies the planr-challenger-review rule when you mention it in chat. Parts to fill in, shown with their example text: - The Operate cycle: this month's operating review ## Why this works The challenger tests only claims that could change a decision: unsupported claims, a weak assumption repeated by several advisors, a missing alternative, or downside nobody named. It does not invent objections to look busy. ## Make it stick [Track delivery and run operating reviews](https://openplanr.dev/docs/guides/operate.md) --- title: Test the change in a real browser description: Check routes, forms, phone sizes, accessibility, console, and network behavior. url: https://openplanr.dev/docs/prompts/browser-qa-flow updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/check-page-accessibility.md - https://openplanr.dev/docs/prompts/apply-pinned-feedback.md - https://openplanr.dev/docs/prompts/audit-plan-drift.md --- # Test the change in a real browser Check routes, forms, phone sizes, accessibility, console, and network behavior. ## Prompt Claude Code: ```text /browser-qa the sign-in flow on /login at phone and desktop sizes, including the expired-link error ``` If /browser-qa runs another command, use /planr:browser-qa. Codex: ```text $browser-qa the sign-in flow on /login at phone and desktop sizes, including the expired-link error ``` With the OpenPlanr plugin for Codex, use $planr:browser-qa. Cursor: ```text @planr-browser-qa the sign-in flow on /login at phone and desktop sizes, including the expired-link error ``` Cursor applies the planr-browser-qa rule when you mention it in chat. Parts to fill in, shown with their example text: - The flow to test: the sign-in flow on /login - The failure case to cover: the expired-link error ## Why this works Give the route, the sizes, and the failure case. Browser QA starts or reuses your local app, exercises the flow in a real browser, and reports what it covered. It reports findings instead of fixing them, so rerun it after the fix. ## Make it stick [Review before it lands](https://openplanr.dev/docs/guides/review.md) --- title: Track down a flaky test description: Find out why a test fails some of the time before anyone changes the test. url: https://openplanr.dev/docs/prompts/track-down-a-flaky-test updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/diagnose-without-fixing.md - https://openplanr.dev/docs/prompts/investigate-first.md - https://openplanr.dev/docs/prompts/browser-qa-flow.md --- # Track down a flaky test Find out why a test fails some of the time before anyone changes the test. ## Prompt Claude Code: ```text /investigate The checkout total test fails about one run in ten in CI. Find the cause before changing the test. ``` If /investigate runs another command, use /planr:investigate. Codex: ```text $investigate The checkout total test fails about one run in ten in CI. Find the cause before changing the test. ``` With the OpenPlanr plugin for Codex, use $planr:investigate. Cursor: ```text @planr-investigate The checkout total test fails about one run in ten in CI. Find the cause before changing the test. ``` Cursor applies the planr-investigate rule when you mention it in chat. Parts to fill in, shown with their example text: - The flaky test: The checkout total test - How it fails: fails about one run in ten in CI ## Why this works Investigate traces the call path, state, configuration, and recent changes, then runs the cheapest checks that tell competing causes apart. Asking for the cause first keeps the fix on the code instead of on the test. ## Make it stick [OpenPlanr Investigate](https://openplanr.dev/docs/skills/investigate.md) --- title: Turn review findings into decisions description: Synthesize an operating review into a prioritized decision queue and an action plan. url: https://openplanr.dev/docs/prompts/turn-findings-into-decisions updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/challenge-the-operating-review.md - https://openplanr.dev/docs/prompts/operate-review.md - https://openplanr.dev/docs/prompts/technology-risk-review.md --- # Turn review findings into decisions Synthesize an operating review into a prioritized decision queue and an action plan. ## Prompt Claude Code: ```text /chair-review Turn the findings in this month's operating review into a prioritized decision queue and actions. ``` If /chair-review runs another command, use /planr:chair-review. Codex: ```text $chair-review Turn the findings in this month's operating review into a prioritized decision queue and actions. ``` With the OpenPlanr plugin for Codex, use $planr:chair-review. Cursor: ```text @planr-chair-review Turn the findings in this month's operating review into a prioritized decision queue and actions. ``` Cursor applies the planr-chair-review rule when you mention it in chat. Parts to fill in, shown with their example text: - The Operate cycle: this month's operating review ## Why this works The chair reads the advisor and challenger notes, ranks each decision P0, P1, P2, or unranked, and gives every action a first step, an expected result, a check, and a condition to revisit it. It suggests an owner only when the notes support one. ## Make it stick [Track delivery and run operating reviews](https://openplanr.dev/docs/guides/operate.md) --- title: Write release notes users can read description: Turn what shipped into user-facing notes and an updated changelog that does not read like a git log. url: https://openplanr.dev/docs/prompts/write-release-notes updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/choose-next-version.md - https://openplanr.dev/docs/prompts/diagram-the-flow.md - https://openplanr.dev/docs/prompts/prepare-landing-sequence.md --- # Write release notes users can read Turn what shipped into user-facing notes and an updated changelog that does not read like a git log. ## Prompt Claude Code: ```text /release Write user-facing release notes for everything since the last tag and update the changelog. ``` If /release runs another command, use /planr:release. Codex: ```text $release Write user-facing release notes for everything since the last tag and update the changelog. ``` With the OpenPlanr plugin for Codex, use $planr:release. Cursor: ```text @planr-release Write user-facing release notes for everything since the last tag and update the changelog. ``` Cursor applies the planr-release rule when you mention it in chat. Parts to fill in, shown with their example text: - The release window: everything since the last tag ## Why this works Release classifies each change by one question: does a user have to do, know, or expect something different now? The notes lead with what users can do, describe fixes by the symptom users saw, and leave internal work out. ## Make it stick [OpenPlanr Release](https://openplanr.dev/docs/skills/release.md) --- title: Commit the planning folder with your code description: Keep specs, stories, and tasks in the same commits as the code they describe, so every session and teammate reads the same plan. url: https://openplanr.dev/docs/tips/commit-the-planning-folder updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/audit-plan-drift.md - https://openplanr.dev/docs/prompts/clarify-acceptance-criteria.md - https://openplanr.dev/docs/prompts/pick-the-sprint.md --- # Commit the planning folder with your code Keep specs, stories, and tasks in the same commits as the code they describe, so every session and teammate reads the same plan. The planning folder, `.planr/`, is meant to be committed. Specifications, user stories, tasks, and provenance live there, reviewed and versioned like code. When the plan changes in the same pull request as the code, a reviewer sees both: what the task asked for and what the change did. The next session, the next teammate, and the next agent start from the version of the plan that matches the code they check out. To stop using the planning files in a project, delete the folder by hand. --- title: Keep the CLI installed next to the plugin description: Several skills call the openplanr CLI for deterministic work, so keep it installed even when your agent's plugin is in place. url: https://openplanr.dev/docs/tips/keep-the-cli-installed updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/delegate-to-another-agent.md - https://openplanr.dev/docs/prompts/ship-a-direct-fix.md - https://openplanr.dev/docs/prompts/ship-one-task.md --- # Keep the CLI installed next to the plugin Several skills call the openplanr CLI for deterministic work, so keep it installed even when your agent's plugin is in place. The skills reason inside your coding agent, and several of them call the `openplanr` CLI for deterministic work. The diagram skill may call `openplanr diagram` to render and check diagrams, Land may call `openplanr land`, and Doctor runs `openplanr doctor`. Keep the CLI installed even if you added the plugin to Claude Code yourself instead of through setup. The CLI never calls a model: it validates what the agent wrote, renders it, and keeps trackers in step. --- title: Let your agent see every skill description: Generate the OpenPlanr capabilities guidance so your agent knows every skill and when to reach for it. url: https://openplanr.dev/docs/tips/let-your-agent-see-every-skill updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/route-a-mixed-request.md - https://openplanr.dev/docs/prompts/find-what-is-blocked.md - https://openplanr.dev/docs/prompts/open-the-dashboard.md --- # Let your agent see every skill Generate the OpenPlanr capabilities guidance so your agent knows every skill and when to reach for it. Your agent picks a skill from its description, so it helps when the agent can see every skill and its triggers. Generate the guidance once in each repository: ```bash openplanr rules generate --target all ``` This adds an `## OpenPlanr capabilities` section to `CLAUDE.md` for Claude Code and to `AGENTS.md` for Codex, between managed markers, and writes `.mdc` rule files under `.cursor/rules/` for Cursor. Your own content outside the markers is left alone. When the right skill is still unclear, ask the router. `/openplanr` (Claude Code), `$openplanr` (Codex) or `@planr-openplanr` (Cursor) names the skill that owns your request, says why, and starts it. --- title: Name the files a task must not touch description: Put protected files on a task's Preserve list, and Ship leaves them unchanged while it builds the task. url: https://openplanr.dev/docs/tips/name-files-to-preserve updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/ship-a-direct-fix.md - https://openplanr.dev/docs/prompts/ship-one-task.md - https://openplanr.dev/docs/prompts/ship-within-preserve.md --- # Name the files a task must not touch Put protected files on a task's Preserve list, and Ship leaves them unchanged while it builds the task. Every task has 3 file lists: Create, Modify, and Preserve. Create and Modify tell `/ship` (Claude Code), `$ship` (Codex) or `@planr-ship` (Cursor) where the change should land. Preserve names the files it must leave alone, such as a generated file, a vendored dependency, or a contract another team owns. Ship treats Create and Modify as the expected surface, not a fence, and adds companion files, such as a test, when correctness needs them. Preserve entries stay unchanged, and so do unrelated changes already in your working tree. When a review keeps flagging the same file, add it to the Preserve list of the tasks that come near it. --- title: Skills add no model calls or telemetry description: Every skill runs inside the coding agent you already use, and the CLI never calls a model. url: https://openplanr.dev/docs/tips/no-model-calls updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/find-what-is-blocked.md - https://openplanr.dev/docs/prompts/open-the-dashboard.md - https://openplanr.dev/docs/prompts/route-a-mixed-request.md --- # Skills add no model calls or telemetry Every skill runs inside the coding agent you already use, and the CLI never calls a model. OpenPlanr is not a second model. Every skill runs inside the coding agent you already use. Skills and the openplanr CLI add no model calls or telemetry; the optional design engine calls OpenAI only when you select its OpenAI provider and supply your own key. The CLI never calls a model. It validates what the agent wrote, renders it, and keeps trackers in step. If a skill ever asks you for an API key or runs a planning command, it is an old version: run setup again, restart the agent, and check `openplanr upgrade status`. --- title: Plan and ship are separate steps description: Your agent never chains planning into building on its own, so you can review the plan before any code changes. url: https://openplanr.dev/docs/tips/plan-and-ship-are-separate updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/plan-a-spec.md - https://openplanr.dev/docs/prompts/plan-from-intent.md - https://openplanr.dev/docs/prompts/plan-ui-from-design.md --- # Plan and ship are separate steps Your agent never chains planning into building on its own, so you can review the plan before any code changes. `/planr:plan` (Claude Code), `$plan` (Codex) or `@planr-plan` (Cursor) ends with a handoff: it names the next ready task and gives you the exact command to build it. It never starts building on its own, and the router never chains the two on your behalf. That pause is the point. Read the stories and tasks, fix what is wrong, and commit them. Then start the build with `/ship` (Claude Code), `$ship` (Codex) or `@planr-ship` (Cursor) and one task ID. --- title: Restart your agent after setup description: Your coding agent loads its skills when it starts, so restart it after setup or a plugin update before you look for a skill. url: https://openplanr.dev/docs/tips/restart-after-setup updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/diagnose-setup.md - https://openplanr.dev/docs/prompts/diagnose-without-fixing.md - https://openplanr.dev/docs/prompts/investigate-first.md --- # Restart your agent after setup Your coding agent loads its skills when it starts, so restart it after setup or a plugin update before you look for a skill. Setup writes the skills, but your coding agent loads its skill list when it starts. Restart Claude Code, Codex, or Cursor after setup, and again after a plugin update, before you look for a skill. If a skill is still missing after the restart, run `openplanr doctor --json`. It lists every managed installation, so you can confirm that setup targeted the agent and the scope you expected. Doctor checks registration and the files OpenPlanr owns. It cannot tell whether an agent that is already open has reloaded its skills, which is why the restart comes first. --- title: Start with doctor when a skill misbehaves description: The doctor command shows every managed installation and what is unhealthy, and previews repairs before it changes anything. url: https://openplanr.dev/docs/tips/start-with-doctor updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/diagnose-setup.md - https://openplanr.dev/docs/prompts/diagnose-without-fixing.md - https://openplanr.dev/docs/prompts/investigate-first.md --- # Start with doctor when a skill misbehaves The doctor command shows every managed installation and what is unhealthy, and previews repairs before it changes anything. When a skill misbehaves, run `openplanr doctor --json` before you change anything. It checks the installation, the agent adapters, and the project, and lists every managed installation with what is unhealthy. `openplanr doctor --fix` previews repairs to the files OpenPlanr owns, then asks once before applying them. It keeps each agent's saved scope and Codex discovery choice, uses the plugin bundled with the running CLI, and does not upgrade the CLI or change credentials. A healthy second run makes no changes. In your agent, `/planr:doctor` (Claude Code), `$doctor` (Codex) or `@planr-doctor` (Cursor) runs the same diagnosis and previews every repair. Installing packages, changing versions, and deleting files always wait for your confirmation. --- title: Ask for status as often as you like description: Status reads the plan and changes nothing, so it is safe to run before every standup or handoff. url: https://openplanr.dev/docs/tips/status-changes-nothing updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/find-what-is-blocked.md - https://openplanr.dev/docs/prompts/status-check.md - https://openplanr.dev/docs/prompts/open-the-dashboard.md --- # Ask for status as often as you like Status reads the plan and changes nothing, so it is safe to run before every standup or handoff. `/planr:status` (Claude Code), `$status` (Codex) or `@planr-status` (Cursor) reads the planning files, task statuses, dependency graph, and current branch, then reports what is ready, blocked, and pending, plus the most useful next action. It does not repair files, start Plan or Ship, or change any status. It works from the files in your repository. It queries GitHub or Linear only when you ask for live remote state, and it says which data it inspected and how fresh it is. Name a spec to see one feature, or ask without one for the whole project. ## Prompt Claude Code: ```text /planr:status ``` Codex: ```text $status ``` With the OpenPlanr plugin for Codex, use $planr:status. Cursor: ```text @planr-status ``` Cursor applies the planr-status rule when you mention it in chat. --- title: You can undo setup description: Roll back to the state before setup, or remove one agent's OpenPlanr files, without losing files you changed. url: https://openplanr.dev/docs/tips/undo-setup updated: 2026-10-06 related: - https://openplanr.dev/docs/prompts/diagnose-setup.md - https://openplanr.dev/docs/prompts/diagnose-without-fixing.md - https://openplanr.dev/docs/prompts/investigate-first.md --- # You can undo setup Roll back to the state before setup, or remove one agent's OpenPlanr files, without losing files you changed. Setup backs up existing files byte for byte before it writes, and in those files it replaces only the marker blocks it manages. That makes it reversible: - `openplanr runtime rollback` restores the last pre-setup state for every managed agent. - `openplanr runtime remove claude` removes one agent's OpenPlanr files, as long as they still match what OpenPlanr wrote. Removal deletes only files OpenPlanr wrote and still recognizes. Modified or unknown files are reported and left in place, so your own edits survive. To remove the planning folder, `.planr/`, delete it by hand. --- title: openplanr init description: "openplanr init: Initialize deterministic OpenPlanr project storage. Usage and options including --name, --force." url: https://openplanr.dev/docs/cli/init updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/server.md - https://openplanr.dev/docs/cli/setup.md - https://openplanr.dev/docs/cli/doctor.md --- # openplanr init Initialize deterministic OpenPlanr project storage ```text openplanr init [options] ``` Options: - `--name <name>`: project name - `--force`: replace the existing project configuration --- title: openplanr server description: "openplanr server: Inspect and stop owned local Studio services. Subcommands: list, stop." url: https://openplanr.dev/docs/cli/server updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/init.md - https://openplanr.dev/docs/cli/setup.md - https://openplanr.dev/docs/cli/doctor.md --- # openplanr server Inspect and stop owned local Studio services ```text openplanr server [options] [command] ``` ## openplanr server list List local Studio instances ```text openplanr server list [options] ``` Options: - `--json`: machine-readable output ## openplanr server stop Drain saves and stop recorded local services by instance, port or project ```text openplanr server stop [options] [instance-or-port] ``` Arguments: - `instance-or-port` (optional) Options: - `--all`: stop all recorded owned local services - `--project <directory>`: stop only services recorded for this exact project - `--yes`: confirm an unfiltered --all shutdown - `--json`: machine-readable output --- title: openplanr setup description: "openplanr setup: Set up OpenPlanr skills for your coding agents. Usage and options including --runtime, --scope, --skill-mode." url: https://openplanr.dev/docs/cli/setup updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/init.md - https://openplanr.dev/docs/cli/server.md - https://openplanr.dev/docs/cli/doctor.md --- # openplanr setup Set up OpenPlanr skills for your coding agents ```text openplanr setup [options] ``` Options: - `--runtime <runtime>`: auto, claude, codex, cursor, or all - `--scope <scope>`: user, project, or both - `--skill-mode <mode>`: Codex skill delivery: direct, unified-plugin, or project-rule - `--replace-managed`: replace only manifest-owned OpenPlanr discovery content when switching modes; default `false` - `--minimal`: skip agent integrations; keep using the installed CLI; default `false` - `--version <version>`: pin the pipeline and adapter version - `--dry-run`: preview exact changes without writing; default `false` - `--yes`: apply without an interactive confirmation; default `false` - `--json`: emit machine-readable output; default `false` --- title: openplanr doctor description: "openplanr doctor: Diagnose OpenPlanr, pipeline, runtime adapter, and project health. Usage and options including --strict, --fix, --json." url: https://openplanr.dev/docs/cli/doctor updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/server.md - https://openplanr.dev/docs/cli/setup.md - https://openplanr.dev/docs/cli/runtime.md --- # openplanr doctor Diagnose OpenPlanr, pipeline, runtime adapter, and project health ```text openplanr doctor [options] ``` Options: - `--strict`: treat warnings as failures; default `false` - `--fix`: preview and repair managed integrations and stale daemon state; default `false` - `--json`: machine-readable output; default `false` - `--yes`: apply previewed managed integration and stale-daemon repairs without confirmation; default `false` --- title: openplanr runtime description: "openplanr runtime: Manage runtime adapters. Subcommands: detect, list, install, update, remove, rollback, doctor." url: https://openplanr.dev/docs/cli/runtime updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/setup.md - https://openplanr.dev/docs/cli/doctor.md - https://openplanr.dev/docs/cli/artifact.md --- # openplanr runtime Manage runtime adapters ```text openplanr runtime [options] [command] ``` ## openplanr runtime detect The CLI help has no description for this command yet. ```text openplanr runtime detect [options] ``` Options: - `--json`: machine-readable output; default `false` ## openplanr runtime list The CLI help has no description for this command yet. ```text openplanr runtime list [options] ``` Options: - `--json`: machine-readable output; default `false` ## openplanr runtime install The CLI help has no description for this command yet. ```text openplanr runtime install [options] <runtime> ``` Arguments: - `runtime` (required) Options: - `--scope <scope>`: user, project, or both; default `"both"` - `--version <version>`: adapter version - `--dry-run`: preview without writing; default `false` - `--yes`: apply without confirmation; default `false` - `--json`: machine-readable output; default `false` ## openplanr runtime update The CLI help has no description for this command yet. ```text openplanr runtime update [options] <runtime> ``` Arguments: - `runtime` (required) Options: - `--scope <scope>`: user, project, or both; default `"both"` - `--version <version>`: adapter version - `--dry-run`: preview without writing; default `false` - `--yes`: apply without confirmation; default `false` - `--json`: machine-readable output; default `false` ## openplanr runtime remove The CLI help has no description for this command yet. ```text openplanr runtime remove [options] <runtime> ``` Arguments: - `runtime` (required) Options: - `--yes`: remove without confirmation; default `false` - `--json`: machine-readable output; default `false` ## openplanr runtime rollback The CLI help has no description for this command yet. ```text openplanr runtime rollback [options] ``` Options: - `--backup <path>`: specific backup directory - `--yes`: restore without confirmation; default `false` - `--json`: machine-readable output; default `false` ## openplanr runtime doctor The CLI help has no description for this command yet. ```text openplanr runtime doctor [options] ``` Options: - `--json`: machine-readable output; default `false` --- title: openplanr artifact description: "openplanr artifact: Review, share, import, and export diagrams, designs, and HTML artifacts. Subcommands: open, handoff, share, publish, sync, import, export." url: https://openplanr.dev/docs/cli/artifact updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/doctor.md - https://openplanr.dev/docs/cli/runtime.md - https://openplanr.dev/docs/cli/dashboard.md --- # openplanr artifact Review, share, import, and export diagrams, designs, and HTML artifacts ```text openplanr artifact [options] [command] [file] ``` Arguments: - `file` (optional) Options: - `--title <title>`: review title - `--root <asset-root>`: root for local artifact dependencies - `--theme <theme>`: auto, light, or dark; default `"auto"` - `--presentation <presentation>`: auto, document, or canvas; default `"auto"` - `--port <port>`: loopback review port - `--no-open`: do not open a browser - `--json`: emit machine-readable output; default `false` ## openplanr artifact open Open a local diagram, design, or HTML review session ```text openplanr artifact open [options] <file> ``` Arguments: - `file` (required) Options: - `--title <title>`: review title - `--root <asset-root>`: root for local artifact dependencies - `--theme <theme>`: auto, light, or dark; default `"auto"` - `--presentation <presentation>`: auto, document, or canvas; default `"auto"` - `--port <port>`: loopback review port - `--no-open`: do not open a browser - `--json`: emit machine-readable output; default `false` ## openplanr artifact handoff Prepare a factual design review handoff for refinement and owner approval ```text openplanr artifact handoff [options] <file> ``` Arguments: - `file` (required) Options: - `--json`: emit machine-readable output; default `false` ## openplanr artifact share Share a native diagram, design, or generic HTML review ```text openplanr artifact share [options] <file> ``` Arguments: - `file` (required) Options: - `--title <title>`: review title - `--root <asset-root>`: root for local artifact dependencies - `--presentation <presentation>`: auto, document, or canvas; default `"auto"` - `--short`: create an encrypted expiring short link; default `false` - `--snapshot`: create an immutable snapshot instead of a live room; default `false` - `--ttl <ttl>`: generic artifact retention: 1d, 7d (default), or 30d - `--no-open`: do not open the review link - `--json`: emit machine-readable output; default `false` - `--yes`: confirm encrypted upload non-interactively; default `false` - `--secret-output <path>`: write capabilities to a new private 0600 file - `--resume <private-file>`: retry the exact saved generic encrypted paste operation ## openplanr artifact publish Publish a new revision to a shared diagram or design review ```text openplanr artifact publish [options] <file> ``` Arguments: - `file` (required) Options: - `--yes`: confirm encrypted publication non-interactively; default `false` - `--json`: emit machine-readable output; default `false` ## openplanr artifact sync Synchronize hosted diagram or design feedback ```text openplanr artifact sync [options] <file> ``` Arguments: - `file` (required) Options: - `--yes`: confirm encrypted publication non-interactively; default `false` - `--json`: emit machine-readable output; default `false` ## openplanr artifact import Import one or more live-room or immutable review links ```text openplanr artifact import [options] [review-url...] ``` Arguments: - `review-url...` (optional) Options: - `--secret-input <path|->`: read a private capability bundle from a 0600 file or stdin - `--output <path>`: also write the merged review state to this path - `--allow-stale`: preview and explicitly accept stale feedback; default `false` - `--json`: emit machine-readable output; default `false` - `--yes`: confirm stale import non-interactively; default `false` ## openplanr artifact export Export feedback from a live local review session ```text openplanr artifact export [options] <session-id> ``` Arguments: - `session-id` (required) Options: - `--format <format>`: json or markdown; default `"json"` - `--output <path>`: write the export to a file --- title: openplanr dashboard description: "openplanr dashboard: Serve the local Planning and Operate dashboard. Usage and options including --port, --no-watch, --json." url: https://openplanr.dev/docs/cli/dashboard updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/runtime.md - https://openplanr.dev/docs/cli/artifact.md - https://openplanr.dev/docs/cli/diagram.md --- # openplanr dashboard Serve the local Planning and Operate dashboard ```text openplanr dashboard [options] ``` Options: - `--port <port>`: loopback port; default `"7474"` - `--no-watch`: disable project file watching - `--json`: machine-readable output --- title: openplanr diagram description: "openplanr diagram: Create, verify, inspect, and rerender offline professional diagrams. Subcommands: new, edit, apply, render, inspect, check, gallery." url: https://openplanr.dev/docs/cli/diagram updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/artifact.md - https://openplanr.dev/docs/cli/dashboard.md - https://openplanr.dev/docs/cli/linear.md --- # openplanr diagram Create, verify, inspect, and rerender offline professional diagrams ```text openplanr diagram [options] [command] ``` ## openplanr diagram new Create a canonical editable diagram bundle ```text openplanr diagram new [options] <path> ``` Arguments: - `path` (required): canonical diagrams/{slug}/{slug}.planr-diagram-bundle.json path Options: - `--title <title>`: diagram title - `--json`: output one stable machine envelope ## openplanr diagram edit Open the local owner studio for an existing diagram ```text openplanr diagram edit [options] <path> ``` Arguments: - `path` (required): canonical diagram bundle path Options: - `--json`: output one stable machine envelope ## openplanr diagram apply Preview a scoped edit, then explicitly accept that preview ```text openplanr diagram apply [options] <path> ``` Arguments: - `path` (required): canonical diagram bundle path Options: - `--transaction <file>`: typed diagram-edit-transaction JSON - `--dry-run`: preview semantic and layout changes without applying - `--accept <preview-token>`: apply the exact previewed transaction - `--json`: output one stable machine envelope ## openplanr diagram render Render a verified offline diagram set ```text openplanr diagram render [options] <input> ``` Arguments: - `input` (required): canonical .planr-diagram.json or Mermaid source Options: - `--slug <slug>`: override the output slug - `--output <directory>`: output root; defaults to the repository root - `--json`: output one stable machine envelope ## openplanr diagram inspect Inspect source or generated manifest custody ```text openplanr diagram inspect [options] <input-or-manifest> ``` Arguments: - `input-or-manifest` (required): diagram source, manifest, or generated diagram directory Options: - `--json`: output one stable machine envelope ## openplanr diagram check Validate source or verify generated bytes against their manifest ```text openplanr diagram check [options] <input-or-manifest> ``` Arguments: - `input-or-manifest` (required): diagram source, manifest, or generated diagram directory Options: - `--json`: output one stable machine envelope ## openplanr diagram gallery List the searchable diagram grammar and primitive gallery ```text openplanr diagram gallery [options] ``` Options: - `--type <type>`: filter by grammar, alias, or layout family - `--json`: output one stable machine envelope ## openplanr diagram rerender Rerender after an intentional source edit ```text openplanr diagram rerender [options] <manifest> ``` Arguments: - `manifest` (required): generated diagram manifest Options: - `--accept <source>`: choose ir, mermaid, or excalidraw when source branches conflict - `--json`: output one stable machine envelope --- title: openplanr linear description: "openplanr linear: Linear.app integration: init, push, sync, status mapping, task checklists. Subcommands: init, sync, status, push, tasklist-sync." url: https://openplanr.dev/docs/cli/linear updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/dashboard.md - https://openplanr.dev/docs/cli/diagram.md - https://openplanr.dev/docs/cli/operate.md --- # openplanr linear Linear.app integration: init, push, sync, status mapping, task checklists ```text openplanr linear [options] [command] ``` ```text Subcommands: init Store PAT, choose allowed teams, save a default team sync Pull workflow status (features/stories) + bidirectional task checkboxes push <artifact> Create/update Linear entities at any granularity: EPIC-XXX → project + features + stories + tasklists FEAT-XXX → feature + its stories + its tasklist US-XXX → one story sub-issue TASK-XXX → one tasklist sub-issue status Show local OpenPlanr ↔ Linear mapping (no API calls) tasklist-sync Sync TASK checkbox lines with Linear task-list issues Common flags: --dry-run Show planned work without writes (push: no API; sync: read-only to Linear, no local writes) --update-only push: only update existing linked entities, never create --push-parents push: if a parent is not yet in Linear, push it first without prompting --team <id|key> push: target any team selected during linear init Examples: openplanr linear sync openplanr linear sync --dry-run openplanr linear push EPIC-001 --dry-run openplanr linear push FEAT-XXX --dry-run openplanr linear push US-054 openplanr linear push TASK-015 --push-parents openplanr linear status --scope EPIC-001 ``` ## openplanr linear init Validate a Linear PAT, choose teams, and save a default team ```text openplanr linear init [options] ``` ## openplanr linear sync Pull workflow status (features & stories) from Linear, then sync task checklists bidirectionally ```text openplanr linear sync [options] ``` Options: - `--dry-run`: Read from Linear to compare, but do not write local files or update Linear issue bodies; default `false` - `--update-only`: Same as default for this command (only artifacts with Linear links are considered); reserved for future use; default `false` - `--on-conflict <mode>`: Status + task-checkbox conflicts: prompt | local | linear (default: prompt; non-interactive runs default to linear); default `"prompt"` ## openplanr linear status Show local OpenPlanr id ↔ Linear id/url mapping from frontmatter (no Linear API calls) ```text openplanr linear status [options] ``` Options: - `--scope <epicId>`: Limit rows to an epic and its features, stories, and tasks in that scope ## openplanr linear push Create or update Linear project/issues for any planning artifact (EPIC/FEAT/US/TASK) ```text openplanr linear push [options] <artifactId> ``` Arguments: - `artifactId` (required): Artifact id: accepts EPIC-XXX (epic + subtree), FEAT-XXX (feature + stories + tasklist), US-XXX (one story), or TASK-XXX (one tasklist) Options: - `--dry-run`: Show what would be created/updated without calling the Linear API; default `false` - `--update-only`: Only update entities that already have Linear ids in frontmatter; never create new project/issues; default `false` - `--push-parents`: If a parent in the chain is not yet pushed to Linear, push it first (upward attachment only: does NOT push the parent's siblings); default `false` - `--no-cascade`: Push only the target artifact (and minimum parent chain when --push-parents is set). EPIC/FEAT pushes skip their descendants. - `--team <id-or-key>`: Target a team selected during `openplanr linear init` - `--as <strategy>`: Epic-only: mapping strategy. One of: project | milestone-of:<projectId> | label-on:<projectId> ## openplanr linear tasklist-sync Bidirectionally sync task checkbox state between local TASK files and Linear TaskList issues ```text openplanr linear tasklist-sync [options] ``` Options: - `--on-conflict <mode>`: When local and Linear differ: prompt, local, or linear (default: prompt; in CI, linear is used when not set); default `"prompt"` - `--dry-run`: Show what would change without writing local files or mutating Linear issue bodies; default `false` --- title: openplanr operate description: "openplanr operate: Run and resume the durable OpenPlanr Operate lifecycle. Subcommands: domains, validate-note, dashboard, start, get, resume, planning." url: https://openplanr.dev/docs/cli/operate updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/diagram.md - https://openplanr.dev/docs/cli/linear.md - https://openplanr.dev/docs/cli/land.md --- # openplanr operate Run and resume the durable OpenPlanr Operate lifecycle ```text openplanr operate [options] [command] ``` ## openplanr operate domains List exact public operating domain identities and registered roles ```text openplanr operate domains [options] ``` Options: - `--json` ## openplanr operate validate-note Inspect one Operate Markdown note against a selected or detected output contract ```text openplanr operate validate-note [options] <file> ``` Arguments: - `file` (required): Markdown note to validate Options: - `--profile <profile>`: advisor, challenger, chair, or board-report; one of `advisor`, `challenger`, `chair`, `board-report` - `--contract-version <version>`: note contract version: auto, 1.0.0, or 2.0.0; default `"auto"`; one of `auto`, `1.0.0`, `2.0.0` - `--json` ## openplanr operate dashboard The CLI help has no description for this command yet. ```text openplanr operate dashboard [options] <cycleId> ``` Arguments: - `cycleId` (required) Options: - `--actor <actorId>`: authorized human actor - `--port <port>`: loopback port; default `"7473"` - `--no-watch`: disable project-local live updates ## openplanr operate start The CLI help has no description for this command yet. ```text openplanr operate start [options] ``` Options: - `--scope <scopeId>` - `--domain <domainId>` - `--domain-version <version>` - `--focus <focus>`: comma-separated focus values; default `""` - `--owner <actorId>`: exact human review and Decision owner - `--route <route>`: contained-execution, planning-work, human-external, or observe-only; default `"observe-only"`; one of `contained-execution`, `planning-work`, `human-external`, `observe-only` - `--json` ## openplanr operate get The CLI help has no description for this command yet. ```text openplanr operate get [options] <cycleId> ``` Arguments: - `cycleId` (required) Options: - `--json` ## openplanr operate resume The CLI help has no description for this command yet. ```text openplanr operate resume [options] <cycleId> ``` Arguments: - `cycleId` (required) Options: - `--json` ## openplanr operate planning Preview and explicitly promote planning-work Actions into SPECs ```text openplanr operate planning [options] [command] ``` ### openplanr operate planning preview The CLI help has no description for this command yet. ```text openplanr operate planning preview [options] <actionId> ``` Arguments: - `actionId` (required) Options: - `--actor <actorId>`: exact authorized human Action owner - `--framing-json <json>`: exact closed Planning framing JSON - `--framing-file <path>`: read exact Planning framing JSON from path or stdin (-) - `--json` ### openplanr operate planning create-spec The CLI help has no description for this command yet. ```text openplanr operate planning create-spec [options] <proposalId> ``` Arguments: - `proposalId` (required) Options: - `--actor <actorId>`: exact human actor bound by planning preview - `--confirm <digest>`: exact digest printed by planning preview - `--json` ## openplanr operate assignment Prepare, validate, and submit one exact issued Assignment packet ```text openplanr operate assignment [options] [command] ``` ### openplanr operate assignment prepare The CLI help has no description for this command yet. ```text openplanr operate assignment prepare [options] <assignmentId> ``` Arguments: - `assignmentId` (required) Options: - `--actor <actorId>`: exact Assignment claimant - `--runtime <runtime>`: exact claimant runtime - `--json` ### openplanr operate assignment validate The CLI help has no description for this command yet. ```text openplanr operate assignment validate [options] <packetId> ``` Arguments: - `packetId` (required) Options: - `--content-file <path>`: UTF-8 JSON result file, or - for stdin - `--json` ### openplanr operate assignment submit The CLI help has no description for this command yet. ```text openplanr operate assignment submit [options] <packetId> ``` Arguments: - `packetId` (required) Options: - `--content-file <path>`: validated UTF-8 JSON result file, or - for stdin - `--json` ### openplanr operate assignment recover The CLI help has no description for this command yet. ```text openplanr operate assignment recover [options] ``` Options: - `--older-than-hours <hours>`: clear unsubmitted packets older than this age; default `"24"` - `--json` ## openplanr operate claim The CLI help has no description for this command yet. ```text openplanr operate claim [options] <assignmentId> ``` Arguments: - `assignmentId` (required) Options: - `--actor <actorId>` - `--runtime <runtime>`: runtime name - `--json` ## openplanr operate submit The CLI help has no description for this command yet. ```text openplanr operate submit [options] <assignmentId> ``` Arguments: - `assignmentId` (required) Options: - `--submission <submissionId>` - `--actor <actorId>`: exact Assignment claimant - `--runtime <runtime>`: exact claimant runtime - `--content-base64 <content>` - `--media-type <type>`: media type; default `"application/json"` - `--encoding <encoding>`: utf-8 or binary; default `"utf-8"` - `--json` ## openplanr operate artifact The CLI help has no description for this command yet. ```text openplanr operate artifact [options] <artifactId> ``` Arguments: - `artifactId` (required) Options: - `--actor <actorId>` - `--actor-kind <kind>`: agent or human - `--runtime <runtime>`: exact actor runtime - `--scope <scopeId>` - `--domain <domainId>` - `--domain-version <version>` - `--assignment <assignmentId>`: issued Assignment (required for agents) - `--representation <representation>`: raw, canonical, metadata, or decoded-json; default `"metadata"`; one of `raw`, `canonical`, `metadata`, `decoded-json` - `--json` ## openplanr operate review The CLI help has no description for this command yet. ```text openplanr operate review [options] <reviewId> ``` Arguments: - `reviewId` (required) Options: - `--actor <actorId>` - `--cycle <cycleId>` - `--scope <scopeId>` - `--domain <domainId>` - `--domain-version <version>` - `--json` ## openplanr operate decide The CLI help has no description for this command yet. ```text openplanr operate decide [options] <reviewId> ``` Arguments: - `reviewId` (required) Options: - `--actor <actorId>` - `--cycle <cycleId>` - `--scope <scopeId>` - `--domain <domainId>` - `--domain-version <version>` - `--choice <choiceId>`: exact choice identity from the latest Review read - `--choice-hash <digest>`: exact choice digest from the latest Review read - `--json` ## openplanr operate measurement Preview and manage disabled-by-default measurement schedules ```text openplanr operate measurement [options] [command] ``` ### openplanr operate measurement preview The CLI help has no description for this command yet. ```text openplanr operate measurement preview [options] ``` Options: - `--request-file <path|->`: exact disabled schedule JSON - `--actor <actorId>`: exact schedule owner - `--json` ### openplanr operate measurement enable The CLI help has no description for this command yet. ```text openplanr operate measurement enable [options] ``` Options: - `--request-file <path|->`: closed JSON with schedule and transition - `--actor <actorId>`: exact schedule owner - `--confirm <digest>`: exact digest returned by preview - `--json` ### openplanr operate measurement disable The CLI help has no description for this command yet. ```text openplanr operate measurement disable [options] <scheduleId> ``` Arguments: - `scheduleId` (required) Options: - `--request-file <path|->`: exact disable transition JSON - `--actor <actorId>`: exact schedule owner - `--confirm <digest>`: current exact schedule digest - `--json` ### openplanr operate measurement status The CLI help has no description for this command yet. ```text openplanr operate measurement status [options] <scheduleId> ``` Arguments: - `scheduleId` (required) Options: - `--actor <actorId>`: exact schedule owner - `--json` ## openplanr operate experience The CLI help has no description for this command yet. ```text openplanr operate experience [options] <cycleId> ``` Arguments: - `cycleId` (required) Options: - `--actor <actorId>` - `--json` ## openplanr operate today The CLI help has no description for this command yet. ```text openplanr operate today [options] <cycleId> ``` Arguments: - `cycleId` (required) Options: - `--actor <actorId>` - `--json` ## openplanr operate cycles The CLI help has no description for this command yet. ```text openplanr operate cycles [options] <cycleId> ``` Arguments: - `cycleId` (required) Options: - `--actor <actorId>` - `--json` ## openplanr operate evidence The CLI help has no description for this command yet. ```text openplanr operate evidence [options] <cycleId> ``` Arguments: - `cycleId` (required) Options: - `--actor <actorId>` - `--json` ## openplanr operate outcomes The CLI help has no description for this command yet. ```text openplanr operate outcomes [options] <cycleId> ``` Arguments: - `cycleId` (required) Options: - `--actor <actorId>` - `--json` ## openplanr operate history The CLI help has no description for this command yet. ```text openplanr operate history [options] <cycleId> ``` Arguments: - `cycleId` (required) Options: - `--actor <actorId>` - `--json` ## openplanr operate cycle The CLI help has no description for this command yet. ```text openplanr operate cycle [options] <cycleId> ``` Arguments: - `cycleId` (required) Options: - `--actor <actorId>` - `--json` ## openplanr operate outcome The CLI help has no description for this command yet. ```text openplanr operate outcome [options] <cycleId> <outcomeId> ``` Arguments: - `cycleId` (required) - `outcomeId` (required) Options: - `--actor <actorId>` - `--json` ## openplanr operate search The CLI help has no description for this command yet. ```text openplanr operate search [options] <cycleId> <query> ``` Arguments: - `cycleId` (required) - `query` (required) Options: - `--actor <actorId>` - `--json` ## openplanr operate export The CLI help has no description for this command yet. ```text openplanr operate export [options] <cycleId> ``` Arguments: - `cycleId` (required) Options: - `--actor <actorId>` - `--format <format>`: json or html; default `"json"` - `--json` ## openplanr operate recovery Inspect or restore durable state ```text openplanr operate recovery [options] [command] ``` ### openplanr operate recovery storage-status Inspect neutral or legacy Operate storage without activating it ```text openplanr operate recovery storage-status [options] ``` Options: - `--json` ### openplanr operate recovery migrate-storage Replay-verify legacy v2 storage and activate its exact state with rollback custody ```text openplanr operate recovery migrate-storage [options] ``` Options: - `--json` ### openplanr operate recovery rollback-storage Restore the verified pre-migration v2 Store and preserve forward state ```text openplanr operate recovery rollback-storage [options] ``` Options: - `--json` ### openplanr operate recovery inspect The CLI help has no description for this command yet. ```text openplanr operate recovery inspect [options] ``` Options: - `--json` ### openplanr operate recovery restore The CLI help has no description for this command yet. ```text openplanr operate recovery restore [options] <generation> ``` Arguments: - `generation` (required) Options: - `--json` ### openplanr operate recovery clear-stale-lock The CLI help has no description for this command yet. ```text openplanr operate recovery clear-stale-lock [options] ``` Options: - `--json` --- title: openplanr land description: "openplanr land: Inspect and owner-advance a certified landing plan. Subcommands: prepare, show, status, advance." url: https://openplanr.dev/docs/cli/land updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/linear.md - https://openplanr.dev/docs/cli/operate.md - https://openplanr.dev/docs/cli/backlog.md --- # openplanr land Inspect and owner-advance a certified landing plan ```text openplanr land [options] [command] ``` ## openplanr land prepare Prepare a read-only landing plan from a terminal PASS receipt ```text openplanr land prepare [options] ``` Options: - `--request-file <path|->`: read one closed landing request - `--json`: machine-readable output; default `false` ## openplanr land show Show exact landing custody without effects ```text openplanr land show [options] <planId> ``` Arguments: - `planId` (required): exact land_ plan identity Options: - `--json`: machine-readable output; default `false` ## openplanr land status Read exact landing custody without effects ```text openplanr land status [options] <planId> ``` Arguments: - `planId` (required): exact land_ plan identity Options: - `--json`: machine-readable output; default `false` ## openplanr land advance Review one neutral docket in a fresh owner terminal, then advance one phase ```text openplanr land advance [options] <planId> ``` Arguments: - `planId` (required): exact land_ plan identity Options: - `--operation <operationId>`: exact lop_ operation identity --- title: openplanr backlog description: "openplanr backlog: Manage backlog artifacts deterministically. Subcommands: add, list, show, update." url: https://openplanr.dev/docs/cli/backlog updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/operate.md - https://openplanr.dev/docs/cli/land.md - https://openplanr.dev/docs/cli/epic.md --- # openplanr backlog Manage backlog artifacts deterministically ```text openplanr backlog [options] [command] ``` ## openplanr backlog add Create a backlog from flags or a JSON object ```text openplanr backlog add [options] [title...] ``` Arguments: - `title...` (optional): backlog title or description Options: - `--title <title>`: backlog title - `--data <path>`: read deterministic JSON fields from a file, or - for stdin - `--file <path>`: deprecated alias for --data - `--json`: emit one machine-readable result - `-p, --priority <priority>`: critical, high, medium, or low - `-t, --tag <tags...>` - `--epic <id>` ## openplanr backlog list List backlog artifacts ```text openplanr backlog list [options] ``` ## openplanr backlog show Print one backlog artifact ```text openplanr backlog show [options] <id> ``` Arguments: - `id` (required) ## openplanr backlog update Update backlog frontmatter fields ```text openplanr backlog update [options] <id> ``` Arguments: - `id` (required) Options: - `--status <status>` - `--owner <owner>` - `--title <title>` --- title: openplanr epic description: "openplanr epic: Manage epic artifacts deterministically. Subcommands: create, list, show, update." url: https://openplanr.dev/docs/cli/epic updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/land.md - https://openplanr.dev/docs/cli/backlog.md - https://openplanr.dev/docs/cli/feature.md --- # openplanr epic Manage epic artifacts deterministically ```text openplanr epic [options] [command] ``` ## openplanr epic create Create a epic from flags or a JSON object ```text openplanr epic create [options] [title...] ``` Arguments: - `title...` (optional): epic title or description Options: - `--title <title>`: epic title - `--data <path>`: read deterministic JSON fields from a file, or - for stdin - `--file <path>`: deprecated alias for --data - `--json`: emit one machine-readable result ## openplanr epic list List epic artifacts ```text openplanr epic list [options] ``` ## openplanr epic show Print one epic artifact ```text openplanr epic show [options] <id> ``` Arguments: - `id` (required) ## openplanr epic update Update epic frontmatter fields ```text openplanr epic update [options] <id> ``` Arguments: - `id` (required) Options: - `--status <status>` - `--owner <owner>` - `--title <title>` --- title: openplanr feature description: "openplanr feature: Manage feature artifacts deterministically. Subcommands: create, list, show, update." url: https://openplanr.dev/docs/cli/feature updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/backlog.md - https://openplanr.dev/docs/cli/epic.md - https://openplanr.dev/docs/cli/story.md --- # openplanr feature Manage feature artifacts deterministically ```text openplanr feature [options] [command] ``` ## openplanr feature create Create a feature from flags or a JSON object ```text openplanr feature create [options] [title...] ``` Arguments: - `title...` (optional): feature title or description Options: - `--title <title>`: feature title - `--data <path>`: read deterministic JSON fields from a file, or - for stdin - `--file <path>`: deprecated alias for --data - `--json`: emit one machine-readable result - `--epic <id>`: parent epic ID; may also come from --data ## openplanr feature list List feature artifacts ```text openplanr feature list [options] ``` ## openplanr feature show Print one feature artifact ```text openplanr feature show [options] <id> ``` Arguments: - `id` (required) ## openplanr feature update Update feature frontmatter fields ```text openplanr feature update [options] <id> ``` Arguments: - `id` (required) Options: - `--status <status>` - `--owner <owner>` - `--title <title>` --- title: openplanr story description: "openplanr story: Manage story artifacts deterministically. Subcommands: create, list, show, update." url: https://openplanr.dev/docs/cli/story updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/epic.md - https://openplanr.dev/docs/cli/feature.md - https://openplanr.dev/docs/cli/task.md --- # openplanr story Manage story artifacts deterministically ```text openplanr story [options] [command] ``` ## openplanr story create Create a story from flags or a JSON object ```text openplanr story create [options] [title...] ``` Arguments: - `title...` (optional): story title or description Options: - `--title <title>`: story title - `--data <path>`: read deterministic JSON fields from a file, or - for stdin - `--file <path>`: deprecated alias for --data - `--json`: emit one machine-readable result - `--feature <id>`: parent feature ID; may also come from --data ## openplanr story list List story artifacts ```text openplanr story list [options] ``` ## openplanr story show Print one story artifact ```text openplanr story show [options] <id> ``` Arguments: - `id` (required) ## openplanr story update Update story frontmatter fields ```text openplanr story update [options] <id> ``` Arguments: - `id` (required) Options: - `--status <status>` - `--owner <owner>` - `--title <title>` --- title: openplanr task description: "openplanr task: Manage task artifacts deterministically. Subcommands: create, list, show, update." url: https://openplanr.dev/docs/cli/task updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/feature.md - https://openplanr.dev/docs/cli/story.md - https://openplanr.dev/docs/cli/quick.md --- # openplanr task Manage task artifacts deterministically ```text openplanr task [options] [command] ``` ## openplanr task create Create a task from flags or a JSON object ```text openplanr task create [options] [title...] ``` Arguments: - `title...` (optional): task title or description Options: - `--title <title>`: task title - `--data <path>`: read deterministic JSON fields from a file, or - for stdin - `--file <path>`: deprecated alias for --data - `--json`: emit one machine-readable result - `--story <id>` - `--feature <id>` ## openplanr task list List task artifacts ```text openplanr task list [options] ``` ## openplanr task show Print one task artifact ```text openplanr task show [options] <id> ``` Arguments: - `id` (required) ## openplanr task update Update task frontmatter fields ```text openplanr task update [options] <id> ``` Arguments: - `id` (required) Options: - `--status <status>` - `--owner <owner>` - `--title <title>` --- title: openplanr quick description: "openplanr quick: Manage quick artifacts deterministically. Subcommands: create, list, show, update." url: https://openplanr.dev/docs/cli/quick updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/story.md - https://openplanr.dev/docs/cli/task.md - https://openplanr.dev/docs/cli/spec.md --- # openplanr quick Manage quick artifacts deterministically ```text openplanr quick [options] [command] ``` ## openplanr quick create Create a quick from flags or a JSON object ```text openplanr quick create [options] [title...] ``` Arguments: - `title...` (optional): quick title or description Options: - `--title <title>`: quick title - `--data <path>`: read deterministic JSON fields from a file, or - for stdin - `--file <path>`: deprecated alias for --data - `--json`: emit one machine-readable result - `--epic <id>` ## openplanr quick list List quick artifacts ```text openplanr quick list [options] ``` ## openplanr quick show Print one quick artifact ```text openplanr quick show [options] <id> ``` Arguments: - `id` (required) ## openplanr quick update Update quick frontmatter fields ```text openplanr quick update [options] <id> ``` Arguments: - `id` (required) Options: - `--status <status>` - `--owner <owner>` - `--title <title>` --- title: openplanr spec description: "openplanr spec: Spec-driven storage and validation for artifacts authored by the active host agent. Subcommands: init, create, shape, list, show, status." url: https://openplanr.dev/docs/cli/spec updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/task.md - https://openplanr.dev/docs/cli/quick.md - https://openplanr.dev/docs/cli/checklist.md --- # openplanr spec Spec-driven storage and validation for artifacts authored by the active host agent. ```text openplanr spec [options] [command] ``` ## openplanr spec init Activate spec-driven mode in this project (creates .planr/specs/ root) ```text openplanr spec init [options] ``` ## openplanr spec create Create a new spec: a self-contained directory with stories/, tasks/, design/ ```text openplanr spec create [options] [title...] ``` Arguments: - `title...` (optional): spec title (alternative to --title) Options: - `--title <title>`: spec title (required if not given as positional argument) - `--slug <slug>`: explicit kebab-case slug; otherwise derived from title - `--priority <priority>`: P0 / P1 / P2 (default: P1); default `"P1"` - `--milestone <milestone>`: milestone label (e.g., v1.0) - `--po <handle>`: Product Owner handle (e.g., @AsemDevs) ## openplanr spec shape Author a decision-complete professional specification ```text openplanr spec shape [options] <specId> ``` Arguments: - `specId` (required): spec ID (e.g., SPEC-001) Options: - `--file <path|->`: read one bounded professional specification JSON object - `--json`: emit one machine-readable result; default `false` ## openplanr spec list List all specs in the project ```text openplanr spec list [options] ``` ## openplanr spec show Print a spec + its decomposition tree (stories, tasks) ```text openplanr spec show [options] <specId> ``` Arguments: - `specId` (required): spec ID (e.g., SPEC-001) ## openplanr spec status Decomposition state across all specs (or one spec if --spec specified) ```text openplanr spec status [options] [specId] ``` Arguments: - `specId` (optional): optional spec ID to scope output ## openplanr spec destroy Remove a spec entirely (rm -rf of its self-contained directory) ```text openplanr spec destroy [options] <specId> ``` Arguments: - `specId` (required): spec ID (e.g., SPEC-001) ## openplanr spec attach-design Copy PNG mockups into a spec's design/ directory and update ui_files frontmatter ```text openplanr spec attach-design [options] <specId> ``` Arguments: - `specId` (required): spec ID (e.g., SPEC-001) Options: - `--files <paths...>`: one or more PNG files to attach ## openplanr spec promote Validate that a spec is ready and print the pipeline handoff command ```text openplanr spec promote [options] <specId> ``` Arguments: - `specId` (required): spec ID (e.g., SPEC-001) ## openplanr spec sync Validate spec integrity (orphaned tasks, stories without tasks, missing specId frontmatter, schema drift) ```text openplanr spec sync [options] [specId] ``` Arguments: - `specId` (optional): optional spec ID to scope; otherwise scans all specs Options: - `--dry-run`: report findings without writing any fixes; default `false` --- title: openplanr checklist description: "openplanr checklist: Manage the agile development checklist. Subcommands: show, toggle, reset." url: https://openplanr.dev/docs/cli/checklist updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/quick.md - https://openplanr.dev/docs/cli/spec.md - https://openplanr.dev/docs/cli/rules.md --- # openplanr checklist Manage the agile development checklist ```text openplanr checklist [options] [command] ``` ## openplanr checklist show Display the agile development checklist ```text openplanr checklist show [options] ``` ## openplanr checklist toggle Toggle checklist items (e.g., `openplanr checklist toggle 1 3 5` or interactive) ```text openplanr checklist toggle [options] [items...] ``` Arguments: - `items...` (optional) ## openplanr checklist reset Reset the checklist to its initial state ```text openplanr checklist reset [options] ``` --- title: openplanr rules description: "openplanr rules: Generate project guidance for host-native coding agents. Subcommands: generate." url: https://openplanr.dev/docs/cli/rules updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/spec.md - https://openplanr.dev/docs/cli/checklist.md - https://openplanr.dev/docs/cli/status.md --- # openplanr rules Generate project guidance for host-native coding agents ```text openplanr rules [options] [command] ``` ## openplanr rules generate Generate rule files for configured AI CLIs ```text openplanr rules generate [options] ``` Options: - `--target <target>`: specific target: cursor, claude, codex, or all; default `"all"` - `--scope <scope>`: rule set to generate: agile (default), pipeline, or all; default `"agile"` - `--dry-run`: show what would be generated without writing files; default `false` --- title: openplanr status description: "openplanr status: Whole-project delivery report: every spec/backlog/quick-task by status, optionally cross-referenced with GitHub PRs + Linear. Usage and." url: https://openplanr.dev/docs/cli/status updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/checklist.md - https://openplanr.dev/docs/cli/rules.md - https://openplanr.dev/docs/cli/config.md --- # openplanr status Whole-project delivery report: every spec/backlog/quick-task by status, optionally cross-referenced with GitHub PRs + Linear ```text openplanr status [options] [scope] ``` Arguments: - `scope` (optional): limit the report to one spec/epic/feature id or slug Options: - `--github`: live-resolve linked GitHub issue state + correlate PRs by id (needs `gh` auth) - `--linear`: live-resolve Linear issue state (else uses reconciled state from frontmatter) - `--md`: output the delivery report as markdown (paste-ready) - `--json`: output the delivery report as JSON - `--all`: show all items without truncation (terminal view) --- title: openplanr config description: "openplanr config: Manage deterministic OpenPlanr configuration. Subcommands: show, set-agent, set-upgrade-policy." url: https://openplanr.dev/docs/cli/config updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/rules.md - https://openplanr.dev/docs/cli/status.md - https://openplanr.dev/docs/cli/export.md --- # openplanr config Manage deterministic OpenPlanr configuration ```text openplanr config [options] [command] ``` ## openplanr config show Display current configuration ```text openplanr config show [options] ``` ## openplanr config set-agent Set the preferred host for generated project guidance ```text openplanr config set-agent [options] [agent] ``` Arguments: - `agent` (optional): claude, cursor, or codex ## openplanr config set-upgrade-policy Configure upgrade checks ```text openplanr config set-upgrade-policy [options] ``` Options: - `--auto-upgrade <true|false>` - `--update-check <true|false>` - `--never-ask` - `--ask-again` --- title: openplanr export description: "openplanr export: Export planning artifacts as markdown, JSON, or HTML report. Usage and options including --format, --scope, --output." url: https://openplanr.dev/docs/cli/export updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/status.md - https://openplanr.dev/docs/cli/config.md - https://openplanr.dev/docs/cli/report.md --- # openplanr export Export planning artifacts as markdown, JSON, or HTML report ```text openplanr export [options] ``` Options: - `--format <format>`: output format: markdown, json, html; default `"markdown"` - `--scope <epicId>`: only export artifacts under a specific epic - `--output <path>`: output file or directory; default `"."` --- title: openplanr report description: "openplanr report: Generate stakeholder report (sprint, weekly, executive, standup, retro, release) from OpenPlanr + GitHub. Usage and options including." url: https://openplanr.dev/docs/cli/report updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/config.md - https://openplanr.dev/docs/cli/export.md - https://openplanr.dev/docs/cli/report-linter.md --- # openplanr report Generate stakeholder report (sprint, weekly, executive, standup, retro, release) from OpenPlanr + GitHub ```text openplanr report [options] <type> ``` Arguments: - `type` (required) Options: - `--sprint <id>`: sprint id, e.g. SPRINT-001 - `--days <n>`: GitHub lookback days; default `"7"` - `--no-github`: skip GitHub commit/PR signals - `--format <fmt>`: markdown | html; default `"markdown"` - `--output <dir>`: directory under project; default `.planr/reports` - `--stdout`: print markdown to stdout instead of writing file - `--lint`: run report linter on generated markdown - `--strict-evidence`: fail if bullet claims under ## headings lack URLs or #issue references; default `false` - `--push <targets>`: comma-separated destinations: github, slack - `--dry-run`: with --push: show actions only; default `false` --- title: openplanr report-linter description: "openplanr report-linter: Lint a stakeholder report markdown file. Usage and options including --type." url: https://openplanr.dev/docs/cli/report-linter updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/export.md - https://openplanr.dev/docs/cli/report.md - https://openplanr.dev/docs/cli/context.md --- # openplanr report-linter Lint a stakeholder report markdown file ```text openplanr report-linter [options] [file] ``` Arguments: - `file` (optional) Options: - `--type <t>`: report type for rule selection; default `"weekly"` --- title: openplanr context description: "openplanr context: Print stakeholder report context pack as JSON. Usage and options including --report-type, --sprint, --days." url: https://openplanr.dev/docs/cli/context updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/report.md - https://openplanr.dev/docs/cli/report-linter.md - https://openplanr.dev/docs/cli/voice.md --- # openplanr context Print stakeholder report context pack as JSON ```text openplanr context [options] ``` Options: - `--report-type <type>`: logical report type for placeholders; default `"weekly"` - `--sprint <id>`: sprint id - `--days <n>`: GitHub lookback days; default `"7"` - `--no-github`: omit GitHub signals --- title: openplanr voice description: "openplanr voice: Voice-oriented standup helpers. Subcommands: standup." url: https://openplanr.dev/docs/cli/voice updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/report-linter.md - https://openplanr.dev/docs/cli/context.md - https://openplanr.dev/docs/cli/github.md --- # openplanr voice Voice-oriented standup helpers ```text openplanr voice [options] [command] ``` ## openplanr voice standup Convert a transcript file (or stdin) into structured standup markdown ```text openplanr voice standup [options] ``` Options: - `--file <path>`: path to transcript text - `--write <path>`: write standup markdown to this path (relative to project or absolute) - `--edit`: open generated markdown in $EDITOR before output/save (interactive only) - `--reload-file`: after generating, offer to re-read --file from disk (interactive + --file only) - `--append-story <storyId>`: append standup under ## Standup notes on this story - `--lint`: run standup through report linter --- title: openplanr github description: "openplanr github: Sync planning artifacts with GitHub Issues. Subcommands: push, sync, status." url: https://openplanr.dev/docs/cli/github updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/context.md - https://openplanr.dev/docs/cli/voice.md - https://openplanr.dev/docs/cli/graph.md --- # openplanr github Sync planning artifacts with GitHub Issues ```text openplanr github [options] [command] ``` ## openplanr github push Push artifacts to GitHub Issues ```text openplanr github push [options] [artifactId] ``` Arguments: - `artifactId` (optional): artifact ID to push (e.g., TASK-001) Options: - `--epic <epicId>`: push all artifacts under an epic - `--all`: push all artifacts across all types ## openplanr github sync Sync artifact status with GitHub Issues (bi-directional) ```text openplanr github sync [options] ``` Options: - `--direction <dir>`: sync direction: pull (GitHub→local), push (local→GitHub), or both; default `"both"` ## openplanr github status Show sync status of all linked artifacts ```text openplanr github status [options] ``` --- title: openplanr graph description: "openplanr graph: Emit the OpenPlanr artifact graph. Usage and options including --json." url: https://openplanr.dev/docs/cli/graph updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/voice.md - https://openplanr.dev/docs/cli/github.md - https://openplanr.dev/docs/cli/search.md --- # openplanr graph Emit the OpenPlanr artifact graph ```text openplanr graph [options] ``` Options: - `--json`: output the graph as JSON --- title: openplanr search description: "openplanr search: Search across all planning artifacts. Usage and options including --type, --status." url: https://openplanr.dev/docs/cli/search updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/github.md - https://openplanr.dev/docs/cli/graph.md - https://openplanr.dev/docs/cli/sprint.md --- # openplanr search Search across all planning artifacts ```text openplanr search [options] <query> ``` Arguments: - `query` (required): search term or phrase Options: - `--type <type>`: filter by artifact type (epic, feature, story, task, quick, adr) - `--status <status>`: filter by status (pending, in-progress, done) --- title: openplanr sprint description: "openplanr sprint: Manage sprint artifacts deterministically. Subcommands: create, list, show, update, refinement, diff, close, apply." url: https://openplanr.dev/docs/cli/sprint updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/graph.md - https://openplanr.dev/docs/cli/search.md - https://openplanr.dev/docs/cli/sync.md --- # openplanr sprint Manage sprint artifacts deterministically ```text openplanr sprint [options] [command] ``` ## openplanr sprint create Create a sprint from flags or a JSON object ```text openplanr sprint create [options] [title...] ``` Arguments: - `title...` (optional): sprint title or description Options: - `--title <title>`: sprint title - `--data <path>`: read deterministic JSON fields from a file, or - for stdin - `--file <path>`: deprecated alias for --data - `--json`: emit one machine-readable result - `-d, --duration <duration>`: sprint duration; default `"2w"` ## openplanr sprint list List sprint artifacts ```text openplanr sprint list [options] ``` ## openplanr sprint show Print one sprint artifact ```text openplanr sprint show [options] <id> ``` Arguments: - `id` (required) ## openplanr sprint update Update sprint frontmatter fields ```text openplanr sprint update [options] <id> ``` Arguments: - `id` (required) Options: - `--status <status>` - `--owner <owner>` - `--title <title>` ## openplanr sprint refinement Store a refinement document: validate it, write the note and JSON, fill the sprint ```text openplanr sprint refinement [options] <id> ``` Arguments: - `id` (required): sprint id, e.g. SPRINT-004 Options: - `--data <path>`: refinement JSON document, or - for stdin - `--json`: emit one machine-readable result ## openplanr sprint diff Show what moved between two refinement documents ```text openplanr sprint diff [options] <from> <to> ``` Arguments: - `from` (required): earlier sprint id - `to` (required): later sprint id Options: - `--json`: emit one machine-readable result ## openplanr sprint close Close the sprint and record its leftovers for the next refinement ```text openplanr sprint close [options] <id> ``` Arguments: - `id` (required): sprint id Options: - `--json`: emit one machine-readable result ## openplanr sprint apply Write the approved status changes from the refinement document to the artifacts ```text openplanr sprint apply [options] <id> ``` Arguments: - `id` (required): sprint id Options: - `--yes`: confirm the write-back after the host skill asked its approval question - `--dry-run`: list the changes without writing anything - `--force`: skip status vocabulary validation - `--commit`: commit exactly the changed files as chore(planr): refine backlog for <id> - `--json`: emit one machine-readable result --- title: openplanr sync description: "openplanr sync: Validate and fix cross-references across all artifacts. Usage and options including --dry-run." url: https://openplanr.dev/docs/cli/sync updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/search.md - https://openplanr.dev/docs/cli/sprint.md - https://openplanr.dev/docs/cli/template.md --- # openplanr sync Validate and fix cross-references across all artifacts ```text openplanr sync [options] ``` Options: - `--dry-run`: show what would change without writing files --- title: openplanr template description: "openplanr template: Reusable task patterns for common development tasks. Subcommands: list, show, use, save, delete." url: https://openplanr.dev/docs/cli/template updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/sprint.md - https://openplanr.dev/docs/cli/sync.md - https://openplanr.dev/docs/cli/update.md --- # openplanr template Reusable task patterns for common development tasks ```text openplanr template [options] [command] ``` ## openplanr template list List available task templates ```text openplanr template list [options] ``` ## openplanr template show Preview a template ```text openplanr template show [options] <name> ``` Arguments: - `name` (required): template name ## openplanr template use Generate a task list from a template ```text openplanr template use [options] <name> ``` Arguments: - `name` (required): template name Options: - `--title <title>`: task list title ## openplanr template save Save an existing task list as a reusable template ```text openplanr template save [options] <taskId> ``` Arguments: - `taskId` (required): task ID to save as template (e.g., TASK-001, QT-003) Options: - `-n, --name <name>`: template name (lowercase, hyphenated) ## openplanr template delete Delete a custom template ```text openplanr template delete [options] <name> ``` Arguments: - `name` (required): template name --- title: openplanr update description: "openplanr update: Update artifact fields (status, owner, priority). Usage and options including --status, --owner, --priority." url: https://openplanr.dev/docs/cli/update updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/sync.md - https://openplanr.dev/docs/cli/template.md - https://openplanr.dev/docs/cli/upgrade.md --- # openplanr update Update artifact fields (status, owner, priority) ```text openplanr update [options] <ids...> ``` Arguments: - `ids...` (required): one or more artifact IDs (e.g., TASK-001 FEAT-002) Options: - `--status <status>`: new status value - `--owner <owner>`: new owner (epics and features only) - `--priority <priority>`: new priority (backlog only) - `--all-done`: set status=done AND flip every `N.M` task checkbox to `[x]` (task / quick artifacts only) - `--all-pending`: set status=pending AND flip every `N.M` task checkbox to `[ ]` (task / quick artifacts only) - `--force`: skip status validation --- title: openplanr upgrade description: "openplanr upgrade: Reconcile the installed OpenPlanr tuple against the published compatible set. Subcommands: status, apply." url: https://openplanr.dev/docs/cli/upgrade updated: 2026-10-06 related: - https://openplanr.dev/docs/cli/sync.md - https://openplanr.dev/docs/cli/template.md - https://openplanr.dev/docs/cli/update.md --- # openplanr upgrade Reconcile the installed OpenPlanr tuple against the published compatible set ```text openplanr upgrade [options] [command] ``` ## openplanr upgrade status Report whether the installed tuple is aligned, upgradable, or incompatible ```text openplanr upgrade status [options] ``` Options: - `--json`: machine-readable output; default `false` ## openplanr upgrade apply Upgrade the OpenPlanr CLI and list the command that updates each coding agent ```text openplanr upgrade apply [options] ``` Options: - `--yes`: proceed with the upgrade without an interactive confirmation; default `false` - `--notes <mode>`: what's new: highlights or full; default `"highlights"` - `--json`: machine-readable output; default `false` --- title: Changelog description: CLI numbering. openplanr releases are <major>.<YYWW>.<n>. url: https://openplanr.dev/docs/changelog updated: 2026-10-06 related: [] --- # Changelog - **CLI numbering.** `openplanr` releases are `<major>.<YYWW>.<n>`. `YYWW` is the ISO week-year and week the version PR was prepared in, and `n` counts earlier releases in that week. For example, 2026 week 39 gives `2.2639.0`, and a second release that week gives `2.2639.1`. Changesets still decides whether the CLI releases and whether it is a new major; `cli-version.mjs` then takes the week number from the UTC date and the patch count from npm, and fails rather than produce a version below one already published. The numbering cannot be reverted: after `2.2639.0`, returning to small minor numbers needs a new major. - **Library numbering.** `planr-pipeline` and `@openplanr/protocol` keep ordinary SemVer. - **Cadence.** Merge the version PR once a week. An urgent fix can still be released on another day; it becomes the next patch of that week's number. - **Bump types.** Write `patch` changesets by default, `minor` only for a milestone the maintainers call out, and `major` for a breaking change. --- title: openplanr 2.2641.1 description: Published 2026-10-06. The command is now openplanr, with opr as its short alias. url: https://openplanr.dev/docs/changelog/2.2641.1 updated: 2026-10-06 related: - https://openplanr.dev/docs/changelog/2.2641.0.md - https://openplanr.dev/docs/changelog/2.2640.9.md - https://openplanr.dev/docs/changelog/2.2640.8.md --- # openplanr 2.2641.1 Published 2026-10-06. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.2641.1) ## Minor Changes The command is now `openplanr`, with `opr` as its short alias. `planr` keeps working in this release and prints a one-line notice; it will be removed in the next release, so switch scripts, shell aliases and CI to `openplanr` or `opr`. `openplanr doctor` reports installed skills that still use the old command and how to refresh them. Skill names such as `/planr:plan`, the `planr` plugin and the `.planr/` folder are unchanged. ## Patch Changes `@openplanr/protocol/names` exports `PLANNING_FOLDER` and `CLI_COMMAND`, the planning folder and command names. The CLI, the pipeline and the bundled sync skill read them from there instead of spelling them out. Output is unchanged. The pipeline command is now `openplanr-pipeline`. `planr-pipeline` keeps working in this release and prints a one-line notice; it will be removed in the next release, so switch scripts to `openplanr-pipeline`. OpenPlanr no longer writes into a `.planr/` folder it didn't create. When that folder has no OpenPlanr `config.json` but holds other planning files, `openplanr init`, project setup, provenance appends and design taste updates stop and list what they found. Move or rename that folder, or use OpenPlanr in another repository. The estimation guide that `openplanr init` writes no longer documents the removed `estimate` command, and the pipeline's SHIP procedure and docs call `openplanr-pipeline` instead of the removed pipeline command. --- title: openplanr 2.2641.0 description: Published 2026-10-05. Align Design Studio mode controls with header actions, including consistent phone touch targets and visible hover, selected and… url: https://openplanr.dev/docs/changelog/2.2641.0 updated: 2026-10-05 related: - https://openplanr.dev/docs/changelog/2.2641.1.md - https://openplanr.dev/docs/changelog/2.2640.9.md - https://openplanr.dev/docs/changelog/2.2640.8.md --- # openplanr 2.2641.0 Published 2026-10-05. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.2641.0) ## Patch Changes Align Design Studio mode controls with header actions, including consistent phone touch targets and visible hover, selected and keyboard-focus states. --- title: openplanr 2.2640.9 description: Published 2026-10-05. Improve offline Studio and review runtime packaging while preserving existing designs and installations. url: https://openplanr.dev/docs/changelog/2.2640.9 updated: 2026-10-05 related: - https://openplanr.dev/docs/changelog/2.2641.1.md - https://openplanr.dev/docs/changelog/2.2641.0.md - https://openplanr.dev/docs/changelog/2.2640.8.md --- # openplanr 2.2640.9 Published 2026-10-05. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.2640.9) ## Patch Changes Improve offline Studio and review runtime packaging while preserving existing designs and installations. Verify packaged files before publication and restore the previous package if an update fails. Use profile-specific authentication for local model diagnostics. --- title: openplanr 2.2640.8 description: Published 2026-10-04. Block Delegate runs when inspected routing conflicts with a pinned destination, and show safe native failure details, observed tool… url: https://openplanr.dev/docs/changelog/2.2640.8 updated: 2026-10-04 related: - https://openplanr.dev/docs/changelog/2.2641.0.md - https://openplanr.dev/docs/changelog/2.2640.9.md - https://openplanr.dev/docs/changelog/2.2640.7.md --- # openplanr 2.2640.8 Published 2026-10-04. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.2640.8) ## Patch Changes Block Delegate runs when inspected routing conflicts with a pinned destination, and show safe native failure details, observed tool progress and live elapsed time. Local metadata checks use bounded authenticated reads without generating requests or loading models. Preview reports the actual context inventory and profile changes. Accept runner actions on the command line or in stdin JSON. Allow explicit cleanup of unchanged, never-started owned runs while retaining edits, sessions and recovery evidence. Ship complete, readable browser scripts in skill packages instead of arbitrary byte fragments. Verify that executable resources parse independently and retain offline behavior, source provenance and compatibility with older packages. Skill cards and summaries consistently use OpenPlanr branding and clearly report completed work, useful deliverables, checks and remaining action. Activation descriptions come from each skill's frontmatter. Setup and doctor accept recorded skill discovery modes through an additive runtime-lock contract while preserving legacy locks and native namespaces. Share operational Design and review-validation resources within native skill suites and keep standalone downloads self-contained. Plan carries only its planning and handoff-inspection dependencies. Generated-output cleanup preserves modified and unknown files across upgrades and branch changes. Maintainer guides remain in the source workspace rather than the installed pipeline package. Keep project skill integrations small by resolving exact verified runtime resources from the OpenPlanr home. Native plugins retain their complete runtime in one package. Setup, upgrades and doctor share the same ownership checks and preserve modified files, concurrent edits and retained runtime resources during recovery. Use host-neutral stack overrides with legacy compatibility. Improve installed invocation guidance, local Delegate profile discovery and concise result summaries. --- title: openplanr 2.2640.7 description: Published 2026-10-04. New backlog items now end with the supported closing command openplanr backlog update <id> --status closed instead of nonexistent… url: https://openplanr.dev/docs/changelog/2.2640.7 updated: 2026-10-04 related: - https://openplanr.dev/docs/changelog/2.2640.9.md - https://openplanr.dev/docs/changelog/2.2640.8.md - https://openplanr.dev/docs/changelog/2.2640.6.md --- # openplanr 2.2640.7 Published 2026-10-04. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.2640.7) ## Patch Changes New backlog items now end with the supported closing command `openplanr backlog update <id> --status closed` instead of nonexistent close/promote commands. Keep Codex setup and repairs in the selected native profile, report installed skill paths and separate package/skill versions, and distinguish cached upgrade evidence from a fresh registry check. Runtime updates refresh only the selected coding agent and preserve its saved scope and Codex discovery mode unless a scope change is explicitly requested. Other agents and native profiles keep their managed files and recovery records. Setup failure recovery checks captured and applied file identities before restoring anything, preserving unexpected concurrent edits for inspection. Delegate an implementation scope through the signed-in Claude Code, Codex or Cursor CLI. New native runs inherit the selected CLI's trusted configuration, tools, permissions and sandbox controls. Show the engine, model selection, routing, configuration trust and working directory before dispatch. Profiles are optional, native summaries remain readable, and permission requests or denials require attention without weakening the CLI's safeguards. Ordinary Ship remains host-native, and no public delegate CLI command is added. Prepare dependencies once, keep complete readable task context, save focused independent check evidence and show phase timings. Continue only the recorded native session, integrate reviewed changes as an uncommitted diff while preserving concurrent edits, and remove the run's owned worktree after successful integration unless retention was requested. Retained legacy runs use their pinned helpers unchanged; generic adapters remain experimental under their existing protocol. Report a Codex session that permits only filesystem reads as needing native permission resolution, retaining its exact session for continuation. Make Design Studio notifications dismissible, keep repeated dismissed sync warnings closed, and clear save warnings after a successful retry while preserving unsaved drafts. Make local Design Studio previews load selected screens with bounded frames, phase diagnostics and retry. Share authored sources across responsive views, support protected Studio routes and exact service lifecycle, preserve durable feedback and explicit offline imports, and add screen search, actual-size inspection and navigation links. Keep legacy artifact contracts and hosted publication limits compatible. Display rendered diagram shapes directly on the studio canvas, remove the white page and shadow, and strengthen neutral shape fills while preserving saved geometry and export bytes. Preserve saved skill discovery and installation scopes during doctor repair, reconcile stale managed Codex plugin registrations through native commands, and show grouped repair previews with exact JSON evidence and host restart guidance. Retire the managed Codex plugin when switching both user and project scopes to project skills, while preserving global plugins during project-only setup. Use native Claude Code, Codex and Cursor execution for delegation, with optional profiles, plain summaries, focused independent verification and safe owned-worktree cleanup. Allow source expressions and explicit dummy values in delegation context while retaining credential file and token detection. Honor explicit Claude configuration during dispatch and continuation, and safely integrate into linked worktrees on a different filesystem from Git metadata. Keep `openplanr context` stdout valid JSON for scripts, with its evidence summary on stderr. Limit scoped planning export evidence to stories and tasks under the selected epic while retaining complete unscoped exports. Simplify setup around OpenPlanr skills, show installation destinations and backed-up file replacements, and provide scope-aware recovery guidance without changing existing installation IDs or flags. Project-only Codex setup preserves the existing global plugin configuration. Correct supported Node.js versions to match the installed production dependencies. The CLI now checks support before loading prompt modules and gives an actionable error in startup, setup, doctor, and installers. Pipeline, Artifact, and Design declare their parser's Node.js 20.19 minimum. Standalone Protocol retains its Node.js 20 import contract. --- title: openplanr 2.2640.6 description: Published 2026-09-30. Shared diagram reviews show the canvas status as a small caption instead of a line above the drawing, and space the selected element's… url: https://openplanr.dev/docs/changelog/2.2640.6 updated: 2026-09-30 related: - https://openplanr.dev/docs/changelog/2.2640.8.md - https://openplanr.dev/docs/changelog/2.2640.7.md - https://openplanr.dev/docs/changelog/2.2640.5.md --- # openplanr 2.2640.6 Published 2026-09-30. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.2640.6) ## Patch Changes Shared diagram reviews show the canvas status as a small caption instead of a line above the drawing, and space the selected element's actions as the local review does. The navigator names an unlabeled connection by its endpoints, such as "Owner shares the diagram → Reviewer opens the link". Elements without a description no longer show placeholder text. --- title: openplanr 2.2640.5 description: Published 2026-09-30. The Share design dialog keeps its primary button label readable in light and dark themes at rest, on hover, when pressed and during… url: https://openplanr.dev/docs/changelog/2.2640.5 updated: 2026-09-30 related: - https://openplanr.dev/docs/changelog/2.2640.7.md - https://openplanr.dev/docs/changelog/2.2640.6.md - https://openplanr.dev/docs/changelog/2.2640.4.md --- # openplanr 2.2640.5 Published 2026-09-30. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.2640.5) ## Patch Changes The **Share design** dialog keeps its primary button label readable in light and dark themes at rest, on hover, when pressed and during keyboard focus. Disabled buttons retain their disabled appearance instead of picking up the hover fill. Regenerated Mermaid copies now rename node and group IDs that are Mermaid keywords, such as `end`, to an unused ID with an underscore suffix. Connections use the renamed IDs, and the export reports a `keyword-id-renamed` fidelity notice. This prevents invalid Mermaid output while preserving the editable bundle's IDs and content. Share a verified diagram manifest or authored bundle as a native encrypted review: ```bash openplanr artifact share <manifest-or-bundle> openplanr artifact publish <manifest-or-bundle> openplanr artifact sync <manifest-or-bundle> ``` The local studio's **Share diagram** dialog previews the selected title, revision, publication contents, destination and retention. It provides separate controls for copying the stable link and access token. Reviews work while the owner's laptop is offline and last until revoked or deleted. The native viewer preserves saved geometry and provides outline/search, inspection, pan/zoom, Fit, Present, Discussion, Revisions, and SVG/PNG or feedback exports without an HTML wrapper. Publish later revisions explicitly to the same link. Sync revision-bound feedback into the local ledger without changing the diagram; earlier revisions remain readable and do not accept new comments. Owner credentials stay outside the repository and ordinary command output remains credential-free. Protocol 1.15 adds `@openplanr/protocol/diagram-review-contracts`, with validators and TypeScript types for diagram review bundles, feedback and encrypted workspace records. Its six schemas are `schemas/v1.15.0/diagram-review-bundle.schema.json`, `diagram-review-feedback.schema.json`, `diagram-review-workspace.schema.json`, `diagram-workspace-create.schema.json`, `diagram-workspace-revision.schema.json` and `diagram-workspace-event.schema.json`. These additive contracts use payload `schemaVersion: "1.0.0"`; existing schema versions remain unchanged. Diagram sharing requires a compatible hosted service. An older runtime or service reports `E_DIAGRAM_SHARE_UNSUPPORTED`. Existing HTML reviews and design links keep working and are not migrated or republished automatically. --- title: openplanr 2.2640.4 description: Published 2026-09-30. Design Share stores each repeated screen, script and style once and compresses the review before encrypting it, so large designs fit the… url: https://openplanr.dev/docs/changelog/2.2640.4 updated: 2026-09-30 related: - https://openplanr.dev/docs/changelog/2.2640.6.md - https://openplanr.dev/docs/changelog/2.2640.5.md - https://openplanr.dev/docs/changelog/2.2640.3.md --- # openplanr 2.2640.4 Published 2026-09-30. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.2640.4) ## Patch Changes Design Share stores each repeated screen, script and style once and compresses the review before encrypting it, so large designs fit the upload limit. A 13-screen design at three sizes shrank from 19 MiB to 0.24 MiB. Links shared earlier keep opening. --- title: openplanr 2.2640.3 description: Published 2026-09-29. openplanr upgrade apply, openplanr runtime update and openplanr setup now print only what changed. url: https://openplanr.dev/docs/changelog/2.2640.3 updated: 2026-09-29 related: - https://openplanr.dev/docs/changelog/2.2640.5.md - https://openplanr.dev/docs/changelog/2.2640.4.md - https://openplanr.dev/docs/changelog/2.2640.2.md --- # openplanr 2.2640.3 Published 2026-09-29. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.2640.3) ## Patch Changes `openplanr upgrade apply`, `openplanr runtime update` and `openplanr setup` now print only what changed. After an upgrade you see the new version, up to five highlights per release with a link to the full release notes (`--notes full` prints every entry), and one command per installed coding agent, planned by the newly installed CLI instead of the version you upgraded from. `openplanr runtime update` prints one line per coding agent and which ones to restart; `--verbose` adds the changed files and `--json` prints the full result. --- title: openplanr 2.2640.2 description: Published 2026-09-29. Honor backlog priority supplied through --data when no --priority flag is given. url: https://openplanr.dev/docs/changelog/2.2640.2 updated: 2026-09-29 related: - https://openplanr.dev/docs/changelog/2.2640.4.md - https://openplanr.dev/docs/changelog/2.2640.3.md - https://openplanr.dev/docs/changelog/2.2640.1.md --- # openplanr 2.2640.2 Published 2026-09-29. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.2640.2) ## Patch Changes Honor backlog priority supplied through `--data` when no `--priority` flag is given. New backlog files keep priority in frontmatter only, and updating an older file also updates its existing body priority so the two values cannot disagree. The design studio, the design board and `openplanr artifact` reviews now render up to 100 MiB of HTML in total, up from 10 MiB, so a large clickable prototype renders at every frame size. Share links keep their current size limits. --- title: openplanr 2.2640.1 description: Published 2026-09-29. The Claude Code plugin no longer ships each skill's openplanr.skill.json build manifest; the Codex plugin keeps it. url: https://openplanr.dev/docs/changelog/2.2640.1 updated: 2026-09-29 related: - https://openplanr.dev/docs/changelog/2.2640.3.md - https://openplanr.dev/docs/changelog/2.2640.2.md - https://openplanr.dev/docs/changelog/2.2640.0.md --- # openplanr 2.2640.1 Published 2026-09-29. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.2640.1) ## Patch Changes The Claude Code plugin no longer ships each skill's `openplanr.skill.json` build manifest; the Codex plugin keeps it. The package README says 25+ skills instead of an exact count. The local Claude Code and Codex marketplaces name OpenPlanr as their owner and list the plugin with its description. The Claude Code and Codex plugin manifests now carry the README headline as their description. The CEO, CTO, CPO, CMO, COO and challenger review skills no longer pre-approve `git log`, `git show` and `git diff`; running them follows your Claude Code permission settings. --- title: openplanr 2.2640.0 description: Published 2026-09-28. The bundled design helper in the design, design-loop, design-review and plan skills now ships as scripts/design.mjs plus flat sibling… url: https://openplanr.dev/docs/changelog/2.2640.0 updated: 2026-09-28 related: - https://openplanr.dev/docs/changelog/2.2640.2.md - https://openplanr.dev/docs/changelog/2.2640.1.md - https://openplanr.dev/docs/changelog/2.2639.5.md --- # openplanr 2.2640.0 Published 2026-09-28. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.2640.0) ## Patch Changes The bundled design helper in the design, design-loop, design-review and plan skills now ships as `scripts/design.mjs` plus flat sibling `scripts/design-*.mjs` modules, each under 256 KiB and unminified, so the Claude Code plugin meets the plugin directory's per-file size limit. Commands, flags and output are unchanged. The skill registry and the pipeline's protocol projection carry the new resource digests. The Claude Code plugin now ships an icon, credits OpenPlanr as its author, and declares its privacy policy, terms of service, support and documentation links for the plugin directory. The executive review skills (CEO, CTO, CPO, CMO, COO, challenger and chair review) now pre-approve file edits only under `.planr/operate/`, where they write their notes, instead of any file; writes elsewhere ask first. The `planr-sync` skill's bundled helper no longer talks to Linear or reads `PLANR_LINEAR_TOKEN`. Linear synchronization runs through the host's Linear connector or the `openplanr linear` CLI, which stores its own token. To migrate, run `openplanr linear init` once, audit with `openplanr linear sync --dry-run`, and create or update issues with `openplanr linear push <artifact-id>`. `sync.mjs linear …` now exits with `E_SYNC_USAGE` and names these commands. GitHub and local reconciliation are unchanged and still need no CLI. --- title: openplanr 2.2639.5 description: Published 2026-09-28. Creating an artifact (openplanr backlog add, openplanr epic create and the other create commands) no longer reissues the id of a removed… url: https://openplanr.dev/docs/changelog/2.2639.5 updated: 2026-09-28 related: - https://openplanr.dev/docs/changelog/2.2640.1.md - https://openplanr.dev/docs/changelog/2.2640.0.md - https://openplanr.dev/docs/changelog/2.2639.4.md --- # openplanr 2.2639.5 Published 2026-09-28. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.2639.5) ## Patch Changes Creating an artifact (`openplanr backlog add`, `openplanr epic create` and the other create commands) no longer reissues the id of a removed item, continues past 999 (`FEAT-1000`), gives concurrent runs different ids, and ignores `SPRINT-NNN/` notes folders; issued ids are recorded as empty files in each artifact folder's `.issued-ids/`, which belongs in version control with the rest of `.planr/`. `planr <type> list` now shows ids past 999, in numeric order. `openplanr github sync` now reads the upper-case issue states `gh` reports, so pull no longer resets artifacts linked to closed issues to `pending`, push closes or reopens only the issues whose state differs, and the default direction reports a conflict only where the two sides disagree. An issue number that names a merged pull request counts as closed, and `openplanr github status` marks an issue it could not fetch as out of sync. Landing custody now clears a stored `recovery_required` receipt when the rollback or compensate intent is committed, so a landing host built on it can dispatch the recovery instead of failing with `LANDING_BINDING_MISMATCH`. A `reportLinter.vaguePhrases[].pattern` in `.planr/config.json` that is not a valid regular expression, or that can match empty text such as `(soon)?`, now fails config loading with `E_CONFIG_INVALID` naming the field and the pattern. Before, `openplanr report`, `openplanr report-linter` and `openplanr voice` failed with a raw `SyntaxError` or looped until the process ran out of memory. --- title: openplanr 2.2639.4 description: Published 2026-09-27. Positional artifact ids must now look like an artifact id such as US-001 (an uppercase prefix, a hyphen and three or more digits). url: https://openplanr.dev/docs/changelog/2.2639.4 updated: 2026-09-27 related: - https://openplanr.dev/docs/changelog/2.2640.0.md - https://openplanr.dev/docs/changelog/2.2639.5.md - https://openplanr.dev/docs/changelog/2.2639.3.md --- # openplanr 2.2639.4 Published 2026-09-27. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.2639.4) ## Patch Changes Positional artifact ids must now look like an artifact id such as `US-001` (an uppercase prefix, a hyphen and three or more digits). `planr <type> show|update`, `openplanr update`, `openplanr spec shape|show|status|destroy|attach-design|promote|sync`, `openplanr sprint refinement|diff|close|apply`, `openplanr template save`, `openplanr github push` and `openplanr linear push` reject anything else with `E_ARTIFACT_ID_INVALID` instead of printing another artifact for `.*`, resolving the bare prefix `SPEC` to the first spec, or crashing on `(`. Artifact, Gherkin, spec, managed-block and id-prefix lookups now match names literally. The one-time migration of `~/.planr/credentials.json` now moves only the CLI's own keys and leaves other entries, such as the design engine's `openai_api_key`, in the file, deleting it only when nothing else remains. If an earlier run moved the design engine's key, store it again with the design engine's `setup` command or set `OPENAI_API_KEY`. `--verbose` now prints the stack of a failed command and every cause it wraps, while the default output stays one line and `--json` output stays one envelope. JSON mode and the `upgrade` exemption from the inline upgrade offer are read from the parsed command instead of scanning the raw arguments, so an option value spelled `--json` no longer switches the output to JSON and an argument that is merely the word `upgrade` no longer suppresses the offer. A thrown non-`Error` value is reported as its text instead of `undefined`, and `--verbose` explains why the compatibility manifest could not be fetched or read. JSON the CLI reads from `gh`, `claude` and `codex`, from the credential store and from the published compatibility manifest is now validated against a schema where it is parsed. A malformed or changed payload fails with `E_EXTERNAL_JSON_INVALID`, naming the command or file and each offending field, instead of a `TypeError` deep in a service; credential documents never echo their contents in the message. A legacy `~/.planr/credentials.json` that cannot be read is now kept for a later migration instead of being deleted as empty, and an off-schema compatibility manifest is ignored rather than cached. `openplanr template save --name` and `openplanr template delete` now accept only lowercase words joined by hyphens (such as `rest-endpoint`, at most 64 characters) and fail with `E_TEMPLATE_NAME_INVALID` for anything else, so a name like `../../package` or an absolute path can no longer write or delete a file outside `.planr/templates`. Both commands refuse a templates directory that links outside the planning directory (`E_TEMPLATE_DIR_OUTSIDE`), and `save` replaces an existing template file atomically instead of writing through a link. `openplanr operate dashboard` and `planr-pipeline dashboard` now load `startDashboard` from `planr-pipeline/dashboard` instead of the deprecated package-root alias. Behavior is unchanged; the command registry and its projection record the two changed command sources. The remaining source modules over 800 lines open with a short comment that names what the module owns and its entry points, and three module comments that misdescribed their files now match the code. Only comments change: code, exports and behaviour are unchanged, and the bundled dashboard assets differ only in their source-derived build id. Source modules over 800 lines open with a short comment that names what the module owns and its entry points, and several stale comments now match the code. Only comments change: code, exports and behaviour are unchanged, and the bundled dashboard assets differ only in their source-derived build id. `PLANR_HOME` now also relocates the CLI's runtime state and backups, the pipeline runtime lookup and `doctor`, and design share custody, as it already did for the design engine and the review and dashboard daemons. `OPENPLANR_HOME` is deprecated: when `PLANR_HOME` is unset it still resolves to `$OPENPLANR_HOME/.planr`, and it prints a one-time warning on stderr; when both are set, `PLANR_HOME` wins. Design share custody kept under `OPENPLANR_HOME` moves from `$OPENPLANR_HOME/design-shares` to `$OPENPLANR_HOME/.planr/design-shares`, so move that directory if you set the variable. The doctor skill documents both variables. --- title: openplanr 2.2639.3 description: Published 2026-09-27. The generated Claude Code plugin now ships a README.md beside plugin.json, rendered from a template with the current skill and agent… url: https://openplanr.dev/docs/changelog/2.2639.3 updated: 2026-09-27 related: - https://openplanr.dev/docs/changelog/2.2639.5.md - https://openplanr.dev/docs/changelog/2.2639.4.md - https://openplanr.dev/docs/changelog/2.2639.2.md --- # openplanr 2.2639.3 Published 2026-09-27. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.2639.3) ## Patch Changes The generated Claude Code plugin now ships a `README.md` beside `plugin.json`, rendered from a template with the current skill and agent counts and the plugin version, so the plugin folder meets the Anthropic plugin directory's README requirement. `plugin.json` also carries `displayName`, `homepage`, `repository`, and `keywords`. The Operate client's Assignment submission, governed Action and experience read transactions run from their own service modules under `dist/services/operate/`. `openplanr operate` behaviour and the exports of `services/operate/client.js` are unchanged. Recording a `rejected` or `deferred` Action approval through `operate.action.approve` now commits the decision and moves the Action to `rejected` or `deferred`. Previously the command failed with `STATE_TRANSITION_INVALID` ("operating-event: $ matched 0/57 branches") because the follow-up Action Event carried no reason, and the Action stayed `proposed`. --- title: openplanr 2.2639.2 description: Published 2026-09-25. openplanr init now creates .planr/specs/ when the new configuration turns on spec-driven mode, which the default configuration does. url: https://openplanr.dev/docs/changelog/2.2639.2 updated: 2026-09-25 related: - https://openplanr.dev/docs/changelog/2.2639.4.md - https://openplanr.dev/docs/changelog/2.2639.3.md - https://openplanr.dev/docs/changelog/2.2639.1.md --- # openplanr 2.2639.2 Published 2026-09-25. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.2639.2) ## Patch Changes `openplanr init` now creates `.planr/specs/` when the new configuration turns on spec-driven mode, which the default configuration does. A first run no longer leaves the project in spec-driven mode without its specs folder. The Operate review-note validator (`scripts/validate-note.mjs` in `planr-operate` and the seven review skills) now exits 0 when a note passes and 1 only when it reports diagnostics. It previously exited 1 on every note, including clean ones. Correct the setup documentation: `openplanr setup` installs `planr@openplanr-local` from the marketplace bundled with the installed package and never reads `openplanr/marketplace`. `CROSS_RUNTIME_SETUP.md` now lists the four installation channels and their status, and advises using one Claude Code channel per machine. `openplanr upgrade status` and `openplanr upgrade apply` now judge and prescribe the plugin `openplanr setup` installs, `planr@openplanr-local` from the bundled `openplanr-local` marketplace, instead of the retired `openplanr@openplanr` and `planr-pipeline@openplanr` plugins. After a CLI upgrade the prescribed commands refresh `openplanr-local`, update `planr@openplanr-local`, and remove leftover legacy plugins; when the marketplace was never registered the advice is `openplanr setup --runtime claude --scope user`. `openplanr setup` and `openplanr doctor` also warn when a marketplace-installed `planr@openplanr` sits beside `planr@openplanr-local` and give the exact `claude plugin uninstall` command to keep one, without removing anything themselves. --- title: openplanr 2.2639.1 description: Published 2026-09-24. No changes are listed for this version. url: https://openplanr.dev/docs/changelog/2.2639.1 updated: 2026-09-24 related: - https://openplanr.dev/docs/changelog/2.2639.3.md - https://openplanr.dev/docs/changelog/2.2639.2.md - https://openplanr.dev/docs/changelog/2.2639.0.md --- # openplanr 2.2639.1 Published 2026-09-24. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.2639.1) No changes are listed for this version. --- title: openplanr 2.2639.0 description: Published 2026-09-24. Releases are now numbered by release week. url: https://openplanr.dev/docs/changelog/2.2639.0 updated: 2026-09-24 related: - https://openplanr.dev/docs/changelog/2.2639.2.md - https://openplanr.dev/docs/changelog/2.2639.1.md - https://openplanr.dev/docs/changelog/2.6.3.md --- # openplanr 2.2639.0 Published 2026-09-24. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.2639.0) Releases are now numbered by release week. The middle number is the year and ISO week the release was prepared in (2026, week 39), and further releases in the same week raise the last number. The version still increases with every release, so existing `^2` ranges accept it. --- title: openplanr 2.6.3 description: Published 2026-09-24. No changes are listed for this version. url: https://openplanr.dev/docs/changelog/2.6.3 updated: 2026-09-24 related: - https://openplanr.dev/docs/changelog/2.2639.1.md - https://openplanr.dev/docs/changelog/2.2639.0.md - https://openplanr.dev/docs/changelog/2.6.2.md --- # openplanr 2.6.3 Published 2026-09-24. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.6.3) No changes are listed for this version. --- title: openplanr 2.6.2 description: Published 2026-09-23. Save complete authored diagram bundles with durable retries and recovery, render persisted geometry through a shared portable scene, and… url: https://openplanr.dev/docs/changelog/2.6.2 updated: 2026-09-23 related: - https://openplanr.dev/docs/changelog/2.2639.0.md - https://openplanr.dev/docs/changelog/2.6.3.md - https://openplanr.dev/docs/changelog/2.6.1.md --- # openplanr 2.6.2 Published 2026-09-23. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.6.2) ## Patch Changes Save complete authored diagram bundles with durable retries and recovery, render persisted geometry through a shared portable scene, and export immutable SVG, PNG and review HTML snapshots. Add explicit selected-layout previews and read-only legacy migration inspection without changing legacy sources. Add a portable diagram editor session with atomic gesture previews, conditional undo, indexed hit testing, bounded clipboard data and refresh recovery. A separate local owner transport saves complete authored bundles through the existing durable store without granting review sessions access to drafts. Editor controls and authoring CLI commands remain separate upcoming work. --- title: openplanr 2.6.1 description: Published 2026-09-22. Correct Codex inspection errors to identify the CLI's bundled host package and the setup repair command. url: https://openplanr.dev/docs/changelog/2.6.1 updated: 2026-09-22 related: - https://openplanr.dev/docs/changelog/2.6.3.md - https://openplanr.dev/docs/changelog/2.6.2.md - https://openplanr.dev/docs/changelog/2.6.0.md --- # openplanr 2.6.1 Published 2026-09-22. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.6.1) ## Patch Changes Correct Codex inspection errors to identify the CLI's bundled host package and the setup repair command. Make professional-skill catalog reads work in an isolated pipeline installation by defaulting to its bundled compatibility snapshots. Current-source inspection and evaluation now require an explicit source root instead of reading retired package host trees. Build pipeline compatibility projections from canonical workspace sources during packaging, preserving the self-contained published package. Validate generated archive contents against the existing projection manifests. --- title: openplanr 2.6.0 description: Published 2026-09-22. Add the five-step Design Handoff Center, including server-projected readiness, review resolution, implementation package composition,… url: https://openplanr.dev/docs/changelog/2.6.0 updated: 2026-09-22 related: - https://openplanr.dev/docs/changelog/2.6.2.md - https://openplanr.dev/docs/changelog/2.6.1.md - https://openplanr.dev/docs/changelog/2.5.0.md --- # openplanr 2.6.0 Published 2026-09-22. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.6.0) ## Minor Changes Add the five-step Design Handoff Center, including server-projected readiness, review resolution, implementation package composition, exact owner approval, and an explicit zero-effect Continue to Plan handoff. --- title: openplanr 2.5.0 description: Published 2026-09-21. Add Protocol 1.11 contracts for design handoff readiness, implementation packages, and planning lineage. url: https://openplanr.dev/docs/changelog/2.5.0 updated: 2026-09-21 related: - https://openplanr.dev/docs/changelog/2.6.1.md - https://openplanr.dev/docs/changelog/2.6.0.md - https://openplanr.dev/docs/changelog/2.4.0.md --- # openplanr 2.5.0 Published 2026-09-21. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.5.0) ## Minor Changes Add Protocol 1.11 contracts for design handoff readiness, implementation packages, and planning lineage. Design now exposes a deterministic fail-closed readiness compiler, while pipeline and installed OpenPlanr skill packages carry the exact generated contracts for offline validation. The new records authorize only an explicit continuation to Plan; they do not invoke Plan, Ship, Git, release, publication, or deployment actions. ## Patch Changes Reconcile every design review comment into one deterministic, revision-bound owner-decision projection. Keep resolved comments visible, block stale accepted work and unresolved blockers, normalize unambiguous legacy metadata, and verify hosted feedback replay, ordering, and receipts before reporting synchronization success. Bind Design implementation approval to the exact reviewed package and preserve immutable version history. Add auditable supersession and revocation, deterministic comparison, idempotent retries, crash recovery, authorization checks, and owner-only daemon actions that grant only preparation for Plan. Compose compact design implementation packages from exact repository-relative references and stable numbered requirements. Add byte-stable JSON and Markdown projections, offline import/export, source verification, crash recovery, and owner-only Design Studio daemon operations without copying canonical design bodies or invoking Plan or Ship. Connect approved Design implementation packages to explicit host-native Plan handoffs, atomic requirement-to-acceptance-to-task lineage, task-scoped Ship context, and read-only delivery status. Preserve ordinary no-design Plan and Ship behavior while reporting stale package context honestly across generated Claude Code, Codex, ChatGPT, and Cursor skills. --- title: openplanr 2.4.0 description: "Published 2026-09-21. openplanr diagram render, rerender, inspect and check now report the rendered set's quality in their JSON envelope: a quality object with…" url: https://openplanr.dev/docs/changelog/2.4.0 updated: 2026-09-21 related: - https://openplanr.dev/docs/changelog/2.6.0.md - https://openplanr.dev/docs/changelog/2.5.0.md - https://openplanr.dev/docs/changelog/2.3.0.md --- # openplanr 2.4.0 Published 2026-09-21. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.4.0) ## Minor Changes `openplanr diagram render`, `rerender`, `inspect` and `check` now report the rendered set's quality in their JSON envelope: a `quality` object with `status`, `failedChecks` and `warningChecks`, and one `warnings` entry per failed or warning check. A set whose quality is `invalid` returns no `nextAction`, so an agent does not hand over a diagram the engine could not lay out. An unreadable quality report is reported as a warning with no summary rather than failing the command. The `planr-diagram` skill reads the new field, treats anything other than `pass` as unfinished, and gains authoring guidance for lane grammars now that the engine draws them. --- title: openplanr 2.3.0 description: Published 2026-09-18. The planr-diagram skill (1.1.0) gains layout heuristics (flow direction, fan-out and node budgets, relation kinds, when a back edge or a… url: https://openplanr.dev/docs/changelog/2.3.0 updated: 2026-09-18 related: - https://openplanr.dev/docs/changelog/2.5.0.md - https://openplanr.dev/docs/changelog/2.4.0.md - https://openplanr.dev/docs/changelog/2.2.2.md --- # openplanr 2.3.0 Published 2026-09-18. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.3.0) ## Minor Changes The `planr-diagram` skill (1.1.0) gains layout heuristics (flow direction, fan-out and node budgets, relation kinds, when a back edge or a group is acceptable) and a mandatory look-before-handover step that treats a passing quality report as necessary but not sufficient. --- title: openplanr 2.2.2 description: "Published 2026-09-18. Rewrite the package README and shipped guides around the product as it ships today: install and quick start for Claude Code, Codex, and…" url: https://openplanr.dev/docs/changelog/2.2.2 updated: 2026-09-18 related: - https://openplanr.dev/docs/changelog/2.4.0.md - https://openplanr.dev/docs/changelog/2.3.0.md - https://openplanr.dev/docs/changelog/2.2.1.md --- # openplanr 2.2.2 Published 2026-09-18. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.2.2) ## Patch Changes Rewrite the package README and shipped guides around the product as it ships today: install and quick start for Claude Code, Codex, and Cursor, the command groups, the skills each host installs, and current troubleshooting. Retired commands, plugin identities, and provider language are removed. --- title: openplanr 2.2.1 description: Published 2026-09-18. Stamp the generated Claude, Codex and Cursor plugin manifests, the local marketplaces and the host adapter registry with the CLI package… url: https://openplanr.dev/docs/changelog/2.2.1 updated: 2026-09-18 related: - https://openplanr.dev/docs/changelog/2.3.0.md - https://openplanr.dev/docs/changelog/2.2.2.md - https://openplanr.dev/docs/changelog/2.2.0.md --- # openplanr 2.2.1 Published 2026-09-18. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.2.1) ## Patch Changes Stamp the generated Claude, Codex and Cursor plugin manifests, the local marketplaces and the host adapter registry with the CLI package version instead of a fixed `0.1.0`, so `openplanr runtime update` and the host plugin panels see a real version change on every release. --- title: openplanr 2.2.0 description: "Published 2026-09-18. Add the storage layer for the planr:sprint skill: openplanr sprint refinement <id> --data validates a refinement document, writes…" url: https://openplanr.dev/docs/changelog/2.2.0 updated: 2026-09-18 related: - https://openplanr.dev/docs/changelog/2.2.2.md - https://openplanr.dev/docs/changelog/2.2.1.md - https://openplanr.dev/docs/changelog/2.1.1.md --- # openplanr 2.2.0 Published 2026-09-18. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.2.0) ## Minor Changes Add the storage layer for the `planr:sprint` skill: `openplanr sprint refinement <id> --data` validates a refinement document, writes `.planr/sprints/<id>/refinement.{json,md}` and fills the sprint's `## Tasks` with one checkbox per selected item grouped by batch; `openplanr sprint diff` compares two runs; `openplanr sprint apply` writes the approved status changes (optionally as one `chore(planr): refine backlog for <id>` commit); `openplanr sprint close` records leftovers. Sprints gain `releaseCut`, `capacityDays`, `refinedAt` and `closedAt`; the sprint status vocabulary is `planned`, `active`, `closed`; `openplanr status` reports the active sprint with its cut and progress; graph readers skip `sprints/SPRINT-NNN/` note directories. --- title: openplanr 2.1.1 description: Published 2026-09-17. Keep plugins outside the expected marketplace ids out of the openplanr upgrade status verdict; they stay listed for openplanr doctor's… url: https://openplanr.dev/docs/changelog/2.1.1 updated: 2026-09-17 related: - https://openplanr.dev/docs/changelog/2.2.1.md - https://openplanr.dev/docs/changelog/2.2.0.md - https://openplanr.dev/docs/changelog/2.1.0.md --- # openplanr 2.1.1 Published 2026-09-17. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.1.1) ## Patch Changes Keep plugins outside the expected marketplace ids out of the `openplanr upgrade status` verdict; they stay listed for `openplanr doctor`'s warning instead of turning a current installation `incompatible`. --- title: openplanr 2.1.0 description: "Published 2026-09-17. Generate an ## OpenPlanr capabilities section into CLAUDE.md and AGENTS.md listing every skill with its triggers (and the delegated…" url: https://openplanr.dev/docs/changelog/2.1.0 updated: 2026-09-17 related: - https://openplanr.dev/docs/changelog/2.2.0.md - https://openplanr.dev/docs/changelog/2.1.1.md - https://openplanr.dev/docs/changelog/2.0.1.md --- # openplanr 2.1.0 Published 2026-09-17. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.1.0) ## Minor Changes Generate an `## OpenPlanr capabilities` section into `CLAUDE.md` and `AGENTS.md` listing every skill with its triggers (and the delegated agents for Claude Code), and add the `planr-openplanr` router skill that picks the best OpenPlanr skill for a request. ## Patch Changes Reconcile `openplanr upgrade status` against the npm registry's published CLI and the pipeline it bundles instead of the retired marketplace manifest, and report a leftover legacy host plugin as the incompatibility. --- title: openplanr 2.0.1 description: Published 2026-09-17. No changes are listed for this version. url: https://openplanr.dev/docs/changelog/2.0.1 updated: 2026-09-17 related: - https://openplanr.dev/docs/changelog/2.1.1.md - https://openplanr.dev/docs/changelog/2.1.0.md - https://openplanr.dev/docs/changelog/2.0.0.md --- # openplanr 2.0.1 Published 2026-09-17. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.0.1) No changes are listed for this version. --- title: openplanr 2.0.0 description: Published 2026-09-17. Move semantic planning and implementation into the active coding agent. url: https://openplanr.dev/docs/changelog/2.0.0 updated: 2026-09-17 related: - https://openplanr.dev/docs/changelog/2.1.1.md - https://openplanr.dev/docs/changelog/2.1.0.md - https://openplanr.dev/docs/changelog/2.0.1.md --- # openplanr 2.0.0 Published 2026-09-17. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/openplanr%402.0.0) ## Major Changes Move semantic planning and implementation into the active coding agent. This is a breaking CLI change: `openplanr plan`, `openplanr spec decompose`, and the model-backed pipeline, estimate, refine, revise, and evidence command roots are retired. The CLI no longer accepts AI-provider configuration or calls model providers. Use the installed Plan, Spec, Ship, and review skills for semantic work, with the current repository context and the host's own models and tools. Existing manual artifact CRUD, document readers, integration commands, rendering, local studios, dashboard, setup, and diagnostics remain available. Existing `planr`, `openplanr`, and `opr` binary names still use the same parser. ## Minor Changes Consolidate the portable OpenPlanr product into one reproducible monorepo with explicit package ownership, generated host adapters, preserved compatibility lineages, and isolated packed-package verification. Keep the CLI and pipeline self-contained for consumers without sibling repositories or private workspace dependencies. Add permanent encrypted design reviews with separately entered access tokens, explicit revision publishing, private local owner custody, and synchronized revision-bound feedback. Fix Notes dismissal and unavailable sharing controls. Render sequence diagrams as readable time-ordered conversations with participant headers, lifelines, phases, distinct message rows, annotations, and emphasis. Detect overlapping rendered labels, support sequence Mermaid and Excalidraw round trips, and open verified diagram manifests in the native Diagram studio after rendering. Use one SVG camera with outline/search, fit controls, compact persisted comments, and verified drawing and agent review exports; avoid fixed document frames and nested scrolling. Shorten unified-plugin invocations to `planr:<verb>` across Codex and Claude Code while preserving canonical `planr-*` skill identities and Cursor rules. Migrate managed local installations from the former `openplanr` plugin namespace after the replacement package is installed. Complete the design studio's team review flow with reviewer orientation, adjustable panels, thumbnails, organized feedback, revision comparison, canvas navigation, and a read-only implementation inspector. Add revision-bound owner dispositions and explicit review handoff drafts and approvals. Preserve existing design documents and shared URLs, and package the same deterministic tools for standalone skills and hosted reviews. Bound live previews on touch devices, load the opening screen first, and release older previews while preserving review drafts. Navigation waits for an authenticated destination frame before revealing it; failed previews can be retried. Desktop canvases retain their existing loading behavior. ## Patch Changes Make the local planning console easier to operate on real projects: stage dependency graphs by delivery order, contain board scrolling within each status column, present readable inspector metadata with route feedback, and turn sprint records into delivery workspaces that include scope, blockers, and current Operate context. Update the bundled dashboard to React Router 7.18.3, closing the current production security advisories while preserving the existing routing contract. Turn completed local Operate reviews into a structured, read-only operating console with distinct decision, action, lens, evidence, outcome, history, and recovery views. Keep the board report available as the durable audit record. --- title: openplanr 1.25.3 description: Published 2026-08-05. Ship with planr-pipeline@0.42.0, which requires an explicit protocolVersion when building a legacy advisor brief. url: https://openplanr.dev/docs/changelog/1.25.3 updated: 2026-08-05 related: - https://openplanr.dev/docs/changelog/1.25.2.md - https://openplanr.dev/docs/changelog/1.25.1.md - https://openplanr.dev/docs/changelog/1.25.0.md --- # openplanr 1.25.3 Published 2026-08-05. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.25.3) ## Patch Changes Ship with `planr-pipeline@0.42.0`, which requires an explicit `protocolVersion` when building a legacy advisor brief. The previous silent default allowed a frozen v1.2 contract to reach a Protocol v1.4 mandate. --- title: openplanr 1.25.2 description: Published 2026-08-05. Close the operate defects a live board cycle surfaced. url: https://openplanr.dev/docs/changelog/1.25.2 updated: 2026-08-05 related: - https://openplanr.dev/docs/changelog/1.25.3.md - https://openplanr.dev/docs/changelog/1.25.1.md - https://openplanr.dev/docs/changelog/1.25.0.md --- # openplanr 1.25.2 Published 2026-08-05. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.25.2) ## Patch Changes Close the operate defects a live board cycle surfaced. The v1.4 mandate disclosed the frozen v1.2 response schema while enforcing v1.4, so an advisor that followed the disclosed contract failed validation every time — the self-describing contract was confidently wrong rather than merely absent. The disclosure is now resolved from the mandate's own `responseSchema`, bundled self-contained, and bounded to what a v1.4 action can express. Recording an advisor result discarded the whole result on any secret detection, including the soft categories meant to be redacted rather than blocked; a legitimate analysis was rejected for quoting a public workflow permission line. The record paths now block only on hard categories and report every offending field at once. `status`, `review`, and the cycle report claimed a quiet board and a reached review gate while a cycle sat in `advising` with recorded actions on disk. A blocked second binding was handed the command that had just failed as its recovery. `inspect` advertised the frozen artifact-envelope version instead of the protocol mandates are enforced at. --- title: openplanr 1.25.1 description: Published 2026-08-04. Fix openplanr setup failing against the published plugin tuple. url: https://openplanr.dev/docs/changelog/1.25.1 updated: 2026-08-04 related: - https://openplanr.dev/docs/changelog/1.25.3.md - https://openplanr.dev/docs/changelog/1.25.2.md - https://openplanr.dev/docs/changelog/1.25.0.md --- # openplanr 1.25.1 Published 2026-08-04. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.25.1) ## Patch Changes Fix `openplanr setup` failing against the published plugin tuple. The CLI pins its pipeline sibling exactly in `optionalDependencies`, and at runtime resolves the installed copy's version to decide which Claude plugin version to expect — compared by strict equality. The 1.25.0 release shipped that pin at `0.40.0` while publishing alongside pipeline `0.41.0`, so every `planr setup` on a correctly-installed machine failed `E_CLAUDE_PLUGIN_UPDATE_FAILED` and rolled back, reporting the user's newer plugin as drift. The skills plugin target was stale for the same reason (`1.26.0`, published `1.26.1`), silently omitting it from prescriptions. Both pins now track the released tuple, and a new parity guard compares the declared pin against the pipeline revision the environment resolves — the same guard the skills bundle already had, which is why the release canary caught its stale pin and nothing caught this one. No existing test could: the suites set `OPENPLANR_PIPELINE_ROOT` to a source checkout, which bypasses the node_modules resolution the pin governs. --- title: openplanr 1.25.0 description: Published 2026-08-04. Make the Operating Board's contracts visible to the agents they bind, and its state visible to the surfaces that render it. url: https://openplanr.dev/docs/changelog/1.25.0 updated: 2026-08-04 related: - https://openplanr.dev/docs/changelog/1.25.2.md - https://openplanr.dev/docs/changelog/1.25.1.md - https://openplanr.dev/docs/changelog/1.24.1.md --- # openplanr 1.25.0 Published 2026-08-04. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.25.0) ## Minor Changes Make the Operating Board's contracts visible to the agents they bind, and its state visible to the surfaces that render it. A full board cycle run through real coding agents took fourteen schema rejections, three lease expiries, and a Chair that could only be recorded with zero actions — every failure traced to a contract that was enforced precisely and disclosed nowhere. This release fixes the habit, not just the symptoms. **The response contract ships inside every mandate.** `harness prepare` now discloses the response `jsonSchema`, the per-role proposal cap, and the allowed proposal types — the exact values the record path enforces. A new `openplanr operate harness validate` dry-run checks a payload with the same validator as `record`, returns **every** violation in one response, and consumes no lease and no idempotency key. **The Chair can propose again.** Its proposal bounds are now derived from the operating registry — the runtime and the registry can no longer disagree — so a consolidation with real route proposals records instead of being rejected wholesale. Registry agreement is asserted for every role by iterating the registry itself. **Citations accept what mandates authorize.** The record-time anchor is aligned with the v1.4 citation contract: dot-prefixed roots (`.github`, `.planr`, …) anchor with line precision; backlog (`BL-`) and quick-task (`QT-`) artifacts are citable; citations into sibling workspace components resolve against that component's checkout, and a component that cannot be resolved is reported honestly as unresolved — never as fabricated. A second stale copy of the old pattern in the git read layer was found and aligned too. **The lease is a visible deadline.** Every harness handoff carries `session.expiresAt` and `leaseTtlSeconds`; recording renews the lease; the default window now comfortably outlasts a long single-agent dispatch and is tunable via `OPENPLANR_ADAPTER_LEASE_MS`. **The dashboard can finally see cycles.** The CLI emits a public, read-only projection at the paths the pipeline dashboard reads — a deliberate un-retirement of the v1.3 path as a derived surface, including a fix for a storage-migration collision that would otherwise have silently deleted the projection on the next write. **The CLI stops succeeding silently.** The non-interactive `operate init` that printed nothing and exited 0 now states what input is needed and exits with the input-required code; unrecognized result shapes always render something; `inspect` points first-time users at the research-first path; and `openplanr operate report --html` renders a cycle as a self-contained page ready for `openplanr artifact open`. **Commitment conflicts are representable and visible.** An advisor can record a conflict between an action and a published commitment (one action key plus the commitment reference), and the rendered conflict line carries the commitment's statement and source. A cross-component conformance suite now asserts the seams that failed — mandate roots are citable, registry equals runtime, the projection writer and the dashboard reader name the same paths, disclosed contracts equal enforced contracts — so this class of skew fails CI instead of a live cycle. The release workflow also gains a post-publish check that turns manifest drift into a red run instead of a silent gap. --- title: openplanr 1.24.1 description: Published 2026-08-04. Report an invalid .planr/config.json as an actionable error instead of a raw stack trace. url: https://openplanr.dev/docs/changelog/1.24.1 updated: 2026-08-04 related: - https://openplanr.dev/docs/changelog/1.25.1.md - https://openplanr.dev/docs/changelog/1.25.0.md - https://openplanr.dev/docs/changelog/1.24.0.md --- # openplanr 1.24.1 Published 2026-08-04. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.24.1) ## Patch Changes Report an invalid `.planr/config.json` as an actionable error instead of a raw stack trace. `targets` and `createdAt` are the two config fields required with no default, while every other field defaults. A config missing either — hand-edited, partially written, or hand-authored — crashed **every** config-reading command with an unhandled `ZodError` stack trace, because the CLI's top-level handler rethrows anything without an `E_` code. The failure now names the file, every failing field with its path, and the command to repair it, exiting cleanly through the handler's existing error contract. A genuinely missing required field still fails — it just says so legibly rather than dumping a trace. Make `setup` and `doctor` describe the install they actually produced. **`doctor` names the skill file that exists.** Its three `operate-skill` messages hardcoded the namespaced `planr-operate`, so a `--no-prefix` install — where the file on disk is `operate` — got a diagnostic with the right status about a filename the user does not have. All three now interpolate the installed name. **The setup preview states the naming scheme.** The choice is persisted per project, so a plain re-run could install bare verbs with nothing in the summary saying so. The preview now reports `Command names: namespaced` or `bare (--no-prefix)`, resolved from the same value the installer uses. **The Cursor no-op is now pinned by a test.** `applyCommandPrefix` is threaded through the Cursor branch but computes identity there, since no Cursor rule filename starts with `planr-`. That "intentional symmetry, not dead code" claim rested entirely on a source comment; a later broadening of the prefix match would have silently begun renaming Cursor rules with nothing to catch it. Stop `openplanr upgrade` from offering a downgrade, and make it actually print the plugin-half commands it promises. **An installed version ahead of the registry is no longer an "upgrade".** Drift was computed as plain inequality, so "different" and "older" were the same thing: anyone on a build ahead of published — a linked dev build, a prerelease, a maintainer mid-release — was offered a downgrade labelled as an upgrade, and accepting "always keep me current" would have rolled the newer build back on every invocation. Only a version strictly _behind_ now counts. Range violations are untouched, since those are direction-independent. **The prescription is no longer promised and withheld.** When the CLI is already current but the host plugins trail — the state every release creates for anyone who upgrades the npm half first — `apply` returned early with a message ending "run the prescribed commands below" and then printed nothing, on both the human and `--json` surfaces. The commands are now built on that path too, from the same helpers the post-upgrade path uses, so the two can never print different instructions for the same machine. **The skills plugin is no longer silently omitted.** The version the CLI targets for the skills bundle had drifted three releases behind, and because the prescription derives its target from it, a genuinely stale skills plugin was left out of the commands entirely — a user could run every prescribed command and still be behind, believing they were current. --- title: openplanr 1.24.0 description: Published 2026-08-03. Make openplanr setup a front door that reports honestly, recovers cleanly, and remembers what you named things (SPEC-007 FR3, FR4, FR5). url: https://openplanr.dev/docs/changelog/1.24.0 updated: 2026-08-03 related: - https://openplanr.dev/docs/changelog/1.25.0.md - https://openplanr.dev/docs/changelog/1.24.1.md - https://openplanr.dev/docs/changelog/1.23.0.md --- # openplanr 1.24.0 Published 2026-08-03. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.24.0) ## Minor Changes Make `openplanr setup` a front door that reports honestly, recovers cleanly, and remembers what you named things (SPEC-007 FR3, FR4, FR5). **Every skip is reported.** The non-guided setup preview now prints a `Skipped:` block naming each runtime the run dropped and why — one that requires project scope while the run defaulted to user scope ("requires project scope"), and one that is not installed ("not detected on PATH"). Previously this existed only in the guided wizard, so a flag-driven install could skip a runtime silently. Detecting nothing was already a clear error; now a partial skip is reported too. **A partial apply is never reported as success.** At setup's one remaining partial-apply seam, a failing Claude plugin step now restores the owned files from the backup taken before mutating, and the error states plainly what was restored, naming every path. If the restore itself fails, both failures surface with the backup location — the failure during a failure is never swallowed. Proven by a forced-failure test that lets inspection succeed so owned files are genuinely written, then fails the first mutating command, and asserts the file is returned to its pre-setup state and the project record cleared. **Command names are your choice, and they persist.** `openplanr setup --no-prefix` installs the workflows under bare verbs (`plan`, `ship`, `operate`, …); `--prefix` keeps the namespaced names (`planr-plan`, …). For Codex the choice controls both the installed skill directory and the skill's frontmatter `name:`; for Cursor it flows through the installed rule filenames. The choice is recorded on the per-project runtime-state record and read back on every later run, so an upgrade or a plain re-run never silently changes what you type. The default stays namespaced and the transform is identity in that mode, so an install that never opts in is byte-identical to before and existing installs keep their current names — nothing is force-renamed. `openplanr doctor` honours the same persisted choice: it now diagnoses the installed operate skill under the name the installer actually wrote, so a bare install is validated on its content instead of being falsely reported missing — which previously also caused the skill's content contract to be silently skipped. --- title: openplanr 1.23.0 description: Published 2026-08-03. Installed-tuple reconciliation and a safe, honest upgrade path (SPEC-006). url: https://openplanr.dev/docs/changelog/1.23.0 updated: 2026-08-03 related: - https://openplanr.dev/docs/changelog/1.24.1.md - https://openplanr.dev/docs/changelog/1.24.0.md - https://openplanr.dev/docs/changelog/1.22.0.md --- # openplanr 1.23.0 Published 2026-08-03. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.23.0) ## Minor Changes Installed-tuple reconciliation and a safe, honest upgrade path (SPEC-006). Until now the CLI could tell you your install had drifted and then leave you to derive the fix yourself across two package managers. `doctor` already computed component, digest, adapter, and CLI drift correctly — nothing acted on it, and nothing read back the compatibility ranges the ecosystem manifest already publishes. **Reconcile the installed tuple, not "is something newer".** A new `openplanr upgrade status [--json]` reads the published compatibility manifest, compares it against the real installed tuple — this CLI plus both host-plugin versions — and reports `aligned`, `upgrade-available`, `incompatible`, or `unknown`. The warn-versus-fail distinction is not re-derived: `doctor`'s inline lock-drift classification is extracted into a single exported `classifyComponentDrift` that both surfaces call, so a CLI merely trailing an upgrade stays a warning while a genuinely incompatible tuple fails. Every pre-existing `doctor` assertion passes unchanged as proof the extraction preserved its behaviour. An absent plugin is recorded as absent, never as a violation, so a planning-only install does not read as broken. **Offline capability is preserved by construction.** The manifest fetch trusts a short-TTL cache without any network round-trip, carries a hard timeout that wins even when a fetch hangs, falls back to a stale cache when the network fails, and reports `unknown` when there is neither — so a captive portal, a VPN, or an airplane can never make `planr` block. Proven by offline and hung-network tests and by a packed-install end-to-end test that reads the real installed version rather than a fixture. **Execute the half it owns; prescribe the half it cannot.** `openplanr upgrade apply [--yes] [--json]` performs `npm install -g openplanr@<target>` and prints the plugin commands it structurally cannot run — plugin installation is a host command, not something a CLI can own. The prescription is rendered from the plugin integration's own operation list, so the printed commands can never drift from what an apply would really run, and the marketplace-refresh command is always placed first: without it the installer reinstalls the stale version and the user believes they upgraded. A grep gate proves the upgrade service never imports the plugin-apply path, and an end-to-end test proves no mutating plugin command is ever spawned. **A partially-upgraded install can never report success.** The previously installed version is captured as a restorable backup before any mutation, and the on-disk version is re-read afterwards. A clean exit that did not land the target restores the previous version automatically and states exactly what was restored and how to retry. On success, the changelog entries strictly between the old and new version are summarised verbatim — never inventing a change the changelog does not carry — and `CHANGELOG.md` now ships in the package so that summary works on a real installation rather than only in-repo. **The offer comes to you.** An available upgrade now surfaces on an ordinary interactive command as a four-way choice — upgrade now · always keep me current · not now · never ask — so nobody has to run a diagnostic to discover they are stale; accepting resumes the command you originally invoked. "Not now" snoozes with escalating backoff (24 hours, then 48, then a week) so it never nags. `auto_upgrade` and `update_check` are real settings, neither inferred from a bare invocation, and "never ask again" is a permanent opt-out that always states the exact command reversing it. A snooze, a never-ask, or a disabled check short-circuits before any reconcile, so a command that already declined touches no network and adds no delay; the state file is read fail-open, and the offer never surfaces for machine-readable or non-interactive invocations. **Upgrades can now carry state forward.** Idempotent migrations keyed to a version run automatically when an upgrade crosses that version, for state a reinstall cannot repair — stale config, orphaned files, a changed on-disk layout. A strict lower bound means a migration at or below the installed version never re-runs, and one migration failing neither aborts the others nor is swallowed into an overall success. The legacy operating-profile migration is registered as the proving case by delegating to the existing implementation, reusing its exact-backup, journalled write with rollback, and idempotency guarantees rather than forking them; the standalone `operate profiles migrate` command keeps working unchanged. A migration failure reports failure while still reporting the npm step's real success, so a half-migrated install can never claim to be clean. --- title: openplanr 1.22.0 description: "Published 2026-08-03. Operate durable orchestration (SPEC-005): per-role durability, honest state, and a one-invocation review gate." url: https://openplanr.dev/docs/changelog/1.22.0 updated: 2026-08-03 related: - https://openplanr.dev/docs/changelog/1.24.0.md - https://openplanr.dev/docs/changelog/1.23.0.md - https://openplanr.dev/docs/changelog/1.21.2.md --- # openplanr 1.22.0 Published 2026-08-03. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.22.0) ## Minor Changes Operate durable orchestration (SPEC-005): per-role durability, honest state, and a one-invocation review gate. Bundled pipeline dependency pinned to `planr-pipeline@0.39.0`. Every claim below is backed by a named passing test; coordinated sibling releases still in flight under this same version are described as landing with the release, never as a phase this repository has already verified. **The field fix that matters most: the advisor fan-out no longer deadlocks on a hung lens.** The pre-driver fan-out awaited every advisor together, so one lens stalling left the whole `Promise.all` unresolved while completed analyses sat unrecorded and the shared lease expired underneath them. Dispatch now runs through a deterministic lifecycle driver with bounded per-role retry, a per-attempt timeout, and an automatic lease heartbeat that renews independently of any role recording. A stalled non-required lens is resolved `not_evaluated` with a governed gap while its siblings record and the cycle reaches Chair. Proven by `tests/integration/operate-lifecycle-chair-wiring.test.ts` ("terminates a stalled lens not_evaluated while siblings record, renews the lease, and reaches Chair") and `tests/unit/operate-lifecycle-driver.test.ts` ("resolves a role past its retry budget to not_evaluated with a governed gap without blocking siblings" and "renews the lease as the window approaches without any role completing"). **Immediate per-role commit and an engine-managed heartbeat lease.** Each advisor result is validated, recorded, persisted, and reflected in cycle progress the moment it returns, and survives a sibling stalling; recording never waits on the batch. Proven by the lifecycle-driver state-machine and heartbeat suites in `tests/unit/operate-lifecycle-driver.test.ts`. **Partial validated progress and honest status/report.** Every recorded lens is inspectable before Chair finalizes, and a mid-cycle report renders recorded lenses with their real analysis plus the exact recovery action for pending roles — an active advising cycle is never described as quiet. Proven by `tests/integration/operate-partial-report.test.ts` ("renders recorded lenses with their real analysis and the exact recovery action for pending roles"). **Chair works with partial valid boards.** Chair consolidates the recorded, verified board and surfaces an absent lens as an explicit gap; it never invents a missing lens's conclusions, and it stays closed while a structurally-required role is only `not_evaluated`. Proven by `tests/unit/operate-lifecycle-driver.test.ts` ("holds the Chair closed while a structurally-required role is only not_evaluated") and the chair-wiring happy-path test above ("records a five-lens board and reaches Chair with no fabricated gap on the happy path"). **Owned scratch storage with a `doctor --fix` cleanup.** Operate scratch lives under an OpenPlanr-owned, project-and-machine-keyed path recorded in an ownership manifest, cleaned automatically after record/finalize, detected by `doctor` when abandoned, and removed by the FR7-named `openplanr doctor --fix` — which acts only on scratch a valid ownership manifest confirms is ours, never on an unrelated file under the scratch tree. Proven by `tests/unit/operate-doctor-staleness.test.ts` ("warns on abandoned owned scratch and removes only it, leaving other machine-local caches") and `tests/unit/operate-doctor-fix-wiring.test.ts` ("removes abandoned OpenPlanr-owned scratch and leaves an unrelated file untouched"). **Completion discipline.** Completion requires on-disk verification of every phase-F artifact and flips to incomplete when any is removed or abandoned owned scratch remains. Proven by `tests/unit/operate-completion.test.ts` ("reports complete only with every phase-F artifact, and flips when any is removed"). **Legacy operating-profile migration.** `openplanr operate profiles migrate inspect|apply` detects a legacy profile, previews and converts the supported subset, writes an exact pre-migration backup, and is idempotent — the CLI never suggests a profile it will reject. Proven by `tests/unit/operate-profile-migration.test.ts` ("writes an exact pre-migration backup and rewrites the profile to the supported subset" and "is idempotent: a second apply reports already-applied and makes no further change"). **Bundled pipeline pin.** The packed CLI carries `optionalDependencies.planr-pipeline = 0.39.0`, asserted by `tests/e2e/operate-packed-install.test.ts` and `tests/e2e/operate-guided-packed-install.test.ts`. Coordinated, not yet released with this changeset: `@openplanr/skills@1.24.0` (thin workflow regeneration) and the marketplace ledger and real-runtime canary land only after `planr-pipeline@0.39.0` and this `openplanr` version publish. --- title: openplanr 1.21.2 description: Published 2026-08-02. Align the bundled pipeline dependency with planr-pipeline 0.38.0. url: https://openplanr.dev/docs/changelog/1.21.2 updated: 2026-08-02 related: - https://openplanr.dev/docs/changelog/1.23.0.md - https://openplanr.dev/docs/changelog/1.22.0.md - https://openplanr.dev/docs/changelog/1.21.1.md --- # openplanr 1.21.2 Published 2026-08-02. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.21.2) ## Patch Changes Align the bundled pipeline dependency with planr-pipeline 0.38.0. --- title: openplanr 1.21.1 description: Published 2026-08-02. Align the bundled pipeline with planr-pipeline 0.37.2 so released Operate canaries execute correctly through the Windows command shim. url: https://openplanr.dev/docs/changelog/1.21.1 updated: 2026-08-02 related: - https://openplanr.dev/docs/changelog/1.22.0.md - https://openplanr.dev/docs/changelog/1.21.2.md - https://openplanr.dev/docs/changelog/1.21.0.md --- # openplanr 1.21.1 Published 2026-08-02. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.21.1) ## Patch Changes Align the bundled pipeline with planr-pipeline 0.37.2 so released Operate canaries execute correctly through the Windows command shim. --- title: openplanr 1.21.0 description: Published 2026-08-02. Rebuild openplanr operate around agent-native, runtime-bound research, six advisory roles, expressive cited reports, and approval-gated… url: https://openplanr.dev/docs/changelog/1.21.0 updated: 2026-08-02 related: - https://openplanr.dev/docs/changelog/1.21.2.md - https://openplanr.dev/docs/changelog/1.21.1.md - https://openplanr.dev/docs/changelog/1.20.0.md --- # openplanr 1.21.0 Published 2026-08-02. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.21.0) ## Minor Changes Rebuild `openplanr operate` around agent-native, runtime-bound research, six advisory roles, expressive cited reports, and approval-gated canonical proposal drafts across Claude Code, Codex, and Cursor. --- title: openplanr 1.20.0 description: Published 2026-08-01. The Operating Board harness pivot for openplanr operate (SPEC-004), the openplanr minor bump 1.19.0 → 1.20.0 — the agent is the engine;… url: https://openplanr.dev/docs/changelog/1.20.0 updated: 2026-08-01 related: - https://openplanr.dev/docs/changelog/1.21.1.md - https://openplanr.dev/docs/changelog/1.21.0.md - https://openplanr.dev/docs/changelog/1.19.0.md --- # openplanr 1.20.0 Published 2026-08-01. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.20.0) ## Minor Changes The Operating Board harness pivot for `openplanr operate` (SPEC-004), the `openplanr` minor bump 1.19.0 → 1.20.0 — the agent is the engine; the CLI harnesses, verifies, and records. Every landed claim below is backed by a named proof; coordinated sibling work still completing under this same version is described as landing with the release, never as a phase this repository has already verified. **The mandate replaces the collector as the unit of dispatch.** A per-role operating mandate carries the lens question, declared read boundaries (workspace roots — including the `.planr/` tree — a sensitivity ceiling, and forbidden paths), a required response schema, and a citation requirement, and it carries no evidence bodies and no evidence index — structurally forbidden rather than merely omitted. Proven by `tests/unit/operate-adapter-mission-dispatch.test.ts` ("prepares a mandate (not a pack) with declared boundaries and no evidence body ..."), whose fixture fails if any file body ever leaks into the body-free, index-free mandate. **Evidence is an output, not an input, and citation resolution is the universal gate.** `adapter record` resolves every citation in a response fail-closed and mints the evidence-of-record from what was actually cited. A fabricated path, a wrong line range, a moved revision, or a citation above the role's sensitivity ceiling each becomes a governed gap — on every dispatch path and every source — and a response resolving zero citations records its role `not_evaluated` with a governed gap naming the empty grounding. Proven by `tests/unit/operate-citation-resolution.test.ts` ("rejects a fabricated path, a wrong line range, and a moved revision with distinct reasons and one gap each" and "commits a role not_evaluated with a governed gap when its citations resolve zero evidence") and by the above-ceiling refusal in `tests/unit/operate-mission-honeytoken-isolation.test.ts` ("refuses a read above the sensitivity ceiling inside a granted root"). **Hard-blocked secrets in cited content are rejected, not redacted-and-accepted.** A citation whose snapshot contains a hard-blocked secret category is refused as an unresolvable citation gap instead of being persisted in redacted form. Proven by `tests/unit/operate-citation-resolution.test.ts` ("rejects a citation into HARD-blocked-secret content as unresolvable, never redacted-and-accepted"), with a soft-secret assignment still redacted-and-accepted so the distinction is exercised both ways. **A gitignored `.planr/` tree is fully citable — by architecture.** The dispatched agent reads the filesystem directly rather than `git ls-files`, so a project that gitignores its `.planr/` control surface can still ground the three lenses (CPO, CMO, COO) that the fourth field audit found unsatisfiable when candidates came only from tracked files — the defect that starved three of six lenses is gone by construction, not by repair. Proven by `tests/unit/operate-mission-honeytoken-isolation.test.ts` ("reads a gitignored .planr/ tree — the mission tool walks the filesystem, not git ls-files (finding 2)"). **Guided init has no livelock, no dead-end advice, and a revise path.** An answer envelope is accepted on its binding validity (session id, questionnaire digest, project head) rather than on wall-clock ordering, a transiently stale session un-latches when the tree is restored, a genuinely terminal rejection names the resumable session id and its exact `--resume` command, a previously answered question can be re-answered before apply, and the questionnaire advertises `--answers-file` as a stdin-parity transport alternate with per-question renderability metadata. Proven by `tests/unit/operate-question-session.test.ts` ("accepts an answer envelope whose submittedAt predates the session (livelock regression)" and "un-latches a transiently stale session when the tree is restored"), `tests/integration/operate-question-resume.test.ts` (the resume command surfaced in the next actions), and `tests/unit/operate-question-engine.test.ts` ("advertises --answers-file as a stdin-parity transport alternate with its exact argv" and "carries repeated-text renderability metadata sufficient to present without improvisation"). **Completing the pivot in the same coordinated release.** Sibling work landing under this version retires the now-dead evidence collector — its walks and budgets, role packs, mission packets, and the `pack|mission` dispatch-mode split — behind the mandate contract; renders cycle integrity (citation rejections, boundary refusals, `not_evaluated` roles) as a first-class section of the readable tree and a `doctor` check; makes the persisted `cycles/<id>/report.md` a self-contained record with complete registers; corrects the "commit-safe root" claim to an honest, redaction-based statement; and collapses runtime classification to mandate-capable-or-unsupported with no silent structured fallback. On the same schedule, the CLI's own structured-provider advisor path and its `--ai` planning surfaces are deprecated (FR4) — functional this release, pointed at the harness flow, and scheduled for removal, never broken and never silently removed. These items land with this release rather than ahead of it; their per-task proofs live under `.planr/specs/SPEC-004-operate-agent-harness-architecture/`. **Pins the optional `planr-pipeline` runtime to the exact `0.36.1`** — the build that publishes the additive operating-mandate schema (the same additive pattern as `create-quick-task`/`create-epic`), the regenerated mandate-flow command/skill instructions, the registry investigation mandates, and the reclassified adapter capability rows this release dispatches against. Verified: `optionalDependencies["planr-pipeline"] === "0.36.1"`, the three workflow `ref: v0.36.1` pins, and both packed-install e2e assertions. --- title: openplanr 1.19.0 description: Published 2026-08-01. Operating Board outputs and epic-loop release for openplanr operate (SPEC-003), the openplanr minor bump 1.18.0 → 1.19.0. url: https://openplanr.dev/docs/changelog/1.19.0 updated: 2026-08-01 related: - https://openplanr.dev/docs/changelog/1.21.0.md - https://openplanr.dev/docs/changelog/1.20.0.md - https://openplanr.dev/docs/changelog/1.18.0.md --- # openplanr 1.19.0 Published 2026-08-01. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.19.0) ## Minor Changes Operating Board outputs and epic-loop release for `openplanr operate` (SPEC-003), the `openplanr` minor bump 1.18.0 → 1.19.0. Every claim below is backed by a named proof; nothing describes a phase this repository has not actually reached. Cycle reports and boards are now persisted as truthful on-disk artifacts: a single rich assembly drives both `cycles/<id>/report.md` and every `board/<role>.md`, so `report.md` is byte-identical to the review rendering and each evaluated board file carries its lens recommendations with impact/confidence/ease (I/C/E) scores — proven by `tests/unit/operate-projection-persistence.test.ts` ("renders cycles/<id>/report.md and rich board files from the assembled lens artifacts"). The readable tree is consolidated: the legacy `projections/` directory is retired (never written), the parked-findings `backlog.md` is promoted to the top level, and `state.json` moves under `.state/` — proven by `tests/integration/operate-preview-boundaries.test.ts` and the persistence suite's asserted paths (`.planr/operate/backlog.md`, `.planr/operate/.state/state.json`, no `projections/`). Evidence loss is never silent. A capped repository walk names the last path it reached and the top-level directories it never scanned, mission-index drops are counted and surfaced as cycle warnings, sensitivity narrowing is scoped to the offending items, and a starved role is gated not-ready with a governed data gap while every ready role still dispatches — proven by `tests/integration/operate-evidence-recovery.test.ts` ("gates a starved repository role with a governed gap while other roles still dispatch (FR2)"). Collection is prioritized and fair: per-top-level-directory round-robin plus git-recency ordering, with split repository/planr file budgets replacing the shared `maxFiles` counter — proven by `tests/integration/operate-evidence-monorepo-fairness.test.ts` ("samples every product top-level directory under a cap the tree exceeds combined" and its deterministic re-selection check). Mission budgets are sized for real repositories: the derived mission-budget clamp ceiling rises from 9 to 32 KiB against real index-item costs, per-role `maxEvidenceItems` caps are enforced, and an oversized index is truncated to fit with the drop reported as a cycle warning — never a silent drop and never an unexplained fail-closed on a healthy repo — proven by `tests/unit/operate-mission-packet.test.ts` ("truncates a monorepo-scale index to the cap, fits the budget, and reports the drop (FR4)" and "leaves a healthy repository under its cap untouched — no warning, no fail-closed (FR4)"), with the field-scale pack path still failing closed with no provider invocation in `tests/unit/operate-advisor-pack-scale.test.ts`. Re-initialization preserves machine-local preferences: a no-flag re-init carries `dispatchModeOverrides`, `adapterLeaseDurationMs`, and `lastRunAt` forward, and the init preview names exactly which preference a re-init will change — proven by `tests/unit/operate-initialization-replay.test.ts` ("carries dispatchModeOverrides, adapterLeaseDurationMs, and lastRunAt forward on a re-init with no flags (field repro)") and `tests/integration/operate-guided-init.test.ts` ("names exactly which machine-local preferences a re-init will change in the preview"). The epic loop closes: the report groups related accepted findings into a ready-to-run `openplanr epic create --title …` suggestion naming the member findings, and the `create-epic` route applies a real `.planr/epics/EPIC-NNN-<slug>.md` artifact through the write-ahead journal with byte-exact rollback while never invoking PLAN or SHIP (R1 intact) — proven by `tests/integration/operate-decision-brief-render.test.ts` ("renders one openplanr epic create suggestion naming both accepted findings") and `tests/integration/operate-route-lanes.test.ts` ("elects, applies, and byte-exact rolls back a grouped-finding epic without ever invoking PLAN or SHIP"). Pins the optional `planr-pipeline` runtime to the exact `0.35.0` — the build that ships the FR4 packet-enforcement half, the additive FR8 `create-epic` operating-route-plan schema, the reviewed registry role budgets, and the regenerated operate assets this release proves against (`optionalDependencies["planr-pipeline"] === "0.35.0"`, mirrored by the three workflow `ref: v0.35.0` pins and both packed-install e2e assertions). --- title: openplanr 1.18.0 description: Published 2026-07-31. Field-fix release for the openplanr operate Operating Board (SPEC-002), hardening the Protocol v1.3 agentic engine against issues found… url: https://openplanr.dev/docs/changelog/1.18.0 updated: 2026-07-31 related: - https://openplanr.dev/docs/changelog/1.20.0.md - https://openplanr.dev/docs/changelog/1.19.0.md - https://openplanr.dev/docs/changelog/1.17.0.md --- # openplanr 1.18.0 Published 2026-07-31. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.18.0) ## Minor Changes Field-fix release for the `openplanr operate` Operating Board (SPEC-002), hardening the Protocol v1.3 agentic engine against issues found once real field incidents drove the board. Native mission dispatch is now wired end to end: a bound role prepares a mission packet (not a v1.2 pack) and hands back a v1.3 mission record action on a claude-code runtime, threading v1.3 citation-bearing responses through the recorded-proposal gate, while codex/cursor fail closed to the pack path — proven by `tests/unit/operate-adapter-mission-dispatch.test.ts` ("native mission dispatch reaches the record action"). Advisor pack budgets now fail closed at field-incident scale: `createOperatingAdvisorPack` throws before returning a field-scale pack, and both the dispatch and adapter-lifecycle prepare call sites refuse with no provider invocation and persist no session, with checkpoints holding at 10,000 events. The human review renderer presents the write-free `review` stage — question, evidence, options, and blockers — before any initialization is applied. Guided continuations return `ok: true` and hand the runner a directly executable `confirmArgv` on a digest-confirmable action. Adapter sessions bind to board identity so a re-inited board never collides with a prior generation, and `doctor` gains two staleness diagnostics (FR11): a stale adapter session bound to a superseded board generation and a stale incremental baseline whose `workspaceDigest` drifted, each with a scoped fix. Provider bootstrap failures surface as typed `E_OPERATE_ADVISOR_FAILED` errors with a remedy, the readiness preflight names a missing provider key before a cycle starts, and runtime detection resolves the real host from env markers instead of stamping `unknown`/`none`. The init questionnaire is on a diet with preselection (only unanswered canonical questions are returned; the decision owner is suggested from the git user) and accepts `--answers-file` as a bounded stdin-parity alias under the same 64 KiB cap. Adapter leases surface their expiry and remaining time in prepare output and the handoff (default 15 minutes), refresh on each successful record, and honor a machine-local configured lease duration. Pins the optional `planr-pipeline` runtime to `0.34.0`, the build that ships the regenerated v1.3 templates this release proves against. --- title: openplanr 1.17.0 description: "Published 2026-07-31. Advance openplanr operate to the Protocol v1.3 agentic engine (OPERATE-SPEC-004): automatic, lossless .state/ layout migration that is…" url: https://openplanr.dev/docs/changelog/1.17.0 updated: 2026-07-31 related: - https://openplanr.dev/docs/changelog/1.19.0.md - https://openplanr.dev/docs/changelog/1.18.0.md - https://openplanr.dev/docs/changelog/1.16.2.md --- # openplanr 1.17.0 Published 2026-07-31. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.17.0) ## Minor Changes Advance `openplanr operate` to the Protocol v1.3 agentic engine (OPERATE-SPEC-004): automatic, lossless `.state/` layout migration that is journal-driven (crash-safe) and byte-exactly reversible; a live evidence index with digest-bound mission packets; bounded, read-only native dispatch guarded by a mission honeytoken refusal suite and per-role `pack`/`mission` dispatch-mode overrides; citation resolution as the audit mechanism, fail-closed and reporting a distinct dirty-working-tree outcome; quick-task routing; self-contained offline decision briefs that fail closed on any non-local reference; cadence status that only reports and never requests an action; a skill-first operate cycle; and v1.3 doctor checks. Pins the optional `planr-pipeline` runtime to 0.33.1, the build that ships the `schemas/v1.3.0` mission-packet surface. --- title: openplanr 1.16.2 description: Published 2026-07-30. Manage compatible Claude Code marketplace plugins during confirmed setup and runtime updates, and diagnose stale versions or invalid… url: https://openplanr.dev/docs/changelog/1.16.2 updated: 2026-07-30 related: - https://openplanr.dev/docs/changelog/1.18.0.md - https://openplanr.dev/docs/changelog/1.17.0.md - https://openplanr.dev/docs/changelog/1.16.1.md --- # openplanr 1.16.2 Published 2026-07-30. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.16.2) ## Patch Changes Manage compatible Claude Code marketplace plugins during confirmed setup and runtime updates, and diagnose stale versions or invalid plugin identities. --- title: openplanr 1.16.1 description: Published 2026-07-30. Complete bare Planr Operate invocations through the native runtime cycle, prevent Unicode evidence truncation from corrupting state,… url: https://openplanr.dev/docs/changelog/1.16.1 updated: 2026-07-30 related: - https://openplanr.dev/docs/changelog/1.17.0.md - https://openplanr.dev/docs/changelog/1.16.2.md - https://openplanr.dev/docs/changelog/1.16.0.md --- # openplanr 1.16.1 Published 2026-07-30. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.16.1) ## Patch Changes Complete bare Planr Operate invocations through the native runtime cycle, prevent Unicode evidence truncation from corrupting state, quarantine advisor-ineligible excerpts before readiness, make cancellation retry-safe, and diagnose stale questionnaire-first runtime skills. --- title: openplanr 1.16.0 description: Published 2026-07-30. Run Operating Board cycles through bounded native runtime advisors, quarantine unsafe evidence without blocking unrelated lenses, and add… url: https://openplanr.dev/docs/changelog/1.16.0 updated: 2026-07-30 related: - https://openplanr.dev/docs/changelog/1.16.2.md - https://openplanr.dev/docs/changelog/1.16.1.md - https://openplanr.dev/docs/changelog/1.15.1.md --- # openplanr 1.16.0 Published 2026-07-30. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.16.0) ## Minor Changes Run Operating Board cycles through bounded native runtime advisors, quarantine unsafe evidence without blocking unrelated lenses, and add actionable Markdown/JSON executive reports. --- title: openplanr 1.15.1 description: Published 2026-07-30. Make direct Operating Board initialization previews return a self-contained, digest-bound replay command that applies without restarting… url: https://openplanr.dev/docs/changelog/1.15.1 updated: 2026-07-30 related: - https://openplanr.dev/docs/changelog/1.16.1.md - https://openplanr.dev/docs/changelog/1.16.0.md - https://openplanr.dev/docs/changelog/1.15.0.md --- # openplanr 1.15.1 Published 2026-07-30. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.15.1) ## Patch Changes Make direct Operating Board initialization previews return a self-contained, digest-bound replay command that applies without restarting the questionnaire, and route focused integration gates through their executable Vitest configuration. --- title: openplanr 1.15.0 description: Published 2026-07-29. Add CLI-owned guided Operating Board questionnaires, resumable typed-answer sessions, digest-scoped actions, deterministic charter… url: https://openplanr.dev/docs/changelog/1.15.0 updated: 2026-07-29 related: - https://openplanr.dev/docs/changelog/1.16.0.md - https://openplanr.dev/docs/changelog/1.15.1.md - https://openplanr.dev/docs/changelog/1.14.4.md --- # openplanr 1.15.0 Published 2026-07-29. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.15.0) ## Minor Changes Add CLI-owned guided Operating Board questionnaires, resumable typed-answer sessions, digest-scoped actions, deterministic charter assistance, value-free evidence recovery, runtime-native presentation contracts, and setup/doctor diagnostics without weakening PLAN, SHIP, provider, or route authority gates. --- title: openplanr 1.14.4 description: Published 2026-07-29. Prevent Operating Board evidence redaction from quarantining safe assignments or reprocessing its own redaction sentinels. url: https://openplanr.dev/docs/changelog/1.14.4 updated: 2026-07-29 related: - https://openplanr.dev/docs/changelog/1.15.1.md - https://openplanr.dev/docs/changelog/1.15.0.md - https://openplanr.dev/docs/changelog/1.14.3.md --- # openplanr 1.14.4 Published 2026-07-29. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.14.4) ## Patch Changes Prevent Operating Board evidence redaction from quarantining safe assignments or reprocessing its own redaction sentinels. --- title: openplanr 1.14.3 description: Published 2026-07-29. Derive Operating Board producer provenance from the installed OpenPlanr package version instead of a copied release literal. url: https://openplanr.dev/docs/changelog/1.14.3 updated: 2026-07-29 related: - https://openplanr.dev/docs/changelog/1.15.0.md - https://openplanr.dev/docs/changelog/1.14.4.md - https://openplanr.dev/docs/changelog/1.14.2.md --- # openplanr 1.14.3 Published 2026-07-29. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.14.3) ## Patch Changes Derive Operating Board producer provenance from the installed OpenPlanr package version instead of a copied release literal. Report a missing OpenPlanr configuration as the actionable advisor error instead of an unexpected internal failure. `openplanr operate init` writes `.planr/operate/config.json`, not the project-wide `.planr/config.json`, so a project that ran only the operate initializer reached the structured adapter with no config at all and surfaced "an unexpected internal Operating Board error" on the primary first-run path. --- title: openplanr 1.14.2 description: Published 2026-07-29. Reject secrets in native Operating Board advisor results before any commit-safe event or projection is persisted, and pin Changesets'… url: https://openplanr.dev/docs/changelog/1.14.2 updated: 2026-07-29 related: - https://openplanr.dev/docs/changelog/1.14.4.md - https://openplanr.dev/docs/changelog/1.14.3.md - https://openplanr.dev/docs/changelog/1.14.1.md --- # openplanr 1.14.2 Published 2026-07-29. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.14.2) ## Patch Changes Reject secrets in native Operating Board advisor results before any commit-safe event or projection is persisted, and pin Changesets' development-only YAML parsers to patched versions. --- title: openplanr 1.14.1 description: Published 2026-07-29. Point test:operate:packed at the config that owns the packed-install suite. url: https://openplanr.dev/docs/changelog/1.14.1 updated: 2026-07-29 related: - https://openplanr.dev/docs/changelog/1.14.3.md - https://openplanr.dev/docs/changelog/1.14.2.md - https://openplanr.dev/docs/changelog/1.14.0.md --- # openplanr 1.14.1 Published 2026-07-29. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.14.1) ## Patch Changes Point `test:operate:packed` at the config that owns the packed-install suite. The suite moved out of the default vitest project so it could not saturate the shared worker pool, but the script still used the default config, where the file is now excluded — so it exited "No test files found" instead of running. Stabilize the native Operating Board lifecycle under parallel CI load and close the operating lock file safely when its initial durable write fails. --- title: openplanr 1.14.0 description: Published 2026-07-29. Add openplanr operate, an evidence-to-decision operating control plane with safe workspace initialization, event-sourced cycles, isolated… url: https://openplanr.dev/docs/changelog/1.14.0 updated: 2026-07-29 related: - https://openplanr.dev/docs/changelog/1.14.2.md - https://openplanr.dev/docs/changelog/1.14.1.md - https://openplanr.dev/docs/changelog/1.13.3.md --- # openplanr 1.14.0 Published 2026-07-29. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.14.0) ## Minor Changes Add `openplanr operate`, an evidence-to-decision operating control plane with safe workspace initialization, event-sourced cycles, isolated advisory lenses, separate finding acceptance and route application, typed outcomes, recovery, strict JSON automation, and cross-runtime workflow support. --- title: openplanr 1.13.3 description: Published 2026-07-23. Bundle artifacts from their own directory by default, and report safely vendored remote assets in local review output. url: https://openplanr.dev/docs/changelog/1.13.3 updated: 2026-07-23 related: - https://openplanr.dev/docs/changelog/1.14.1.md - https://openplanr.dev/docs/changelog/1.14.0.md - https://openplanr.dev/docs/changelog/1.13.2.md --- # openplanr 1.13.3 Published 2026-07-23. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.13.3) ## Patch Changes Bundle artifacts from their own directory by default, and report safely vendored remote assets in local review output. --- title: openplanr 1.13.2 description: Published 2026-07-23. Update the optional planr-pipeline runtime to 0.29.0 so openplanr artifact uses the released minimal document review chrome with the… url: https://openplanr.dev/docs/changelog/1.13.2 updated: 2026-07-23 related: - https://openplanr.dev/docs/changelog/1.14.0.md - https://openplanr.dev/docs/changelog/1.13.3.md - https://openplanr.dev/docs/changelog/1.13.1.md --- # openplanr 1.13.2 Published 2026-07-23. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.13.2) ## Patch Changes Update the optional `planr-pipeline` runtime to 0.29.0 so `openplanr artifact` uses the released minimal document review chrome with the floating comments rail. --- title: openplanr 1.13.1 description: Published 2026-07-22. Update the bundled pipeline to 0.28.5 so document artifacts use a single outer scrollbar instead of competing iframe scrolling. url: https://openplanr.dev/docs/changelog/1.13.1 updated: 2026-07-22 related: - https://openplanr.dev/docs/changelog/1.13.3.md - https://openplanr.dev/docs/changelog/1.13.2.md - https://openplanr.dev/docs/changelog/1.13.0.md --- # openplanr 1.13.1 Published 2026-07-22. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.13.1) ## Patch Changes Update the bundled pipeline to 0.28.5 so document artifacts use a single outer scrollbar instead of competing iframe scrolling. --- title: openplanr 1.13.0 description: Published 2026-07-22. Allow Linear setup to configure one, several, or all accessible teams, select a default, and target configured teams per push with --team. url: https://openplanr.dev/docs/changelog/1.13.0 updated: 2026-07-22 related: - https://openplanr.dev/docs/changelog/1.13.2.md - https://openplanr.dev/docs/changelog/1.13.1.md - https://openplanr.dev/docs/changelog/1.12.4.md --- # openplanr 1.13.0 Published 2026-07-22. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.13.0) ## Minor Changes Allow Linear setup to configure one, several, or all accessible teams, select a default, and target configured teams per push with `--team`. --- title: openplanr 1.12.4 description: Published 2026-07-19. Update the bundled pipeline to 0.28.4 for stable live-room sharing, clearer fragment limits, visible copy confirmation, reviewer identity… url: https://openplanr.dev/docs/changelog/1.12.4 updated: 2026-07-19 related: - https://openplanr.dev/docs/changelog/1.13.1.md - https://openplanr.dev/docs/changelog/1.13.0.md - https://openplanr.dev/docs/changelog/1.12.3.md --- # openplanr 1.12.4 Published 2026-07-19. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.12.4) ## Patch Changes Update the bundled pipeline to 0.28.4 for stable live-room sharing, clearer fragment limits, visible copy confirmation, reviewer identity feedback, and keyboard comment submission. --- title: openplanr 1.12.3 description: Published 2026-07-19. Make openplanr doctor --fix preview and safely remove stale Planr-owned design and dashboard daemon state. url: https://openplanr.dev/docs/changelog/1.12.3 updated: 2026-07-19 related: - https://openplanr.dev/docs/changelog/1.13.0.md - https://openplanr.dev/docs/changelog/1.12.4.md - https://openplanr.dev/docs/changelog/1.12.2.md --- # openplanr 1.12.3 Published 2026-07-19. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.12.3) ## Patch Changes Make `openplanr doctor --fix` preview and safely remove stale Planr-owned design and dashboard daemon state. Missing runtimes are now informational unless the current setup selected them. --- title: openplanr 1.12.2 description: Published 2026-07-16. Decode feedback from existing encrypted live artifact review rooms whose persisted events predate the room-event version field. url: https://openplanr.dev/docs/changelog/1.12.2 updated: 2026-07-16 related: - https://openplanr.dev/docs/changelog/1.12.4.md - https://openplanr.dev/docs/changelog/1.12.3.md - https://openplanr.dev/docs/changelog/1.12.1.md --- # openplanr 1.12.2 Published 2026-07-16. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.12.2) ## Patch Changes Decode feedback from existing encrypted live artifact review rooms whose persisted events predate the room-event version field. --- title: openplanr 1.12.1 description: Published 2026-07-16. Use planr-pipeline 0.28.1 so live collaborative rooms encrypt the compressed artifact payload correctly, including rooms created from… url: https://openplanr.dev/docs/changelog/1.12.1 updated: 2026-07-16 related: - https://openplanr.dev/docs/changelog/1.12.3.md - https://openplanr.dev/docs/changelog/1.12.2.md - https://openplanr.dev/docs/changelog/1.12.0.md --- # openplanr 1.12.1 Published 2026-07-16. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.12.1) ## Patch Changes Use planr-pipeline 0.28.1 so live collaborative rooms encrypt the compressed artifact payload correctly, including rooms created from legacy artifact shares. --- title: openplanr 1.12.0 description: Published 2026-07-16. Make encrypted live artifact review rooms the default sharing workflow, retain immutable snapshots behind --snapshot, support live-room… url: https://openplanr.dev/docs/changelog/1.12.0 updated: 2026-07-16 related: - https://openplanr.dev/docs/changelog/1.12.2.md - https://openplanr.dev/docs/changelog/1.12.1.md - https://openplanr.dev/docs/changelog/1.11.0.md --- # openplanr 1.12.0 Published 2026-07-16. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.12.0) ## Minor Changes Make encrypted live artifact review rooms the default sharing workflow, retain immutable snapshots behind `--snapshot`, support live-room feedback imports, and bundle `planr-pipeline` 0.28.0. --- title: openplanr 1.11.0 description: Published 2026-07-15. Add headless document and zoomable canvas presentations to openplanr artifact, including --presentation auto document canvas, resolved… url: https://openplanr.dev/docs/changelog/1.11.0 updated: 2026-07-15 related: - https://openplanr.dev/docs/changelog/1.12.1.md - https://openplanr.dev/docs/changelog/1.12.0.md - https://openplanr.dev/docs/changelog/1.10.0.md --- # openplanr 1.11.0 Published 2026-07-15. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.11.0) ## Minor Changes Add headless document and zoomable canvas presentations to `openplanr artifact`, including `--presentation auto|document|canvas`, resolved JSON output, and the planr-pipeline 0.27.1 compatibility update. --- title: openplanr 1.10.0 description: Published 2026-07-15. Add openplanr artifact for secure local HTML review, private fragment or encrypted short-link sharing, returned-review import, and… url: https://openplanr.dev/docs/changelog/1.10.0 updated: 2026-07-15 related: - https://openplanr.dev/docs/changelog/1.12.0.md - https://openplanr.dev/docs/changelog/1.11.0.md - https://openplanr.dev/docs/changelog/1.9.1.md --- # openplanr 1.10.0 Published 2026-07-15. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.10.0) ## Minor Changes Add `openplanr artifact` for secure local HTML review, private fragment or encrypted short-link sharing, returned-review import, and live-session export. --- title: openplanr 1.9.1 description: Published 2026-07-12. Make installation quiet and configuration explicit, add guided runtime setup with safe user-scope defaults, prevent accidental project… url: https://openplanr.dev/docs/changelog/1.9.1 updated: 2026-07-12 related: - https://openplanr.dev/docs/changelog/1.11.0.md - https://openplanr.dev/docs/changelog/1.10.0.md - https://openplanr.dev/docs/changelog/1.9.0.md --- # openplanr 1.9.1 Published 2026-07-12. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.9.1) ## Patch Changes Make installation quiet and configuration explicit, add guided runtime setup with safe user-scope defaults, prevent accidental project writes outside Git or initialized OpenPlanr projects, and diagnose legacy home-directory setup files. --- title: openplanr 1.9.0 description: "Published 2026-07-12. Add the unified cross-runtime distribution flow: openplanr setup, runtime adapter lifecycle management, pipeline routing, unified doctor…" url: https://openplanr.dev/docs/changelog/1.9.0 updated: 2026-07-12 related: - https://openplanr.dev/docs/changelog/1.10.0.md - https://openplanr.dev/docs/changelog/1.9.1.md - https://openplanr.dev/docs/changelog/1.8.1.md --- # openplanr 1.9.0 Published 2026-07-12. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.9.0) ## Minor Changes Add the unified cross-runtime distribution flow: `openplanr setup`, runtime adapter lifecycle management, pipeline routing, unified doctor diagnostics, exact runtime locks, and append-only planning provenance. The full `planr-pipeline` package is installed by default with `--minimal` as the planning-only escape hatch. Codex skills and Cursor rules now come from the shared portable registries, while migrations preserve hand-written content, back up exact bytes, retain shared user assets safely, and support conflict-safe rollback and removal. --- title: openplanr 1.8.1 description: Published 2026-07-11. Update generated rule templates to reference Sonnet 5 (was Sonnet 4.6) for the analysis/decomposition tier, matching planr-pipeline v0.24. url: https://openplanr.dev/docs/changelog/1.8.1 updated: 2026-07-11 related: - https://openplanr.dev/docs/changelog/1.9.1.md - https://openplanr.dev/docs/changelog/1.9.0.md - https://openplanr.dev/docs/changelog/1.8.0.md --- # openplanr 1.8.1 Published 2026-07-11. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.8.1) ## Patch Changes Update generated rule templates to reference **Sonnet 5** (was Sonnet 4.6) for the analysis/decomposition tier, matching planr-pipeline v0.24.10. The cursor (`planr-pipeline.mdc.hbs`, `agents/designer-agent.md`, `agents/qa-agent.md`, `agents/specification-agent.md`) and codex (`_pipeline-section.md.hbs`) rule-generator templates now render the current analysis-tier model. The DEV/codegen tier stays on Opus 4.8. --- title: openplanr 1.8.0 description: Published 2026-06-26. Add openplanr graph --json, a read-only artifact graph export for dashboard and ecosystem conformance. url: https://openplanr.dev/docs/changelog/1.8.0 updated: 2026-06-26 related: - https://openplanr.dev/docs/changelog/1.9.0.md - https://openplanr.dev/docs/changelog/1.8.1.md - https://openplanr.dev/docs/changelog/1.7.2.md --- # openplanr 1.8.0 Published 2026-06-26. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.8.0) ## Minor Changes Add `openplanr graph --json`, a read-only artifact graph export for dashboard and ecosystem conformance. The command emits the shared OpenPlanr Protocol graph shape `{ nodes, edges }`, namespaces spec-local story/task ids, and preserves `contains` and `depends_on` edges from frontmatter. --- title: openplanr 1.7.2 description: Published 2026-06-10. openplanr status is now the whole-project delivery report. url: https://openplanr.dev/docs/changelog/1.7.2 updated: 2026-06-10 related: - https://openplanr.dev/docs/changelog/1.8.1.md - https://openplanr.dev/docs/changelog/1.8.0.md - https://openplanr.dev/docs/changelog/1.7.1.md --- # openplanr 1.7.2 Published 2026-06-10. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.7.2) ## Patch Changes `openplanr status` is now the **whole-project delivery report**. With no argument it rolls up every Spec / Backlog item / Quick Task (or the agile epic→task tree) by status — **done** · **promoted/superseded** (addressed, never counted as done or outstanding) · **outstanding** — cross-referenced with the GitHub issue/PR and Linear identifiers recorded in frontmatter, ending with a Summary and an **Outstanding work** section. New: an optional `[scope]` argument (one spec/epic/feature id or slug), `--md` (paste-ready markdown report), `--json` (machine-readable for agents/CI), and `--github` / `--linear` to live-resolve PR + issue states (offline frontmatter by default). Powered by the new `delivery-status-service` (deterministic aggregation over the existing artifact/GitHub/Linear services); the previous truncated tree view is superseded by the delivery view (`--all` still controls terminal truncation). --- title: openplanr 1.7.1 description: Published 2026-06-10. Align generated rule templates and the spec-schema reference to Opus 4.8 (was Opus 4.7). url: https://openplanr.dev/docs/changelog/1.7.1 updated: 2026-06-10 related: - https://openplanr.dev/docs/changelog/1.8.0.md - https://openplanr.dev/docs/changelog/1.7.2.md - https://openplanr.dev/docs/changelog/1.7.0.md --- # openplanr 1.7.1 Published 2026-06-10. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.7.1) ## Patch Changes Align generated rule templates and the spec-schema reference to **Opus 4.8** (was Opus 4.7). The cursor (`planr-pipeline.mdc.hbs`, `agents/specification-agent.md`) and codex (`_pipeline-section.md.hbs`) rule-generator templates, plus `docs/reference/spec-schema.md`, now render the current DEV-tier codegen model — matching the planr-pipeline plugin v0.10.0 bump to `claude-opus-4-8[1m]`. --- title: openplanr 1.7.0 description: "Published 2026-05-10. feat: artifact integrity + rules generator managed-block markers" url: https://openplanr.dev/docs/changelog/1.7.0 updated: 2026-05-10 related: - https://openplanr.dev/docs/changelog/1.7.2.md - https://openplanr.dev/docs/changelog/1.7.1.md - https://openplanr.dev/docs/changelog/1.6.0.md --- # openplanr 1.7.0 Published 2026-05-10. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.7.0) ## Minor Changes feat: artifact integrity + rules generator managed-block markers ### Managed-block markers for `rules generate` (fixes AGENTS.md clobber bug) `openplanr rules generate --scope pipeline` no longer overwrites the entire AGENTS.md / CLAUDE.md. Generated content is now wrapped in `<!-- ##planr-pipeline:begin## -->` / `<!-- ##planr-pipeline:end## -->` HTML comment markers. On regeneration, only the content between markers is replaced — project headers, agile content, and hand-written sections are preserved. Same treatment for `--scope agile` via `<!-- ##planr-agile:begin## -->` markers. ### Write-time artifact validation `updateArtifact()` now validates structural invariants before writing: frontmatter fences present, YAML parses, `id:` field unchanged, and checkbox IDs preserved. On violation, throws `ArtifactInvariantError` with the specific violation. This stops AI-driven corruption from `openplanr refine` / `openplanr revise` at the door — the file on disk is never poisoned by malformed AI output. ### AI contract: structured deltas for `openplanr refine` `openplanr refine` now asks the AI for structured deltas (`frontmatterChanges` + `bodyChanges`) instead of a whole-file `improvedMarkdown` blob. Our code applies deltas deterministically — the AI never holds a pen on raw bytes. Legacy `improvedMarkdown` responses are validated and rejected if they break structural invariants. ### Migration - First run of `openplanr rules generate` on an existing project wraps content in markers automatically (non-destructive). - `openplanr refine` change is transparent to users (AI contract is an implementation detail). - Files previously corrupted by refine must be manually repaired or restored via `git checkout`. --- title: openplanr 1.6.0 description: "Published 2026-05-05. feat(types): widen TaskStatus to include 'blocked' for v0.8.0 plugin alignment" url: https://openplanr.dev/docs/changelog/1.6.0 updated: 2026-05-05 related: - https://openplanr.dev/docs/changelog/1.7.1.md - https://openplanr.dev/docs/changelog/1.7.0.md - https://openplanr.dev/docs/changelog/1.5.2.md --- # openplanr 1.6.0 Published 2026-05-05. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.6.0) ## Minor Changes feat(types): widen `TaskStatus` to include `'blocked'` for v0.8.0 plugin alignment The planr-pipeline v0.8.0 task schema enum is `['pending', 'in-progress', 'done', 'blocked']`. Prior CLI versions silently coerced `blocked` → `pending` via `asTaskStatus()`, dropping the R6-failure signal that the pipeline writes alongside `T-NNN-error-report.md`. Changes: - `TaskStatus` union now includes `'blocked'` (`src/models/types.ts`) - All four `asTaskStatus()` normalizers accept and preserve `'blocked'` (linear-pull, linear-push, scope-loaders) - `DEFAULT_LINEAR_STATE_TO_OP` adds `['blocked', 'blocked']` so a Linear "Blocked" workflow state pulls back into a blocked task file - `buildNameToStatusMap` accepts `'blocked'` from user `linear.statusMap` overrides - `aggregateTaskStatus()` adds top-precedence rule: any blocked child → blocked parent (escalation, not averaging) Migration: zero-friction. Tasks that don't carry `blocked` are unaffected. The CLI no longer demotes blocked back to pending on Linear pull. --- title: openplanr 1.5.2 description: Published 2026-04-30. Fix a leftover OpenPlanr-pipeline-aware phrase in the cursor master rule template that the v1.5.1 rename sed missed (mixed-case compound… url: https://openplanr.dev/docs/changelog/1.5.2 updated: 2026-04-30 related: - https://openplanr.dev/docs/changelog/1.7.0.md - https://openplanr.dev/docs/changelog/1.6.0.md - https://openplanr.dev/docs/changelog/1.5.1.md --- # openplanr 1.5.2 Published 2026-04-30. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.5.2) ## Patch Changes Fix a leftover `OpenPlanr-pipeline-aware` phrase in the cursor master rule template that the v1.5.1 rename sed missed (mixed-case compound adjective). After upgrade, regenerated `.cursor/rules/planr-pipeline.mdc` files use `planr-pipeline-aware` consistently with the renamed plugin. No behavioural change. Run `openplanr rules generate --target cursor --scope pipeline` to refresh existing projects. --- title: openplanr 1.5.1 description: "Published 2026-04-30. Plugin rename: openplanr-pipeline → planr-pipeline. Brand convergence on the planr CLI binary." url: https://openplanr.dev/docs/changelog/1.5.1 updated: 2026-04-30 related: - https://openplanr.dev/docs/changelog/1.6.0.md - https://openplanr.dev/docs/changelog/1.5.2.md - https://openplanr.dev/docs/changelog/1.5.0.md --- # openplanr 1.5.1 Published 2026-04-30. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.5.1) ## Patch Changes Plugin rename: `openplanr-pipeline` → `planr-pipeline`. Brand convergence on the `planr` CLI binary. The CLI's TypeScript API is unchanged — only generated artifact names + slash command identifiers. **What changes for users:** - Generated cursor rule filenames: `openplanr-pipeline.mdc` → `planr-pipeline.mdc` (also `-plan.mdc` and `-ship.mdc` variants) - Claude sibling reference card: `openplanr-pipeline.md` → `planr-pipeline.md` - Slash commands: `/openplanr-pipeline:plan` → `/planr-pipeline:plan` (same for `:ship`) **Migration:** re-run `openplanr rules generate` to pick up the new files. Legacy filenames trigger a one-line cleanup hint pointing at safe-to-delete paths — never auto-deleted. **Pairs with:** `planr-pipeline` Claude Code plugin v0.7.0 (renamed from `openplanr-pipeline` v0.6.0); `openplanr` skill v1.4.0; marketplace pin updated to v0.7.0. --- title: openplanr 1.5.0 description: "Published 2026-04-29. Multi-runtime rules: extend openplanr rules generate with a --scope flag for cross-runtime pipeline support." url: https://openplanr.dev/docs/changelog/1.5.0 updated: 2026-04-29 related: - https://openplanr.dev/docs/changelog/1.5.2.md - https://openplanr.dev/docs/changelog/1.5.1.md - https://openplanr.dev/docs/changelog/1.4.3.md --- # openplanr 1.5.0 Published 2026-04-29. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.5.0) ## Minor Changes Multi-runtime rules: extend `openplanr rules generate` with a `--scope` flag for cross-runtime pipeline support. `openplanr rules generate` now accepts `--scope <agile|pipeline|all>` (default: `agile` — preserves existing behaviour byte-for-byte). The new `pipeline` scope generates rule files that drive the openplanr-pipeline two-phase spec-driven flow on the chosen runtime, giving Cursor and Codex first-class parity with the Claude Code plugin. **Cursor (`--target cursor --scope pipeline`):** - `.cursor/rules/openplanr-pipeline.mdc` — master rule (mode detection, R1 human gate, runtime parity notes) - `.cursor/rules/openplanr-pipeline-plan.mdc` — PO Phase orchestration (Composer subagent dispatch) - `.cursor/rules/openplanr-pipeline-ship.mdc` — DEV Phase orchestration (parallel subagents, qa gate, snapshot, marker) - `.cursor/rules/agents/{db,designer,specification,frontend,backend,qa,devops,doc-gen}-agent.md` — 8 role bodies vendored verbatim from `openplanr-pipeline/agents/` (frontmatter stripped; Cursor uses different permission model) **Codex (`--target codex --scope pipeline`):** - `AGENTS.md` extended with a `## OpenPlanr Pipeline Orchestration` section. Roles modelled as personas (Codex doesn't have separate subagent processes); R1, R2, R5, R6, R8, R9 declared at prompt level with conformance-test enforcement. **Claude (`--target claude --scope pipeline`):** - `CLAUDE.md` gets a conditional `## OpenPlanr Pipeline (Path A)` block under `{{#if pipelineScope}}` - Sibling `openplanr-pipeline.md` reference card with install commands, slash command list, and cross-runtime pointer `--scope all` produces both agile and pipeline rules side-by-side. **Compatibility matrix and OpenPlanr Protocol v1.0.0** documented in `openplanr-pipeline/docs/protocol/` and `openplanr-pipeline/docs/compatibility-matrix.md` (pipeline plugin v0.6.0+). **`openplanr init` now auto-generates pipeline rules by default.** The init flow asks "Generate openplanr-pipeline rules?" with default `Yes` — meaning a single `openplanr init` produces a complete, ready-to-use cross-runtime project (Cursor + Codex pipeline rules pre-installed; Claude Code skill activates the same workflow via the plugin). Opt out with `openplanr init --no-pipeline-rules` to preserve the previous agile-only behaviour. This closes the cross-runtime DX gap so each tool (Cursor, Codex, Claude Code) is self-sufficient after a single command — no manual `openplanr rules generate --scope pipeline` step required for the common case. **Migration:** none. Existing projects can either re-run `openplanr init` (it auto-detects existing config and asks to overwrite) or run `openplanr rules generate --scope all` to add pipeline rules without touching config. `--scope agile` (the previous default for `openplanr rules generate`) keeps producing the existing 6 Cursor `.mdc` files, single CLAUDE.md, single AGENTS.md outputs unchanged. --- title: openplanr 1.4.3 description: Published 2026-04-29. Four improvements that close real workflow gaps in openplanr linear push, openplanr linear tasklist-sync, and the per-type update… url: https://openplanr.dev/docs/changelog/1.4.3 updated: 2026-04-29 related: - https://openplanr.dev/docs/changelog/1.5.1.md - https://openplanr.dev/docs/changelog/1.5.0.md - https://openplanr.dev/docs/changelog/1.4.2.md --- # openplanr 1.4.3 Published 2026-04-29. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.4.3) ## Patch Changes Four improvements that close real workflow gaps in `openplanr linear push`, `openplanr linear tasklist-sync`, and the per-type `update` commands. **Granular push scope (BL-012).** `openplanr linear push` adds `--no-cascade` and redefines `--push-parents` to be upward-attachment only. - `--no-cascade` on EPIC/FEAT pushes skips descendants (stories, tasklists, linked QT/BL). No-op for leaves. - `--push-parents` no longer drags in the parent's other children. Pushing `TASK-004 --push-parents` now creates EPIC + parent FEAT + this tasklist only — not the feature's sibling stories. **TASK status now propagates to Linear (BL-014).** `openplanr linear push` resolves a workflow stateId for the merged TaskList issue using an aggregation rule across all task files under the feature: all `done` → Linear Done, any `in-progress` → Linear In Progress, mix of done+pending → In Progress, all `pending` → Linear Todo. Closes the gap where `TASK-006 status: done` locally left Linear's TaskList in Backlog. **Bulk subtask completion (BL-015).** `openplanr task update`, `openplanr quick update`, and `openplanr update` add `--all-done` and `--all-pending` flags that set the frontmatter status AND flip every `N.M` task checkbox in the body in one operation. Replaces the manual `sed`-or-edit-each-box workflow when shipping a feature. **tasklist-sync no longer skips healthy issue UUIDs (BL-016).** `openplanr linear tasklist-sync` previously rejected every task file whose `linearIssueId` was a UUIDv4 — the entire population of healthy task files — because a shape-based pre-screen flagged them as "looks like a workflow state UUID." Linear issue ids and workflow-state ids are both UUIDv4 and indistinguishable by shape, so the pre-screen has been removed; the existing `isLikelyLinearIssueId` check still rejects truly malformed values like `ENG42`. Backward-compat note: scripts that relied on `--push-parents` cascading downward will see fewer entities pushed. --- title: openplanr 1.4.2 description: "Published 2026-04-26. Spec-driven workflow polish: clearer errors, schema reference, readiness check." url: https://openplanr.dev/docs/changelog/1.4.2 updated: 2026-04-26 related: - https://openplanr.dev/docs/changelog/1.5.0.md - https://openplanr.dev/docs/changelog/1.4.3.md - https://openplanr.dev/docs/changelog/1.4.1.md --- # openplanr 1.4.2 Published 2026-04-26. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.4.2) ## Patch Changes Spec-driven workflow polish: clearer errors, schema reference, readiness check. - **Friendlier `openplanr spec decompose` error** when AI is unavailable — surfaces two actionable paths (configure AI, or hand-author from the schema reference) instead of one terse line. - **`openplanr config show` now includes a "Spec-driven readiness" section** — at-a-glance view of whether `openplanr spec decompose` can run given the current AI config. - **`openplanr init --no-ai` prints a warning** listing the AI-dependent commands (`spec decompose`, `refine`, `backlog prioritize`) that will be unavailable, with a one-liner to re-enable later. - **Canonical schema reference at `docs/reference/spec-schema.md`** — single source of truth for spec / story / task frontmatter, body sections, lifecycle states, and the `.pipeline-shipped` marker. To be hosted at `openplanr.dev/docs/reference/spec-schema`. - Spec template footnote updated with concrete pipeline / CLI handoff routes. --- title: openplanr 1.4.1 description: Published 2026-04-25. Fix openplanr spec shape UX — replace $EDITOR-opening prompts with single-line prompts. url: https://openplanr.dev/docs/changelog/1.4.1 updated: 2026-04-25 related: - https://openplanr.dev/docs/changelog/1.4.3.md - https://openplanr.dev/docs/changelog/1.4.2.md - https://openplanr.dev/docs/changelog/1.4.0.md --- # openplanr 1.4.1 Published 2026-04-25. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.4.1) ## Patch Changes Fix `openplanr spec shape` UX — replace `$EDITOR`-opening prompts with single-line prompts. Previously, `openplanr spec shape <SPEC-id>` opened `$EDITOR` (vim by default for many users) for the Context, Business Rules, and Decomposition Notes questions. This was hostile UX — users unfamiliar with vim couldn't navigate, and a single accidental Enter on an empty buffer aborted the entire interactive flow. **v1.4.1 changes:** - **Question 1 (Context)** is now three single-line prompts: primary user, problem solved, expected outcome. Each is optional; provide what you can. The shape skill composes the Context section from your answers using markdown subheadings. - **Question 3 (Business Rules)** is now a single line. Hint guides the user to edit the spec markdown file directly for longer-form rules. - **Optional Decomposition Notes** is now a single line. Same guidance — edit file directly for longer prose. - Functional Requirements (Q2) and Acceptance Criteria (Q4) are unchanged — they were already comma-separated lists. Net effect: the entire shape flow now runs in the terminal with single-line prompts only. No `$EDITOR` open. No accidentally-empty-buffer aborts. For users who genuinely want long-form prose, the recommended path is: run `openplanr spec shape` for quick capture, then edit `.planr/specs/SPEC-NNN-{slug}/SPEC-NNN-{slug}.md` directly in your editor of choice afterward. Origin: surfaced by real-world testing where a user pressed Enter past the vim buffer without writing anything and lost the entire shape flow. --- title: openplanr 1.4.0 description: Published 2026-04-25. Add spec-driven planning mode — third planning posture alongside agile + QT, designed for humans planning for AI coding agents. url: https://openplanr.dev/docs/changelog/1.4.0 updated: 2026-04-25 related: - https://openplanr.dev/docs/changelog/1.4.2.md - https://openplanr.dev/docs/changelog/1.4.1.md - https://openplanr.dev/docs/changelog/1.3.0.md --- # openplanr 1.4.0 Published 2026-04-25. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.4.0) ## Minor Changes Add spec-driven planning mode — third planning posture alongside agile + QT, designed for humans planning _for_ AI coding agents. A new `openplanr spec` command namespace authors specs that decompose into User Stories and Tasks with the **same artifact contract as the [openplanr-pipeline](https://github.com/openplanr/openplanr-pipeline) Claude Code plugin** — file Create/Modify/Preserve lists, Type=UI|Tech, agent assignment, DoD with build/test commands. The two products share one schema; no conversion adapter ever. **Subcommands shipped:** - `openplanr spec init` — Activate spec-driven mode in the current project - `openplanr spec create [title]` — Create a self-contained `.planr/specs/SPEC-NNN-{slug}/` directory - `openplanr spec shape <id>` — Interactive 4-question SPEC authoring (Context, Functional Requirements, Business Rules, Acceptance Criteria) - `openplanr spec decompose <id>` — AI-driven generation of User Stories + Tasks; matches openplanr-pipeline schema; works with all 3 AI providers (Anthropic, OpenAI, Ollama). Flags: `--force`, `--no-code-context`, `--max-stories <n>` - `openplanr spec sync [id]` — Validate spec integrity (orphaned tasks, stories without tasks, missing `specId`, schema drift); auto-fixes safe issues; `--dry-run` reports without writing - `openplanr spec list` — List all specs with status + decomposition counts - `openplanr spec show <id>` — Print a spec + its US/Task tree - `openplanr spec status [id]` — Decomposition state across one or all specs - `openplanr spec destroy <id>` — `rm -rf` of a single self-contained spec directory - `openplanr spec attach-design <id> --files <png>...` — Attach UI mockups for the pipeline's designer-agent - `openplanr spec promote <id>` — Validate completeness, mark `ready-for-pipeline`, print the `/openplanr-pipeline:plan {slug}` handoff command **Directory layout (per spec, self-contained):** ``` .planr/specs/SPEC-NNN-{slug}/ ├── SPEC-NNN-{slug}.md # the spec document ├── design/ # PNG mockups + design-spec.md (written by pipeline's designer-agent) ├── stories/US-NNN-{slug}.md # US-NNN scoped to this spec └── tasks/T-NNN-{slug}.md # T-NNN scoped to this spec ``` **ID scoping:** 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. **Coexistence:** purely additive — agile (epic/feature/story/task) and QT modes work unchanged. Activate spec mode per project via `openplanr spec init`. Modes are independent; pick the posture that fits the work. **Decompose AI behavior:** - Always scans the project codebase via the existing `buildCodebaseContext()` so generated tasks reference real file paths matching the user's stack - Reads `input/tech/stack.md` (best-effort) for stack-specific hints - Detects `ui_files` in SPEC frontmatter to drive 1-vs-2 tasks per US (per openplanr-pipeline rule R2) - Refuses to overwrite an existing decomposition unless `--force` is passed - Status: pending|shaping → decomposing → decomposed **Pipeline integration:** When this CLI marks a spec `ready-for-pipeline`, the openplanr-pipeline Claude Code plugin (v0.3.0+) reads `.planr/specs/SPEC-NNN-{slug}/` directly — no conversion. See `docs/proposals/spec-driven-mode.md` for the full design proposal and BL-011 for the original strategic feedback. --- title: openplanr 1.3.0 description: Published 2026-04-24. **openplanr linear** — full Linear.app integration for OpenPlanr (EPIC-004). url: https://openplanr.dev/docs/changelog/1.3.0 updated: 2026-04-24 related: - https://openplanr.dev/docs/changelog/1.4.1.md - https://openplanr.dev/docs/changelog/1.4.0.md - https://openplanr.dev/docs/changelog/1.2.8.md --- # openplanr 1.3.0 Published 2026-04-24. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.3.0) ## Minor Changes **`openplanr linear`** — full Linear.app integration for OpenPlanr (EPIC-004). ### Subcommands - `openplanr linear init` — validate a Linear PAT, pick a team, save settings. - `openplanr linear push <artifactId>` — create/update Linear entities at any scope: - `EPIC-XXX` → project + features + stories + tasklists - `FEAT-XXX` → feature + its stories + its tasklist - `US-XXX` → one story sub-issue - `TASK-XXX` → one tasklist sub-issue - `QT-XXX` → quick task in the standalone project - `BL-XXX` → backlog item (auto-labeled) in the standalone project - `openplanr linear sync` — pull workflow status + bidirectional task checkboxes. - `openplanr linear tasklist-sync` — sync TASK checkbox lines with Linear issue bodies. - `openplanr linear status` — local mapping table (no API calls). ### Flags on `push` `--dry-run`, `--update-only`, `--push-parents`, `--as <strategy>`. ### Epic mapping strategies (chosen once, stored in `linearMappingStrategy`) - `project` (default) — Epic = Linear Project, one-to-one. - `milestone-of:<projectId>` — Epic becomes a `ProjectMilestone` in an existing project; descendants carry `projectMilestoneId`. - `label-on:<projectId>` — Epic becomes a team-scoped label; descendants carry `labelIds` (merged with user-added labels, never stomped). First-time push prompts interactively. CI consumers use `--as` or `linear.defaultEpicStrategy`. ### Parent-chain pre-flight Granular pushes (`FEAT-/US-/TASK-`) refuse to run when the parent chain is not yet in Linear — unless `--push-parents` is set, which cascades up. Unsupported prefixes (`ADR-/SPRINT-/checklist-`) error with a pointer to the parent epic. ### Standalone project for `QT-` / `BL-` Quick tasks and backlog items push as top-level issues in a user-chosen Linear project (`linear.standaloneProjectId`, set once via an interactive first-push prompt). Backlog items auto-apply a team-scoped `backlog` label for filtering. ### Security & reliability - Linear IDs validated before every API call — accepts UUID or `ENG-42` identifier; corrupted frontmatter falls through to create instead of 404-ing. - Frontmatter writer preserves regex-special sequences (`$1`, `$&`, `$$`) literally — Linear values can contain them. - SDK error fallback sanitizes raw GraphQL bodies; known error types keep their user-friendly guidance. - Rate-limit retries honor Linear's `Retry-After` (never retry sooner than the server asked, never faster than our exponential backoff). - Non-interactive conflict decisions audited to `.planr/reports/`. - Three-way checkbox merge warns when a baseline looks corrupted. - PATs stored via keychain-first credentials service, never in `config.json`. ### Bidirectional status sync with three-way merge (fixes silent data loss) `openplanr linear sync` now reconciles workflow status in **both directions** via a three-way merge: - **Local changed, Linear unchanged** → pushes local to Linear (fixes the data-loss bug where `openplanr quick update --status done` followed by `openplanr linear sync` silently reverted local back to Linear's stale state). - **Linear changed, local unchanged** → pulls Linear to local (existing behavior, preserved). - **Both changed** → conflict resolved per `--on-conflict prompt|local|linear`. Interactive runs prompt per artifact; CI/non-interactive runs auto-resolve to `linear` and log the decision to `.planr/reports/linear-sync-conflicts-<date>.md`. Baseline is stored per-artifact in new frontmatter fields `linearStatusReconciled` and `linearStatusSyncedAt`, written on every successful sync. `openplanr quick update --status` and `openplanr backlog update --status` automatically clear `linearStatusReconciled` so the next sync recognizes the local change and pushes it up. `--on-conflict` now applies to both status and checkbox conflicts (previously checkbox-only). Applies to FEAT / US / QT / BL. TASK stays deferred (aggregate issue, needs its own aggregation rules). ### Status sync now covers QT + BL (zero-config) `openplanr linear push QT-XXX` and `openplanr linear push BL-XXX` now write local status to Linear's workflow state. `openplanr linear sync` pulls state changes back into QT and BL frontmatter alongside features and stories. - **Zero-config:** push auto-derives the status→stateId map from Linear's canonical state types (`backlog` / `unstarted` / `started` / `completed` / `canceled`) on every run. `linear.pushStateIds` is now an optional override, not a requirement. - Quick tasks use the task vocabulary (`pending` / `in-progress` / `done`), plus transparent aliases for Linear-native wording (`completed` / `cancelled` / `canceled` / `todo`). - Backlog items use their own vocabulary (`open` / `closed` / `promoted`). Pull is asymmetric by design: any Linear "in flight" state maps to `open`, `Done`/`Cancelled` maps to `closed`, and local `promoted` is never overwritten (it implies a target pointer Linear can't know about). - TASK status sync stays on the TODO list. One Linear TaskList issue aggregates many task files, so a 1:1 status mapping doesn't apply; use `openplanr linear tasklist-sync` for per-checkbox state. **Fix:** Linear's API rejects `stateId: null` on update (`InvalidInput`). All push paths — feature, story, QT, BL — now omit the `stateId` field entirely when unmapped instead of sending an explicit null, so pushes without any state configuration continue to succeed. ### `openplanr revise` — unchanged-content short-circuit Revise now detects when the agent returns content that is effectively identical to the original (byte-exact, or differs only in trailing whitespace that LLM markdown serializers routinely strip). Behavior in that case: - No file write, no backup sidecar produced, no confirm prompt. - New audit outcome `unchanged-by-agent` (distinct from `skipped-by-agent` / `flagged`). - UI renders "(no changes — agent's revised output matches the current file; nothing to apply)" in place of an empty diff block. Prevents the confusing `Outcome: applied` report when the only on-disk delta was a trailing newline strip. ### `openplanr linear status` — full URLs, no truncation Reordered the table so the URL column is last and never truncated. Clickable URLs are the primary value of the table; the previous 28-char ellipsis made them useless for copy-paste. ### Estimate sync for FEAT / US / QT / BL `openplanr linear push` now writes local `estimatedPoints` (from `openplanr estimate --save`, or hand-edited `storyPoints`) to Linear's native Issue estimation field, snapped to the team's configured scale: - **Fibonacci** — snap to `{0, 1, 2, 3, 5, 8, 13, 21}` (e.g. `4 → 5`, `7 → 8`). - **Linear** — snap to `{0, 1, 2, 3, 4, 5}`. - **Exponential** — snap to `{0, 1, 2, 4, 8, 16}`. - **tShirt** — skipped with one-per-run warning (no reliable numeric → XS/S/M/L/XL mapping). - **notUsed** — skipped silently. Zero-config: the team's `issueEstimationType` is auto-detected per push run (one extra API round-trip, cached). TASK is deferred — one Linear TaskList issue aggregates multiple task files, so 1:1 estimate mapping doesn't apply. ### Story body fixes - **Empty role/goal/benefit no longer renders `As a \*\***, I want \***\* so that \*\***.`\*\* Suppresses the "As a" sentence entirely when any of the three fields is blank (or whitespace-only). - **Gherkin scenarios now push to Linear.** Stories following the OpenPlanr convention store acceptance criteria as Gherkin in a sibling `<storyId>-gherkin.feature` file. Before this fix the push path never loaded the `.feature` content and Linear stories rendered empty for convention-following teams. - **Epic project description trims whitespace-only fields** — no more empty `**Risks**` headers. ### Linear label case + workspace-scope fix `ensureIssueLabel` lookup is now **case-insensitive and workspace-wide** (matching Linear's own uniqueness rule). Previously a workspace with a `Feature` label blocked creation of `feature` with an `InvalidInput: Label already exists` error. Push now adopts the existing cross-team label instead of failing. ### Revise — next-step guidance + rejected-proposal preservation - Flagged outcomes now print actionable next steps (read the audit log, hand-edit, re-run with `--scope-to prose`, re-run with `--no-code-context`) instead of leaving users in a dead end. - Demoted `revise → flag` decisions preserve the agent's rejected rewrite in the audit log as a `REJECTED by verifier` diff so users can inspect and hand-apply the parts that make sense. The file is still not written (action remains `flag`); the markdown is kept for audit purposes only. ### BL → QT promote is now AI-driven `openplanr backlog promote BL-XXX --quick` feeds the full BL markdown body (description, acceptance criteria, notes, threat models) through the same AI pipeline used by `openplanr quick create`, producing a realistic task breakdown instead of a single checkbox that restates the title. The new QT carries `sourceBacklog: "BL-XXX"` as provenance and inherits `epicId` from the BL (or an explicit `--epic` override) so `openplanr linear push EPIC-XXX` cascades to it. Use `--manual` to opt out of AI and keep the legacy single-task behavior. ### Config additions ```jsonc { "linear": { "teamId": "UUID", "teamKey": "ENG", "defaultProjectLead": "UUID", "pushStateIds": { "pending": "UUID", "in-progress": "UUID", "done": "UUID" }, "statusMap": { "In Review": "in-progress" }, "standaloneProjectId": "UUID", "standaloneProjectName": "Planr", "defaultEpicStrategy": "project" } } ``` --- title: openplanr 1.2.8 description: Published 2026-04-21. Add openplanr revise — agent-driven alignment of planning artifacts with codebase reality url: https://openplanr.dev/docs/changelog/1.2.8 updated: 2026-04-21 related: - https://openplanr.dev/docs/changelog/1.4.0.md - https://openplanr.dev/docs/changelog/1.3.0.md - https://openplanr.dev/docs/changelog/1.2.7.md --- # openplanr 1.2.8 Published 2026-04-21. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.2.8) ## Patch Changes Add `openplanr revise` — agent-driven alignment of planning artifacts with codebase reality New command complementing `openplanr refine` (prose polish) with a focus on _factual_ alignment: - `openplanr revise <ID>` — revise a single artifact (epic / feature / story / task) - `openplanr revise <ID> --cascade` — top-down revision of an artifact and its descendants (epic → features → stories → tasks); children see the _revised_ parent in their context - `openplanr revise --all` — revise every epic in the project, with a content-hash cache that skips unchanged artifacts - `--dry-run`, `--yes`, `--allow-dirty`, `--scope-to prose|references|paths|all`, `--no-code-context`, `--no-sibling-context`, `--audit-format md|json`, `--max-writes-per-run` Four-layer safety pipeline (every run): 1. **Clean-tree gate** — refuses to run on a dirty git working tree (override with `--allow-dirty`) 2. **Evidence verification** — every AI citation uses a typed kind (`file_exists`, `file_absent`, `grep_match`, `sibling_artifact`, `source_quote`, `pattern_rule`); unverifiable citations are dropped. When a majority of evidence fails to verify, the decision is demoted from `revise` to `flag` so a human reviews instead of silently applying 3. **Diff preview + confirmation** — per-artifact menu: `[a]pply / [s]kip / [e]dit rationale / [d]iff again / [q]uit`; `--yes` still requires typed "YES" at start in an interactive TTY, skipped in non-TTY (CI) environments 4. **Post-flight graph-integrity check + git rollback** — after writes, `syncParentChildLinks` runs; if any cross-reference broke, affected artifact paths are restored via `git checkout`. This is the only v1 mechanism allowed to use the word "rollback"; atomic writes are called atomicity Template-conformance guardrail: - Revise is taught the canonical `## Section` set for each artifact type (from the Handlebars templates) and instructed to flag rather than add sections outside it. Prevents task-level conventions like `## Relevant Files` from leaking into epics - Existing user-maintained custom sections are preserved byte-for-byte Other safety properties: - **Atomic writes** with sidecar backups (`.planr/reports/revise-<scope>-<date>/backup/`) — no partial files ever on disk - **Facts win from code, plan wins on intent** — concrete paths and symbols are rewritten to match the repo; what the feature is _supposed to do_ is never rewritten (intent conflicts surface as `flag` with ambiguous entries) - **Graceful mid-cascade interrupt** — Ctrl+C and `[q]uit` let any in-flight atomic write complete, stop cleanly, and flush the audit log immediately; already-applied artifacts stay applied - **SIGINT closes the audit log cleanly** with an `interrupted: sigint` footer, so Ctrl+C at the confirmation prompt doesn't leave a half-written log Every run emits a Markdown or JSON audit log under `.planr/reports/` capturing applied / skipped / flagged / failed artifacts with rationale, evidence, ambiguities, and unified diffs — dry-run included. After a successful apply, revise prints: ``` git commit -am "chore(plan): revise <SCOPE> against codebase" ``` See the [README section on `openplanr revise`](https://github.com/openplanr/OpenPlanr/blob/main/README.md#planr-revise--align-planning-with-reality) for workflow examples. --- title: openplanr 1.2.7 description: Published 2026-04-19. Add stakeholder reporting & PM intelligence layer url: https://openplanr.dev/docs/changelog/1.2.7 updated: 2026-04-19 related: - https://openplanr.dev/docs/changelog/1.3.0.md - https://openplanr.dev/docs/changelog/1.2.8.md - https://openplanr.dev/docs/changelog/1.2.6.md --- # openplanr 1.2.7 Published 2026-04-19. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.2.7) ## Patch Changes Add stakeholder reporting & PM intelligence layer New commands: - `openplanr report <type>` — generate `sprint`, `weekly`, `executive`, `standup`, `retro`, or `release` reports from `.planr/` artifacts and (optionally) recent GitHub commits/PRs, written as Markdown + HTML under `.planr/reports/` - `openplanr report-linter [file]` — validate stakeholder markdown against configurable rules (vague language, evidence density, required sections per report type) with coaching hints - `openplanr context` — emit the report context pack (artifacts + sprint state + GitHub signals + flat evidence index) as JSON for piping - `openplanr voice standup` — convert a transcript file or stdin into a structured Yesterday / Today / Blockers standup, with optional `--lint`, `--edit`, `--reload-file`, and `--append-story` - `openplanr story standup --story <ID>` — append linted standup notes onto an existing user story Reporting features: - `--lint` and `--strict-evidence` quality gates so vague or unsupported claims do not ship - `--push slack` via [Incoming Webhooks](https://api.slack.com/messaging/webhooks) (`distribution.slackWebhookUrl` in `.planr/config.json`); `--dry-run` works without a webhook configured - `--push github` archives the report as a `planr:report` GitHub issue via the local `gh` CLI - Optional org branding and extra sections via the `reports` block in config; optional rule overrides via the `reportLinter` block Out of scope for this release (deferred): - Bundled PDF rendering (`--format pdf` exits with a clear "not in this build" message) - SMTP email delivery (the email path is a documented stub) - Live microphone capture and bundled speech-to-text — pair `openplanr voice standup` with any STT or OS dictation tool - Per-segment audio replay, Slack OAuth / multi-channel routing, native git-tree report commits, persistent cross-session coaching history See [docs/EPIC-PM-REPORTING-LAYER.md](https://github.com/openplanr/OpenPlanr/blob/main/docs/EPIC-PM-REPORTING-LAYER.md) for the design and shipped-vs-deferred matrix. --- title: openplanr 1.2.6 description: Published 2026-04-14. Replace gray-matter with yaml package to eliminate eval() vulnerability url: https://openplanr.dev/docs/changelog/1.2.6 updated: 2026-04-14 related: - https://openplanr.dev/docs/changelog/1.2.8.md - https://openplanr.dev/docs/changelog/1.2.7.md - https://openplanr.dev/docs/changelog/1.2.5.md --- # openplanr 1.2.6 Published 2026-04-14. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.2.6) ## Patch Changes Replace gray-matter with yaml package to eliminate eval() vulnerability - Remove gray-matter dependency (+ 6 transitive deps including js-yaml with eval) - Add yaml package (zero deps, YAML 1.2 spec, no eval, maintained by YAML spec editors) - Custom frontmatter parse/stringify in ~15 lines with robust regex handling --- title: openplanr 1.2.5 description: Published 2026-04-12. Add artifact update commands and GitHub issue type auto-assignment url: https://openplanr.dev/docs/changelog/1.2.5 updated: 2026-04-12 related: - https://openplanr.dev/docs/changelog/1.2.7.md - https://openplanr.dev/docs/changelog/1.2.6.md - https://openplanr.dev/docs/changelog/1.2.4.md --- # openplanr 1.2.5 Published 2026-04-12. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.2.5) ## Patch Changes Add artifact update commands and GitHub issue type auto-assignment - Add `openplanr update <ids...>` top-level command with batch support, status validation, and `--force` override - Add `update` subcommand to all artifact types: epic, feature, story, task, quick, backlog - Supported fields: `--status` (all types), `--owner` (epic/feature), `--priority` (backlog) - Auto-set GitHub issue types (Task, Feature) via GraphQL when pushing with `openplanr github push` - Extract shared `updateArtifactFields()` using regex-based replacement to preserve file formatting - Harden environment variable access with explicit allowlist in credentials-service --- title: openplanr 1.2.4 description: Published 2026-04-10. Code quality and performance improvements url: https://openplanr.dev/docs/changelog/1.2.4 updated: 2026-04-10 related: - https://openplanr.dev/docs/changelog/1.2.6.md - https://openplanr.dev/docs/changelog/1.2.5.md - https://openplanr.dev/docs/changelog/1.2.3.md --- # openplanr 1.2.4 Published 2026-04-10. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.2.4) ## Patch Changes Code quality and performance improvements - Faster sprint and sync commands via parallelized artifact loading - Consistent error messages across all AI-powered commands - Shared formatting utilities to reduce internal code duplication - JSDoc documentation added to all core service functions --- title: openplanr 1.2.3 description: Published 2026-04-09. Add prompt injection protection with input boundary delimiters and file size validation for --file arguments url: https://openplanr.dev/docs/changelog/1.2.3 updated: 2026-04-09 related: - https://openplanr.dev/docs/changelog/1.2.5.md - https://openplanr.dev/docs/changelog/1.2.4.md - https://openplanr.dev/docs/changelog/1.2.2.md --- # openplanr 1.2.3 Published 2026-04-09. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.2.3) ## Patch Changes Add prompt injection protection with input boundary delimiters and file size validation for --file arguments --- title: openplanr 1.2.2 description: Published 2026-04-09. Reduce AI over-engineering in plan generation with scope discipline rules, count guidance per artifact level, and anti-enumeration… url: https://openplanr.dev/docs/changelog/1.2.2 updated: 2026-04-09 related: - https://openplanr.dev/docs/changelog/1.2.4.md - https://openplanr.dev/docs/changelog/1.2.3.md - https://openplanr.dev/docs/changelog/1.2.1.md --- # openplanr 1.2.2 Published 2026-04-09. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.2.2) Reduce AI over-engineering in plan generation with scope discipline rules, count guidance per artifact level, and anti-enumeration batching ([#62](https://github.com/openplanr/OpenPlanr/pull/62)) --- title: openplanr 1.2.1 description: Published 2026-04-09. Fix project root resolution for monorepos — planr now walks up the directory tree to find .planr/config.json, so commands work from any… url: https://openplanr.dev/docs/changelog/1.2.1 updated: 2026-04-09 related: - https://openplanr.dev/docs/changelog/1.2.3.md - https://openplanr.dev/docs/changelog/1.2.2.md - https://openplanr.dev/docs/changelog/1.2.0.md --- # openplanr 1.2.1 Published 2026-04-09. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.2.1) Fix project root resolution for monorepos — planr now walks up the directory tree to find `.planr/config.json`, so commands work from any subdirectory ([#55](https://github.com/openplanr/OpenPlanr/pull/55)) --- title: openplanr 1.2.0 description: Published 2026-04-08. Add agent-friendly non-interactive mode and API key UX improvements url: https://openplanr.dev/docs/changelog/1.2.0 updated: 2026-04-08 related: - https://openplanr.dev/docs/changelog/1.2.2.md - https://openplanr.dev/docs/changelog/1.2.1.md - https://openplanr.dev/docs/changelog/1.1.0.md --- # openplanr 1.2.0 Published 2026-04-08. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.2.0) Add agent-friendly non-interactive mode and API key UX improvements - Add `--yes`/`-y` flag for fully unattended planning workflows (Claude Code, Cursor, Codex) - Auto-detect non-interactive terminals via TTY detection - All prompts return sensible defaults when non-interactive - Add `openplanr config remove-key` command to delete stored API keys - Show clear multi-line guidance when API key is not configured - Detect existing API keys (env var, OS keychain, encrypted file) during init - Replace magic numbers with named CHECKLIST constants - Fix TOCTOU race condition in checklist reads All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). --- title: openplanr 1.1.0 description: Published 2026-04-06. **.planr/ directory** — all config and planning artifacts now live under .planr/ instead of polluting the project root with… url: https://openplanr.dev/docs/changelog/1.1.0 updated: 2026-04-06 related: - https://openplanr.dev/docs/changelog/1.2.1.md - https://openplanr.dev/docs/changelog/1.2.0.md - https://openplanr.dev/docs/changelog/1.0.1.md --- # openplanr 1.1.0 Published 2026-04-06. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.1.0) ## Added **`.planr/` directory** — all config and planning artifacts now live under `.planr/` instead of polluting the project root with `planr.config.json` and `docs/agile/`. IDE-required files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/`) remain at their mandated locations **Auto-generate AI agent rules on `openplanr init`** — creates `CLAUDE.md`, `AGENTS.md`, and `.cursor/rules/` immediately so users get working agent rules without a separate `openplanr rules generate` step **`openplanr checklist toggle 1 3 5`** — direct argument support alongside interactive mode, with validation of item indices **Auto-check checklist items** — `checkItem()` automatically marks checklist items as done when relevant commands complete (epic→1, feature→2, story→3, task→10) ## Changed **Config path** — `planr.config.json` → `.planr/config.json` **Artifact root** — `docs/agile/` → `.planr/` **Cursor rule templates** — renamed from numeric prefixes (`2000-agile-checklist.mdc`) to clean descriptive names (`agile-checklist.mdc`) to avoid colliding with user's existing rule files ## Fixed **Broken checklist paths** — `{{agilePath}}` template variable was missing from `createChecklist()` template data, producing broken file references **Checklist toggle reporting** — direct-args mode now validates indices against actual checklist items and reports accurate update counts ## Breaking Changes Existing v1.0.x projects need to re-run `openplanr init` --- title: openplanr 1.0.1 description: Published 2026-04-05. No changes are listed for this version. url: https://openplanr.dev/docs/changelog/1.0.1 updated: 2026-04-05 related: - https://openplanr.dev/docs/changelog/1.2.0.md - https://openplanr.dev/docs/changelog/1.1.0.md - https://openplanr.dev/docs/changelog/1.0.0.md --- # openplanr 1.0.1 Published 2026-04-05. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.0.1) No changes are listed for this version. --- title: openplanr 1.0.0 description: Published 2026-04-05. **openplanr backlog** — capture, prioritize, and promote work items from a lightweight backlog url: https://openplanr.dev/docs/changelog/1.0.0 updated: 2026-04-05 related: - https://openplanr.dev/docs/changelog/1.2.0.md - https://openplanr.dev/docs/changelog/1.1.0.md - https://openplanr.dev/docs/changelog/1.0.1.md --- # openplanr 1.0.0 Published 2026-04-05. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v1.0.0) ## Added **`openplanr backlog`** — capture, prioritize, and promote work items from a lightweight backlog - `openplanr backlog add` — capture ideas with priority and tags without breaking your flow - `openplanr backlog list` — filter by tag, priority, or status; sorted by priority - `openplanr backlog prioritize` — AI scores items by impact/effort and reorders them - `openplanr backlog promote` — promote to quick task (`--quick`) or story (`--story --feature`) - `openplanr backlog close` — archive completed or irrelevant items **`openplanr sprint`** — time-boxed iterations with velocity tracking - `openplanr sprint create` — create a sprint with name and duration (1–4 weeks); enforces one-active-at-a-time - `openplanr sprint add` — assign tasks manually or with `--auto` AI selection based on priority and velocity - `openplanr sprint status` — progress dashboard with per-task completion, progress bars, and days remaining - `openplanr sprint close` — archive sprint, list incomplete tasks, optional retrospective - `openplanr sprint list` — all sprints with status badges and task counts - `openplanr sprint history` — velocity chart with bar visualization across closed sprints **`openplanr template`** — reusable task templates for common development workflows - `openplanr template list` — list built-in and custom templates with task counts - `openplanr template show` — preview template contents and variables - `openplanr template use` — generate task list from a template with variable substitution - `openplanr template save` — save an existing task list as a reusable custom template - `openplanr template delete` — remove a custom template **5 built-in task templates** — `rest-endpoint`, `react-component`, `database-migration`, `api-integration`, `auth-flow` **User-defined AI rules** — `.planr/rules.md` injected into AI prompts as mandatory project rules **Auto-extracted pattern rules** — 5 heuristic detectors (generic CRUD, command registration, central types, ID generation, template rendering) produce explicit rules from architecture files **Post-generation validation** — warns about modify-on-missing, create-on-existing, dependency gaps, and unknown directories before user accepts AI output **Dependency chain detection** — import-based file dependency hints injected into AI context **`display` utility** — 13 methods for formatted user-facing output (tables, progress bars, key-value pairs, status badges) **`ArtifactFrontmatter` type** — shared typed interface for artifact frontmatter across all parsers **Shared task-creation helpers** — extracted `buildTaskItems`, `displayTaskPreview`, `displayValidationWarnings`, and related helpers into reusable module **ESM `exports` field** — `package.json` now declares explicit ESM entry point **Dynamic CLI version** — `planr --version` reads version from `package.json` at runtime instead of hardcoding ## Changed **Version** — bumped to 1.0.0 **Package description** — updated to reflect full planning platform: backlog, sprints, task templates, estimation, GitHub sync, and AI agent rules **README** — complete rewrite with expanded feature list, backlog/sprint/template quick start, and organized command tables **CLI.md** — added backlog, sprint, template, and quick task command sections; updated ID convention table, config example, workflow diagram **`openplanr status`** — now shows backlog items with priority badges and active sprint with days remaining **`openplanr search`** — now searches backlog and sprint artifacts **Codebase context builder** — dynamic `src/` subdirectory discovery instead of hardcoded directory list; pattern rules and dependency hints injected into AI prompts **Rules templates rewritten** — Cursor, Claude Code, and Codex templates replaced with 4-step context-gathering protocol (read task → walk parent chain → read ADRs → scan codebase) **Sprint task entries** — now include task title and relative file link (`- [ ] **TASK-001** title — [view](...)`) **Sprint auto-select** — sends subtask counts and parent feature context to AI for smarter velocity-aware selection **Bare catch blocks eliminated** — 39 bare `catch {}` blocks converted to `catch (err) { logger.debug(..., err) }` for `--verbose` debuggability **Strict Biome rules** — enabled `noExplicitAny`, `noNonNullAssertion`, `noConsole` as errors **`@anthropic-ai/sdk`** — bumped from 0.80.0 to 0.81.0 ## Removed **`openplanr task implement` and `openplanr quick implement`** — coding agents (Claude Code, Cursor, Codex) handle implementation directly via generated rules **`openplanr task fix` and `openplanr quick fix`** — replaced by iterative agent workflows **8 agent adapter files** (~1,150 lines) — `agent-factory`, `claude-agent`, `codex-agent`, `cursor-agent`, `implementation-bridge`, `progress`, `prompt-composer`, `types` **Orphaned retry utilities** — dead `MAX_RETRIES`, `isRetryableError`, `sleep` removed after agent deletion **Duplicate `CodingAgentName` type** — consolidated to single definition in `models/types.ts` ## Fixed **Hardcoded source inventory directories** — replaced 7-directory list with dynamic `readdir` discovery that expands into leaf directories **Source inventory listing directories as files** — uses `readdir` with `withFileTypes` and `.isFile()` filter **`countInventoryMatches` counting lines** — now parses comma-separated file names per inventory line **Dependency chain warning wording** — "modified but" changed to "referenced but" for accuracy **`displayValidationWarnings` loose typing** — `action?: string` replaced with `action: 'modify' | 'create'` **`--file` flag error handling** — stack trace on bad file path replaced with user-friendly error message in quick.ts and epic.ts **Rules reader empty vs missing** — `!content` replaced with explicit `content === null` check **Slugify `ENAMETOOLONG` crash** — filenames truncated at 80 chars with word-boundary trimming **Backlog title triplication** — title no longer repeated three times in generated backlog items **Task parser bold ID regex** — fixed regex that caused empty template saves when IDs were bold-formatted **Sprint "untitled" filename** — sprint creation now uses sprint name for slug instead of falling back to "untitled" **Plan summary overcounting** — reports only artifacts created in current run; task generation failures no longer miscounted **`truncateTitle` empty input** — guards against empty description producing empty artifact titles **`progressBar` percent clamping** — clamps to [0,100] to prevent `String.repeat()` with negative count **`logger.debug` Error formatting** — formats Error instances with stack traces instead of `[object Object]` **Safer Map access patterns** — guarded `Map.get()` returns in sync and dependency-chains to prevent silent no-ops ## Developer Experience **47 new tests** — display utility (22), task-creation helpers (21), E2E smoke (4), edge cases **Coverage thresholds raised** — from 3% to 14% (lines, functions, branches, statements) **`display.*` / `logger.*` separation** — formatted user-facing output vs operational messages --- title: openplanr 0.9.0 description: Published 2026-04-02. **openplanr github push** — push planning artifacts to GitHub Issues. url: https://openplanr.dev/docs/changelog/0.9.0 updated: 2026-04-02 related: - https://openplanr.dev/docs/changelog/0.8.0.md - https://openplanr.dev/docs/changelog/0.7.0.md - https://openplanr.dev/docs/changelog/0.6.0.md --- # openplanr 0.9.0 Published 2026-04-02. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v0.9.0) ## Added **`openplanr github push`** — push planning artifacts to GitHub Issues. Supports single artifact (`openplanr github push EPIC-001`), all artifacts under an epic (`--epic EPIC-001`), or everything (`--all`). Creates labeled issues with type-aware formatting, metadata tables, and collapsible artifact sources. Stores the GitHub issue number in artifact frontmatter for bi-directional linking **`openplanr github sync`** — bi-directional status sync between local artifacts and GitHub Issues. Supports `--direction pull` (GitHub→local), `push` (local→GitHub), or `both` (interactive conflict resolution). Detects open/closed state changes and maps them to artifact status fields **`openplanr github status`** — show sync status of all linked artifacts (local status vs GitHub issue state) **`openplanr export`** — generate consolidated planning reports in markdown (`--format markdown`), JSON (`--format json`), or HTML (`--format html`). Supports epic scoping (`--scope EPIC-001`) and custom output path (`--output ./reports`). HTML reports are self-contained with collapsible sections, status badges, and inline CSS **`openplanr epic create --file <path>`** — read epic description from a file (e.g., a PRD or requirements document) instead of single-line input. Supports multi-line documents of any size **Type-aware GitHub issue formatting** — different body builders for task, epic, feature, and story artifacts with metadata tables, section reordering, and collapsible details **Temp file body delivery** — uses `--body-file` for GitHub issue creation/update to avoid OS argument length limits on large artifacts **Graceful deleted issue handling** — when a linked GitHub issue has been deleted, falls back to creating a new one instead of failing **HTML export template** — self-contained Handlebars template with collapsible `<details>` sections, color-coded status badges, and full hierarchy rendering ## Changed **Epic prompt framing** — `buildEpicPrompt()` detects detailed input (>5 lines) and uses document extraction framing instead of "brief description" framing, so AI faithfully processes large PRDs **Epic system prompt** — updated to explicitly handle detailed PRD input: "extract and incorporate ALL sections — do not summarize or ignore content" **Epic token budget** — increased from 4096 to 8192 to support richer output from detailed PRD input --- title: openplanr 0.8.0 description: Published 2026-03-31. **openplanr estimate <id>** — AI-powered effort estimation for any artifact (task, story, feature, epic, quick). url: https://openplanr.dev/docs/changelog/0.8.0 updated: 2026-03-31 related: - https://openplanr.dev/docs/changelog/0.9.0.md - https://openplanr.dev/docs/changelog/0.7.0.md - https://openplanr.dev/docs/changelog/0.6.0.md --- # openplanr 0.8.0 Published 2026-03-31. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v0.8.0) ## Added **`openplanr estimate <id>`** — AI-powered effort estimation for any artifact (task, story, feature, epic, quick). Returns story points (Fibonacci 1-21), estimated hours, complexity, risk factors, and reasoning **`openplanr estimate --epic <id>`** — Estimates all tasks under an epic and produces a rollup table with total points and hours **`openplanr estimate --calibrate`** — Accuracy report from past estimates on completed artifacts **`openplanr estimate --save`** — Persists estimate to artifact frontmatter (`estimatedPoints`, `estimatedHours`, `complexity`) and appends a full `## Estimate` section to the artifact body **Interactive estimate prompt** — After displaying results, prompts to save, re-estimate, or discard (single artifact) or save all / discard all (epic rollup) **`openplanr search <query>`** — Full-text search across all artifact types with highlighted snippets and 1 line of context **`openplanr search --type <type>`** — Filter search by artifact type (epic, feature, story, task, quick, adr) **`openplanr search --status <status>`** — Filter search results by artifact status **`docs/agile/ESTIMATION.md`** — Estimation rubric generated by `openplanr init` with the full Fibonacci scale, complexity levels, risk categories, and team calibration guidance ## Fixed **Estimate save preserves frontmatter formatting** — Injects estimate fields directly into raw YAML without re-serializing through gray-matter, so original quoting and structure is preserved **Legacy `estimatedEffort` field cleanup** — Free-text `estimatedEffort` fields added by AI during task generation are removed when saving a structured estimate ## Changed **Estimation AI prompt** — Embeds the full story point rubric (Fibonacci scale definitions, complexity levels, risk categories) for consistent and calibrated scoring across all artifacts --- title: openplanr 0.7.0 description: Published 2026-03-31. **openplanr quick** — standalone task lists without the full agile hierarchy (Epic → Feature → Story → Task). url: https://openplanr.dev/docs/changelog/0.7.0 updated: 2026-03-31 related: - https://openplanr.dev/docs/changelog/0.9.0.md - https://openplanr.dev/docs/changelog/0.8.0.md - https://openplanr.dev/docs/changelog/0.6.0.md --- # openplanr 0.7.0 Published 2026-03-31. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v0.7.0) ## Added **`openplanr quick`** — standalone task lists without the full agile hierarchy (Epic → Feature → Story → Task). Ideal for prototyping, bug fixes, hackathons, or any work that doesn't need agile ceremony **`openplanr quick create`** — AI generates a structured task list from a one-line description, with codebase-aware context and relevant file detection **`openplanr quick --manual`** — interactive task entry without AI **`openplanr quick list`** — list all quick task lists **`openplanr quick promote`** — graduate a quick task into the agile hierarchy by attaching to a story or feature **Auto-mark subtasks as done** — after a coding agent completes successfully, implemented subtask checkboxes are automatically checked off in the task markdown **Quick tasks in `openplanr status`** — standalone quick tasks shown in their own section with completion metrics ## Fixed **Claude retry for stdout API errors** — "API Error: 400 due to tool use concurrency" was emitted via stdout (stream-json) rather than stderr, so the retry logic never caught it. Now checks both streams for retryable errors ## Type System Added `'quick'` to `ArtifactType` union Made `TaskList.storyId` optional (quick tasks have no parent story) Added `QT` prefix to ID system and `quick/` directory to artifact mapping --- title: openplanr 0.6.0 description: Published 2026-03-29. Error context helper — truncates large build logs for clearer failure output url: https://openplanr.dev/docs/changelog/0.6.0 updated: 2026-03-29 related: - https://openplanr.dev/docs/changelog/0.8.0.md - https://openplanr.dev/docs/changelog/0.7.0.md - https://openplanr.dev/docs/changelog/0.5.0.md --- # openplanr 0.6.0 Published 2026-03-29. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v0.6.0) ## Added **Error context helper** — truncates large build logs for clearer failure output ## Fixed **Agent hangs on large prompts** — implementation prompt is delivered via temp file + stdin pipe instead of a giant CLI argument (avoids OS argv limits and interactive “wait forever” behavior) **Stream backpressure** — prompt delivery uses `createReadStream` → `stdin` pipe instead of buffered `stdin.write` **Codex sandbox** — `--full-auto` and `--json` so Codex can write files and emit structured events (matches Claude-style progress output) **Claude stderr** — retryable 400/429/5xx errors detected while still showing output in real time ## Changed **Agent stdout/stderr** — `stdio: inherit` for live agent output where applicable **Safety** — system prompt guidance to reduce destructive cross-project commands ## Developer Experience **Linting and formatting** — ESLint and Prettier replaced with [Biome](https://biomejs.dev/) (`biome check` / `biome format`) --- title: openplanr 0.5.0 description: Published 2026-03-28. Secure credential storage — API keys are now stored in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)… url: https://openplanr.dev/docs/changelog/0.5.0 updated: 2026-03-28 related: - https://openplanr.dev/docs/changelog/0.7.0.md - https://openplanr.dev/docs/changelog/0.6.0.md - https://openplanr.dev/docs/changelog/0.4.0.md --- # openplanr 0.5.0 Published 2026-03-28. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v0.5.0) ## Added **Secure credential storage** — API keys are now stored in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) via `@napi-rs/keyring`, with AES-256-GCM encrypted file fallback for environments without a keychain (CI, Docker, SSH) **Automatic credential migration** — existing plaintext `~/.planr/credentials.json` keys are migrated to the secure backend on first access, then the plaintext file is deleted **Credential source display** — `openplanr config show` now shows where the API key is stored: `(OS keychain)`, `(encrypted file)`, or `(env: ANTHROPIC_API_KEY)` **Per-command token budgets** — each command uses a tuned `maxTokens` limit (epic: 4K, feature/story/refine: 8K, task: 16K, task --feature: 32K) instead of a one-size-fits-all default **Definitive truncation detection** — uses `stop_reason` (Anthropic) / `finish_reason` (OpenAI) to detect truncated responses instead of heuristic token thresholds **8 new truncation unit tests** covering skip-retry, per-attempt token reporting, and streaming truncation ## Changed **`openplanr config set-key`** now shows the storage backend: `"saved to OS keychain"` or `"saved to encrypted file"` **AI service refactored** — `generateJSON` and `generateStreamingJSON` now share a common `generateCore()` function, eliminating duplicated validation/retry/truncation logic **GitHub Actions** updated to v6 (checkout, setup-node) and v7 (upload-artifact) with Node.js 24 ## Fixed **Task generation from features failing** — `openplanr task create --feature` was truncating AI responses at 4,096 tokens, producing invalid JSON. Now uses 32K budget **Spinner not stopping on API errors** — spinner animation no longer mixes with error messages when the AI provider throws **Spinner showing ✓ before validation** — `succeed()` now only fires after successful parse/validation, not before **Truncation error over-reporting tokens** — error messages now show per-attempt output tokens instead of cumulative totals **Keychain write failures crashing** — `saveCredential` now catches keychain errors and falls back to encrypted file **Migration flag set before completion** — `migrateCredentials` now resets the flag on failure so it retries next invocation **`resolveApiKeySource` skipping migration** — `config show` now properly triggers legacy credential migration ## Security API keys no longer stored in plaintext on disk Encrypted file uses AES-256-GCM with machine-derived key (hostname + username + per-installation salt via scrypt) File permissions set to `0o600` on all credential files ## Developer Experience Test coverage: 261 → 269 tests across 23 test files Added `tests/unit/ai-service-truncation.test.ts` (8 tests) Added `tests/unit/credential-backends.test.ts` (8 tests) Expanded `tests/unit/credentials-service.test.ts` with mocked backends (13 tests) --- title: openplanr 0.4.0 description: Published 2026-03-28. Token usage display — shows input/output token counts after every AI call (✓ Done (1,240 in → 860 out tokens)) url: https://openplanr.dev/docs/changelog/0.4.0 updated: 2026-03-28 related: - https://openplanr.dev/docs/changelog/0.6.0.md - https://openplanr.dev/docs/changelog/0.5.0.md - https://openplanr.dev/docs/changelog/0.3.0.md --- # openplanr 0.4.0 Published 2026-03-28. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v0.4.0) ## Added **Token usage display** — shows input/output token counts after every AI call (`✓ Done (1,240 in → 860 out tokens)`) **`openplanr refine --cascade`** — refines an artifact then cascades to all children down the full hierarchy (epic → features → stories → tasks) **Parent-aligned refinements** — child refinements receive updated parent content as context so AI aligns changes with the parent **Post-refine next steps** — after applying without `--cascade`, suggests which children may need re-alignment **Cumulative token usage** for cascade operations (`Cascade complete: 7 artifacts refined (12,400 in → 8,200 out tokens total)`) **Spinner `succeed()` method** — shows green checkmark with completion message instead of silently clearing ## Changed **Updated all dependencies** to latest major versions: `@anthropic-ai/sdk` 0.80, `openai` 6.x, `zod` 4.x, `commander` 14.x, `@inquirer/prompts` 8.x, `typescript` 6.x, `vitest` 4.x **Removed `fs-extra`** dependency — replaced with Node.js built-in `fs/promises` **Removed `ora`** dependency — replaced with lightweight built-in spinner **Dropped Node 18 support** — minimum Node version is now 20 **Refine prompt** now preserves existing cross-reference links instead of adding phantom references **"Suggestions" renamed to "Improvements"** in refine output for clearer UX ## Fixed **Refine command** no longer adds feature/story references that don't exist on disk **CI publish workflow** — fixed npm trusted publishing with bypass 2FA token --- title: openplanr 0.3.0 description: Published 2026-03-27. **openplanr story create --epic <ID>** — batch-generate stories for all features under an epic url: https://openplanr.dev/docs/changelog/0.3.0 updated: 2026-03-27 related: - https://openplanr.dev/docs/changelog/0.5.0.md - https://openplanr.dev/docs/changelog/0.4.0.md - https://openplanr.dev/docs/changelog/0.2.0.md --- # openplanr 0.3.0 Published 2026-03-27. [Release on GitHub](https://github.com/openplanr/OpenPlanr/releases/tag/v0.3.0) ## Added **`openplanr story create --epic <ID>`** — batch-generate stories for all features under an epic **`openplanr checklist toggle`** — interactively toggle checklist items with multi-select prompt **`openplanr config set-provider/set-key/set-model/set-agent`** — full AI configuration commands **`--verbose` global flag** — debug logging across all commands **`--all` flag on `openplanr status`** — show all items without truncation **`--manual` flag** on epic, feature, story, and task create commands **`--feature` filter** on `openplanr story list` **Integration test suite** with real file system tests for artifact lifecycle and sync **Test helpers** (`createTestProject`, `writeSampleEpic/Feature/Story`) for integration testing **Pre-commit hooks** with husky + lint-staged (runs related tests on commit) **Coverage reporting** with `@vitest/coverage-v8` and CI artifact upload **CODEOWNERS** file for automatic review assignment **Architecture guide** (`docs/ARCHITECTURE.md`) **Troubleshooting guide** (`docs/TROUBLESHOOTING.md`) **Security policy**, issue templates, and PR template ## Changed **`openplanr status`** — enhanced with tree view (epic → features → stories), task completion metrics with color-coded progress, and overall completion summary **`openplanr refine`** — apply action now works: writes improved markdown to disk with view/apply/skip options **`openplanr checklist show`** — now displays color-coded completion progress **Documentation** — CLI.md now covers all 25 command variants with complete option tables **README commands table** — expanded from 19 to 25 entries ## Fixed **Refine command** returning JSON instead of markdown in `improvedMarkdown` field — added explicit prompt instructions and JSON-detection fallback **ID gap-filling** — `getNextId()` now reuses gaps (e.g., TASK-001 if only TASK-002 exists) **npm bin paths** — added `./` prefix to suppress publish warnings ## Security Bumped `handlebars` from 4.7.8 to 4.7.9 (fixes critical vulnerability) Dropped Node 18 support (EOL) — minimum Node 20 ## Developer Experience Test coverage: 3 → 15 test files, 167 tests passing Unit tests for: task-parser, markdown, fs, id-service, artifact-service, config-service, template-service, prompt-builder, logger, checklist-service Integration tests for: artifact lifecycle, sync command CI runs coverage on Node 22 with summary artifact upload Upgraded to vitest 4.x --- title: openplanr 0.2.0 description: Published 2026-03-26. **openplanr plan** — full automated flow (Epic → Features → Stories → Tasks) url: https://openplanr.dev/docs/changelog/0.2.0 updated: 2026-03-26 related: - https://openplanr.dev/docs/changelog/0.4.0.md - https://openplanr.dev/docs/changelog/0.3.0.md - https://openplanr.dev/docs/changelog/0.1.0.md --- # openplanr 0.2.0 Published 2026-03-26. ## Added **`openplanr plan`** — full automated flow (Epic → Features → Stories → Tasks) **`openplanr refine <ID>`** — AI-powered review and improvement suggestions **`openplanr sync`** — validate and fix cross-references across artifacts **`openplanr config show`** — display current configuration **`openplanr task create --feature <ID>`** — AI task list from every story under the feature, with parent feature and epic, all Gherkin files for those stories, all ADRs, and codebase-derived context (higher output token budget than per-story task create) Feature-level task generation shares the same rich context model as `--story`, aggregated across the feature --- title: openplanr 0.1.0 description: "Published 2026-03-25. CLI tool with planr command (alias: opr)" url: https://openplanr.dev/docs/changelog/0.1.0 updated: 2026-03-25 related: - https://openplanr.dev/docs/changelog/0.4.0.md - https://openplanr.dev/docs/changelog/0.3.0.md - https://openplanr.dev/docs/changelog/0.2.0.md --- # openplanr 0.1.0 Published 2026-03-25. ## Added **CLI tool** with `planr` command (alias: `opr`) **`openplanr init`** — initialize project with config and agile directory structure **`openplanr epic create/list`** — create and list epics **`openplanr feature create/list`** — create features from epics **`openplanr story create/list`** — create user stories with Gherkin acceptance criteria **`openplanr task create/list`** — task lists from a story or from all stories in a feature (AI mode includes epic, feature, Gherkin, ADRs, codebase context) **`openplanr checklist show/reset`** — agile development checklist **`openplanr rules generate`** — generate AI agent rule files - Cursor (`.cursor/rules/*.mdc`) - Claude Code (`CLAUDE.md`) - Codex (`AGENTS.md`) **`openplanr status`** — project planning progress overview Handlebars template system for all artifact generation Zod schema validation for configuration Auto-incrementing ID system (EPIC-001, FEAT-001, US-001, TASK-001) Full agile hierarchy enforcement (epic > feature > story > task) --- title: Resources description: Reference pages, support, release verification, and what the docs offer coding agents, plus where to contribute to OpenPlanr on GitHub. url: https://openplanr.dev/docs/resources updated: 2026-10-06 related: - https://openplanr.dev/docs/resources/agents.md - https://openplanr.dev/docs/resources/support.md - https://openplanr.dev/docs/resources/verify-a-release.md --- # Resources Pages that support the rest of the docs: how to get help, how to check what you installed, and how the planning files are shaped. ## Reference - [Spec-driven planning files](https://openplanr.dev/docs/reference/spec-schema.md): the file-level reference for specs, stories, and tasks. - [CLI reference](https://openplanr.dev/docs/cli): every public `openplanr` command and option. - [Changelog](https://openplanr.dev/docs/changelog.md): every release of the `openplanr` package. ## Help and trust - [Support](https://openplanr.dev/docs/resources/support.md): where to ask questions, how to report a bug, and what to include. - [Verifying a release](https://openplanr.dev/docs/resources/verify-a-release.md): check that a published version came from a reviewed commit, with its npm provenance attestation. - [For coding agents](https://openplanr.dev/docs/resources/agents.md): Markdown versions of every page and the `llms.txt` index. ## Contribute OpenPlanr is developed in the open under the MIT license. The architecture guide, contributing guide, skill authoring guide, and release process live in the [OpenPlanr repository on GitHub](https://github.com/openplanr/OpenPlanr). --- title: For coding agents description: Every docs page as Markdown, an llms.txt index, and Copy page, so the coding agent working for you can read the OpenPlanr docs directly. url: https://openplanr.dev/docs/resources/agents updated: 2026-10-07 related: - https://openplanr.dev/docs/resources.md - https://openplanr.dev/docs/resources/support.md - https://openplanr.dev/docs/resources/verify-a-release.md --- # For coding agents These docs are written for people and for the coding agents that read them on your behalf. Every page is available as plain Markdown, and an index tells an agent where to look. ## Read any page as Markdown Add `.md` to the address of any docs page to get its Markdown version. For example, [this page](https://openplanr.dev/docs/resources/agents.md) is also at `/docs/resources/agents.md`. The same Markdown comes back when a request sends `Accept: text/markdown`, and every page points to its Markdown version with `<link rel="alternate" type="text/markdown">`. ## Start from the index `/docs/llms.txt` follows the [llms.txt proposal](https://llmstxt.org/). It lists every docs page by section, each with a one-line summary and a link to its Markdown version. `/docs/llms-full.txt` holds every docs page in one Markdown file. ## Copy a page The Copy page button on every page copies the page as Markdown. Its menu also opens the Markdown version, or opens the page in Claude or ChatGPT with its address filled in. ## Set up OpenPlanr from an agent The [agent setup guide](https://openplanr.dev/setup.md) is a Markdown file written for coding agents. [Set up from your agent](https://openplanr.dev/docs/get-started/agent-setup.md) explains what it does and what it asks you first. To set up OpenPlanr for a user, fetch https://openplanr.dev/setup.md and follow its steps in order. To answer a question about OpenPlanr, start from https://openplanr.dev/docs/llms.txt and read the Markdown version of the relevant page. ## Connect over MCP Connect a Streamable HTTP MCP client to `https://openplanr.dev/docs/mcp`. The server is read-only and needs no API key. `search(query, section?)` returns up to six passages with a title, an anchored URL and text. The optional section is a URL segment such as `get-started`, `skills`, `prompts` or `cli`. `fetch_page(url)` returns the same Markdown as the page's twin; it accepts `/docs/...` paths and `https://openplanr.dev/docs/...` URLs, including `.md` links. For [Claude Code](https://code.claude.com/docs/en/mcp), run: ```sh claude mcp add --transport http openplanr-docs https://openplanr.dev/docs/mcp ``` For [Codex](https://developers.openai.com/codex/mcp), run: ```sh codex mcp add openplanr-docs --url https://openplanr.dev/docs/mcp ``` For [Cursor](https://cursor.com/docs/context/mcp), add this entry to `.cursor/mcp.json` in your project, merging it with any existing servers: ```json { "mcpServers": { "openplanr-docs": { "url": "https://openplanr.dev/docs/mcp" } } } ``` The endpoint is rate limited. If it replies with HTTP 429, try again later or read `/docs/llms.txt` and the linked Markdown pages directly. It searches the published docs without calling a model. --- title: Support description: "Use GitHub Discussions: Q&A for setup and usage questions, Ideas for proposals, Show and tell for what you built." url: https://openplanr.dev/docs/resources/support updated: 2026-10-06 related: - https://openplanr.dev/docs/resources.md - https://openplanr.dev/docs/resources/agents.md - https://openplanr.dev/docs/resources/verify-a-release.md --- # Support ## Ask a question Use [GitHub Discussions](https://github.com/openplanr/OpenPlanr/discussions): **Q&A** for setup and usage questions, **Ideas** for proposals, **Show and tell** for what you built. Search first; many setup questions are answered in the [getting started guide](https://openplanr.dev/docs/get-started/install.md) and the [troubleshooting guide](https://openplanr.dev/docs/get-started/troubleshooting.md). ## Report a bug Open an issue through the [issue forms](https://github.com/openplanr/OpenPlanr/issues/new/choose). Include: ```bash openplanr --version openplanr doctor --json ``` plus the host (Claude Code, Codex, or Cursor) and its version, the scope you installed with, the exact command or skill invocation, what you expected, and what happened. Doctor output redacts secrets; check it anyway before pasting. ## A skill misbehaves Use the **Skill behavior** form. Say which skill, what you asked, what it produced, and which files under `.planr/` it touched. Rerun `openplanr setup` and restart the host first; a same-version plugin that carries old content is replaced by setup. ## Security Do not open a public issue. Follow [SECURITY.md](https://github.com/openplanr/OpenPlanr/blob/4d4fb273180f65c6c648e6babd4b9c6ae8465ff2/SECURITY.md). ## What to expect Support is best-effort from the maintainers and community. There is no response-time commitment for the open-source project. Bugs with a reproduction and doctor output are triaged first. --- title: Verifying a release description: Every OpenPlanr package version is published by publish-packages.yml from a reviewed commit on main, with an npm provenance attestation, and is never… url: https://openplanr.dev/docs/resources/verify-a-release updated: 2026-10-06 related: - https://openplanr.dev/docs/resources.md - https://openplanr.dev/docs/resources/agents.md - https://openplanr.dev/docs/resources/support.md --- # Verifying a release Every OpenPlanr package version is published by `publish-packages.yml` from a reviewed commit on `main`, with an npm provenance attestation, and is never republished: a correction is always a new version. The release workflow rebuilds each package from its build commit, compares the archive file by file with what it publishes, then creates a package-qualified tag (`<package>@<version>`) at that commit and a GitHub release carrying the integrity string, the attested build commit, and the run that produced it. ## Check a version yourself ```bash npm install openplanr@<version> --ignore-scripts npm audit signatures ``` `npm audit signatures` verifies the registry signature and the provenance attestation, which names the source commit and the workflow run that built the archive. The same evidence is on the [releases page](https://github.com/openplanr/OpenPlanr/releases), one release per published version, and in npm's provenance panel on each package page: - [`openplanr`](https://www.npmjs.com/package/openplanr) - [`planr-pipeline`](https://www.npmjs.com/package/planr-pipeline) - [`@openplanr/protocol`](https://www.npmjs.com/package/@openplanr/protocol) To rebuild an archive yourself, check out the tag, run `npm ci && npm run generate && npm run build`, then `npm pack --ignore-scripts` in the package directory and compare the result with the archive the registry serves. ## Notes `@openplanr/protocol@0.2.0` was published by hand moments before its workflow run and carries a registry signature but no build attestation. Every later version of every package was published by the workflow. `planr-pipeline` versions `0.43.0` and `0.44.0` were internal release candidates that were never published; the registry history runs `0.42.0` → `0.45.0`. ## License OpenPlanr is [MIT licensed](https://github.com/openplanr/OpenPlanr/blob/4d4fb273180f65c6c648e6babd4b9c6ae8465ff2/LICENSE); see also the [CLI](https://github.com/openplanr/OpenPlanr/blob/4d4fb273180f65c6c648e6babd4b9c6ae8465ff2/packages/cli/LICENSE) and [pipeline](https://github.com/openplanr/OpenPlanr/blob/4d4fb273180f65c6c648e6babd4b9c6ae8465ff2/packages/pipeline/LICENSE) license files and [THIRD_PARTY-DIAGRAM-NOTICES.md](https://github.com/openplanr/OpenPlanr/blob/4d4fb273180f65c6c648e6babd4b9c6ae8465ff2/packages/pipeline/THIRD_PARTY-DIAGRAM-NOTICES.md). Third-party dependencies retain their own licenses. --- title: Spec-driven planning files (schema 1.0.0) description: "This is the file-level reference for spec-driven mode: what the planr-spec, planr-plan, and planr-ship skills write under .planr/specs/, and what the openplanr…" url: https://openplanr.dev/docs/reference/spec-schema updated: 2026-10-06 related: [] --- # Spec-driven planning files (schema 1.0.0) This is the file-level reference for spec-driven mode: what the `planr-spec`, `planr-plan`, and `planr-ship` skills write under `.planr/specs/`, and what the `openplanr spec` commands validate. The canonical JSON Schemas live in [`packages/protocol/schemas/v1.0.0`](https://github.com/openplanr/OpenPlanr/tree/main/packages/protocol/schemas/v1.0.0); the CLI and the `planr-pipeline` package read the same contract with no conversion layer. When authoring these files by hand, use the templates below verbatim. > **Schema version:** `1.0.0` > **Pinning rule:** the `schemaVersion` field on every artifact MUST match the > reader's expected version. Breaking changes start in the Protocol schema source > and are mirrored here before release. --- ## Directory layout Every spec is a self-contained directory under `.planr/specs/`: ``` .planr/specs/SPEC-NNN-{slug}/ ├── SPEC-NNN-{slug}.md # the functional spec (one per directory) ├── design/ # optional — UI mockups + design-spec │ ├── *.png # PNG mockups attached via `openplanr spec attach-design` │ └── design-spec.md # written by the designer agent ├── stories/ │ └── US-NNN-{slug}.md # user stories scoped to this spec ├── tasks/ │ └── T-NNN-{slug}.md # tasks scoped to this spec ├── qa-report.md # written by the QA agent after planr-ship ├── error-report.md # written if a task fails 3 iterations └── .pipeline-shipped # written by planr-ship — proof of execution ``` **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 the `specId` frontmatter field. --- ## SPEC frontmatter ```yaml --- id: "SPEC-001" # required · format: SPEC-\d{3} title: "User authentication" # required · human-readable title slug: "auth" # required · URL-safe lowercase, used in path schemaVersion: "1.0.0" # required · pinned to reader version status: "pending" # required · pending | shaping | shaped | decomposing | decomposed | in-pipeline | done priority: "P0" # required · P0 | P1 | P2 | P3 milestone: "v1.0" # optional · links to a milestone or release po: "product-owner" # optional · spec owner (Product Owner) created: "2026-04-26" # required · ISO date (YYYY-MM-DD) updated: "2026-04-26" # required · ISO date, bumped on edit ui_files: [] # required · array of PNG paths under design/ (empty if none) tech_dependencies: [] # required · array of strings; informational only --- ``` ### Field meanings | Field | Type | Meaning | |---|---|---| | `id` | string | Project-globally unique. Format `SPEC-NNN` (3-digit). The directory MUST be `SPEC-NNN-{slug}/`. | | `title` | string | Display title. Human-readable. | | `slug` | string | URL-safe lowercase. Used in the directory name and in story and task slugs. | | `schemaVersion` | string | Pinned schema version. `1.0.0` currently. Readers MUST refuse mismatched versions. | | `status` | enum | Lifecycle marker: `pending` (just created) → `shaping` (questions in progress) → `shaped` (body authored) → `decomposing` (planning in progress) → `decomposed` (stories and tasks written) → `in-pipeline` (ship in progress) → `done` (shipped). | | `priority` | enum | `P0` (must) / `P1` (should) / `P2` (nice) / `P3` (defer). | | `milestone` | string? | Optional release/milestone tag. | | `po` | string? | Optional Product Owner identifier (email or username). | | `created` / `updated` | string | ISO 8601 date. Bumped automatically by `openplanr spec` commands. | | `ui_files` | array | List of PNG file paths under `design/`. Non-empty lists route the designer agent. | | `tech_dependencies` | array | Free-form list of upstream tech dependencies. Informational; not consumed automatically. | ### SPEC body sections (in order) The spec body uses the following H2 sections. `openplanr spec shape` writes them from interactive questions; the `planr-plan` skill reads them. 1. **`## Context & Goal`** — 2-5 sentences on the user need + outcome 2. **`## Functional Requirements`** — bullet list, action verbs 3. **`## Business Rules`** — constraints and validations 4. **`## User Flows`** — numbered step-by-step flows 5. **`## Out of Scope`** — explicit non-goals 6. **`## Acceptance Criteria`** — Given/When/Then bullets 7. **`## Notes for Decomposition`** *(optional)* — hints for planning, NOT requirements The `## Notes for Decomposition` section is freeform prose hinting at the intended story split, special attention areas, or files to preserve. The `planr-plan` skill reads it to bias its output. Example: ```markdown - Suggested US split: auth flow (UI), session management (Tech) - Special attention: the delete flow needs a confirmation dialog - Preserve: do not modify the existing UserService ``` --- ## Story frontmatter Stories live at `.planr/specs/SPEC-NNN-{slug}/stories/US-NNN-{story-slug}.md`. ```yaml --- id: "US-001" # required · format: US-\d{3} (scoped to parent SPEC) title: "Login form" # required specId: "SPEC-001" # required · MUST match parent spec id slug: "login-form" # required · URL-safe; matches filename suffix schemaVersion: "1.0.0" # required status: "pending" # required · pending | in-progress | done priority: "P0" # required · P0 | P1 | P2 | P3 created: "2026-04-26" # required updated: "2026-04-26" # required --- ``` ### Story body sections ```markdown # US-001 — Login form > **Spec:** SPEC-001 ## Story As a **<role>** I want **<action>** so that **<benefit>**. ## Scope <2-3 sentences describing what's in scope for this story> ## Acceptance Criteria - [ ] Given <context>, when <action>, then <observable outcome>. - [ ] Given …, when …, then … ## Dependencies <Optional: tasks or stories this depends on, by id> ``` --- ## Task frontmatter Tasks live at `.planr/specs/SPEC-NNN-{slug}/tasks/T-NNN-{task-slug}.md`. ```yaml --- id: "T-001" # required · format: T-\d{3} (scoped to parent SPEC) title: "Build login form component" # required storyId: "US-001" # required · MUST match a story id under the same spec specId: "SPEC-001" # required · MUST match the parent spec id slug: "login-form-component" # required · URL-safe; matches filename suffix schemaVersion: "1.0.0" # required type: "UI" # required · "UI" | "Tech" agent: "frontend-agent" # required · subagent that owns this task status: "pending" # required · pending | in-progress | done created: "2026-04-26" # required updated: "2026-04-26" # required --- ``` ### Type → agent mapping | `type` | Default `agent` | Notes | |---|---|---| | `UI` | `frontend-agent` | UI-focused work: components, pages, styles | | `Tech` | `backend-agent` | Backend, services, controllers, DTOs, migrations | The `frontend-agent` reads tasks where `type: UI`; the `backend-agent` reads tasks where `type: Tech`. Setting `agent` to a different value (e.g. a custom subagent name) overrides the default routing. ### Task body sections ```markdown # T-001 — Build login form component > **User Story:** US-001 > **Spec:** SPEC-001 > **Type:** UI > **Agent:** `frontend-agent` ## Objective <1-2 sentences: what does this task accomplish?> ## Files ### Create - `src/components/auth/LoginForm.tsx` - `src/components/auth/LoginForm.test.tsx` ### Modify - `src/app/login/page.tsx` (mount the component) ### Preserve - `src/app/layout.tsx` (do not touch) - `package.json` (do not add dependencies) ## Technical Spec <Implementation detail: libraries, patterns, integration points. The frontend or backend agent reads this verbatim.> ## Test Requirements <Build / test commands and DoD checks. The qa-agent reads this to verify completion.> ## Definition of Done - [ ] Code compiles (`npm run build`) - [ ] Tests pass (`npm test`) - [ ] Lint clean - [ ] All Create files exist - [ ] All Modify files updated only as described - [ ] All Preserve files unchanged (verified via `git diff`) ``` The **`### Create` / `### Modify` / `### Preserve`** lists are NOT optional — the qa-agent verifies them via `git diff` before accepting the task as done. A task that touches files outside these lists fails QA. --- ## `.pipeline-shipped` marker Written by the `planr-ship` skill at the end of a successful (or partially successful) run. This is the canonical proof that the work was shipped through the workflow, not a hand-authored Markdown file. ```yaml shipped_at: "2026-04-26T22:30:00Z" pipeline_version: "0.4.0" mode: "spec-driven" feature: "auth" tasks_executed: 3 tasks_failed: 0 qa_gate_status: "passed" duration_seconds: 287 agents_invoked: - frontend-agent - backend-agent - qa-agent - devops-agent - doc-gen-agent devops_status: "generated" docs_status: "generated" snapshot_status: "refreshed" error_reports: [] ``` If the marker is absent, the work was not shipped through the workflow. Audit trails reference this file by path: `.planr/specs/SPEC-NNN-{slug}/.pipeline-shipped`. --- ## Status lifecycle (the full path) A spec moves through these states, in order: ``` pending → shaping → shaped → decomposing → decomposed → in-pipeline → done ``` | State | Set by | Meaning | |---|---|---| | `pending` | `openplanr spec create` | Spec directory exists; body is the empty template | | `shaping` | `openplanr spec shape` (in progress) | Q&A flow active | | `shaped` | `openplanr spec shape` (complete) | Spec body has Context/FRs/Rules/AC sections filled | | `decomposing` | `planr-plan` skill (in progress) | Stories and tasks are being written | | `decomposed` | `planr-plan` skill (complete) | `stories/` and `tasks/` are populated | | `in-pipeline` | `planr-ship` skill (in progress) | Implementation running | | `done` | `planr-ship` skill (complete) | Tasks executed, QA passed, marker written | --- ## Schema version compatibility The CLI, the skills, and the `planr-pipeline` package produce and consume schema `1.0.0`. Breaking changes bump `schemaVersion` in lockstep. Keep them aligned: ```bash npm install -g openplanr@latest openplanr setup openplanr upgrade status ``` --- ## See also - [`openplanr` package README](https://github.com/openplanr/OpenPlanr/blob/4d4fb273180f65c6c648e6babd4b9c6ae8465ff2/packages/cli/README.md) - [CLI reference](https://openplanr.dev/docs/cli) - [`planr-pipeline` package](https://github.com/openplanr/OpenPlanr/tree/main/packages/pipeline) - [Pipeline rules](https://github.com/openplanr/OpenPlanr/blob/main/packages/pipeline/docs/rules.md)