opencode-ship 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to `opencode-ship` are recorded here.
+
+## 0.2.0 — npm-distributed installer release
+
+`opencode-ship@0.2.0` replaces the v0.1.x copy-the-shim workflow. The package is now an npm-distributed CLI plus a self-contained OpenCode plugin. Run `pnpm dlx opencode-ship@latest init` from any consumer repo to materialise everything needed for the delivery workflow.
+
+### Changed
+
+- **Package name and public API.** The package is now `opencode-ship` (was `opencode-delivery`). The package root exports the bundled OpenCode plugin; the previous library surface is still reachable through `opencode-ship/core`.
+- **`pnpm dlx opencode-ship@latest <command>`.** Five idempotent subcommands: `init`, `diff`, `update`, `doctor`, `uninstall`. Manual copying is no longer required.
+- **Self-contained plugin.** `dist/plugin.js` is a single ESM bundle that inlines `@opencode-ai/plugin`. The nine `delivery_*` tools are registered against the bundled tool helper, no consumer-side wrapper is needed.
+- **User-owned config + managed lock.** `.opencode/ship.config.json` is user-owned and preserved across updates; `.opencode/ship.lock.json` records installed version, schema version, managed paths, SHA-256 hashes, and an integrity digest.
+- **Hash-based reconciliation.** Every managed file's previous lock hash, current disk hash, and desired hash determine the action. Modified managed files are refused with a precise conflict report, never silently overwritten.
+- **Recoverable multi-file transactions.** Staged writes, sibling temporary files, journaled backups, and atomic rename per file. Pre-commit failures roll back in reverse order. The lock is promoted last as the commit marker.
+- **Build permissions only.** `init` merges only Build-agent delivery permissions into the root `opencode.json` (or `.jsonc`); everything else is preserved untouched.
+- **`init` auto-runs `doctor`.** After a successful commit, `init` runs the doctor checks and embeds the result in the JSON envelope (`doctor`, `doctorChecks`). Pass `--strict-doctor` to fail init when the doctor reports unhealthy checks.
+- **Post-merge cleanup is immediate.** Successful merge triggers `delivery_cleanup` automatically. Failures persist `cleanupPending` in the lock; the next delivery task or plugin startup retries the queue.
+- **Verifier permission isolation.** The verifier's frontmatter now explicitly allows only `delivery_verify` and denies every other `delivery_*` tool, mirroring the reviewer.
+- **Models.** Agents inherit the consumer's default model; no hardcoded provider/model pin.
+- **Schema files published.** `project-adapter.schema.json`, `ship-config.schema.json`, and `ship-lock.schema.json` are accessible through `opencode-ship/schema/*` exports.
+- **Reviewer change-of-SHA guard.** Reviewer must capture the PR head SHA before recording; mismatch returns `head-mismatch` and `missing-head-sha`.
+- **`gh pr view` no longer requests the unsupported `merged` field.** `merged` is now derived from `state === "MERGED"` (falling back to a non-null `mergedAt`), so the merge path is portable across `gh` 2.x versions where the field may be missing.
+- **Verification pipeline.** `npm run verify` runs `format:check`, `lint`, `typecheck`, `build`, and the auto-discovered test suite against all `tests/**/*.test.mjs`.
+- **Packed-artifact smoke test.** `tests/package/packed-artifact.test.mjs` runs `npm pack`, inspects the file list, extracts the tarball, copies the bundled plugin into an isolated consumer with no `node_modules`, and asserts that the plugin loads with exactly nine tool definitions.
+- **Fail-closed `prepack`.** `scripts/prepack.mjs` requires `esbuild` and `tsc`, builds the project, and verifies every required build artifact before publishing.
+
+### Added
+
+- **Install manifests and commands.** `init`, `diff`, `update`, `doctor`, `uninstall` CLI commands; exit codes 0–5.
+- **JSON-pointer ownership** for the Build-agent permission block; the installer's edits are reversible from the lock.
+- **`--force-root-config`** flag that synthesises a minimal `opencode.json` with installer-owned permissions when the consumer has none.
+- **`--strict-doctor`** flag that turns doctor issues into a hard init failure.
+- **`ship.config.json`** with a nested shape (`project`, `delivery`) and a flat legacy-adapter compatibility layer in `src/installer/ship-adapter.js`.
+- **Migration** from legacy v0.1.x consumers (`.opencode/delivery.json`, `.opencode/delivery.lock.json`, generic `delivery.ts` shim). Migration does not delete legacy artifacts and refuses destructive changes when customised.
+- **Agent and skill discovery** tests (`tests/agents/delivery-reviewer-contract.test.mjs`, `tests/agents/delivery-verifier-contract.test.mjs`, `tests/agents/reviewer-permission-boundary.test.mjs`, `tests/agents/skill-discovery.test.mjs`).
+- **Installer plugin-load smoke test** (`tests/plugin/plugin-load.test.mjs`) that imports the bundled artifact and asserts exactly nine tool definitions.
+
+### Fixed
+
+- **`gh pr view merged blocker.** The GitHub driver no longer requests the unsupported `merged` field on `gh pr view --json`. `merged` is derived from `state` / `mergedAt` instead.
+- **Cleanup-after-merged-PR race.** Cleanup preconditions are validated atomically; the agent-owned worktree and local branch are removed only after the manifest is sealed.
+- **Deterministic cleanup recovery.** A `merged` manifest that has no PR is recovered when the worktree is clean and the recorded head SHA matches the local head.
+- **Stale lockfile / missing adapter schema.** The lockfile is regenerated during `npm install`; the previously missing `schema/project-adapter.schema.json` is published.
+- **Locked JSON parse drift.** Config files generated with extra fields the schema rejected (`inferredFrom`) no longer fail validation; detection now produces schema-compliant output.
+- **Hash-corruption in root-config writes.** The order-preserving JSONC walker now merges new keys with the original source order, so existing pointers are not lost on rewrite.
+
+### Compatibility
+
+- Requires Node `>=22.6.0` (matches `engines` and doctor).
+- Requires `@opencode-ai/plugin >= 1.15.5 < 2` as a peer dependency (it is provided by OpenCode at runtime).
+- The plugin auto-discovers from `.opencode/plugin/opencode-ship.js`; consumers do NOT add a `plugin` entry to `opencode.json` for the bundled plugin (avoid double registration).
+
+### Removed
+
+- The previous source-pinned package layout that required copying `delivery.json`, the project plugin shim, the agents, and the skills by hand.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vktr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# opencode-ship
+
+> npm-distributed OpenCode installer and delivery plugin: a single command materialises the lifecycle plugin, reviewer/verifier agents, and skills into any consumer repository, with a recoverable lock and never silently overwrites managed files.
+>
+> **Status:** v0.2.0. The installer is now a `pnpm dlx opencode-ship@latest <cmd>` workflow. Five idempotent CLI commands manage a managed-file lock, a transactional promoter, and a compiled ESM plugin that registers the canonical nine `delivery_*` tools. Post-merge cleanup is immediate and recoverable. All 150 tests and the packed-artifact smoke check pass under `npm run verify`.
+
+---
+
+## What this package is
+
+`opencode-ship` is the npm-distributed successor to `opencode-delivery`. It bundles:
+
+- a **nine-tool OpenCode plugin** that auto-loads from `.opencode/plugin/opencode-ship.js`;
+- a **lifecycle state machine** for one issue → one worktree → one PR → one merge → one cleanup;
+- a **Git worktree driver** (no rebase-after-push, no force-push, no `--force-with-lease`);
+- a **GitHub CLI driver** that talks only to typed `gh pr/issue` verbs (never `gh api`);
+- a **project adapter** (`.opencode/ship.config.json`) so any project can declare its own verify/bootstrap/CI commands;
+- **reviewer** and **verifier** subagents, both with strictly bounded `delivery_*` permissions;
+- a **delivery-workflow** skill that drives the canonical lifecycle;
+- a **planning-research-checkpoint** skill that offers a single, optional Deep Research gate per non-trivial plan;
+- a **delivery doctor** that validates the adapter, package pin, and OpenCode compatibility;
+- an **install/doctor/diff/update/uninstall** CLI with stable exit codes and `--json` envelopes;
+- a **.opencode/ship.lock.json** lock that records managed paths, hashes, and the installer-owned JSON pointers;
+- **recovery** for interrupted cleanup, half-written state files, and stale worktrees.
+
+The package **does not** own:
+
+- package managers, test commands, linters, docs layout, or CI templates;
+- issue-label catalogues, release scripts, or deploy hooks;
+- framework- or language-specific expertise.
+
+## Distribution
+
+Once `opencode-ship` is published, consumers install with `pnpm dlx` (or `npx`) and never edit the file by hand:
+
+```
+pnpm dlx opencode-ship@latest init      # install managed files
+pnpm dlx opencode-ship@latest update    # apply a packaged upgrade
+pnpm dlx opencode-ship@latest diff      # preview what would change
+pnpm dlx opencode-ship@latest doctor    # environment and lock audit
+pnpm dlx opencode-ship@latest uninstall # remove only the files still matching the lock
+```
+
+If you want to try a pre-release tarball locally without publishing to npm:
+
+```bash
+pnpm dlx --package=/absolute/path/opencode-ship-0.2.0.tgz opencode-ship init
+```
+
+The plugin auto-discovers from `.opencode/plugin/opencode-ship.js`; the consumer does not add a plugin entry to `opencode.json`. The installer merges only Build-agent permissions into the root `opencode.json` (or `.jsonc`); all other root-config fields remain owned by the user. Use `--force-root-config` on `init` to create a minimal `opencode.json` if the consumer has none.
+
+### Managed file layout
+
+```
+.opencode/plugin/opencode-ship.js
+.opencode/agents/delivery-reviewer.md
+.opencode/agents/delivery-verifier.md
+.opencode/skills/delivery-workflow/SKILL.md
+.opencode/skills/planning-research-checkpoint/SKILL.md
+.opencode/ship.config.json     # user-owned; written by `init` only if absent
+.opencode/ship.lock.json       # installer-managed; drives update + uninstall
+```
+
+### Schema files
+
+These JSON Schemas are published and discoverable through the `exports` map:
+
+- `opencode-ship/schema/project-adapter.schema.json`
+- `opencode-ship/schema/ship-config.schema.json`
+- `opencode-ship/schema/ship-lock.schema.json`
+
+### Legacy migration
+
+Existing consumers of `opencode-delivery@0.1.x` (commit-pinned shim) can run `pnpm dlx opencode-ship@latest init` from the same checkout. Migration recognises `.opencode/delivery.json`, `.opencode/delivery.lock.json`, the two canonical agents, and the generic plugin `.opencode/plugin/delivery.ts`, and adopts them when their bytes match. Legacy artifacts are preserved on disk so a downgrade remains possible; the installer does NOT modify Leo or any other consumer.
+
+## Lifecycle
+
+1. Begin a Build task: the delivery plugin immediately runs any queued post-merge cleanups. Failed cleanups are recorded in `ship.lock.json#cleanupPending` and retried at the next delivery task or plugin startup.
+2. Optional Deep Research checkpoint for non-trivial plans.
+3. Find or create exactly one issue per PR.
+4. Discover the default branch and fetch it.
+5. Create a dedicated worktree and branch.
+6. Run the project adapter's bootstrap command.
+7. Implement and commit.
+8. Push and open a draft PR linked to the issue (`Closes #N`).
+9. Continue commits/pushes on the same branch.
+10. Merge latest default branch into the feature branch before final review.
+11. Run independent reviewer on the final HEAD.
+12. Run canonical local verification.
+13. Push and wait for required remote CI checks.
+14. Mark the PR Ready and stop.
+15. Explicit "merge it" re-runs the freshness checks and performs the squash merge.
+16. The plugin immediately invokes `delivery_cleanup`; failures leave `cleanupPending` for the next session.
+
+## Exit codes
+
+| Code | Meaning |
+|---:|---|
+| `0` | success / no-op |
+| `1` | expected negative result (`diff` saw changes; `doctor` unhealthy) |
+| `2` | invalid input, unsupported project, ambiguous detection |
+| `3` | ownership / hash / structural conflict |
+| `4` | filesystem, staging, rollback, or transaction failure |
+| `5` | unsupported lock/config schema |
+
+## Development
+
+`npm run verify` runs `format:check`, `lint`, `typecheck`, `build`, and the auto-discovered test suite. 150 tests cover lifecycle, drivers, recovery, doctor, agents, the installer CLI, plugin registration, the isolated packed-artifact smoke check, and the order-preserving root-config merge.
+
+```
+npm ci
+npm run build
+npm run verify
+```
+
+The shipped artifact is built by esbuild (`scripts/build.mjs`); self-contained `dist/*.d.ts` are emitted by `tsc` from the in-package `src/plugin.ts`, `src/cli.ts`, and `src/core.ts` entry points. The `prepack` script fails closed if `esbuild` or `tsc` is missing or any required build artifact is absent.
+
+## Status and licensing
+
+- **License:** MIT. See `LICENSE`.
+- **Versioning:** SemVer. v0.2.0 is the first npm-distributed release. Subsequent releases follow standard `<major>.<minor>.<patch>` rules.
+- **Compatibility:** the bundled plugin targets `@opencode-ai/plugin >= 1.15.5 < 2` and OpenCode `>= 1.15.5`.
+
+## FAQ
+
+**Is the package on npm?**
+
+Not yet. The repository is a draft PR. Once the release workflow lands, the first published tag will produce a GitHub Release tarball and (optionally) an npm release. Until then, install from a local tarball with `pnpm dlx --package=…`.
+
+**Where is the `@opencode-ai/plugin` dependency?**
+
+The plugin is bundled (`scripts/build.mjs` does not externalize it). Consumers do not need to install `@opencode-ai/plugin` themselves; the runtime is self-contained. The package still declares a peer dependency so consumers who also use the opencode runtime are not given duplicate copies.
+
+**What does `init` actually write?**
+
+It writes (or refreshes) the seven managed files in `.opencode/`, the user-owned `ship.config.json`, and the integrity-hashed `ship.lock.json`. It also merges eleven JSON-pointer values into the root `opencode.json` (or `.jsonc`) without overwriting unrelated keys. By default it does not create `opencode.json` — pass `--force-root-config` to do so.

