openplanr 3.1.1 → 3.3.0

package/lib/host-packages/openai/openplanr/skills/ship/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: ship
-description: 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.
+description: 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, or to plan and implement an accepted change. Invoke before editing files for the requested change. Not for planning only, landing, release, or work handed to another coding agent.
 license: MIT
 ---
 
 # OpenPlanr Ship
 
-Produce an implementation-complete local repository in this active coding
-session. Landing and release preparation belong to `planr-land`. Ordinary
+Produce an implementation-complete local repository in this active coding session.
+Landing and release preparation belong to `planr-land`. Ordinary
 Ship stays host-native. Do not delegate implementation to a command-line or model subprocess. If the user explicitly asks another coding agent to implement,
 hand off to `planr-delegate` before implementation. That separate opt-in workflow
 previews the selected context, writable repository, profile, and destination;
@@ -40,13 +40,34 @@ context is sufficient; missing planning files do not create a gate.
 
 ## Implement with native roles
 
-Use the host's read, edit, shell, browser, and test capabilities. When native
-agents are available, dispatch only the applicable frontend, backend, database,
-QA, DevOps, and documentation roles inside this session. Give each role its
-owned outcome, relevant context paths, and explicit file coordination boundary.
-Run independent work in parallel. Host-native role agents remain part of this
-Ship session and do not invoke the separate `planr-delegate` helper. When native
-agents are unavailable, perform the same lenses sequentially in the active agent.
+The main session owns scope, decisions, integration, and final verification.
+Use the host's read, edit, shell, browser, and test capabilities inside this session.
+Keep small coherent changes 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.
+
+Frontend and backend own substantial bounded implementation assignments.
+Persistence implementation, including a task carrying the legacy `db-agent`
+identity, belongs to backend with the relevant database guidance; preserve the
+task's recorded identity. Database is optional read-only introspection when
+repository schemas are insufficient, never migration implementation. Keep small
+documentation updates with their implementation; delegate substantial documentation
+or requested configuration work separately. DevOps never deploys. Entity
+scaffolding remains manual, on explicit request.
+
+Use a separate QA reviewer for authorization, credentials, data-loss risk,
+migrations, public contracts, release behavior, or substantial delegated
+implementation. Small low-risk edits use focused verification in the main session.
+QA retains verification tools, subject to role policy and session permissions.
+
+Select the exact registered identity from the host's roster; Claude plugin
+agents use names such as `planr:planr-backend` and `planr:planr-qa`. 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. Host-native workers do not invoke the separate `planr-delegate` helper.
+When the host lacks the native role, perform the work sequentially in this session
+and disclose capability limitations; never claim an unavailable specialist ran.
 
 Integrate the complete change, then verify behavior. `reviewRisks` and
 `browserSurfaces` select useful checks; empty arrays are normal and neither field
@@ -61,10 +82,15 @@ Discover checks in this order:
 3. package and task-runner scripts;
 4. applicable CI and pre-commit configuration.
 
-The packaged read-only [verification discovery helper](scripts/discover-verification.mjs)
-may list candidates. Resolve it relative to this `SKILL.md` and run
+Run `openplanr ship checks --json --task <task-path>` (omit `--task` for a direct
+request; add `--tier story` or `--tier push` before pushing) and run its `checks`
+from each `cwd`. The command never executes checks or writes files. When
+`complete` is `false`, report its error diagnostics and treat the check set as
+incomplete: a pass is not CI-equivalent. Without the CLI, the packaged read-only
+[verification discovery helper](scripts/discover-verification.mjs) may list
+candidates. Resolve it relative to this `SKILL.md` and run
 `node <helper> --project <repository-root> --task <task-path>`; omit `--task` for a
-direct request. It never executes checks or writes files. If it is unavailable,
+direct request. It never executes checks or writes files. If both are unavailable,
 inspect those four sources directly. Missing commands are diagnostics, not a
 reason to invent or skip all verification.
 
