openplanr 1.25.2 → 2.0.0

package/lib/host-packages/claude/openplanr/skills/release/references/release-notes.md

@@ -0,0 +1,127 @@
+# Writing user-facing release notes
+
+Contents:
+1. Who is reading
+2. Voice rules
+3. Worked rewrites
+4. Handling breaking changes
+5. Section ordering and grouping
+6. Channel formats
+7. What to leave out
+
+---
+
+## 1. Who is reading
+
+Someone who uses the product, has a limited budget of attention for it, and is scanning for one of three things: did the thing that annoyed me get fixed, can I now do something I could not before, and do I have to change anything.
+
+Everything below follows from that. The reader does not care which service was refactored, and will never read a sentence that opens with "we".
+
+---
+
+## 2. Voice rules
+
+**Lead with the user's new capability, not the implementation.** The subject of the sentence should be the thing they can do or the thing that now works, not the code that was written.
+
+**Use the product's own vocabulary.** If the UI says "Availability", the notes say Availability, not `schedule_slots` and not "the calendar module". A reader who cannot map an entry to something they can see on screen will skip it.
+
+**Describe fixes by symptom.** The reader recognizes the symptom, because they experienced it. They have no way to recognize the cause.
+
+**One line per entry.** If an entry genuinely needs more, write one line and link to a doc. Multi-paragraph entries mean the section is being used as a blog post.
+
+**Second person, present tense.** "You can now export" over "users are now able to export".
+
+**No em dashes.** Use a colon, a comma, or two sentences.
+
+**No filler openers.** Cut "we're excited to announce", "as always", "in this release we've been hard at work". The reader is scanning, and every filler word costs them.
+
+**No hedging on fixes.** "Fixed an issue where some users may have occasionally experienced" is four qualifiers protecting the writer at the reader's expense. It broke, it is fixed, say so.
+
+---
+
+## 3. Worked rewrites
+
+**Feature**
+- Before: `feat(booking): implement recurring slot generation with rrule parsing`
+- After: `Set a session to repeat weekly or monthly instead of creating each one by hand.`
+
+**Feature, buried in implementation**
+- Before: `Migrated the availability resolver to a new interval-tree lookup, improving query performance.`
+- After: `Availability now loads instantly, even on calendars with hundreds of sessions.`
+
+**Fix, described by cause**
+- Before: `Fixed a race condition in the webhook handler's idempotency check.`
+- After: `Payments confirmed twice in quick succession no longer create duplicate bookings.`
+
+**Fix, over-hedged**
+- Before: `Resolved an issue where some users may have intermittently seen incorrect timezone offsets in certain edge cases.`
+- After: `Session times now show in your local timezone after travelling between regions.`
+
+**Improvement, too vague to be worth printing**
+- Before: `Various performance improvements and bug fixes.`
+- After: either name what got faster and what got fixed, or cut the line entirely. This sentence has never informed anyone.
+
+**Breaking change, softened into invisibility**
+- Before: `Updated the booking API response format for consistency.`
+- After: `The booking API now returns `startsAt` instead of `start_time`. Update your integration before 15 October, when the old field is removed.`
+
+**Internal work that should not appear at all**
+- Before: `Upgraded Prisma to 6.2, refactored the seed script, added integration tests for the payout flow.`
+- After: nothing. None of this is observable. Track it in commits.
+
+---
+
+## 4. Handling breaking changes
+
+A breaking change entry needs four things in one or two lines: what changed, what breaks, what to do, and by when.
+
+```
+### Removed
+- The `/v1/sessions/list` endpoint is gone. Use `/v1/sessions` with the `status`
+  filter, which returns the same records. See the migration guide: <link>
+```
+
+Rules:
+
+- Put it first, before Added. The reader who stops after three lines must have seen it.
+- Never bundle it into a list of unrelated improvements. It gets its own section and, where possible, its own release.
+- A changelog entry is not sufficient notice on its own. Anything with an integration cost also needs an in-product notice or a direct message to affected users, because most people do not read changelogs.
+- State the date, not "soon".
+
+---
+
+## 5. Section ordering and grouping
+
+Use Keep a Changelog headings so the format is recognizable and tooling can parse it: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`.
+
+Order by cost of missing it:
+
+1. `Removed` and breaking items in `Changed`
+2. `Security`
+3. `Added`
+4. `Changed`
+5. `Deprecated`
+6. `Fixed`
+
+Omit any section with nothing in it. Never write "N/A" or "No changes".
+
+If a release has more than about ten entries in one section, group by product area with bold sublabels. Past that length the flat list stops being scannable, which defeats the purpose.
+
+---
+
+## 6. Channel formats
+
+The same release, adapted per channel. Do not paste the changelog everywhere.
+
+- **CHANGELOG.md**: the full record. Every user-visible change, versioned and dated, never edited retroactively except to correct an error.
+- **In-product "what's new"**: the top three entries, plain language, linked to the feature. Skip patch releases entirely; interrupting users for a bug fix trains them to dismiss the panel.
+- **Email or announcement**: only for features worth an interruption, and for breaking changes. One feature per email beats a digest nobody finishes.
+- **Git tag annotation or GitHub release**: the changelog section verbatim, plus the compare link.
+
+---
+
+## 7. What to leave out
+
+Refactors, test coverage, CI changes, dependency bumps without behavior change, formatting, internal renames, infrastructure moves that users cannot detect, and anything gated behind a flag that is still off.
+
+That last one matters at high cadence: code merged behind a disabled flag has not shipped. It belongs in the release where the flag turns on, described from the user's side. Announcing it early produces notes that reference features nobody can find.

package/lib/host-packages/claude/openplanr/skills/release/references/schemes.md

@@ -0,0 +1,103 @@
+# Choosing and running a versioning scheme
+
+Contents:
+1. The question the version number answers
+2. SemVer
+3. CalVer
+4. Two version lines
+5. Monorepos
+6. Pre-1.0 and pre-release tags
+7. Worked selections
+
+---
+
+## 1. The question the version number answers
+
+A version number is a compression of "what am I dealing with". Different audiences ask different questions, and the scheme should answer the one that actually gets asked.
+
+- A developer who installed your package asks **"can I upgrade without breaking?"** That is a compatibility question, and SemVer answers it.
+- A user of a hosted app asks **"is this current, and what changed?"** That is a recency question, and CalVer answers it.
+- Support asks **"which build is this person on?"** Either works, as long as it is visible in the product.
+
+Pick the scheme that answers the question your actual audience asks. Applying SemVer to a SaaS dashboard where nobody can pin a version produces a number that looks meaningful and is not.
+
+---
+
+## 2. SemVer
+
+`MAJOR.MINOR.PATCH`, incremented on compatibility impact against a declared public API.
+
+Use when consumers pin, install or integrate: npm and PyPI packages, SDKs, CLIs, public HTTP APIs, anything with a dependency range pointed at it.
+
+**The prerequisite is a declared public surface.** Without it the scheme is unusable, because "breaking" is defined relative to something. Write the surface down in the profile. For a TypeScript package that means exported types and functions from the entrypoint, not everything importable via deep paths. For an HTTP API it means documented endpoints, request and response shapes, status codes, auth flow and webhook payloads.
+
+Anything outside the declared surface can change in a patch. This is what makes SemVer survivable: without a boundary, every internal rename is theoretically breaking and you never ship a minor again.
+
+**Bump rules:**
+
+- MAJOR: remove or rename anything in the surface, change a response or return shape, change a default that alters outcomes, tighten validation to reject formerly valid input, add a required parameter, change error semantics that callers branch on.
+- MINOR: add to the surface, add an optional parameter, add a new endpoint or export, ship a deprecation warning.
+- PATCH: fix behavior to match documentation, performance, internal changes, dependency updates with no surface impact.
+
+**The judgement call that comes up most:** a bug fix that changes behavior people depend on. Strictly it is a fix, but if the buggy behavior is load-bearing for existing users, treat it as breaking. The test is whether shipping it silently would generate support tickets.
+
+---
+
+## 3. CalVer
+
+`YYYY.MM.PATCH` (recommended default), `YYYY.MM.DD`, or `YY.MINOR.PATCH`.
+
+Use for hosted apps, internal tools, and anything where the user is always on the latest version because you put them there.
+
+**What it does well:** answers "how stale is this" instantly, no argument about whether something is a minor or a major, and it maps naturally onto a release rhythm.
+
+**What it cannot do:** carry a compatibility signal. `2026.09.1` to `2026.10.0` tells the reader nothing about whether anything broke. That obligation moves entirely onto the release notes, so a CalVer product must lead its notes with breaking changes and must announce them in-product, not just in a changelog nobody reads.
+
+Recommended format is `YYYY.MM.PATCH`: `2026.09.0` for the first September release, `2026.09.1` for the next. The month gives recency, the counter distinguishes multiple releases within it, and it sorts correctly as a string. Avoid `YYYY.M.D` with unpadded numbers, since it sorts wrong and reads ambiguously.
+
+---
+
+## 4. Two version lines
+
+The most common structural mistake is a single number covering both an app and the API it exposes. They change for unrelated reasons and have different audiences, so one number cannot serve both. A UI redesign is a big deal to users and a non-event to integrators. An API field rename is the reverse.
+
+When a product has both, run:
+
+- **App version:** CalVer, shown in the UI footer or settings, referenced in support and release notes.
+- **API version:** SemVer, or a dated URL version (`/v1/`, `2026-09-08`), governed by its own compatibility policy and deprecation timeline.
+
+Record both in the profile, with a note on which one the release notes are written against. Usually the app version leads and API changes appear as a clearly marked section.
+
+---
+
+## 5. Monorepos
+
+Two viable models. Pick one and record it.
+
+**Fixed (single version across all packages).** Every package ships the same number. Simple to reason about, simple to support, at the cost of publishing no-change versions for untouched packages. Good when the packages are only ever consumed together.
+
+**Independent (per-package versions).** Each package versions on its own changes. Correct for consumers, more machinery. Use Changesets in a JS/TS monorepo: contributors add a changeset describing the change and its bump level as part of the PR, and the tool aggregates them into version bumps and changelog entries at release time.
+
+Independent versioning plus Changesets is the better default when packages have separate consumers, because it captures the bump decision at the moment the author still remembers the intent, rather than reconstructing it from commit messages weeks later.
+
+---
+
+## 6. Pre-1.0 and pre-release tags
+
+**0.x** signals "the surface is not stable yet, expect breaks". Under SemVer convention, `0.MINOR.PATCH` treats minor as the breaking position. This is a legitimate state for something genuinely still forming.
+
+It stops being legitimate once real users depend on it. A product with paying customers on `0.x` is either lying about its stability or has forgotten to cut 1.0. Cutting 1.0 is a promise about the public surface, not a claim of feature completeness, and delaying it past the point of real usage costs credibility.
+
+**Pre-release identifiers:** `1.4.0-beta.1`, `2026.09.0-rc.2`. Use for builds going to a subset of users before general release. They sort before the final version, and package managers exclude them from normal ranges. Do not use them as a permanent staging label; something that lives on `-beta` for a year is just the product.
+
+---
+
+## 7. Worked selections
+
+**A booking site for a single business.** One audience, always on latest, no integrators. CalVer `YYYY.MM.PATCH`. The public surface is the booking flow itself, and the only breaking-class events are things like changing how existing appointment links resolve.
+
+**A mentorship platform with a Stripe-backed API and webhooks.** Two lines. CalVer for the app, SemVer for the API and webhook payloads, because integrators parse those payloads and a field rename genuinely breaks them. Webhook payload shape belongs in the declared public surface even though it is easy to forget.
+
+**A published npm package used by other teams.** SemVer, strict, with the declared surface listed as the entrypoint exports. Consumers automate upgrades against the number, so accuracy matters more than convenience.
+
+**An internal admin tool.** CalVer, minimal ceremony. Nobody pins it, and the useful question is "is this the build from before or after the fix".

package/lib/host-packages/claude/openplanr/skills/release/scripts/collect_changes.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# Collect everything that shipped in a window, as raw material for release notes.
+#
+# Usage:
+#   ./collect_changes.sh                         # since the last tag
+#   ./collect_changes.sh "2026-09-01"            # since a date
+#   ./collect_changes.sh --include-prs            # include remote PR metadata
+#   ./collect_changes.sh "2026-09-01" --include-prs
+#
+# Output is raw material, not release notes. Classify it before writing.
+
+set -uo pipefail
+
+SINCE_ARG=""
+INCLUDE_PRS=0
+
+for ARG in "$@"; do
+  case "$ARG" in
+    --include-prs)
+      INCLUDE_PRS=1
+      ;;
+    -*)
+      printf 'Unknown option: %s\n' "$ARG" >&2
+      exit 2
+      ;;
+    *)
+      if [ -n "$SINCE_ARG" ]; then
+        printf 'Only one date window may be supplied.\n' >&2
+        exit 2
+      fi
+      SINCE_ARG="$ARG"
+      ;;
+  esac
+done
+
+if [ -n "$SINCE_ARG" ]; then
+  RANGE_DESC="since $SINCE_ARG"
+  LOG_ARGS=(--since="$SINCE_ARG")
+  PR_SEARCH="merged:>=$SINCE_ARG"
+else
+  LAST_TAG="$(git describe --tags --abbrev=0 2>/dev/null || true)"
+  if [ -z "$LAST_TAG" ]; then
+    RANGE_DESC="all history (no previous tag found)"
+    LOG_ARGS=()
+    PR_SEARCH=""
+  else
+    TAG_DATE="$(git log -1 --format=%cs "$LAST_TAG")"
+    RANGE_DESC="since $LAST_TAG ($TAG_DATE)"
+    LOG_ARGS=("$LAST_TAG..HEAD")
+    PR_SEARCH="merged:>=$TAG_DATE"
+  fi
+fi
+
+echo "=============================================="
+echo "Changes $RANGE_DESC"
+echo "=============================================="
+echo
+echo "--- Recent tags (match this format when tagging) ---"
+git tag --list --sort=-creatordate | head -5 || echo "none"
+echo
+echo "--- Commits (merges excluded) ---"
+git log "${LOG_ARGS[@]}" --no-merges --pretty=format:'%h %s' || true
+echo
+echo
+echo "--- Files touched, by area ---"
+git log "${LOG_ARGS[@]}" --name-only --pretty=format: 2>/dev/null \
+  | awk 'NF' \
+  | awk -F/ '{ if (NF>1) print $1"/"$2; else print $1 }' \
+  | sort | uniq -c | sort -rn | head -20
+echo
+echo "--- Merged PRs ---"
+if [ "$INCLUDE_PRS" -eq 1 ] && command -v gh >/dev/null 2>&1 && [ -n "$PR_SEARCH" ]; then
+  gh pr list --state merged --search "$PR_SEARCH" --limit 100 \
+    --json number,title \
+    --template '{{range .}}#{{.number}} {{.title}}{{"\n"}}{{end}}' 2>/dev/null \
+    || echo "gh is installed but the query failed. Check: gh auth status"
+else
+  echo "PR collection not requested, unavailable, or missing a date window."
+fi
+echo
+echo "=============================================="
+echo "Check whether this misses config or feature flag"
+echo "changes, infrastructure, work from other repos,"
+echo "or other user-visible behavior before finalizing."
+echo "=============================================="

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

@@ -0,0 +1,80 @@
+---
+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.
+license: MIT
+---
+
+# Planr Ship
+
+Produce an implementation-complete local repository in this active coding
+session. Landing and release preparation belong to `planr-land`. Do not
+delegate implementation to a command-line or model subprocess.
+Keep the work local; do not publish or deploy it.
+
+## Resolve the task and context
+
+For a selector, locate exactly one task and read it completely. Then follow its
+`storyId` and `specId` to the parent story, acceptance criteria, Gherkin file
+when present, and specification. Also read repository instructions, ADRs,
+planning rules, applicable stack guidance, relevant design/database context,
+implementation code, tests, and interfaces produced by declared dependencies.
+
+Only `dependsOn` defines semantic ordering. When a dependency has not produced
+the interface this task consumes, report that concrete gap. Never infer a
+dependency from order or overlapping paths. Isolate independent executions when
+the host supports it; otherwise serialize only overlapping writes.
+
+Create and Modify describe the expected surface, not an artificial file fence.
+Include companion files needed for correctness, leave Preserve entries
+unchanged, and retain unrelated working-tree changes. If a selector resolves to
+zero or multiple tasks, report the searched locations and candidates instead of
+guessing. For a direct implementation request, the request plus repository
+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. When native agents are unavailable, perform
+the same lenses sequentially in the active agent.
+
+Integrate the complete change, then verify behavior. `reviewRisks` and
+`browserSurfaces` select useful checks; empty arrays are normal and neither field
+is a workflow gate.
+
+## Discover and run verification
+
+Discover checks in this order:
+
+1. task Test Requirements;
+2. repository instructions;
+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`; pass the repository
+root and task path. It never executes checks or writes files. If it is unavailable,
+inspect those four sources directly. Missing commands are diagnostics, not a
+reason to invent or skip all verification.
+
+Run the strongest applicable focused checks while working, then the relevant
+regression checks. Fix failures caused by the change and rerun affected checks.
+Read [the result contract](references/result-contract.md) before reporting.
+
+## Return
+
+Return the existing five fields:
+
+- **Outcome:** `completed`, `partial`, or `blocked`, followed by what now works.
+- **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`.
+
+For a completed outcome, append `Next: planr-land` to the human summary. It is
+presentation guidance, not a sixth machine field.
+
+When the OpenPlanr dashboard is running, the shipped work is browsable at
+`#/detail/<T-###>` and the board at `#/board`. This is navigation only.

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

