opencode-ship 0.10.0 → 1.1.0-rc.1

package/CHANGELOG.md

@@ -2,15 +2,107 @@
 
 All notable changes to `opencode-ship` are recorded here.
 
+## 1.1.0-rc.1 — One-liner install, easy setup, skill discovery
+
+### Breaking changes
+
+- **The `core` profile is removed.** `init --profile core` now
+  fails with exit 2 and a clear message. Every consumer on the
+  `1.1.x` line installs the engineering profile, which is the
+  superset of the previous core surface. Existing locks declaring
+  `manager.profile: "core"` are upgraded to `engineering` on the
+  next `init` or `update`. There is no migration of bytes — the
+  engineering catalog is a strict superset of the core catalog.
+
+### Added
+
+- **One-liner install.** `pnpm dlx opencode-ship@latest init` works
+  without any flags. The installer writes the full engineering
+  catalog and a `ship.config.json` with an empty `workflow.models`
+  block. The setup-pending marker
+  (`.opencode/ship.setup-pending.json`) is written so the
+  controller knows to route the first `ship-deliver` through the
+  setup skill.
+- **One-shot `setup-ship-workflow` skill.** Run via
+  `/setup-ship-workflow` in chat, or automatically by `ship-deliver`
+  when the setup-pending marker is present. The skill walks the
+  user through:
+  1. issue tracker (GitHub / GitLab / local markdown / other);
+  2. triage labels (default is `needs-triage`, `needs-info`,
+     `ready-for-agent`, `ready-for-human`, `wontfix`);
+  3. domain docs (single-context default, multi-context for
+     monorepos);
+  4. AI model roles (planner / builder / finalReviewer) with
+     `openai/gpt-5.6-sol` and `minimax/MiniMax-M3` defaults;
+  5. provider auth probe (`opencode providers list`);
+  6. permissions sanity (`opencode-ship doctor`);
+  7. AGENTS.md / CLAUDE.md block.
+  Re-running the skill is safe and idempotent.
+- **Skill discovery** (`assets/skills/skill-discovery/SKILL.md` and
+  `src/tools/skill-discovery.js`). The controller runs
+  `npx skills find <query>` before planning; trusted-source skills
+  (default: `vercel-labs`, `anthropics`, `obra`, `mattpocock`,
+  `ComposioHQ`) auto-install project-locally. Non-trusted
+  candidates are presented to the user. Allowlist and
+  `minInstalls` threshold are configurable via
+  `ship.config.json#skillDiscovery`.
+- **Ask-first deep-research gate.** The
+  `planning-research-checkpoint` skill now asks the user one
+  question before generating any research prompt. Default path
+  is "no research, continue with the plan as written", saving
+  tokens. The research prompt is only generated on explicit
+  consent.
+
+### Changed
+
+- `init` no longer requires `--planner-model` / `--builder-model`
+  / `--final-reviewer-model` flags. The flags remain available as
+  overrides for users who know exactly which models they want.
+- `ship.config.json#workflow.models` is now optional at install
+  time. The ship controller refuses to dispatch
+  (`ship-deliver`) until all three role ids are populated, or
+  routes through `/setup-ship-workflow` automatically.
+- `ship.config.json#profile` is the engineering profile. The CLI
+  still accepts `--profile engineering` (no-op) but rejects
+  `--profile core` with a helpful error.
+- The release qualification workflow now publishes under the
+  `candidate` dist-tag for 1.1.x and `next` for 0.10.x. 1.1.0 is
+  promoted to `latest` after the formal S5 dogfood passes (or after
+  a maintainer-approved exception is recorded in issue #37).
+- README, RELEASING, and this changelog are rewritten for the
+  one-liner install + setup-skill flow.
+
+### Fixed
+
+- WP0.1: the duplicate skill frontmatter `name: setup-matt-pocock-skills`
+  (set on both `setup-engineering-workflow` and
+  `engineering-workflow` SKILL.md files) is fixed; the
+  setup skill is now `setup-ship-workflow` and the workflow
+  reference is `engineering-workflow`.
+- The installer previously refused to commit if
+  `workflow.models` was incomplete. The new flow accepts the
+  empty-models state and relies on the setup skill to populate
+  them. Existing 1.0.x locks continue to work.
+
 ## Unreleased
 
-- The `release/0.10.0` branch is the live release branch carrying
-  the complete production runtime for the planned `0.10.0` and
-  `1.0.0` releases. Release candidates are published under the
-  `next` npm dist-tag. No `0.10.0` or `1.0.0` has been published;
-  consumers should keep using `opencode-ship@0.9.0`. The local
-  `v0.10.0` and `v1.0.0` tags are placeholders only and must not
-  be pushed.
+- `1.0.0` is on `npm dist-tag latest`; `0.10.0` stable is on
+  `npm dist-tag next`. The `release/0.10.0` branch is the live
+  release branch for both releases; the `1.0.0` tag was promoted
+  from the same runtime source as `0.10.0` so the
+  version-independent `runtimeSourceSha256` digest is preserved
+  across both releases (CI-reported digest
+  c750d709dd68dc3663eef3890d5b9d8f8a1ec3b14eae011382e151874cb50c89).
+- The S5 real 14-step dogfood was skipped because the OpenAI
+  OAuth credential in `~/.local/share/opencode/auth.json`
+  expired (48 days ago) and the opencode CLI 1.18.15 cannot
+  dispatch to `openai/gpt-5.6-sol` or `minimax/MiniMax-M3`.
+  The dogfood fixture is preserved at
+  `https://github.com/Viktorxyz/opencode-ship-dogfood` for
+  re-execution once a valid provider credential is supplied.
+  The npm CLI verification (`npm install opencode-ship@latest`
+  + `node_modules/.bin/opencode-ship --version`) prints
+  `1.0.0`, confirming the published artefact is reachable.
 - See `docs/release/1.0.0-execution-plan.md` for the authoritative
   execution plan and issue #37 for the bounded evidence ledger.
 

package/README.md

@@ -2,17 +2,48 @@
 
 > 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.9.0 is the current `npm latest`. The `release/0.10.0` branch is the live release branch carrying the complete production runtime for the upcoming `0.10.0` and `1.0.0` releases: 24 typed tools (9 existing delivery tools + 7 control-plane tools + 8 workflow tools), the deterministic controller, the contract-version-2 envelope, the GitHub operation store, the immutable plan + run + commit ledgers, the same-HEAD gate, the bounded compaction block, the per-run resume lock, the fail-closed engineering profile, the version-independent `runtimeSourceSha256` digest, the ten-job release qualification pipeline with a real OpenCode discovery smoke, and the prerelease-aware GitHub release metadata. Release candidates are published under `npm dist-tag next`; stable `0.10.0` and `1.0.0` remain unpublished until their gates pass. The previously-mentioned `release/1.0-completion` branch is not the live release branch and is not referenced by this README or `RELEASING.md`. See `docs/release/1.0.0-execution-plan.md` for the authoritative execution plan and issue #37 for the bounded evidence ledger.
+> **Status:** `1.1.0-rc.1` is the next release. From 1.1.0 forward, the engineering profile is the only supported profile (`core` is removed). `init` works as a one-liner: `pnpm dlx opencode-ship@latest init`. The user fills in the AI model roles through a one-shot `setup-ship-workflow` skill that runs after the install. Skill discovery is integrated; trusted-source skills auto-install locally to the repo. The deep-research gate now asks first and only generates a prompt on explicit consent. See `docs/release/1.1.0-execution-plan.md` for the authoritative plan.
 >
-> Consumers should keep using `opencode-ship@0.9.0` until `1.0.0` is promoted to `npm dist-tag latest`.
+> Consumers should use `opencode-ship@1.1.0` (or `opencode-ship@latest`). The previous `1.0.0` line remains on `npm dist-tag latest` until 1.1.0 promotion; `0.10.0` stable is on `npm dist-tag next`.
 
 ---
 
+## Quick start (1.1.0+)
+
+```sh
+# 1. Install managed files. No flags required.
+pnpm dlx opencode-ship@latest init
+
+# 2. Restart OpenCode in this repo.
+
+# 3. In chat, run the one-shot setup skill:
+/setup-ship-workflow
+
+# 4. The skill asks for:
+#    - issue tracker (GitHub / GitLab / local / other)
+#    - triage labels (defaults are fine)
+#    - domain docs (single-context default)
+#    - AI model roles (planner / builder / finalReviewer)
+#    - AGENTS.md / CLAUDE.md block
+
+# 5. Start work. The controller drives everything.
+Ship issue 1
+# or
+Ship issue 1   (after opening an issue with a real description)
+```
+
+The `init` command succeeds without any model flags. The setup skill writes the per-repo configuration. The controller refuses to dispatch until the setup is complete.
+
 ## What this package is
 
-`opencode-ship` is the npm-distributed successor to `opencode-delivery`. It bundles:
+`opencode-ship` is the npm-distributed successor to `opencode-delivery`. From 1.1.0 it bundles:
 
-- a **nine-tool OpenCode plugin** that auto-loads from `.opencode/plugins/opencode-ship.js`;
+- a **24-tool OpenCode plugin** that auto-loads from `.opencode/plugins/opencode-ship.js`;
+- **8 ship agents** (controller, planner, builder, task-reviewer, final-standards-reviewer, final-spec-reviewer) plus the two legacy delivery agents (reviewer, verifier);
+- **3 ship commands** (`ship-deliver`, `ship-resume`, `ship-status`) plus the new one-shot `setup-ship-workflow`;
+- **26 skills** (delivery-workflow, planning-research-checkpoint, the Matt + Superpowers engineering catalog, the new setup-ship-workflow and skill-discovery);
+- **setup-ship-workflow skill** that walks the user through tracker / labels / docs / model roles;
+- **skill-discovery** that auto-installs trusted-source skills from the open agent skills ecosystem.
 - 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`);

package/THIRD_PARTY_NOTICES.md

@@ -1,6 +1,6 @@
 # Third-Party Notices
 
-`opencode-ship@0.10.0` ships the complete Matt Pocock and Superpowers
+`opencode-ship@1.1.0-rc.1` ships the complete Matt Pocock and Superpowers
 methodology under the MIT license, plus the Ship-owned installer,
 plugin, agents, and skills. The complete immutable pin list is in
 `vendor/sources.json`; the upstream snapshots are under
@@ -34,12 +34,6 @@ helpers shipped verbatim from upstream under MIT).
 | engineering | `assets/skills/domain-modeling/ADR-FORMAT.md` | `mattpocock/skills` | MIT (see `vendor/mattpocock/LICENSE`) | unchanged |
 | engineering | `assets/skills/domain-modeling/CONTEXT-FORMAT.md` | `mattpocock/skills` | MIT (see `vendor/mattpocock/LICENSE`) | unchanged |
 | engineering | `assets/skills/domain-modeling/SKILL.md` | `mattpocock/skills` | MIT (see `vendor/mattpocock/LICENSE`) | adapted |
-| engineering | `assets/skills/engineering-workflow/domain.md` | `mattpocock/skills` | MIT (see `vendor/mattpocock/LICENSE`) | unchanged |
-| engineering | `assets/skills/engineering-workflow/issue-tracker-github.md` | `mattpocock/skills` | MIT (see `vendor/mattpocock/LICENSE`) | unchanged |
-| engineering | `assets/skills/engineering-workflow/issue-tracker-gitlab.md` | `mattpocock/skills` | MIT (see `vendor/mattpocock/LICENSE`) | unchanged |
-| engineering | `assets/skills/engineering-workflow/issue-tracker-local.md` | `mattpocock/skills` | MIT (see `vendor/mattpocock/LICENSE`) | unchanged |
-| engineering | `assets/skills/engineering-workflow/SKILL.md` | `mattpocock/skills` | MIT (see `vendor/mattpocock/LICENSE`) | adapted |
-| engineering | `assets/skills/engineering-workflow/triage-labels.md` | `mattpocock/skills` | MIT (see `vendor/mattpocock/LICENSE`) | unchanged |
 | engineering | `assets/skills/executing-plans/SKILL.md` | `obra/superpowers` | MIT (see `vendor/superpowers/LICENSE`) | adapted |
 | engineering | `assets/skills/grill-with-docs/SKILL.md` | `mattpocock/skills` | MIT (see `vendor/mattpocock/LICENSE`) | adapted |
 | engineering | `assets/skills/grilling/SKILL.md` | `mattpocock/skills` | MIT (see `vendor/mattpocock/LICENSE`) | adapted |
@@ -51,12 +45,6 @@ helpers shipped verbatim from upstream under MIT).
 | engineering | `assets/skills/requesting-code-review/code-reviewer.md` | `obra/superpowers` | MIT (see `vendor/superpowers/LICENSE`) | unchanged |
 | engineering | `assets/skills/requesting-code-review/SKILL.md` | `obra/superpowers` | MIT (see `vendor/superpowers/LICENSE`) | adapted |
 | engineering | `assets/skills/research/SKILL.md` | `mattpocock/skills` | MIT (see `vendor/mattpocock/LICENSE`) | adapted |
-| engineering | `assets/skills/setup-engineering-workflow/domain.md` | `mattpocock/skills` | MIT (see `vendor/mattpocock/LICENSE`) | unchanged |
-| engineering | `assets/skills/setup-engineering-workflow/issue-tracker-github.md` | `mattpocock/skills` | MIT (see `vendor/mattpocock/LICENSE`) | unchanged |
-| engineering | `assets/skills/setup-engineering-workflow/issue-tracker-gitlab.md` | `mattpocock/skills` | MIT (see `vendor/mattpocock/LICENSE`) | unchanged |
-| engineering | `assets/skills/setup-engineering-workflow/issue-tracker-local.md` | `mattpocock/skills` | MIT (see `vendor/mattpocock/LICENSE`) | unchanged |
-| engineering | `assets/skills/setup-engineering-workflow/SKILL.md` | `mattpocock/skills` | MIT (see `vendor/mattpocock/LICENSE`) | adapted |
-| engineering | `assets/skills/setup-engineering-workflow/triage-labels.md` | `mattpocock/skills` | MIT (see `vendor/mattpocock/LICENSE`) | unchanged |
 | engineering | `assets/skills/subagent-driven-development/implementer-prompt.md` | `obra/superpowers` | MIT (see `vendor/superpowers/LICENSE`) | unchanged |
 | engineering | `assets/skills/subagent-driven-development/re-review-prompt.md` | `obra/superpowers` | MIT (see `vendor/superpowers/LICENSE`) | unchanged |
 | engineering | `assets/skills/subagent-driven-development/SKILL.md` | `obra/superpowers` | MIT (see `vendor/superpowers/LICENSE`) | adapted |

package/assets/agents/ship-controller.md

@@ -34,6 +34,8 @@ permission:
     "git worktree remove *": deny
     "git worktree prune *": deny
     "gh *": deny
+    "npx skills find *": allow
+    "npx skills add *": allow
     "node *": allow
     "npm *": allow
     "pnpm *": allow
@@ -77,6 +79,8 @@ permission:
   ship_resume: allow
   ship_status: allow
   ship_deliver: allow
+  ship_skill_discover: allow
+  ship_skill_install: allow
 ---
 
 # ship-controller

package/assets/commands/setup-ship-workflow.md

@@ -0,0 +1,173 @@
+---
+description: Configure the opencode-ship workflow for this repo: issue tracker, triage labels, domain docs, and AI model roles. Run once after `init` with /setup-ship-workflow.
+---
+
+# Setup Ship Workflow
+
+First-run setup for `opencode-ship@1.1`. Run this exactly once after `init` and before any `ship-deliver`. It is prompt-driven, idempotent, and refuses to return until every step is committed or explicitly skipped.
+
+## When you trigger
+
+- The user runs `/setup-ship-workflow` or types "set up ship" / "continue ship setup".
+- The installer creates `.opencode/ship.setup-pending.json` after `init`; the controller also routes `ship-deliver` here until this skill has cleared the marker.
+
+Do **not** trigger on a normal planning or delivery request.
+
+## Process
+
+Take the sections in order. Lead every question with a recommended default so the user can accept in one word. Skip a section only when exploration already settled it.
+
+### 1. Explore
+
+```bash
+git remote -v
+git status --short
+ls -la AGENTS.md CLAUDE.md docs/ .opencode/ 2>/dev/null || true
+cat .opencode/opencode.json 2>/dev/null || true
+cat .opencode/ship.config.json 2>/dev/null || true
+cat .opencode/ship.lock.json 2>/dev/null || true
+cat .opencode/ship.setup-pending.json 2>/dev/null || true
+opencode providers list 2>/dev/null || true
+```
+
+Also check:
+
+- is `.opencode/ship.setup-pending.json` present? (it makes this run mandatory)
+- is the `triage` skill installed? (decides whether Section B runs)
+- monorepo signals (`pnpm-workspace.yaml`, `packages/*`)
+
+### 2. Section A — Issue tracker
+
+Default: GitHub (the most common case). If `git remote` points at GitLab, propose GitLab. Otherwise offer:
+
+- GitHub (uses `gh`)
+- GitLab (uses `glab`)
+- Local markdown (writes under `.scratch/<feature>/`)
+- Other (Jira, Linear, etc.) — describe in one paragraph
+
+Write the choice to `docs/agents/issue-tracker.md`. Use the seed template in `assets/skills/setup-engineering-workflow/issue-tracker-<choice>.md` as the starting point.
+
+### 3. Section B — Triage labels
+
+Only if the `triage` skill is installed. Ask one question:
+
+> Keep the default triage labels? (recommended: yes)
+> Defaults: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`.
+
+On **no**, capture the user's overrides so `triage` reuses existing labels instead of creating duplicates.
+
+Write `docs/agents/triage-labels.md`.
+
+### 4. Section C — Domain docs
+
+Default: **single-context** — one `CONTEXT.md` + `docs/adr/` at the repo root. Skip the question unless monorepo signals were found.
+
+Write `docs/agents/domain.md`.
+
+### 5. Section D — AI model roles
+
+Three questions, one at a time. Default to `openai/gpt-5.6-sol` and `minimax/MiniMax-M3`; offer alternative families below.
+
+| Role | Default | Suggestion |
+|---|---|---|
+| planner | `openai/gpt-5.6-sol` | strong model for plan writing |
+| builder | `minimax/MiniMax-M3` | cheap/fast model for code |
+| finalReviewer | `openai/gpt-5.6-sol` | strong model for final Standards + Spec review |
+
+Alternatives to mention if the user has no OpenAI/MiniMax:
+
+- Anthropic: `anthropic/claude-opus-4.1`, `anthropic/claude-sonnet-4.5`
+- Google: `google/gemini-2.5-pro`, `google/gemini-2.5-flash`
+- Or any `<provider>/<model>` string the user has credentials for
+
+After the user answers, **update `.opencode/ship.config.json`** so it looks like:
+
+```json
+{
+  "schemaVersion": 2,
+  "profile": "engineering",
+  "project": { ... },
+  "delivery": { ... },
+  "workflow": {
+    "models": {
+      "planner": "<answer>",
+      "builder": "<answer>",
+      "finalReviewer": "<answer>"
+    },
+    "approval": { "mirrorToIssue": true, "maxFailedRounds": 3 }
+  }
+}
+```
+
+Then run `opencode-ship update` to write the change with full transactional coverage.
+
+### 6. Section E — Provider auth probe
+
+```bash
+opencode providers list
+```
+
+If the planner/builder/finalReviewer names are missing credentials, surface a warning and tell the user how to log in:
+
+```bash
+opencode providers login openai
+opencode providers login minimax
+```
+
+Do not invent credentials. Do not retry.
+
+### 7. Section F — Permissions sanity
+
+Run `opencode-ship doctor`. If any pointer is missing, prompt the user to run:
+
+```bash
+opencode-ship update --force-root-config
+```
+
+Do not auto-rewrite root configs without consent.
+
+### 8. Section G — AGENTS.md / CLAUDE.md
+
+Pick the file to edit:
+
+- If `CLAUDE.md` exists, edit it.
+- Else if `AGENTS.md` exists, edit it.
+- If neither, ask the user to pick one — never create both.
+
+If an `## Ship workflow` block exists, update in place. Otherwise append:
+
+```markdown
+## Ship workflow
+
+This repo uses opencode-ship. Read `.opencode/ship.config.json` for the active model roles and approval policy. Issues live in [tracker]. See `docs/agents/issue-tracker.md`. Triage labels are documented in `docs/agents/triage-labels.md`.
+
+For a single-issue delivery, the user invokes `/setup-ship-workflow` once, then `ship-deliver <issue-number>` (or types "Ship issue N"). The controller dispatches the planner, builder, and reviewers; no further user action is required until Ready.
+```
+
+Include the `### Triage labels` sub-block only when the `triage` skill is installed.
+
+### 9. Done
+
+- Delete `.opencode/ship.setup-pending.json`.
+- Print the next-step block below.
+- Tell the user they can edit `docs/agents/*.md` directly; re-running this skill is only necessary to switch trackers or re-configure models.
+
+## Next steps (always print)
+
+```text
+Setup complete.
+
+Next:
+1. Restart OpenCode in this repo (if you haven't already).
+2. Try: Ship issue 1    (or any issue number)
+3. The controller will: plan -> ask approve -> implement -> review -> ready -> wait for "merge it"
+```
+
+## Hard rules
+
+- One question per turn. Never batch.
+- Re-run safe: skip sections already settled by existing config or docs.
+- Never edit the same `docs/agents/*.md` twice in one run.
+- Never silently overwrite a user-owned value in `ship.config.json`; always show the diff first.
+- Never tell the user to "merge it" automatically. The merge step is the only autonomy break.
+- Never hide step failures. If a write fails, surface the error and stop.

package/assets/commands/ship-deliver.md

@@ -1,30 +1,83 @@
 ---
-description: Start a delivery workflow. Triage, grill, spec, and execute the parent issue end-to-end with the same-HEAD Ready and merge gates.
+description: Start a delivery workflow. First checks the setup-pending marker, runs skill discovery, then triggers planning with the same-HEAD Ready and merge gates.
 ---
 
 # ship-deliver
 
 `ship-deliver <issue-number>` is the canonical entry point
-for a delivery workflow. The controller:
-
-1. Resolves the parent issue, the strong planner model, and
-   the durable workflow state.
-2. Dispatches the strong planner child session to produce a
-   PlanV2 contract.
-3. Seeks explicit user approval through `ship_plan_approve`.
-4. Mirrors the plan to the issue.
-5. Drives each task through the cheap builder, the task
-   reviewer (Spec + Quality), and the controller commit
-   loop.
-6. On the final task, dispatches the parallel Standards and
-   Spec final reviewers against one merge-base-to-HEAD
-   package, runs the verifier in an independent session, and
-   binds the Ready gate to the same HEAD.
-7. Stops at Ready and waits for a separate explicit
-   `merge it` request from the user.
-
-The command never force-pushes, never hard-resets, never
-stashes, and never deletes a worktree before the merge
-lands. The strong planner never edits source files; the
-cheap builder cannot commit, push, mutate GitHub, mark
-Ready, merge, clean worktrees, or record reviews.
+for a delivery workflow.
+
+## Procedure
+
+### 0. Setup gate (mandatory)
+
+Before any plan or task dispatch, check for the setup-pending marker:
+
+```bash
+test -f .opencode/ship.setup-pending.json && echo SETUP_PENDING
+```
+
+If the marker is present:
+
+- Read `.opencode/opencode.json` and `.opencode/ship.config.json` to confirm what is missing.
+- Run the `setup-ship-workflow` skill in chat. Do not silently fill the gaps. Do not proceed to plan.
+- After the skill completes and the user has filled in the model roles (and optionally the issue-tracker / triage / domain docs), the skill removes the marker. Re-run `ship-deliver <n>`.
+
+If the marker is absent, continue.
+
+### 1. Skill discovery (mandatory)
+
+Before dispatching the planner, run the `skill-discovery` skill:
+
+```text
+npx skills find "<query from issue/plan>"
+```
+
+Auto-install trusted sources (see `ship.config.json#skillDiscovery.trustedOwners`); present non-trusted candidates to the user. Limit to 5 auto-installs per dispatch.
+
+### 2. Plan + approve
+
+1. Resolve or restore workflow state from `<git-common-dir>/opencode-ship/`.
+2. Dispatch the strong planner (`openai/gpt-5.6-sol` by default) to produce a PlanV2 contract.
+3. Wait for `ship_plan_approve` from the user. Never auto-approve.
+4. Mirror the plan to the issue.
+
+### 3. Execute
+
+Drive each task through:
+
+- cheap builder (`minimax/MiniMax-M3` by default) — implement + report
+- task reviewer (Spec + Quality) — verdict
+- controller commit + push
+- same-HEAD gate: Standards + Spec final reviews, verifier, required CI
+
+### 4. Ready
+
+Stop at Ready. Surface PR URL, worktree path, verifier SHA, and the explicit-merge instruction.
+
+### 5. Merge
+
+On explicit `merge it`: fresh gate recheck, squash merge, cleanup, core downgrade, uninstall, root-config byte restoration.
+
+## Hard rules
+
+- **Never skip the setup gate.** If the marker is present, refuse to plan.
+- **Never skip skill discovery.** The discovery is part of the autonomous-uplift contract.
+- **Never auto-approve a plan.** The user always reviews the plan.
+- **Never mark Ready or merge without a passing Standards review, a passing Spec review, a passing verifier run, and a passing required-CI check, all bound to one HEAD.**
+- **Never force-push, hard-reset, stash, or `git worktree remove`.**
+- **Never use `gh api` or raw shell on GitHub.** Use the typed `delivery_*` tools.
+
+## Single-shot research checkpoint
+
+If you decide the task is non-trivial, pause once and **ask the user** whether to run Deep Research before generating any prompt. The default save-tokens path is "no research, continue with the plan as written". Only on explicit "yes" do you generate a draft Deep Research prompt and run the research; summarize the relevant findings inline and continue. 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.
+
+The full procedure lives in the `planning-research-checkpoint` skill. Do not duplicate the prompt-generation logic here — just trigger the skill and respect its ask-first policy.
+
+## Stop conditions
+
+- Setup pending: stop, run setup, then re-dispatch.
+- 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/delivery-workflow/SKILL.md

@@ -52,7 +52,9 @@ Do **not** trigger on:
 
 ## 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.
+If you decide the task is non-trivial, pause once and **ask the user** whether to run Deep Research before generating any prompt. The default save-tokens path is "no research, continue with the plan as written". Only on explicit "yes" do you generate a draft Deep Research prompt and run the research; summarize the relevant findings inline and continue. 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.
+
+The full procedure lives in the `planning-research-checkpoint` skill. Do not duplicate the prompt-generation logic here — just trigger the skill and respect its ask-first policy.
 
 ## Stop conditions
 

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

@@ -1,10 +1,11 @@
 ---
-name: setup-matt-pocock-skills
-description: Configure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
-disable-model-invocation: true
+name: engineering-workflow
+description: Reference workflow for the engineering lifecycle - brainstorm, spec, plan, implement, review, verify. Use when no more specific skill applies; everything below is opt-in.
 ---
 
-# Setup Matt Pocock's Skills
+# Engineering Workflow Guide
+
+Reference overview of the engineering lifecycle in `opencode-ship@1.1`. Skim this when you are unsure which of the more specific skills applies.
 
 Scaffold the per-repo configuration that the engineering skills assume:
 

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Offers a single, optional Deep Research gate before non-trivial plans proceed to implementation. Triggers on the work being non-trivial; never generates a research prompt without explicit user consent. 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
@@ -15,6 +15,7 @@ You trigger exactly once per non-trivial planning session. Trivial sessions (typ
 - 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
@@ -22,16 +23,19 @@ Do **not** trigger on:
 ## 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.
+2. **Ask the user one question first** — do not generate a research prompt until they consent. Use exactly this wording:
+   > This looks non-trivial. Run Deep Research before continuing? **[yes / no]**
+3. If the answer is **no**:
+   - Proceed with the plan as written.
+   - Do not mention the offer again this session.
+   - Do not generate any research prompt — the explicit goal is to save the user's tokens.
+4. If the answer is **yes**:
+   - 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
+   - Ask the user one question: "Run the research, or proceed without?"
+   - Wait for the result. 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. Never ask the user to formulate the prompt themselves. The draft is yours to write when consent is given.
+6. Never loop. One offer, one outcome, continue.
+7. Never persist the full research output. The summary you write must be yours, dated, and bounded.