opencode-ship 1.0.0 → 1.1.0

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

@@ -1,125 +1,174 @@
 ---
-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.
+name: setup-ship-workflow
+description: First-run setup of opencode-ship. Walks the user through issue tracker, triage labels, domain docs, and AI model roles. Run once after `init` with /setup-ship-workflow.
 disable-model-invocation: true
 ---
 
-# Setup Matt Pocock's Skills
+# Setup Ship Workflow
 
-Scaffold the per-repo configuration that the engineering skills assume:
+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.
 
-- **Issue tracker** — where issues live (GitHub by default; local markdown is also supported out of the box)
-- **Triage labels** — the strings used for the five canonical triage roles
-- **Domain docs** — where `CONTEXT.md` and ADRs live, and the consumer rules for reading them
+## When you trigger
 
-This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.
+- 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
 
-Look at the current repo to understand its starting state. Read whatever exists; don't assume:
+```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
+opencode providers list 2>/dev/null || true
+```
 
-- `git remote -v` and `.git/config` — is this a GitHub repo? Which one?
-- `AGENTS.md` and `CLAUDE.md` at the repo root — does either exist? Is there already an `## Agent skills` section in either?
-- `CONTEXT.md` and `CONTEXT-MAP.md` at the repo root
-- `docs/adr/` and any `src/*/docs/adr/` directories
-- `docs/agents/` — does this skill's prior output already exist?
-- `.scratch/` — sign that a local-markdown issue tracker convention is already in use
-- Is the `triage` skill installed? (a `triage` skill folder alongside this one, or `triage` in your available skills.) This decides whether Section B runs at all.
-- Monorepo signals — a `pnpm-workspace.yaml`, a `workspaces` field in `package.json`, or a populated `packages/*` with its own `src/`. Present only in a genuinely large multi-package repo; their absence means single-context, which is almost every repo.
+Also check:
 