@@ -0,0 +1,48 @@
+{
+  "kind": "openplanr-skill-package",
+  "schemaVersion": "1.0.0",
+  "protocolVersion": "1.8.0",
+  "skillId": "planr-ship",
+  "skillVersion": "1.1.0",
+  "entrypoint": "SKILL.md",
+  "hosts": [
+    "claude-code",
+    "codex",
+    "chatgpt",
+    "cursor"
+  ],
+  "execution": "host-agent",
+  "resources": [
+    {
+      "path": "agents/openai.yaml",
+      "kind": "agent-metadata",
+      "hosts": [
+        "codex",
+        "chatgpt"
+      ],
+      "executable": false
+    },
+    {
+      "path": "references/result-contract.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    },
+    {
+      "path": "scripts/discover-verification.mjs",
+      "kind": "script",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": true
+    }
+  ]
+}

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

@@ -0,0 +1,14 @@
+# Ship result contract
+
+Return one concise human rendering backed by these five machine fields:
+
+1. `outcome`: `completed`, `partial`, or `blocked`, plus the achieved result.
+2. `task`: exact task identity and path, or `direct-request`.
+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.
+
+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
+test the user needs to understand.

package/lib/host-packages/claude/openplanr/skills/ship/scripts/discover-verification.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const COMMAND = /^(?:npm|npx|pnpm|yarn|bun|node|deno|cargo|go|make|just|pytest|python(?:3)?\s+-m|dotnet|mvn|gradle|\.\/gradlew)\b/u;
+const PRIORITY = Object.freeze(['test', 'test:unit', 'test:integration', 'typecheck', 'check', 'lint', 'build']);
+const read = (path) => readFileSync(path, 'utf8').replace(/\r\n/gu, '\n');
+
+function commands(markdown) {
+  const rows = [];
+  for (const match of markdown.matchAll(/```(?:bash|sh|shell|zsh)?\s*\n([\s\S]*?)```/gu)) {
+    for (const line of match[1].split('\n').map((value) => value.trim())) {
+      if (COMMAND.test(line)) rows.push(line);
+    }
+  }
+  for (const match of markdown.matchAll(/`([^`\n]+)`/gu)) {
+    const value = match[1].trim();
+    if (COMMAND.test(value)) rows.push(value);
+  }
+  return rows;
+}
+
+function section(markdown, heading) {
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+  return new RegExp(`^## ${escaped}\\s*$([\\s\\S]*?)(?=^## |(?![\\s\\S]))`, 'mu').exec(markdown)?.[1] ?? '';
+}
+
+function files(directory, predicate) {
+  if (!existsSync(directory) || !statSync(directory).isDirectory()) return [];
+  return readdirSync(directory, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && predicate(entry.name))
+    .map((entry) => resolve(directory, entry.name))
+    .sort();
+}
+
+function packageChecks(root) {
+  const packagePath = resolve(root, 'package.json');
+  if (!existsSync(packagePath)) return [];
+  const scripts = JSON.parse(read(packagePath)).scripts ?? {};
+  const manager = existsSync(resolve(root, 'pnpm-lock.yaml')) ? 'pnpm'
+    : existsSync(resolve(root, 'yarn.lock')) ? 'yarn'
+      : existsSync(resolve(root, 'bun.lock')) || existsSync(resolve(root, 'bun.lockb')) ? 'bun'
+        : 'npm';
+  return Object.keys(scripts)
+    .filter((name) => PRIORITY.includes(name) || /^(?:test|check|lint|build|typecheck)(?::|$)/u.test(name))
+    .sort((left, right) => {
+      const a = PRIORITY.indexOf(left);
+      const b = PRIORITY.indexOf(right);
+      return (a < 0 ? 99 : a) - (b < 0 ? 99 : b) || left.localeCompare(right);
+    })
+    .map((name) => `${manager} run ${name}`);
+}
+
+function parseArgs(argv) {
+  const options = { project: '.', task: null };
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] === '--project') options.project = argv[++index];
+    else if (argv[index] === '--task') options.task = argv[++index];
+    else throw new Error(`Unknown argument: ${argv[index]}`);
+  }
+  return options;
+}
+
+function discover({ project, task }) {
+  const root = resolve(project);
+  const taskPath = task ? resolve(root, task) : null;
+  const groups = [
+    ['task-requirements', taskPath && existsSync(taskPath) ? commands(section(read(taskPath), 'Test Requirements')) : []],
+    ['repository-instructions', ['AGENTS.md', 'CLAUDE.md', '.planr/rules.md'].flatMap((name) => {
+      const path = resolve(root, name);
+      return existsSync(path) ? commands(read(path)) : [];
+    })],
+    ['package-task-runner', packageChecks(root)],
+    ['ci-pre-commit', [
+      ...files(resolve(root, '.github/workflows'), (name) => /\.ya?ml$/u.test(name)),
+      ...files(resolve(root, '.husky'), (name) => !name.startsWith('.')),
+      ...['.gitlab-ci.yml', '.pre-commit-config.yaml', 'Makefile', 'justfile']
+        .map((name) => resolve(root, name))
+        .filter(existsSync),
+    ].flatMap((path) => commands(read(path)))],
+  ];
+  const seen = new Set();
+  const checks = groups.flatMap(([source, values]) => values.flatMap((command) => {
+    if (seen.has(command)) return [];
+    seen.add(command);
+    return [{ command, source }];
+  }));
+  return {
+    kind: 'verification-discovery',
+    schemaVersion: '1.0.0',
+    projectRoot: root,
+    taskPath,
+    checks,
+    diagnostics: [
+      ...(taskPath && !existsSync(taskPath) ? [`Task file not found: ${taskPath}`] : []),
+      ...(checks.length === 0 ? ['No verification commands were discovered; inspect the repository directly.'] : []),
+    ],
+  };
+}
+
+try {
+  process.stdout.write(`${JSON.stringify(discover(parseArgs(process.argv.slice(2))), null, 2)}\n`);
+} catch (error) {
+  process.stderr.write(`E_VERIFICATION_DISCOVERY: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/lib/host-packages/claude/openplanr/skills/spec/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: spec
+description: Shape vague product or engineering intent into a clear, measurable Protocol-compatible specification grounded in the current repository. Use when requirements need clarification before planning or implementation.
+license: MIT
+---
+
+# Planr Spec
+
+Shape vague product or engineering intent into a decision-complete
+specification inside this active coding session. Do not invoke a planning CLI or
+another model process.
+
+## Ground the specification
+
+Read the request, repository instructions, ADRs, product documentation,
+existing planning artifacts, relevant implementation code and tests, stack
+configuration, design inputs, database context, and current behavior. Infer
+facts the repository already answers.
+
+When a missing decision materially changes scope or observable behavior, use
+the host's structured question interface. Ask no more than three short,
+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.
+
+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.
+
+## Author directly
+
+Read [the specification contract](references/specification-contract.md). Write
+the specification to the repository's active planning layout, using a
+project-global monotonic `SPEC-NNN` ID. Inspect the repository's existing
+sequence and planning files before choosing it; never reuse a deleted ID.
+
+Requirements and acceptance criteria must be observable. Put non-goals under
+out-of-scope boundaries. Record concrete repository paths and verification
+signals when they are known. Keep unresolved questions out of the saved
+contract when a repository-backed default exists.
+
+Validate the completed artifact before returning. If a helper is unavailable,
+perform the same deterministic checks directly; never fall back to a
+model-backed CLI.
+
+## Return
+
+- **Outcome:** what the specification now defines.
+- **Artifact:** the saved path, or `not saved` for an explicitly inline result.
+- **Decisions:** locked decisions and grounded defaults.
+- **Open question:** only a decision that still changes the product; omit when
+  none remains.
+- **Next:** a copy-ready host-native `planr-plan` invocation for the saved spec.

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

@@ -0,0 +1,37 @@
+{
+  "kind": "openplanr-skill-package",
+  "schemaVersion": "1.0.0",
+  "protocolVersion": "1.8.0",
+  "skillId": "planr-spec",
+  "skillVersion": "1.0.0",
+  "entrypoint": "SKILL.md",
+  "hosts": [
+    "claude-code",
+    "codex",
+    "chatgpt",
+    "cursor"
+  ],
+  "execution": "host-agent",
+  "resources": [
+    {
+      "path": "agents/openai.yaml",
+      "kind": "agent-metadata",
+      "hosts": [
+        "codex",
+        "chatgpt"
+      ],
+      "executable": false
+    },
+    {
+      "path": "references/specification-contract.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    }
+  ]
+}