@@ -74,6 +100,11 @@ it by its own exit code; to shorten output, write it to a log and read the tail.
 Fix failures caused by the change and rerun affected checks.
 Read [the result contract](references/result-contract.md) before reporting.
 
+Report defects you notice outside the task as [findings](references/findings.md),
+and never fix them in this change unless they block it. The packaged
+[backlog helper](scripts/backlog-item.mjs) lists and files backlog items when no
+CLI is installed; resolve it relative to this `SKILL.md`.
+
 Do not write progress into an approved design package. The studio derives
 approved, planned, implementing, and verified state from canonical planning and
 Ship artifacts after this separate invocation.
@@ -89,7 +120,8 @@ results instead of reproducing them in chat.
 - **Task:** task ID and path, or `direct-request`.
 - **Changed:** material paths grouped by purpose.
 - **Checks:** command, `passed`, `failed`, or `not-run`, plus a concise result.
-- **Issues:** problem, impact, and next action, or `none`.
+- **Issues:** blockers with problem, impact, and next action, or `none`; then
+  findings outside the task, each with its disposition.
 
 Keep the five machine fields unchanged. A human summary may omit empty or unavailable fields,
 but must make partial, blocked or unverified work clear and give the smallest

package/lib/host-packages/openai/openplanr/skills/ship/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "OpenPlanr Ship"
   short_description: "Implement an OpenPlanr plan, specification, task, or clearly…"
-  default_prompt: "Use $planr:ship to 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."
+  default_prompt: "Use $planr:ship to 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, or to plan and implement an accepted change. Invoke before editing files for the requested change. Not for planning only, landing, release, or work handed to another coding agent."
 policy:
   allow_implicit_invocation: true

package/lib/host-packages/openai/openplanr/skills/ship/openplanr.skill.json

@@ -3,7 +3,7 @@
   "schemaVersion": "1.0.0",
   "protocolVersion": "1.8.0",
   "skillId": "planr-ship",
-  "skillVersion": "1.2.1",
+  "skillVersion": "1.4.0",
   "entrypoint": "SKILL.md",
   "hosts": [
     "claude-code",
@@ -54,6 +54,28 @@
         "cursor"
       ],
       "executable": true
+    },
+    {
+      "path": "references/findings.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    },
+    {
+      "path": "scripts/backlog-item.mjs",
+      "kind": "script",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": true
     }
   ]
 }

package/lib/host-packages/openai/openplanr/skills/ship/references/findings.md

