openplanr 1.4.3 → 1.5.0

package/dist/templates/rules/cursor/openplanr-pipeline-plan.mdc.hbs

@@ -0,0 +1,194 @@
+---
+description: "OpenPlanr Pipeline — PO Phase orchestration (plan {feature}). Decomposes a spec into User Stories + Tasks. STOPS at the human-review gate."
+globs: []
+alwaysApply: false
+---
+
+# /plan {feature} — PO Phase orchestration (Cursor)
+
+When the user says **"plan {feature}"** (or "decompose {feature}", or
+similar), follow this rule end-to-end. The argument `{feature}` is the
+feature slug (no `feat-` or `spec-` prefix).
+
+**Hard rule R1: this command STOPS after writing US/Task files.** The user
+must review and explicitly say "ship {feature}" before any DEV-Phase work.
+
+---
+
+## Step 1 — Mode detection + input validation
+
+### 1a — Detect planr spec mode
+
+Before any other checks, look for `.planr/config.json` at the project root:
+
+1. If `.planr/config.json` exists AND its `idPrefix.spec` field is set,
+   assume **spec-driven mode**.
+2. In spec-driven mode, scan `.planr/specs/` for a directory matching
+   `^[A-Z]+-\d{3}-{feature}$`. The first match resolves to
+   `SPEC_DIR = .planr/specs/<that-dir>` (e.g.,
+   `.planr/specs/SPEC-001-auth-flow/` for `feature=auth-flow`).
+3. Otherwise, fall through to **default mode**
+   (`output/feats/feat-{feature}/`).
+
+For the rest of this rule, internally maintain `MODE = "spec-driven"` or
+`"default"`.
+
+### 1b — Validate required inputs
+
+Required (default mode):
+- `input/specs/spec-{feature}.md` — fail with: "spec-{feature}.md not found.
+  Create it (or use spec-driven mode by adding `idPrefix.spec` to
+  `.planr/config.json` and re-running)."
+- `input/tech/stack.md` — fail with: "input/tech/stack.md not found. Create
+  it from `{{cursorRulesRoot}}/templates/stack.md.tpl`."
+
+Required (spec-driven mode):
+- `<SPEC_DIR>/SPEC-NNN-{feature}.md` — if missing, **auto-scaffold** (see below).
+- `input/tech/stack.md` — see **Self-healing** below.
+
+### Auto-scaffolding the spec shell
+
+When `<SPEC_DIR>/SPEC-NNN-{feature}.md` is missing, scaffold instead of aborting:
+
+1. Ensure `.planr/config.json` exists. If absent, write:
+   ```json
+   {
+     "projectName": "<derive from package.json name or repo dir>",
+     "outputPaths": { "agile": ".planr" },
+     "idPrefix": { "spec": "SPEC" }
+   }
+   ```
+2. Ensure `.planr/specs/` exists.
+3. Determine the next SPEC ID. Scan `.planr/specs/` for `SPEC-NNN-*/` dirs,
+   take the highest NNN, increment. Three-digit format (`SPEC-001`).
+4. Create `.planr/specs/SPEC-NNN-{feature}/{stories,tasks,design}/`.
+5. Read `{{cursorRulesRoot}}/templates/spec-driven.md.tpl` (if present;
+   otherwise inline a minimal v1.0.0 spec template). Substitute `{{SPEC_ID}}`,
+   `{{TITLE}}`, `{{SLUG}}`, `{{DATE}}`. Write to
+   `<SPEC_DIR>/SPEC-NNN-{feature}.md`.
+6. Print and abort:
+   ```
+   ✓ Scaffolded SPEC-NNN-{feature} at .planr/specs/SPEC-NNN-{feature}/
+     Edit the spec body, then re-run: plan {feature}
+   ```
+7. **Do not invoke any role.** Decomposition runs only on the second
+   invocation, after the user has filled in the body.
+
+If the spec body exists but contains only placeholder text (detect via
+`_Describe the problem this feature solves` or any `_…_` template hint),
+apply the same abort.
+
+### Self-healing in spec mode
+
+In spec-driven mode, when `input/tech/stack.md` is missing:
+
+1. Read `{{cursorRulesRoot}}/templates/stack.md.tpl` (or inline the template
+   if absent) and write it verbatim to `input/tech/stack.md`. Create
+   `input/tech/` if absent.
+2. Print:
+   ```
+   ✓ Created input/tech/stack.md from template (Cursor pipeline self-heal)
+     Next: edit input/tech/stack.md to declare your real stack:
+           - AppName, Language, Framework, ORM (or DatabaseType if no ORM)
+           - BuildCommand, TestCommand (used by the 3-iteration correction loop)
+     Then re-run: plan {feature}
+   ```
+3. Abort gracefully — exit Step 1 here.
+
+In default mode, missing `stack.md` aborts with the same template guidance
+(no auto-create — default mode missing stack typically means missing the
+entire scaffolding).
+
+### Conditional inputs
+
+- **Default mode:** `input/ui/feat-{feature}/*.png` OR PNGs listed in spec's
+  `UIFiles:` block → triggers designer role.
+- **Spec mode:** PNGs in `<SPEC_DIR>/design/*.png` → triggers designer role.
+- `input/tech/stack.md` has non-empty `DatabaseType` AND DB env vars present →
+  triggers db role.
+- `output/db/schema.json` already up to date → skip db role.
+
+---
+
+## Step 2 — Dispatch roles in dependency order
+
+Run roles **sequentially as Composer subagents**. Each role's output feeds
+the next.
+
+### 2.1 — db role (conditional)
+
+- **Skip** if `output/db/schema.json` exists AND was generated within the
+  last 24h.
+- **Skip** if no `DatabaseType` in `stack.md`.
+- Otherwise: dispatch the **db** subagent with system prompt
+  `{{cursorRulesRoot}}/agents/db-agent.md`. Pass MODE, feature, stack.md.
+- Output: `output/db/schema.json`.
+
+### 2.2 — designer role (conditional)
+
+- PNG resolution depends on MODE:
+  - **Default mode:** PNGs from `UIFiles:` in spec → `input/ui/feat-{feature}/*.png` → `input/ui/*.png`.
+  - **Spec-driven mode:** PNGs from `<SPEC_DIR>/design/*.png`.
+- **Skip silently** if zero PNGs resolve.
+- Otherwise: dispatch the **designer** subagent with system prompt
+  `{{cursorRulesRoot}}/agents/designer-agent.md`. Pass MODE, feature, SPEC_DIR.
+- Output:
+  - **Default:** `output/feats/feat-{feature}/design-spec.md`
+  - **Spec-driven:** `<SPEC_DIR>/design/design-spec.md`
+
+### 2.3 — specification role (always, with skip optimization)
+
+- **Spec-driven mode optimization:** if `<SPEC_DIR>/stories/` is non-empty
+  (the user already ran `planr spec decompose`), skip role invocation. Print:
+  "Decomposition already exists; skipping specification-agent."
+- Otherwise: dispatch the **specification** subagent with system prompt
+  `{{cursorRulesRoot}}/agents/specification-agent.md`. Pass MODE, feature,
+  SPEC_DIR, plus reads of:
+  - **Default:** `input/specs/spec-{feature}.md`, `input/tech/stack.md`,
+    optional `output/feats/feat-{feature}/design-spec.md`, optional
+    `output/db/schema.json`
+  - **Spec-driven:** `<SPEC_DIR>/SPEC-NNN-{feature}.md`,
+    `input/tech/stack.md`, optional `<SPEC_DIR>/design/design-spec.md`,
+    optional `output/db/schema.json`
+- Output:
+  - **Default:** `output/feats/feat-{feature}/us-{N}/us-{N}.md` and
+    `tasks/task-{M}.md`
+  - **Spec-driven:** `<SPEC_DIR>/stories/US-NNN-{slug}.md` and
+    `<SPEC_DIR>/tasks/T-NNN-{slug}.md`
+
+---
+
+## Step 3 — STOP
+
+After the specification role completes, **STOP**. Do NOT invoke any DEV role.
+
+Print a summary:
+
+```
+✓ PO Phase complete for {feature}
+  Mode:        <default | spec-driven>
+  Output dir:  <output/feats/feat-{feature}/ | .planr/specs/SPEC-NNN-{feature}/>
+  Design spec: <created | skipped (no PNGs) | reused>
+  DB schema:   <created | reused | skipped>
+  US created:  N
+  Tasks:       M
+  Next step:   review the generated US/task files, then say "ship {feature}".
+```
+
+The user must explicitly say "ship {feature}" to proceed. Do not auto-chain.
+
+---
+
+## Failure modes
+
+| Condition | Action |
+|---|---|
+| Spec missing (default) | Abort, suggest creating `input/specs/spec-{feature}.md` or switching to spec-driven mode |
+| stack.md missing (default) | Abort, suggest copying from `{{cursorRulesRoot}}/templates/stack.md.tpl` |
+| db role fails (connection) | Continue without schema, flag in summary |
+| designer role fails (corrupt PNG) | Continue without design-spec, flag in summary |
+| specification role fails | Abort, surface the role's error verbatim |
+
+---
+
+*Generated by `planr rules generate --target cursor --scope pipeline`. Pairs with `openplanr-pipeline-ship.mdc` for the DEV phase.*