-### 2. Present findings and ask
+- 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/*`)
 
-Summarise what's present and what's missing. Then take the sections in order — one section, one answer, then the next.
+### 2. Section A — Issue tracker
 
-Lead each section with the recommended answer so the user can accept it in a word. Give a one-line explainer only when the choice genuinely branches; skip the section entirely when exploration already settled it (Section B when `triage` isn't installed, Section C when there's no monorepo).
+Default: GitHub (the most common case). If `git remote` points at GitLab, propose GitLab. Otherwise offer:
 
-**Section A — Issue tracker.**
+- GitHub (uses `gh`)
+- GitLab (uses `glab`)
+- Local markdown (writes under `.scratch/<feature>/`)
+- Other (Jira, Linear, etc.) — describe in one paragraph
 
-> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-tickets`, `triage`, `to-spec`, and `qa` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
+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.
 
-Default posture: these skills were designed for GitHub. If a `git remote` points at GitHub, propose that. If a `git remote` points at GitLab (`gitlab.com` or a self-hosted host), propose GitLab. Otherwise (or if the user prefers), offer:
+### 3. Section B — Triage labels
 
-- **GitHub** — issues live in the repo's GitHub Issues (uses the `gh` CLI)
-- **GitLab** — issues live in the repo's GitLab Issues (uses the [`glab`](https://gitlab.com/gitlab-org/cli) CLI)
-- **Local markdown** — issues live as files under `.scratch/<feature>/` in this repo (good for solo projects or repos without a remote)
-- **Other** (Jira, Linear, etc.) — ask the user to describe the workflow in one paragraph; the skill will record it as freeform prose
+Only if the `triage` skill is installed. Ask one question:
 
-Record the choice in `docs/agents/issue-tracker.md`. The GitHub and GitLab templates carry a "PRs as a request surface" flag, defaulted **off** — leave it off and don't raise it; a user who wants external PRs in the triage queue can flip the flag in the file later.
+> Keep the default triage labels? (recommended: yes)
+> Defaults: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`.
 
-**Section B — Triage label vocabulary.** Skip this section entirely if the `triage` skill isn't installed (exploration told you) — an uninstalled skill needs no labels.
+On **no**, capture the user's overrides so `triage` reuses existing labels instead of creating duplicates.
 
-If it is installed, ask exactly one question:
+Write `docs/agents/triage-labels.md`.
 
-> Do you want to keep the default triage labels? (recommended: **yes**)
+### 4. Section C — Domain docs
 
-The defaults are the five canonical roles, each label string equal to its name: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. On **yes**, write them as-is. Only if the user says no — usually because their tracker already uses other names (e.g. `bug:triage` for `needs-triage`) — collect the overrides so `triage` applies existing labels instead of creating duplicates.
+Default: **single-context** — one `CONTEXT.md` + `docs/adr/` at the repo root. Skip the question unless monorepo signals were found.
 
-**Section C — Domain docs.** Default to **single-context** — one `CONTEXT.md` + `docs/adr/` at the repo root. This fits almost every repo; write it without asking.
+Write `docs/agents/domain.md`.
 
-Offer **multi-context** — a root `CONTEXT-MAP.md` pointing to per-context `CONTEXT.md` files — only when exploration found monorepo signals. Then confirm which layout they want.
+### 5. Section D — AI model roles
 
-### 3. Confirm and edit
+Three questions, one at a time. Default to `openai/gpt-5.6-sol` and `minimax/MiniMax-M3`; offer alternative families below.
 
-Show the user a draft of:
+| 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 |
 
-- The `## Agent skills` block to add to whichever of `CLAUDE.md` / `AGENTS.md` is being edited (see step 4 for selection rules)
-- The contents of `docs/agents/issue-tracker.md`, `docs/agents/domain.md`, and `docs/agents/triage-labels.md` (the last only when `triage` is installed)
+Alternatives to mention if the user has no OpenAI/MiniMax:
 
-Let them edit before writing.
+- 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
 
-### 4. Write
+After the user answers, **update `.opencode/ship.config.json`** so workflow looks like:
 
-**Pick the file to edit:**
+```json
+{
+  "schemaVersion": 2,
+  "profile": "engineering",
+  "project": { ... },
+  "delivery": { ... },
+  "workflow": {
+    "models": {
+      "planner": "<answer>",
+      "builder": "<answer>",
+      "finalReviewer": "<answer>"
+    },
+    "approval": { "mirrorToIssue": true, "maxFailedRounds": 3 }
+  }
+}
+```
 
-- If `CLAUDE.md` exists, edit it.
-- Else if `AGENTS.md` exists, edit it.
-- If neither exists, ask the user which one to create — don't pick for them.
+Then run `opencode-ship update` to write the change with full transactional coverage.
 
-Never create `AGENTS.md` when `CLAUDE.md` already exists (or vice versa) — always edit the one that's already there.
+### 6. Section E — Provider auth probe
 
-If an `## Agent skills` block already exists in the chosen file, update its contents in-place rather than appending a duplicate. Don't overwrite user edits to the surrounding sections.
+```bash
+opencode providers list
+```
 
-The block:
+If the planner/builder/finalReviewer names are missing credentials, surface a warning and tell the user how to log in:
 
-```markdown
-## Agent skills
+```bash
+opencode providers login openai
+opencode providers login minimax
+```
+
+Do not invent credentials. Do not retry.
 
-### Issue tracker
+### 7. Section F — Permissions sanity
 
-[one-line summary of where issues are tracked]. See `docs/agents/issue-tracker.md`.
+Run `opencode-ship doctor`. If any pointer is missing, prompt the user to run:
 
-### Triage labels
+```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.
 
-[one-line summary of the label vocabulary]. See `docs/agents/triage-labels.md`.
+If an `## Ship workflow` block exists, update in place. Otherwise append:
 
-### Domain docs
+```markdown
+## Ship workflow
 
-[one-line summary of layout — "single-context" or "multi-context"]. See `docs/agents/domain.md`.
+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, and write `docs/agents/triage-labels.md`, only when `triage` is installed and Section B ran. When it isn't, both are omitted.
+Include the `### Triage labels` sub-block only when the `triage` skill is installed.
 
-Then write the docs files using the seed templates in this skill folder as a starting point:
+### 9. Done
 
-- [issue-tracker-github.md](./issue-tracker-github.md) — GitHub issue tracker
-- [issue-tracker-gitlab.md](./issue-tracker-gitlab.md) — GitLab issue tracker
-- [issue-tracker-local.md](./issue-tracker-local.md) — local-markdown issue tracker
-- [triage-labels.md](./triage-labels.md) — label mapping (only if `triage` is installed)
-- [domain.md](./domain.md) — domain doc consumer rules + layout
+- 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.
 
-For "other" issue trackers, write `docs/agents/issue-tracker.md` from scratch using the user's description.
+## Next steps (always print)
 
-### 5. Done
+```text
+Setup complete.
 
-Tell the user the setup is complete and which engineering skills will now read from these files. Mention they can edit `docs/agents/*.md` directly later — re-running this skill is only necessary if they want to switch issue trackers or restart from scratch.
+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"
+```
 
-## Ship integration
+## Hard rules
 
-This skill is part of the engineering profile shipped by
-`opencode-ship@1.0`. The strong planner child session is
-configured with `openai/gpt-5.6-sol` and the durable workflow
-state lives under `<git-common-dir>/opencode-ship/`. All
-GitHub mutations go through Ship's typed tools; never use
-`gh api` or raw shell.
+- 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/skills/skill-discovery/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: skill-discovery
+description: Discover and conditionally install skills from the open agent skills ecosystem before non-trivial work. Use when the parent agent is starting a new task and wants to ensure the most relevant public skills (React, testing, deployment, etc.) are available to the cheap builder.
+---
+
+# skill-discovery
+
+Discover skills from the open agent skills ecosystem (`npx skills`) that match the current task objective, then install the trusted ones locally. The hard rule is that this skill is **suggest-first, install-conditionally**: trusted sources may auto-install; everything else must be approved by the user.
+
+## When you trigger
+
+- The parent agent (typically `ship-deliver` or `ship-task-builder`) is about to dispatch a new task.
+- The task objective references a domain where a public skill likely exists (web frameworks, testing, deployment, design, etc.).
+- The user has not yet opted out of skill discovery for this session.
+
+Do **not** trigger on:
+
+- Trivial edits, doc rewrites, single-line fixes
+- Tasks that are already covered by a vendored skill from the engineering catalog
+
+## Procedure
+
+### 1. Extract a discovery query
+
+From the current task brief (interfaces, files, technology stack), build one short query string (2–5 words). Example: `react testing`, `docker deploy`, `postgres migrations`, `tailwind components`.
+
+### 2. Search the skills ecosystem
+
+```bash
+npx skills find "<query>"
+```
+
+The CLI returns candidates with source repo, install count, and skill name. Parse the output, do not transcribe it.
+
+### 3. Score and filter
+
+The install allowlist and quality threshold live in `ship.config.json` under `skillDiscovery`:
+
+```json
+{
+  "skillDiscovery": {
+    "trustedOwners": [
+      "vercel-labs",
+      "anthropics",
+      "obra",
+      "mattpocock",
+      "ComposioHQ"
+    ],
+    "minInstalls": 1000,
+    "blocklist": ["known-bad-owner/example"]
+  }
+}
+```
+
+**Auto-install** is allowed only if all of the following are true:
+
+- source owner is in `trustedOwners`
+- install count >= `minInstalls` (default 1000)
+- skill name does not conflict with a managed `opencode-ship` skill
+- the user has not previously blocked this skill in this repo
+
+Otherwise:
+
+- If the source is untrusted but the skill looks relevant, present 1–3 candidates to the user and wait for a yes/no.
+- If no candidates match, continue without installation.
+
+### 4. Install project-locally
+
+Auto-approved candidates install to `.opencode/skills/<skill>/SKILL.md` (project-local). The typed tool `ship_skill_install` records every install in the run ledger so `doctor` and `uninstall` can audit it.
+
+Manual install if the user prefers global:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+Prefer project-local unless the user explicitly asks for global.
+
+### 5. Report
+
+After discovery, emit a one-line summary in the run:
+
+```text
+Skill discovery: <n> candidates, <m> installed (<owner/skill list>).
+```
+
+If 0 installed, say `Skill discovery: 0 installed, continuing with catalog skills only.`
+
+## Hard rules
+
+- Never run `npx skills add` for an untrusted source without explicit user approval.
+- Never install a skill that shadows a managed opencode-ship skill (name collision).
+- Never run discovery when offline or when the registry is unreachable. Warn and continue.
+- Never install more than 5 skills in one discovery pass.
+- Never persist discovery results to `ship.config.json`. The discovery is per-task, not per-repo.
+
+## Permissions
+
+This skill expects the following bash allowances on the host (configured in `ship-controller` frontmatter):
+
+- `npx skills find *`
+- `npx skills add *`
+- `ls .opencode/skills`
+- `cat .opencode/skills/*/SKILL.md`