@@ -0,0 +1,92 @@
+# Findings outside the task
+
+A finding is a defect or bad practice you observed outside the task: a wrong
+value, the same bug elsewhere, a flaky check. It needs evidence you saw: a
+repo-relative `file:line`, or a command and its output line. A suspicion without
+evidence is not a finding. A problem that stops this task is a blocker, not a
+finding.
+
+## Never fix a finding here
+
+Do not change code for a finding in this run. The one exception is a defect that
+blocks this task's own definition of done: it becomes a blocker, you fix it, and
+**Changed** says it was pre-existing and why it could not wait.
+
+## Shape
+
+`issues` holds two lists. `blockers`: problem, impact, next action.
+`findings`, each with:
+
+- `title`: one plain line stating the defect; it is also the backlog title.
+- `severity`: `critical`, `high`, `medium` or `low`; it becomes the backlog priority.
+- `evidence`: `file:line`, or the command and the output line.
+- `proposed`: the backlog entry: title, priority, tags, and a `description` in
+  Markdown with Problem, Why it matters ("no consequence yet" when that is the
+  honest answer), Evidence, and Fix shape. Label unverified parts as unverified.
+- `disposition`: `filed`, `tracked`, `declined` or `reported`, plus `{ id, path }`
+  when filed or tracked.
+
+Merge duplicates within the run. Sort by severity, highest first, and number from
+1. Show at most 5 in full and summarise the rest as "+N more".
+
+## Check what is already tracked
+
+Before showing findings, list open backlog items with the backlog helper
+linked from SKILL.md, resolved relative to that file: `node <helper> list
+--project <repository-root> --open`. A finding about the same problem as an open item,
+normally the same evidence file and an equivalent title, is `tracked`. Never file
+it again and never edit the existing item.
+
+## Decide, then ask at most once
+
+After checks, and only when at least one finding is untracked, take the first
+rule that applies. File only what it allows.
+
+1. The request says to file findings, or not to: do that.
+2. **Attended run**, the user can answer now: ask one question with the host's
+   structured question tool: "File N findings as backlog items?" with the options
+   "File all N (Recommended)" and "Don't file", and free text for numbers such as
+   "1 3". Without such a tool, ask in one chat line: `File these as backlog items?
+   Reply "all", "none", or the numbers, e.g. "1 3".` File what the answer names.
+3. **Unattended run**, nobody can answer: the host cannot ask and wait (for
+   example a print or exec mode), another skill or a delegate runner started this
+   run, or the user said not to ask. Read `findings.unattended` in
+   `.planr/config.json`. Only `file` files every untracked finding. With
+   `report`, or no setting, do not run `add` at all: mark the findings `reported`.
+
+Never ask per finding, never ask mid-run, and never file or drop a finding
+silently.
+
+## File
+
+Send each item as one JSON object (`title`, `priority`, `tags`, `description`)
+on stdin. Never pass `acceptanceCriteria`.
+
+- When an `openplanr` CLI resolves (the project's `node_modules/.bin`, then
+  `PATH`; never `npx`): `openplanr --project-dir <repository-root> backlog add
+  --data - --json`.
+- Otherwise: `node <helper> add --project <repository-root> --data -`. Its
+  result can carry `cliHint`; end the result with that line, word for word,
+  once. Install only if the user says yes then, by running exactly the command in
+  the line. If the result says `templateOverrideIgnored`, say the default format
+  was used.
+
+If filing fails, report the command and its error, and leave the finding
+`reported`.
+
+## Report
+
+Under **Issues**, write the blockers, or `none for this task.` when only findings
+remain. Then:
+
+```text
+Found outside this task (not changed)
+1. medium · /import has no rate limit · src/routes/import.ts:41
+   Filed BL-431 · .planr/backlog/BL-431-import-endpoint-has-no-rate-limit.md
+2. low · tests/session.test.ts timed out once, passed on rerun · npm test, first run
+   Already tracked as BL-212 · .planr/backlog/BL-212-session-test-times-out.md
+```
+
+Unfiled findings say why in the heading, for example `(not changed, not filed:
+unattended default is "report")`, and end with: `To file them, reply "file 1 2".` In an unattended run, add: `To file automatically in unattended runs, set "findings": { "unattended": "file" } in .planr/config.json.`
+Paths are always repo-relative.

package/lib/host-packages/openai/openplanr/skills/ship/references/result-contract.md

@@ -7,7 +7,9 @@ Return one concise human rendering backed by these five machine fields:
 3. `changed`: material files grouped by purpose.
 4. `checks`: each executed or applicable check with `passed`, `failed`, or
    `not-run` and a concise result.
-5. `issues`: unresolved problem, impact, and next action; use `none` when empty.
+5. `issues`: `blockers` for this task, each with problem, impact, and next
+   action, and `findings` outside the task, shaped as `findings.md` describes;
+   use `none` when both are empty.
 
 Do not add receipts, digests, proof ledgers, fixed review loops, or approval
 narration. Mention evidence only when it is the natural result of a command or

package/lib/host-packages/openai/openplanr/skills/ship/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/openai/openplanr/skills/spec/SKILL.md

@@ -23,6 +23,12 @@ mutually exclusive questions at once and put the recommended option first. If
 the host lacks that interface, ask one concise chat question. Do not present a
 long prose questionnaire.
 