package/dist/templates/rules/cursor/openplanr-pipeline-ship.mdc.hbs

@@ -0,0 +1,242 @@
+---
+description: "OpenPlanr Pipeline — DEV Phase orchestration (ship {feature}). Frontend ‖ backend → qa → devops ‖ doc-gen → snapshot → marker."
+globs: []
+alwaysApply: false
+---
+
+# /ship {feature} — DEV Phase orchestration (Cursor)
+
+When the user says **"ship {feature}"** (or "implement {feature}", "build
+{feature}"), follow this rule end-to-end. The argument `{feature}` is the
+feature slug.
+
+**Per R1, this command MUST NOT be auto-chained from "plan {feature}".**
+The user must explicitly invoke it after reviewing the PO-phase output.
+
+---
+
+## Step 0 — Snapshot sentinel
+
+Cursor has no Stop hook (unlike Claude Code). To approximate the same
+"reminder if /ship aborts before snapshot" guarantee, write
+`.cursor/.snapshot-pending` (empty file) at the start of this rule. If a
+later run encounters this sentinel, surface a one-line reminder to refresh
+`CLAUDE.md` (Step 5) before proceeding.
+
+---
+
+## Step 1 — Mode detection + input validation
+
+### 1a — Detect planr spec mode
+
+Same as `openplanr-pipeline-plan.mdc` Step 1a:
+
+1. If `.planr/config.json` has `idPrefix.spec` set, **spec-driven mode**.
+2. `SPEC_DIR = .planr/specs/<SPEC-NNN-{feature}>/`.
+3. Otherwise, **default mode** (`output/feats/feat-{feature}/`).
+
+| Concept | Default | Spec-driven |
+|---|---|---|
+| Feature root | `output/feats/feat-{feature}/` | `<SPEC_DIR>/` |
+| US files | `output/feats/feat-{feature}/us-*/us-*.md` | `<SPEC_DIR>/stories/US-*.md` |
+| Task files | `output/feats/feat-{feature}/us-*/tasks/task-*.md` | `<SPEC_DIR>/tasks/T-*.md` |
+| Error report | `output/feats/feat-{feature}/us-{N}/tasks/error-report.md` | `<SPEC_DIR>/tasks/error-report.md` |
+| QA report | `output/feats/feat-{feature}/qa-report.md` | `<SPEC_DIR>/qa-report.md` |
+
+### 1b — Validate required inputs
+
+Verify these exist (mode-appropriate). Abort with clear errors if missing.
+
+Required (default mode):
+- `output/feats/feat-{feature}/` — fail: "feat-{feature}/ not found. Run plan {feature} first."
+- ≥1 `output/feats/feat-{feature}/us-*/us-*.md`
+- ≥1 `output/feats/feat-{feature}/us-*/tasks/task-*.md`
+- `input/tech/stack.md`
+
+Required (spec-driven mode):
+- `<SPEC_DIR>/` — fail: "Spec for slug '{feature}' not found under .planr/specs/. Run plan {feature} first."
+- ≥1 `<SPEC_DIR>/stories/US-*.md`
+- ≥1 `<SPEC_DIR>/tasks/T-*.md`
+- `input/tech/stack.md` — see self-heal below.
+
+### Self-healing in spec mode
+
+When MODE=spec-driven AND `input/tech/stack.md` is missing:
+
+1. Read `{{cursorRulesRoot}}/templates/stack.md.tpl` and write to `input/tech/stack.md`.
+2. Print "edit and re-run" message.
+3. Abort gracefully. Do NOT invoke any role.
+
+In default mode, missing `stack.md` aborts with the same template guidance.
+
+---
+
+## Step 2 — Iterate User Stories in topological order
+
+In default mode, iterate each `us-{N}` directory under
+`output/feats/feat-{feature}/` (sorted by US number). In spec-driven mode,
+iterate each `<SPEC_DIR>/stories/US-*.md` (sorted by ID); tasks live in the
+**flat** `<SPEC_DIR>/tasks/` directory and link to their parent story via
+the `storyId` frontmatter field.
+
+For each story, run its tasks:
+
+1. Read the US file to identify which tasks belong to it.
+2. For each task:
+   - Read frontmatter `Type` field.
+   - If `Type: UI` → dispatch the **frontend** subagent
+     (`{{cursorRulesRoot}}/agents/frontend-agent.md`).
+   - If `Type: Tech` → dispatch the **backend** subagent
+     (`{{cursorRulesRoot}}/agents/backend-agent.md`).
+   - frontend and backend tasks within the SAME US may run in parallel
+     (Cursor's Composer supports parallel subagent dispatch — use it).
+3. Each subagent applies the **3-iteration correction loop** (R6):
+   - Iteration 1: direct fix on build/test failure.
+   - Iteration 2: re-read task spec + design-spec/schema, fix holistically.
+   - Iteration 3: minimal safe fix, flag remaining issues.
+   - On 3rd failure: write `error-report.md` (default mode:
+     `output/feats/feat-{feature}/us-{N}/tasks/error-report.md`; spec mode:
+     `<SPEC_DIR>/tasks/error-report.md`). Then STOP that task.
+4. If a task fails after 3 iterations, ship continues with other independent
+   tasks but flags the failed task in the final summary.
+
+---
+
+## Step 3 — QA Gate
+
+After all US tasks complete (or fail with error-reports), dispatch the
+**qa** subagent (`{{cursorRulesRoot}}/agents/qa-agent.md`).
+
+The qa subagent verifies, for each task:
+- All "Create" files exist
+- All "Modify" files were updated (and only as described)
+- All "Preserve" files are unchanged (`git diff` vs base)
+- Tests pass (`BuildCommand` + `TestCommand` from `stack.md`)
+- DoD checklist items satisfied
+
+If QA fails: flag in summary; **still proceed to Step 5 snapshot** so state
+is recorded; skip Step 4 (devops + doc-gen) until the underlying task is fixed.
+
+---
+
+## Step 4 — devops + doc-gen subagents (parallel, optional)
+
+Run only if QA passes.
+
+- Dispatch **devops** subagent
+  (`{{cursorRulesRoot}}/agents/devops-agent.md`) — generates
+  `docker-compose.yml`, `.env.example`, Dockerfiles, CI workflow stubs.
+  **No `Bash` whatsoever** (prompt-level enforcement on Cursor).
+- Dispatch **doc-gen** subagent
+  (`{{cursorRulesRoot}}/agents/doc-gen-agent.md`) — writes
+  `Docs/feat-{feature}/` from US, tasks, generated source code.
+
+---
+
+## Step 5 — Snapshot
+
+Refresh `CLAUDE.md` at the project root. Read
+`{{cursorRulesRoot}}/templates/CLAUDE.md.tpl` and write a populated copy.
+
+Capture in this order:
+
+1. **Project Identity** — `AppName`, `Version`, `DatabaseType`, `Framework`,
+   `Language` from `input/tech/stack.md`. Include ISO 8601 UTC timestamp.
+2. **Phase Status** — scan filesystem to determine actual state.
+3. **Feature Registry** — for each feature folder.
+4. **Active Roles** — list the 8 roles with their model tier.
+5. **Build Log** — append latest build/test outcomes (append-only — never truncate).
+6. **Known Issues** — scan all `error-report.md` files.
+7. **Stack Summary** — embed `input/tech/stack.md` content.
+
+### Snapshot integrity rules
+
+- ✅ Always write a complete, valid `CLAUDE.md` — never partial.
+- ✅ Always include the generation timestamp.
+- ✅ Preserve existing build log entries (append only).
+- ✅ If a scan section fails, write `[scan error]` rather than empty.
+- ❌ Never delete `CLAUDE.md`.
+- ❌ Never leave `CLAUDE.md` partially written.
+
+### Coexistence with planr-managed CLAUDE.md
+
+If the existing `CLAUDE.md` opens with `> Generated by OpenPlanr` or contains
+`## Context-Gathering Protocol`, do **not** overwrite. Print:
+*"CLAUDE.md is planr-managed; pipeline state recorded via .pipeline-shipped
+marker (Step 5.5) and qa-report.md."* Continue to Step 5.5.
+
+After writing (or skipping), remove `.cursor/.snapshot-pending`.
+
+---
+
+## Step 5.5 — Write the `.pipeline-shipped` marker
+
+After Step 5 succeeds, write a marker file recording the pipeline run.
+
+**Default mode:** `output/feats/feat-{feature}/.pipeline-shipped`
+**Spec-driven mode:** `<SPEC_DIR>/.pipeline-shipped`
+
+YAML contents:
+
+```yaml
+shipped_at: "<ISO 8601 UTC timestamp>"
+pipeline_version: "<runtime adapter writes its own version, e.g. 0.6.0>"
+protocol_version: "{{protocolVersion}}"
+runtime: "cursor"
+mode: "<default | spec-driven>"
+feature: "{feature}"
+tasks_executed: <integer>
+tasks_failed: <integer>
+qa_gate_status: "<passed | failed | skipped>"
+duration_seconds: <integer>
+agents_invoked:
+  - frontend-agent          # only list roles that actually ran
+  - backend-agent
+  - qa-agent
+  - devops-agent
+  - doc-gen-agent
+devops_status: "<generated | skipped>"
+docs_status: "<generated | skipped>"
+snapshot_status: "<refreshed | skipped>"
+error_reports:               # paths to any error-report.md files; [] if none
+  - <path>
+```
+
+If Step 5 (snapshot) was skipped due to planr-managed CLAUDE.md, set
+`snapshot_status: skipped` so the partial-success state is recorded.
+
+---
+
+## Step 6 — Print summary
+
+```
+✓ DEV Phase complete for {feature}
+  Runtime:         cursor
+  Mode:            <default | spec-driven>
+  Output dir:      <output/feats/feat-{feature}/ | .planr/specs/SPEC-NNN-{feature}/>
+  Tasks succeeded: X / Y
+  Tasks failed:    Z (see error-report.md files)
+  QA gate:         <passed | failed>
+  DevOps config:   <generated | skipped>
+  Docs:            <generated | skipped>
+  CLAUDE.md:       <refreshed | skipped (planr-managed)>
+  Marker:          <SPEC_DIR>/.pipeline-shipped
+```
+
+If any task failed, list paths to error-report.md files.
+
+---
+
+## Failure modes
+
+| Condition | Action |
+|---|---|
+| feat folder / spec dir missing | Abort, suggest plan {feature} first |
+| No tasks | Abort, suggest re-running plan |
+| Single task fails 3x | Continue with other tasks, surface in summary |
+| All tasks fail | Skip QA + DevOps + Doc-Gen; still run snapshot |
+| QA gate fails | Skip DevOps + Doc-Gen; still run snapshot |
+
+---
+
+*Generated by `planr rules generate --target cursor --scope pipeline`. Pairs with `openplanr-pipeline-plan.mdc` for the PO phase.*

package/dist/templates/rules/cursor/openplanr-pipeline.mdc.hbs

@@ -0,0 +1,134 @@
+---
+description: "OpenPlanr Pipeline orchestration — PO/DEV phase rules, R1 human gate, mode detection, runtime parity for {{projectName}}"
+globs: [".planr/specs/**", "input/specs/**", "output/feats/**"]
+alwaysApply: false
+---
+
+# OpenPlanr Pipeline (Cursor edition — Protocol v{{protocolVersion}})
+
+You are operating inside an OpenPlanr-pipeline-aware project on **Cursor**.
+The pipeline is a two-phase factory:
+
+```
+PO Phase (planning)  →  HUMAN REVIEW  →  DEV Phase (implementation)
+```
+
+**Hard rule R1: NEVER auto-chain PO Phase to DEV Phase.** A human review step
+gates them. Two distinct user invocations are required: "plan {feature}" and
+"ship {feature}".
+
+---
+
+## Mode detection
+
+Before doing anything, decide the project mode:
+
+1. If `.planr/config.json` exists AND its `idPrefix.spec` field is set,
+   the project is in **spec-driven mode**. Spec dir lives at
+   `.planr/specs/SPEC-NNN-{slug}/`.
+2. Otherwise, **default mode**: `output/feats/feat-{name}/`.
+
+| Concept | Default mode | Spec-driven mode |
+|---|---|---|
+| Spec source | `input/specs/spec-{name}.md` | `.planr/specs/SPEC-NNN-{slug}/SPEC-NNN-{slug}.md` |
+| Design spec | `output/feats/feat-{name}/design-spec.md` | `<SPEC_DIR>/design/design-spec.md` |
+| US output | `output/feats/feat-{name}/us-{N}/us-{N}.md` | `<SPEC_DIR>/stories/US-NNN-{slug}.md` |
+| Task output | `output/feats/feat-{name}/us-{N}/tasks/task-{M}.md` | `<SPEC_DIR>/tasks/T-NNN-{slug}.md` |
+
+---
+
+## Routing
+
+When the user says **"plan {feature}"** (or "decompose {feature}", "spec {feature}"):
+follow `.cursor/rules/openplanr-pipeline-plan.mdc`.
+
+When the user says **"ship {feature}"** (or "implement {feature}", "build {feature}"):
+follow `.cursor/rules/openplanr-pipeline-ship.mdc`.
+
+---
+
+## Subagents (8 named roles)
+
+The pipeline ships 8 specialised role prompts. On Cursor, dispatch each as a
+**Composer subagent** with the role's body as the system prompt. The bodies
+live in `{{cursorRulesRoot}}/agents/{role}.md`:
+
+{{#each agentNames}}
+- `{{this}}` — see `{{../cursorRulesRoot}}/agents/{{this}}.md`
+{{/each}}
+
+When invoking a role, prefix the dispatch with the project context:
+`MODE: {default|spec-driven}`, `SPEC_DIR` (if spec mode), `feature/slug`.
+
+---
+
+## Tool restrictions (Cursor parity)
+
+The Claude Code plugin enforces tool restrictions at the manifest layer
+(`tools: Read, Glob, Grep, Edit, Write, Bash(npm:*)` etc.). Cursor uses a
+different permission model — these restrictions are **prompt-level only**
+on Cursor and must be respected by you, the model, voluntarily:
+
+- **db-agent** — read-only DB introspection. Never write SQL DDL/DML. Output
+  goes to `output/db/schema.json` only.
+- **designer-agent** — `Read`, `Glob`, `Write` only. No shell access.
+  Output: `<SPEC_DIR>/design/design-spec.md` (spec mode) or
+  `output/feats/feat-{name}/design-spec.md` (default).
+- **specification-agent** — `Read`, `Glob`, `Grep`, `Write`. Decomposes the
+  spec into US + Task files. No shell.
+- **frontend-agent** — `Read`, `Edit`, `Write`, `Bash(npm:*)` family. Writes
+  UI files only (`src/features/{name}/` UI layer, components, pages, styles).
+  Never touches services, controllers, DTOs, entities.
+- **backend-agent** — same shell tools as frontend, but writes services,
+  DTOs, entities, controllers, DB queries. Never touches UI files.
+- **qa-agent** — read-only on `src/`. Runs build + test commands. Writes only
+  `qa-report.md`.
+- **devops-agent** — `Read`, `Glob`, `Write`, `Edit`. **No `Bash` whatsoever.**
+  Generates `docker-compose.yml`, Dockerfiles, CI workflow stubs. Never deploys.
+- **doc-gen-agent** — `Read`, `Glob`, `Grep`, `Write`. Writes `Docs/feat-{name}/`.
+
+If you, as the model, violate these restrictions on Cursor, the conformance
+test will catch it via the post-ship `git diff` check on each task's "Preserve"
+list. **Treat the restrictions as binding.**
+
+---
+
+## Hard rules (cross-runtime)
+
+- **R1** — Never auto-chain PO → DEV. Two user invocations required.
+- **R2** — Max 2 tasks per US (1 if no PNG, 2 if PNG present).
+- **R3** — Model assignments: roles using `Sonnet 4.6` are analysis/decomposition;
+  roles using `Opus 4.7` are codegen. On Cursor, use the runtime's tier
+  selector (Cursor's "Composer model" setting) and pick the equivalent.
+- **R5** — Files in any task's `Preserve:` list MUST NOT be touched.
+- **R6** — Max 3 correction iterations per task. After 3, write
+  `error-report.md` and stop that task.
+- **R7** — Refresh CLAUDE.md (or coexist with planr-managed CLAUDE.md) at end
+  of `/ship`. Cursor has no Stop hook — see `openplanr-pipeline-ship.mdc`
+  Step 5 for the alternative.
+- **R8** — db-agent role is read-only. Never DDL/DML.
+- **R9** — frontend role only writes UI files; backend role only writes
+  services/DTOs/entities. No crossover.
+
+---
+
+## Conformance proof
+
+On a successful `/ship` run, write the `.pipeline-shipped` YAML marker file
+(see `openplanr-pipeline-ship.mdc` Step 5.5). The marker is the audit-grade
+proof that the pipeline executed; the conformance test harness (in the
+`openplanr-pipeline` repo at `conformance/runner.mjs`) verifies it.
+
+---
+
+## Compatibility matrix
+
+This rule represents the **Cursor adapter** to the OpenPlanr Protocol v1.0.0.
+Other supported runtimes:
+
+- **Claude Code** — install the `openplanr-pipeline` plugin (canonical surface)
+- **Codex** — see the AGENTS.md generated by `planr rules generate --target codex --scope pipeline`
+
+Full parity table: `openplanr-pipeline/docs/compatibility-matrix.md`.
+
+*Generated by `planr rules generate --target cursor --scope pipeline`.*

package/dist/utils/constants.d.ts

@@ -2,6 +2,27 @@ import type { ArtifactType } from '../models/types.js';
 export declare const CONFIG_FILENAME = ".planr/config.json";
 export declare const DEFAULT_AGILE_DIR = ".planr";
 export declare const DEFAULT_CURSOR_RULES_DIR = ".cursor/rules";
+/**
+ * OpenPlanr Protocol version that the `--scope pipeline` rule generators
+ * conform to. The protocol is the runtime-agnostic contract for spec-driven
+ * mode artifacts (SPEC, US, Task schemas; PLAN/SHIP command contracts; agent
+ * roles). Bumps RARELY — only on artifact-schema breaks or workflow
+ * contract changes, NOT on pipeline plugin patches.
+ *
+ * NOT to be confused with the openplanr-pipeline plugin version (which moves
+ * fast and is tracked in the marketplace pin file, not here). Generated rule
+ * files reference the protocol contract; the runtime adapter (Claude Code
+ * plugin / Cursor MDC / Codex AGENTS.md) writes its own actual version into
+ * the `.pipeline-shipped` marker at execution time.
+ *
+ * Read by:
+ *   - CursorGenerator (renders into Cursor MDC headers)
+ *   - ClaudeGenerator (renders into the sibling `openplanr-pipeline.md` reference card)
+ *   - CodexGenerator  (renders into the AGENTS.md pipeline section)
+ *
+ * See `openplanr-pipeline/docs/protocol/` for the full protocol spec.
+ */
+export declare const OPENPLANR_PROTOCOL_VERSION = "1.0.0";
 export declare const ARTIFACT_DIRS: {
     readonly epics: "epics";
     readonly features: "features";

package/dist/utils/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/utils/constants.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAKvD,eAAO,MAAM,eAAe,uBAAuB,CAAC;AAEpD,eAAO,MAAM,iBAAiB,WAAW,CAAC;AAC1C,eAAO,MAAM,wBAAwB,kBAAkB,CAAC;AAExD,eAAO,MAAM,aAAa;;;;;;;;;;CAUhB,CAAC;AAEX,eAAO,MAAM,WAAW;;;;;;;;;CASd,CAAC;AAEX,eAAO,MAAM,cAAc,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC,CAQ3E,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,2GAQtB,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,wEAAwE;AACxE,eAAO,MAAM,yBAAyB,yDAA0D,CAAC;AACjG,eAAO,MAAM,wBAAwB,wDAAyD,CAAC;AAE/F,wBAAgB,eAAe,IAAI,MAAM,CAExC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/utils/constants.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAKvD,eAAO,MAAM,eAAe,uBAAuB,CAAC;AAEpD,eAAO,MAAM,iBAAiB,WAAW,CAAC;AAC1C,eAAO,MAAM,wBAAwB,kBAAkB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,0BAA0B,UAAU,CAAC;AAElD,eAAO,MAAM,aAAa;;;;;;;;;;CAUhB,CAAC;AAEX,eAAO,MAAM,WAAW;;;;;;;;;CASd,CAAC;AAEX,eAAO,MAAM,cAAc,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC,CAQ3E,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,2GAQtB,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,wEAAwE;AACxE,eAAO,MAAM,yBAAyB,yDAA0D,CAAC;AACjG,eAAO,MAAM,wBAAwB,wDAAyD,CAAC;AAE/F,wBAAgB,eAAe,IAAI,MAAM,CAExC"}

package/dist/utils/constants.js

@@ -5,6 +5,27 @@ const __dirname = path.dirname(__filename);
 export const CONFIG_FILENAME = '.planr/config.json';
 export const DEFAULT_AGILE_DIR = '.planr';
 export const DEFAULT_CURSOR_RULES_DIR = '.cursor/rules';
+/**
+ * OpenPlanr Protocol version that the `--scope pipeline` rule generators
+ * conform to. The protocol is the runtime-agnostic contract for spec-driven
+ * mode artifacts (SPEC, US, Task schemas; PLAN/SHIP command contracts; agent
+ * roles). Bumps RARELY — only on artifact-schema breaks or workflow
+ * contract changes, NOT on pipeline plugin patches.
+ *
+ * NOT to be confused with the openplanr-pipeline plugin version (which moves
+ * fast and is tracked in the marketplace pin file, not here). Generated rule
+ * files reference the protocol contract; the runtime adapter (Claude Code
+ * plugin / Cursor MDC / Codex AGENTS.md) writes its own actual version into
+ * the `.pipeline-shipped` marker at execution time.
+ *
+ * Read by:
+ *   - CursorGenerator (renders into Cursor MDC headers)
+ *   - ClaudeGenerator (renders into the sibling `openplanr-pipeline.md` reference card)
+ *   - CodexGenerator  (renders into the AGENTS.md pipeline section)
+ *
+ * See `openplanr-pipeline/docs/protocol/` for the full protocol spec.
+ */
+export const OPENPLANR_PROTOCOL_VERSION = '1.0.0';
 export const ARTIFACT_DIRS = {
     epics: 'epics',
     features: 'features',

package/dist/utils/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/utils/constants.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAE3C,MAAM,CAAC,MAAM,eAAe,GAAG,oBAAoB,CAAC;AAEpD,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAC;AAC1C,MAAM,CAAC,MAAM,wBAAwB,GAAG,eAAe,CAAC;AAExD,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,KAAK,EAAE,OAAO;IACd,QAAQ,EAAE,UAAU;IACpB,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,MAAM;IACZ,UAAU,EAAE,YAAY;CAChB,CAAC;AAEX,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,MAAM;IACf,KAAK,EAAE,IAAI;IACX,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,IAAI;IACX,OAAO,EAAE,IAAI;IACb,MAAM,EAAE,QAAQ;IAChB,GAAG,EAAE,KAAK;CACF,CAAC;AAEX,MAAM,CAAC,MAAM,cAAc,GAAqD;IAC9E,IAAI,EAAE,CAAC,UAAU,EAAE,aAAa,EAAE,MAAM,CAAC;IACzC,OAAO,EAAE,CAAC,UAAU,EAAE,aAAa,EAAE,MAAM,CAAC;IAC5C,KAAK,EAAE,CAAC,UAAU,EAAE,aAAa,EAAE,MAAM,CAAC;IAC1C,IAAI,EAAE,CAAC,SAAS,EAAE,aAAa,EAAE,MAAM,CAAC;IACxC,KAAK,EAAE,CAAC,SAAS,EAAE,aAAa,EAAE,MAAM,CAAC;IACzC,OAAO,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC;IACvC,MAAM,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,CAAC;CAC5C,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,SAAS;IACT,SAAS;IACT,aAAa;IACb,YAAY;IACZ,oBAAoB;IACpB,aAAa;IACb,MAAM;CACE,CAAC;AAIX,wEAAwE;AACxE,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,SAAS,EAAE,cAAc,EAAE,MAAM,EAAE,SAAS,CAAU,CAAC;AACjG,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,SAAS,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,CAAU,CAAC;AAE/F,MAAM,UAAU,eAAe;IAC7B,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;AACpD,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/utils/constants.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAE3C,MAAM,CAAC,MAAM,eAAe,GAAG,oBAAoB,CAAC;AAEpD,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAC;AAC1C,MAAM,CAAC,MAAM,wBAAwB,GAAG,eAAe,CAAC;AAExD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,OAAO,CAAC;AAElD,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,KAAK,EAAE,OAAO;IACd,QAAQ,EAAE,UAAU;IACpB,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,MAAM;IACZ,UAAU,EAAE,YAAY;CAChB,CAAC;AAEX,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,MAAM;IACf,KAAK,EAAE,IAAI;IACX,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,IAAI;IACX,OAAO,EAAE,IAAI;IACb,MAAM,EAAE,QAAQ;IAChB,GAAG,EAAE,KAAK;CACF,CAAC;AAEX,MAAM,CAAC,MAAM,cAAc,GAAqD;IAC9E,IAAI,EAAE,CAAC,UAAU,EAAE,aAAa,EAAE,MAAM,CAAC;IACzC,OAAO,EAAE,CAAC,UAAU,EAAE,aAAa,EAAE,MAAM,CAAC;IAC5C,KAAK,EAAE,CAAC,UAAU,EAAE,aAAa,EAAE,MAAM,CAAC;IAC1C,IAAI,EAAE,CAAC,SAAS,EAAE,aAAa,EAAE,MAAM,CAAC;IACxC,KAAK,EAAE,CAAC,SAAS,EAAE,aAAa,EAAE,MAAM,CAAC;IACzC,OAAO,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC;IACvC,MAAM,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,CAAC;CAC5C,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,SAAS;IACT,SAAS;IACT,aAAa;IACb,YAAY;IACZ,oBAAoB;IACpB,aAAa;IACb,MAAM;CACE,CAAC;AAIX,wEAAwE;AACxE,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,SAAS,EAAE,cAAc,EAAE,MAAM,EAAE,SAAS,CAAU,CAAC;AACjG,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,SAAS,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,CAAU,CAAC;AAE/F,MAAM,UAAU,eAAe;IAC7B,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;AACpD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openplanr",
-  "version": "1.4.3",
+  "version": "1.5.0",
   "description": "AI-powered planning CLI — backlog, sprints, task templates, estimation, GitHub and Linear sync, and AI agent rules for Cursor, Claude Code, and Codex",
   "type": "module",
   "main": "./dist/cli/index.js",