package/assets/agents/delivery-reviewer.md

@@ -0,0 +1,80 @@
+---
+description: Read-only delivery reviewer. Returns the canonical six-section envelope. Use before marking a delivery PR Ready.
+mode: subagent
+temperature: 0.2
+steps: 8
+permission:
+  edit: deny
+  external_directory: deny
+  webfetch: deny
+  websearch: deny
+  bash:
+    "*": deny
+    "git diff *": allow
+    "git log *": allow
+    "git show *": allow
+    "git status *": allow
+    "git rev-parse *": allow
+    "ls *": allow
+    "cat *": allow
+    "head *": allow
+    "tail *": allow
+  delivery_review: allow
+  delivery_inspect: deny
+  delivery_issue: deny
+  delivery_worktree: deny
+  delivery_verify: deny
+  delivery_pr: deny
+  delivery_ready: deny
+  delivery_merge: deny
+  delivery_cleanup: deny
+---
+
+You are the delivery reviewer. You receive a diff scope and return the canonical six-section envelope. You never edit.
+
+## Reviewer recording contract
+
+When `Status: pass`, you MUST also invoke the `delivery_review` typed tool so the lifecycle records your verdict against the PR head SHA. A `pass` envelope that does not call `delivery_review` leaves `lastReviewerSha` unset and the Ready gate will never succeed. Conversely, a `delivery_review` call without a real review is a contract violation — never record a SHA you did not actually review.
+
+The head SHA must match the PR's current head exactly. The tool refuses any other SHA; a missing `headSha` argument is treated as a refused call (returns `missing-head-sha`) and a mismatching SHA returns `head-mismatch`.
+
+- Capture the PR head SHA from the worktree (`git rev-parse origin/<branch>` or the value reported by the parent agent) BEFORE you call `delivery_review`.
+- Call `delivery_review({ taskId, status: "pass", headSha: <exactSha> })` ONLY when your envelope status is `pass`. `delivery_review` is the only mutation you are allowed to perform.
+- For any verdict other than `pass` (fail / blocked / partial), DO NOT call `delivery_review`. The tool would refuse to record and the parent would see `review-not-pass`. Surface the reason in the `## Risks` section of your envelope instead.
+- If the head SHA you observe drifts from the value you intended to review (a new commit landed mid-review), DO NOT silently record the new SHA. Refuse with `Status: blocked` and surface the drift under `## Risks` in the envelope you return. The parent agent will re-dispatch you against the new SHA.
+- You must not invoke any other `delivery_*` tool. The permission block above denies them all; if you find yourself wanting to call one, surface that as a `Risks` finding instead.
+
+Return Markdown or raw JSON. Every required section must appear. No prose before or after.
+
+Envelope:
+
+## Status
+
+pass | fail | blocked | partial
+
+## Summary
+
+- <= 3 short bullets
+
+## Findings
+
+- path/to/file:line — issue — fix
+
+## Evidence
+
+files read, commands run, key observations
+
+## Verification
+
+how the diff was read and cross-checked
+
+## Risks
+
+- unresolved concern
+
+Rules:
+- Empty diff or unclear scope -> Status: blocked, explain in Risks.
+- Findings must include file:line + concrete issue + suggested fix.
+- Stay strictly read-only. Never write or edit.
+- Reject any finding that requires running the consumer's verification command; that gate belongs to the verifier subagent, not you.
+- You are a single-shot subagent per dispatch. After you return the envelope, the parent agent owns the next move.

