Planr Plan

---
name: planr-plan
description: Turn a Protocol-compatible specification or product intent into schema-compatible OpenPlanr stories and implementation tasks. Use for planning and decomposition, not implementation.
license: MIT
---

# OpenPlanr Plan

Turn a decision-complete specification or clear product request into
implementation-ready stories and tasks. Perform the reasoning in this active
coding session. Do not delegate semantic planning to a command-line or model
subprocess. Plan ends with a Ship handoff; it never starts implementation
automatically.

## Resolve context directly

Read the strongest available inputs:

1. the request and selected specification;
2. repository instructions (`AGENTS.md`, `CLAUDE.md`, or equivalents), ADRs,
   planning rules, and active stack files named by the repository;
3. relevant implementation code, tests, package scripts, and CI configuration;
4. design inputs and design specifications when a browser surface is involved;
5. the database schema or persistence code when data behavior is involved.

Use repository-local conventions first. Missing legacy `input/` or `.planr/`
paths do not block a clear request. State what was unavailable and continue when
the remaining context is sufficient.

For a completed Design handoff, read `design-document.json`, the selected
direction, and the authored ten-section `design-spec.md`. The specification lives
inside `design/` in spec-driven mode and beside `design/` in default feature mode.
For a studio-backed design, read its `.design/studio-state.json`: the recorded
`selectedVariant` is authoritative. Verify that the authored document and the
specification describe that same direction before decomposing UI work. If they
disagree, synchronize the design handoff using the settled choice or report the
specific unsynced inputs; do not silently plan the original preview direction.
Use stable screen IDs, component recipes, responsive frames, and interaction
flows as UI-task context. Read the current render's verification result and
unresolved feedback; carry relevant gaps into explicit task checks. Preserve
`finalized.json` compatibility inputs for older designs. Do not regenerate an
existing design or re-extract an authored specification from preview images.

When `review-handoff.json` is present beside `design-spec.md`, read its current
approval and freshness with the bundled
`node scripts/design.mjs handoff <design-document.json> --action inspect --json`. Use approved, current
handoff items as additional planning context, retaining revision/comment links and
unresolved questions. An outdated or unapproved draft is evidence, not agreed scope;
report the changed inputs and obtain the missing decision only when it affects the
requested plan. Never silently substitute a newer draft for an approved snapshot.
A missing review handoff does not block ordinary planning from a clear specification.

When the request carries an approved implementation package, read
[the design handoff contract](references/design-handoff.md). Validate that the
package is still the current approved version before treating its numbered
requirements as scope. A missing package leaves ordinary Plan unchanged.

For a consequential unresolved choice, use the host's structured question
interface. Ask at most three short, mutually exclusive questions at once. If the
host has no structured question interface, ask one concise chat question.

## Apply PO lenses in-session

When the host supports native agents, dispatch the applicable database,
designer, and specification roles inside this session. Give each role the
request, repository root, relevant paths, and the precise decision or artifact
it owns. Parallelize independent lenses. When native agents are unavailable,
perform the same lenses sequentially in the active agent.

The specification role integrates the results. Database and design roles
provide grounded inputs; they do not create a second independent plan.

## Author the decomposition

Read [the artifact contract](references/artifact-contract.md) before writing.
Write stories and tasks directly in the repository's active planning mode.

- Allocate project-global monotonic `US-NNN` and `T-NNN` IDs. Never reuse a
  deleted ID. The packaged [planning ID helper](scripts/planning-ids.mjs) may
  inspect or reserve IDs; it never generates content.
- Give each story stable acceptance IDs starting at `AC-001`.
- Split each story into tasks that are coherent and independently verifiable.
  Separate by ownership first: UI work is a `UI` task for the frontend role and
  server, data, or integration work is a `Tech` task for the backend role.
  Within one owner, split further only for a real output dependency, a distinct
  verification surface, or reviewable size. Most stories need one Tech task,
  plus one UI task when a design surface applies; never fragment one coherent
  change into tasks that cannot be verified alone, and never fold unrelated work
  into one task.
- Map every acceptance ID through `acceptanceRefs` and name it with a concrete
  verification statement under `## Test Requirements`.
- Set `reviewRisks` and `browserSurfaces` from repository evidence; use empty
  arrays when no signal applies.
- Set `dependsOn` only when a task consumes another task's output. File overlap,
  numbering, and prose never create a semantic dependency.
- Name concrete files and repository-grounded checks. Preserve established
  repository headings when they carry additional information.

Validate all frontmatter and acceptance coverage before finishing. If a helper
is unavailable, inspect existing IDs and validate the same invariants directly;
do not route semantic work to a CLI fallback.

For approved design input, author the complete story and task bytes before
touching target paths, then commit those bytes and the sibling
`design-lineage.json` through the public atomic planning-lineage helper described
in the reference. A failed requirement-to-acceptance-to-task mapping writes
nothing. This deterministic commit validates content; it does not generate the
plan or invoke another phase.

## Return

Lead with what is implementation-ready. Keep full story/task inventories and
acceptance mappings in the planning artifacts; link their index or parent story
instead of repeating every path in chat.

- **Outcome:** the ready scope and story/task counts, or what remains partial or blocked.
- **Artifacts:** clickable specification, story and task links grouped by purpose.
- **Checks:** frontmatter, ID and acceptance coverage checks actually performed.
- **Issues:** unresolved inputs or material assumptions, with their impact and recovery step; omit when empty.
- **Next:** the exact ready task selector and a copy-ready host-native
  invocation such as `$planr-ship T-NNN` (Codex/ChatGPT) or
  `/planr-ship T-NNN` (Claude Code).

Mention the planning layout or consulted lenses only when they explain a material
choice. Different summary wording never requires another planning run.

When the OpenPlanr dashboard is running, the planned graph is browsable at
`#/board`; open one story at `#/detail/<US-###>`.

Stop after the handoff.