openplanr 3.1.1 → 3.3.0

package/lib/host-packages/cursor/openplanr/rules/planr-investigate/scripts/backlog-item.mjs

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+// @ts-check
+// The one backlog item writer: the CLI imports it, and skills run it when no CLI is installed.
+
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Holds one empty file per issued ID, so the ID of a removed artifact is never issued again. */
+const ISSUED_IDS_DIR = '.issued-ids';
+const CLOSED_STATUSES = new Set(['closed', 'done']);
+
+/** @type {typeof import('./backlog-item.d.mts').CLI_INSTALL_COMMAND} */
+export const CLI_INSTALL_COMMAND = 'npm install -g openplanr';
+/** @type {typeof import('./backlog-item.d.mts').CLI_HINT} */
+export const CLI_HINT = `Install the OpenPlanr CLI to manage these items: ${CLI_INSTALL_COMMAND}`;
+
+/** @type {typeof import('./backlog-item.d.mts').reserveNextId} */
+export async function reserveNextId(dir, prefix) {
+  const issuedDir = join(dir, ISSUED_IDS_DIR);
+  await mkdir(issuedDir, { recursive: true });
+  const pattern = new RegExp(`^${prefix.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&')}-(\\d{3,})`, 'u');
+  let next = 1;
+  for (const directory of [dir, issuedDir]) {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const match = entry.isDirectory() ? null : pattern.exec(entry.name);
+      if (match) next = Math.max(next, Number.parseInt(match[1], 10) + 1);
+    }
+  }
+  for (; ; next++) {
+    const id = `${prefix}-${String(next).padStart(3, '0')}`;
+    try {
+      await writeFile(join(issuedDir, id), '', { flag: 'wx' });
+      return id;
+    } catch (error) {
+      if (/** @type {NodeJS.ErrnoException} */ (error).code !== 'EEXIST') throw error;
+    }
+  }
+}
+
+/** @type {typeof import('./backlog-item.d.mts').slugify} */
+export function slugify(text, maxLength = 80) {
+  let slug = text
+    .toLowerCase()
+    .trim()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/[\s_]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  if (slug.length > maxLength) {
+    slug = slug.slice(0, maxLength);
+    // Trim at the last whole-word boundary to avoid cut-off words.
+    const lastDash = slug.lastIndexOf('-');
+    if (lastDash > 0) slug = slug.slice(0, lastDash);
+  }
+  return slug;
+}
+
+/** @param {unknown} value */
+function strings(value) {
+  if (Array.isArray(value)) return value.map(String).filter(Boolean);
+  if (typeof value === 'string')
+    return value
+      .split(',')
+      .map((item) => item.trim())
+      .filter(Boolean);
+  return [];
+}
+
+/** @param {unknown} value */
+function optionalText(value) {
+  return value === undefined || value === null || value === '' ? undefined : value;
+}
+
+const PRIORITIES = Object.freeze(['critical', 'high', 'medium', 'low']);
+
+/** Bad backlog input; the code lets the CLI report it as an input error, not a crash. */
+class BacklogInputError extends Error {
+  /** @param {string} message */
+  constructor(message) {
+    super(message);
+    this.name = 'BacklogInputError';
+    this.code = 'E_BACKLOG_INVALID';
+  }
+}
+
+/** @type {typeof import('./backlog-item.d.mts').backlogFields} */
+export function backlogFields(input) {
+  const title = String(input.title ?? input.name ?? '').trim();
+  if (!title) throw new BacklogInputError('A backlog item needs a non-empty title.');
+  const priority = String(input.priority ?? 'medium');
+  if (!PRIORITIES.includes(priority))
+    throw new BacklogInputError(
+      `Backlog priority ${JSON.stringify(priority)} is not valid; use one of ${PRIORITIES.join(', ')}.`,
+    );
+  const criteria = optionalText(input.acceptanceCriteria);
+  const notes = optionalText(input.notes);
+  const epicId = optionalText(input.epicId);
+  return {
+    title,
+    priority,
+    tags: strings(input.tags),
+    description: String(input.description ?? title),
+    ...(criteria === undefined
+      ? {}
+      : { acceptanceCriteria: Array.isArray(criteria) ? criteria.map(String) : String(criteria) }),
+    ...(notes === undefined ? {} : { notes: String(notes) }),
+    ...(epicId === undefined ? {} : { epicId: String(epicId) }),
+  };
+}
+
+/** @type {typeof import('./backlog-item.d.mts').renderBacklogItem} */
+export function renderBacklogItem(id, fields, date) {
+  const quote = JSON.stringify;
+  const lines = [
+    '---',
+    `id: ${quote(id)}`,
+    `title: ${quote(fields.title)}`,
+    `priority: ${quote(fields.priority)}`,
+    `tags: [${fields.tags.map((tag) => quote(tag)).join(', ')}]`,
+    'status: "open"',
+    `created: ${quote(date)}`,
+    `updated: ${quote(date)}`,
+    ...(fields.epicId ? [`epicId: ${quote(fields.epicId)}`] : []),
+    '---',
+    '',
+    `# ${id}: ${fields.title}`,
+    '',
+  ];
+  /** @param {string} heading @param {string} body @param {boolean} [spaced] */
+  const section = (heading, body, spaced = false) =>
+    lines.push(`## ${heading}`, ...(spaced ? [''] : []), body, '');
+  if (fields.tags.length > 0)
+    section('Tags', fields.tags.map((tag) => `- ${tag}`).join('\n'), true);
+  // A description with its own sections stands alone instead of nesting under another heading.
+  if (/^## /u.test(fields.description)) lines.push(fields.description, '');
+  else if (fields.description !== fields.title) section('Description', fields.description);
+  if (fields.acceptanceCriteria !== undefined && fields.acceptanceCriteria.length > 0)
+    section(
+      'Acceptance Criteria',
+      Array.isArray(fields.acceptanceCriteria)
+        ? fields.acceptanceCriteria.map((criterion) => `- ${criterion}`).join('\n')
+        : fields.acceptanceCriteria,
+    );
+  if (fields.notes) section('Notes', fields.notes);
+  lines.push('---', `_Close when done: \`openplanr backlog update ${id} --status closed\`_`, '');
+  return lines.join('\n');
+}
+
+/** @type {typeof import('./backlog-item.d.mts').writeBacklogItem} */
+export async function writeBacklogItem(backlogDir, prefix, fields, date) {
+  await mkdir(backlogDir, { recursive: true });
+  const id = await reserveNextId(backlogDir, prefix);
+  const filePath = join(backlogDir, `${id}-${slugify(fields.title)}.md`);
+  await writeFile(filePath, renderBacklogItem(id, fields, date));
+  return { id, filePath };
+}
+
+/** @param {string} projectDir */
+async function projectConfig(projectDir) {
+  const configPath = join(projectDir, '.planr', 'config.json');
+  let raw;
+  try {
+    raw = await readFile(configPath, 'utf8');
+  } catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code === 'ENOENT')
+      throw new Error(
+        `No OpenPlanr project at ${projectDir}: ${configPath} is missing. Run \`openplanr init\` or pass the project root.`,
+      );
+    throw error;
+  }
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`${configPath} is not valid JSON: ${/** @type {Error} */ (error).message}`);
+  }
+  return { configPath, raw, config };
+}
+
+/** @param {string} projectDir */
+async function projectBacklog(projectDir) {
+  const { config } = await projectConfig(projectDir);
+  const agile = String(config.outputPaths?.agile ?? '.planr').replaceAll('\\', '/');
+  return {
+    backlogDir: resolve(projectDir, agile, 'backlog'),
+    prefix: String(config.idPrefix?.backlog ?? 'BL'),
+    templateOverrides:
+      typeof config.templateOverrides === 'string' ? config.templateOverrides : undefined,
+  };
+}
+
+/** @param {string} projectDir @param {string} filePath */
+const relativePath = (projectDir, filePath) => relative(projectDir, filePath).split(sep).join('/');
+
+/** @type {typeof import('./backlog-item.d.mts').createBacklogItem} */
+export async function createBacklogItem(
+  projectDir,
+  input,
+  date = new Date().toISOString().split('T')[0],
+) {
+  const { backlogDir, prefix } = await projectBacklog(projectDir);
+  const fields = backlogFields(input);
+  const { id, filePath } = await writeBacklogItem(backlogDir, prefix, fields, date);
+  return { id, title: fields.title, artifactPath: relativePath(projectDir, filePath) };
+}
+
+/**
+ * Top-level scalar frontmatter fields; double-quoted values are read as JSON strings.
+ * @param {string} text
+ * @param {string} filePath
+ */
+function frontmatter(text, filePath) {
+  const block = /^---\n([\s\S]*?)\n---/u.exec(text.replace(/\r\n/gu, '\n'))?.[1] ?? '';
+  /** @type {Record<string, string>} */
+  const fields = {};
+  for (const line of block.split('\n')) {
+    const match = /^(\w+):\s*(.*)$/u.exec(line);
+    if (!match) continue;
+    const value = match[2].trim();
+    if (!value.startsWith('"')) {
+      fields[match[1]] = value.replace(/^'(.*)'$/u, '$1');
+      continue;
+    }
+    try {
+      fields[match[1]] = String(JSON.parse(value));
+    } catch (error) {
+      throw new Error(
+        `${filePath}: frontmatter field "${match[1]}" is not a valid quoted string: ${/** @type {Error} */ (error).message}`,
+      );
+    }
+  }
+  return fields;
+}
+
+/** @type {typeof import('./backlog-item.d.mts').listOpenBacklog} */
+export async function listOpenBacklog(projectDir) {
+  const { backlogDir } = await projectBacklog(projectDir);
+  let names;
+  try {
+    names = await readdir(backlogDir);
+  } catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code === 'ENOENT') return [];
+    throw error;
+  }
+  const items = [];
+  for (const name of names.sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))) {
+    const match = /^([A-Z]+-\d{3,})-.+\.md$/u.exec(name);
+    if (!match) continue;
+    const filePath = join(backlogDir, name);
+    const fields = frontmatter(await readFile(filePath, 'utf8'), filePath);
+    const status = fields.status ?? 'open';
+    if (CLOSED_STATUSES.has(status)) continue;
+    items.push({
+      id: fields.id ?? match[1],
+      title: fields.title ?? name.slice(match[1].length + 1, -3).replace(/-/g, ' '),
+      status,
+      path: relativePath(projectDir, filePath),
+    });
+  }
+  return items;
+}
+
+/** @type {typeof import('./backlog-item.d.mts').takeCliHint} */
+export async function takeCliHint(projectDir) {
+  const { configPath, raw, config } = await projectConfig(projectDir);
+  if (config.findings?.cliHintShown === true) return null;
+  const next = { ...config, findings: { ...config.findings, cliHintShown: true } };
+  const indent = /\n(\t| +)"/u.exec(raw)?.[1] ?? '  ';
+  await writeFile(configPath, `${JSON.stringify(next, null, indent)}\n`);
+  return CLI_HINT;
+}
+
+/** @param {string} source */
+async function readInput(source) {
+  const text =
+    source === '-'
+      ? await new Promise((done, fail) => {
+          let value = '';
+          process.stdin.setEncoding('utf8');
+          process.stdin.on('data', (chunk) => {
+            value += chunk;
+          });
+          process.stdin.on('end', () => done(value));
+          process.stdin.on('error', fail);
+        })
+      : await readFile(resolve(source), 'utf8');
+  const parsed = JSON.parse(String(text));
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+    throw new Error('Backlog input must be one JSON object with at least a title.');
+  return parsed;
+}
+
+const USAGE =
+  'Usage: backlog-item.mjs add --project <dir> --data <file|->\n       backlog-item.mjs list --project <dir> --open\n';
+
+/** @param {string[]} argv */
+async function main(argv) {
+  const [command, ...rest] = argv;
+  /** @type {Record<string, string | boolean>} */
+  const options = {};
+  for (let index = 0; index < rest.length; index += 1) {
+    const flag = rest[index];
+    if (flag === '--open') options.open = true;
+    else if (flag === '--project' || flag === '--data')
+      options[flag.slice(2)] = rest[++index] ?? '';
+    else throw new Error(`Unknown argument: ${flag}\n${USAGE}`);
+  }
+  const projectDir = resolve(String(options.project ?? '.'));
+  if (command === 'add') {
+    if (typeof options.data !== 'string' || !options.data)
+      throw new Error(`add needs --data.\n${USAGE}`);
+    const { templateOverrides } = await projectBacklog(projectDir);
+    const result = await createBacklogItem(projectDir, await readInput(options.data));
+    const cliHint = await takeCliHint(projectDir);
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        action: 'backlog.created',
+        ...result,
+        ...(templateOverrides ? { templateOverrideIgnored: true } : {}),
+        ...(cliHint ? { cliHint } : {}),
+      })}\n`,
+    );
+    return;
+  }
+  if (command === 'list' && options.open) {
+    process.stdout.write(`${JSON.stringify({ items: await listOpenBacklog(projectDir) })}\n`);
+    return;
+  }
+  throw new Error(USAGE);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+  });
+}

package/lib/host-packages/cursor/openplanr/rules/planr-investigate.mdc

@@ -1,5 +1,5 @@
 ---
-description: "Diagnose a bug, regression, error, or unexplained behavior and optionally implement a bounded fix. Use for root-cause investigation, not planned feature delivery."
+description: "Diagnose a bug, regression, error, or unexplained behavior and optionally implement a bounded fix. Use for root-cause investigation, including before any fix, not planned feature delivery."
 alwaysApply: false
 ---
 
@@ -23,6 +23,14 @@ When the user asked for a fix, implement the smallest coherent correction within
 repository and run focused regression checks. Preserve unrelated work. Ask only when a missing
 product decision or an irreversible external action genuinely blocks progress.
 
+## Findings outside the cause
+
+Report other defects you notice as [findings](planr-investigate/references/findings.md), and never
+fix them in this change unless they block the requested fix. The established cause
+is never a finding. The packaged [backlog helper](planr-investigate/scripts/backlog-item.mjs) lists
+and files backlog items when no CLI is installed; resolve it relative to this
+`SKILL.md`.
+
 ## Return
 
 Lead with the established cause or clearly labeled remaining hypothesis. Link
@@ -34,7 +42,8 @@ existing report rather than returning raw tool transcripts.
 - **Cause:** established root cause, or the strongest remaining hypotheses.
 - **Change:** files and behavior changed, or none for diagnosis-only work.
 - **Checks:** commands and results.
-- **Issues:** unresolved uncertainty or blocker, or none.
+- **Issues:** unresolved uncertainty or blocker, or none; then findings outside
+  the cause, each with its disposition.
 
 Omit empty sections in the human summary. Different wording does not justify
 another experiment or corrective run.

package/lib/host-packages/cursor/openplanr/rules/planr-plan/schemas/design-document.schema.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://openplanr.dev/schemas/v1.9.0/design-document.schema.json",
+  "$id": "https://openplanr.dev/schemas/v1.22.0/design-document.schema.json",
   "x-openplanr-contract": {
     "id": "design-document",
-    "version": "1.9.0"
+    "version": "1.22.0"
   },
   "title": "OpenPlanr authored design document",
   "type": "object",
@@ -26,7 +26,10 @@
       "const": "openplanr-design-document"
     },
     "schemaVersion": {
-      "const": "1.0.0"
+      "enum": [
+        "1.0.0",
+        "1.1.0"
+      ]
     },
     "id": {
       "$ref": "#/$defs/id"
@@ -118,9 +121,16 @@
             "maximum": 16384
           },
           "height": {
-            "type": "integer",
-            "minimum": 1,
-            "maximum": 16384
+            "anyOf": [
+              {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 16384
+              },
+              {
+                "const": "auto"
+              }
+            ]
           }
         }
       }
@@ -151,6 +161,66 @@
           },
           "anchors": {
             "$ref": "#/$defs/ids"
+          },
+          "props": {
+            "type": "object",
+            "propertyNames": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 128,
+              "pattern": "^[a-z][a-z0-9-]*(?![\\s\\S])"
+            },
+            "additionalProperties": {
+              "oneOf": [
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "type",
+                    "options",
+                    "default"
+                  ],
+                  "properties": {
+                    "type": {
+                      "const": "enum"
+                    },
+                    "options": {
+                      "type": "array",
+                      "minItems": 1,
+                      "uniqueItems": true,
+                      "items": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 128,
+                        "pattern": "^[a-z][a-z0-9-]*(?![\\s\\S])"
+                      }
+                    },
+                    "default": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 128,
+                      "pattern": "^[a-z][a-z0-9-]*(?![\\s\\S])"
+                    }
+                  }
+                },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "type",
+                    "default"
+                  ],
+                  "properties": {
+                    "type": {
+                      "const": "boolean"
+                    },
+                    "default": {
+                      "type": "boolean"
+                    }
+                  }
+                }
+              ]
+            }
           }
         }
       }
@@ -225,6 +295,34 @@
             "additionalProperties": {
               "$ref": "#/$defs/source"
             }
+          },
+          "props": {
+            "type": "object",
+            "propertyNames": {
+              "$ref": "#/$defs/id"
+            },
+            "additionalProperties": {
+              "type": "object",
+              "propertyNames": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128,
+                "pattern": "^[a-z][a-z0-9-]*(?![\\s\\S])"
+              },
+              "additionalProperties": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 128,
+                    "pattern": "^[a-z][a-z0-9-]*(?![\\s\\S])"
+                  },
+                  {
+                    "type": "boolean"
+                  }
+                ]
+              }
+            }
           }
         },
         "if": {
@@ -250,6 +348,67 @@
         "prototype",
         "walkthrough"
       ]
+    },
+    "layout": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "boards": {
+          "type": "object",
+          "description": "Keys are screenId, screenId/frameId or screenId/frameId/variantId; each ID must exist in the document.",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "x",
+              "y"
+            ],
+            "properties": {
+              "x": {
+                "$ref": "#/$defs/coordinate"
+              },
+              "y": {
+                "$ref": "#/$defs/coordinate"
+              },
+              "title": {
+                "$ref": "#/$defs/text"
+              }
+            }
+          }
+        },
+        "sections": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "x",
+              "y",
+              "text"
+            ],
+            "properties": {
+              "id": {
+                "$ref": "#/$defs/id"
+              },
+              "x": {
+                "$ref": "#/$defs/coordinate"
+              },
+              "y": {
+                "$ref": "#/$defs/coordinate"
+              },
+              "text": {
+                "$ref": "#/$defs/text"
+              },
+              "maxW": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 16384
+              }
+            }
+          }
+        }
+      }
     }
   },
   "$defs": {
@@ -301,6 +460,47 @@
           "$ref": "#/$defs/paths"
         }
       }
+    },
+    "coordinate": {
+      "type": "number",
+      "minimum": -10000000,
+      "maximum": 10000000
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "schemaVersion": {
+            "const": "1.1.0"
+          }
+        },
+        "required": [
+          "schemaVersion"
+        ]
+      },
+      "else": {
+        "properties": {
+          "screens": {
+            "items": {
+              "not": {
+                "required": [
+                  "props"
+                ]
+              }
+            }
+          },
+          "variants": {
+            "items": {
+              "not": {
+                "required": [
+                  "props"
+                ]
+              }
+            }
+          }
+        }
+      }
     }
-  }
+  ]
 }

package/lib/host-packages/cursor/openplanr/rules/planr-plan.mdc

@@ -6,9 +6,9 @@ alwaysApply: false
 # 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
+implementation-ready stories and tasks 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
@@ -34,6 +34,9 @@ For a studio-backed design, read its `.design/studio-state.json`: the recorded
 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.
+A hosted design canvas handoff has no `design-document.json` or studio state:
+its `design-spec.md` names the canvas URL and the local board sources, which are
+the design inputs; read the boards rather than the hosted canvas.
 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
@@ -60,14 +63,24 @@ 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.
+The main session owns the plan, decisions, and integration. Keep small coherent
+planning work in this session. Delegate only a self-contained outcome that
+benefits from context isolation, a distinct capability boundary, or independent
+parallel work; agent availability alone is not a reason to dispatch.
+
+Use specification for a distinct planning assignment or completeness review,
+designer for a separate design deliverable or critique, and database only for
+authorized read-only live introspection when repository schemas are insufficient.
+Do not have two planners decompose the same request. Entity scaffolding remains
+manual, on explicit request.
+
+Select the exact registered identity from the host's roster; Claude plugin
+agents use names such as `planr:planr-specification`. Give each worker its outcome,
+authoritative paths, relevant decisions, file ownership, verification requirements,
+and concise return expectations. Parallel workers need disjoint writes or an
+agreed interface. Explain the delegation's purpose briefly in commentary.
+When the host lacks the native role, perform the work sequentially in this session
+and disclose capability limitations; never claim an unavailable specialist ran.
 
 ## Author the decomposition