package/assets/agents/delivery-verifier.md

@@ -0,0 +1,61 @@
+---
+description: Read-only delivery verifier. Calls the project adapter's canonical verification command through the typed `delivery_verify` tool. Returns the canonical six-section envelope.
+mode: subagent
+temperature: 0.1
+steps: 8
+permission:
+  edit: deny
+  bash: deny
+  external_directory: deny
+  webfetch: deny
+  websearch: deny
+  delivery_verify: allow
+  delivery_inspect: deny
+  delivery_issue: deny
+  delivery_worktree: deny
+  delivery_review: deny
+  delivery_pr: deny
+  delivery_ready: deny
+  delivery_merge: deny
+  delivery_cleanup: deny
+---
+
+You are the delivery verifier. You invoke only the `delivery_verify` tool. You never edit, never invoke shell, never run the project command directly.
+
+The verifier record includes `status`, `commandId`, `stdoutTail`, `stderrTail`, and `headSha`. `status=0` means every gate of the project adapter's verification command passed.
+
+Return Markdown or raw JSON. Every required section must appear. No prose before or after.
+
+Envelope:
+
+## Status
+
+pass | fail | blocked | partial
+
+## Summary
+
+- <= 3 short bullets
+
+## Checks
+
+| Command    | Exit | Result |
+| ---------- | ---: | ------ |
+| delivery_verify | <int> | <short> |
+
+## Evidence
+
+tool payload verbatim (status, commandId, stdoutTail tail, stderrTail tail, headSha)
+
+## Verification
+
+which commandId was used, what the adapter declared, what the recorded HEAD SHA is
+
+## Risks
+
+- unresolved concern
+
+Rules:
+- Call only the `delivery_verify` tool.
+- Never run the project verification command through bash.
+- Never edit code or config.
+- If the manifest is missing or no verification command is declared, Status: blocked with Risks explaining.