+If no one can answer, as in a headless run, do not ask: choose the
+repository-backed default, or the recommended one when the repository does not
+settle it, and record each such choice as a bullet starting `Assumption:` under
+`## Notes for Decomposition`, naming the decision and the alternative not taken.
+Record a decision you settle inside a functional requirement the same way.
+
 When native agents are available, use the specification role to consolidate the
 contract and dispatch database or designer roles only when their lens affects
 the decision. Otherwise perform those lenses sequentially in the active agent.

package/lib/host-packages/openai/openplanr/skills/spec/openplanr.skill.json

@@ -3,7 +3,7 @@
   "schemaVersion": "1.0.0",
   "protocolVersion": "1.8.0",
   "skillId": "planr-spec",
-  "skillVersion": "1.0.1",
+  "skillVersion": "1.0.2",
   "entrypoint": "SKILL.md",
   "hosts": [
     "claude-code",

package/lib/host-packages/openai/openplanr/skills/spec/references/specification-contract.md

@@ -30,7 +30,9 @@ template:
 
 Keep evidence and rollback as useful planning context, not approval gates or
 receipt requirements. A risk-specialist section may be empty when no specialist
-lens applies.
+lens applies. Under `## Notes for Decomposition`, list each decision made without
+an answer as a bullet starting `Assumption:` that names the decision and the
+alternative not taken.
 
 For a repository intentionally using default mode, write
 `input/specs/spec-{slug}.md` and preserve its active schema. Do not create a

package/lib/host-packages/openai/openplanr/skills/sprint/references/connectors.md

@@ -3,12 +3,10 @@
 OpenPlanr skills name a kind of service, such as `~~chat`, instead of a product. Connect
 the product your team uses through your host: the vendor publishes the connector, and
 you sign in through the host. OpenPlanr bundles no connectors; they and their credentials
-live in your host. Two optional features need a token: Linear sync (`openplanr linear`) and
-company sign-in (`openplanr company login`). Only when you use them does OpenPlanr store a
-token, in your OS keychain, or in an encrypted file at `~/.planr/credentials.enc` if you set
-`PLANR_CREDENTIAL_FILE_PASSPHRASE`. Tokens are sent only to Linear or to the company server
-you sign in to.
-`openplanr company logout` removes company tokens.
+live in your host. One optional feature needs a token: Linear sync (`openplanr linear`).
+Only when you use it does OpenPlanr store a token, in your OS keychain, or in an encrypted
+file at `~/.planr/credentials.enc` if you set `PLANR_CREDENTIAL_FILE_PASSPHRASE`. The token
+is sent only to Linear.
 Every skill also works with nothing connected and reports any remote step it skipped.
 
 | Category | Placeholder | Products |

package/lib/host-packages/openai/openplanr/skills/status/references/connectors.md

@@ -3,12 +3,10 @@
 OpenPlanr skills name a kind of service, such as `~~chat`, instead of a product. Connect
 the product your team uses through your host: the vendor publishes the connector, and
 you sign in through the host. OpenPlanr bundles no connectors; they and their credentials
-live in your host. Two optional features need a token: Linear sync (`openplanr linear`) and
-company sign-in (`openplanr company login`). Only when you use them does OpenPlanr store a
-token, in your OS keychain, or in an encrypted file at `~/.planr/credentials.enc` if you set
-`PLANR_CREDENTIAL_FILE_PASSPHRASE`. Tokens are sent only to Linear or to the company server
-you sign in to.
-`openplanr company logout` removes company tokens.
+live in your host. One optional feature needs a token: Linear sync (`openplanr linear`).
+Only when you use it does OpenPlanr store a token, in your OS keychain, or in an encrypted
+file at `~/.planr/credentials.enc` if you set `PLANR_CREDENTIAL_FILE_PASSPHRASE`. The token
+is sent only to Linear.
 Every skill also works with nothing connected and reports any remote step it skipped.
 
 | Category | Placeholder | Products |