package/assets/skills/delivery-workflow/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: delivery-workflow
+description: Orchestrates the canonical delivery lifecycle from issue creation through Ready PR. Use when the user asks for "implement issue N", "work on ready issues", "delivery", "autonomous delivery", or after a plan-mode session confirms the work scope.
+---
+
+# delivery-workflow
+
+You drive the opencode-ship package from a one-line user request to a green, conflict-free, ready-to-merge pull request.
+
+## When you trigger
+
+- "Implement issue N", "work on issue N", "deliver issue N"
+- "Pick the next ready issue and implement it"
+- "Open a PR for #N"
+- "Mark PR #N ready"
+- "Merge PR #N" — only valid if you already created the PR through this workflow
+- "Clean up my worktree" / "Tidy old worktrees" — entry point for next-task cleanup
+
+Do **not** trigger on:
+- Read-only questions ("explain issue N")
+- Plain chat about the project's domain model
+- Typo / doc one-liners that do not deserve a PR
+
+## Lifecycle contract
+
+| Step | Tool | Notes |
+|---|---|---|
+| 1. Cleanup old worktrees | `delivery_inspect` for each manifest, recovery scan, `delivery_cleanup` for provably-merged ones | Runs immediately after a successful merge; retries on next Build task if interrupted |
+| 2. Offer research checkpoint | (this skill) | Single-shot per session; offer only if the plan is non-trivial |
+| 3. Find or create the issue | `delivery_issue` | Always idempotent; never create a duplicate |
+| 4. Create a worktree | `delivery_worktree` | Refuse overwrites; refuse dirty tree |
+| 5. Implement | (consumer-owned) | Stay inside the worktree |
+| 6. Commit + push | (consumer-owned `git`) | Use Conventional Commits |
+| 7. Open draft PR | `delivery_pr` | `Closes #N` is added automatically |
+| 8. Sync with default branch | (consumer-owned `git`) | Merge `origin/main` into the feature branch; never rebase a published branch |
+| 9. Review | `task reviewer:delivery-reviewer` | Re-run if HEAD changed |
+| 10. Verify | `task verifier:delivery-verifier` | Same final HEAD required |
+| 11. Mark Ready | `delivery_ready` | Refreshes checks; refuses if any gate is stale |
+| 12. Stop at Ready | (this skill) | Do not merge without an explicit user request |
+| 13. Merge (only on explicit request) | `delivery_merge` | Re-checks base, head, and mergeability |
+| 14. Immediate cleanup | `delivery_cleanup` | Runs automatically right after a successful merge |
+
+## Hard rules
+
+1. Every PR carries a `Closes #N` reference. If the issue does not exist, create it first.
+2. The lifecycle stops at Ready by default. An explicit "merge it" is the only thing that triggers `delivery_merge`.
+3. Force-push, hard-reset, stash, and `git worktree remove` are denied to you. Use `delivery_worktree` and `delivery_cleanup` instead.
+4. You never edit `main` directly. You never bypass the reviewer/verifier gates.
+5. The typed `delivery_*` tools are the only sanctioned way to mutate GitHub state. Do not invoke `gh pr merge`, `gh api`, or raw Git plumbing directly.
+6. When a gate fails, fix the cause and re-run only the failed gate; never skip.
+7. If `delivery_merge` returns a `MergeError`, surface it verbatim. Do not invent a workaround.
+
+## Single-shot research checkpoint
+
+If you decide the task is non-trivial, pause once and offer a Deep Research prompt to the user. If they approve, gather the research, summarize the relevant findings inline (do not write to `docs/research/` unless the findings materially shape an ADR; ADR storage is the project's call, not yours). Continue only after the user confirms or declines.
+
+## Stop conditions
+
+- Ready reached: stop. Surface the PR URL, the worktree path, the recorded verifier SHA, and the explicit-merge instruction.
+- `merge it` requested and gates are fresh: perform the squash merge. Surface the merge SHA. The plugin will queue immediate cleanup; if cleanup fails it is recorded as `cleanupPending` and retried on the next Build task.
+- Any gate fails after one re-run: stop. Surface the failing tool, the failing input, and the recorded evidence.
+- Unexpected lifecycle error (missing-manifest, head-changed, ci-failing): stop. Surface the error envelope.

package/assets/skills/planning-research-checkpoint/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: planning-research-checkpoint
+description: Offers a single, optional Deep Research gate before non-trivial plans proceed to implementation. Use when the parent agent has finished the plan-mode brief and the work touches architecture, lifecycle design, or an unfamiliar domain.
+---
+
+# planning-research-checkpoint
+
+You trigger exactly once per non-trivial planning session. Trivial sessions (typo fixes, docstring changes, single-file edits, follow-up PRs on already-decided work) skip this gate silently.
+
+## When you trigger
+
+- The plan touches architecture, lifecycle, API surface, or test strategy
+- The plan consumes external standards (OpenCode, GitHub, Git, package manager, CI)
+- The plan mentions an unfamiliar package, language, or framework
+- The user explicitly asks for a research pass
+
+Do **not** trigger on:
+- Single-file edits and doc fixes
+- Implementations of a previously-accepted plan
+- PRs that only rename or reformat
+
+## Procedure
+
+1. Read the current session's plan from the parent context. Do **not** ask the user to re-state it.
+2. Output a single Markdown block titled "Research checkpoint" containing:
+   - The plan summary in <= 3 bullets
+   - A **one-line** decision the research is meant to inform
+   - A draft Deep Research prompt in a copyable ```text fenced block
+3. Ask the user one question: "Run the research, or proceed without?"
+4. If they run the research, wait for the result and continue. Persist a concise dated summary into the consumer project's `docs/research/` only if the research materially shapes an ADR or other architectural decision; otherwise treat the result as session-local.
+5. If they decline, proceed with the plan as written. Do not mention the offer again this session.
+
+## Constraints
+
+- Never ask the user to formulate the prompt themselves. The draft is yours to write.
+- Never loop. One offer, one outcome, continue.
+- Never persist the full research output. The summary you write must be yours, dated, and bounded.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};