README.md
# ship
> The task entrypoint for a coordinator-class model (Opus 5). Routes any substantive ask through three gates — design, issues, dispatch — then delegates implementation to the right models (Codex/GPT-5.6-Sol and Opus 5 subagents do the heavy lifting) while the coordinator plans, reviews, and merges.
## What it does
`ship` turns the most expensive model in your setup into what it should be: a tech lead, not a typist. Given a raw task, feature request, bug cluster, or goal, it:
1. **Triages** — trivial work gets done directly with zero ceremony; substantive work enters the gates.
2. **Gate 1 — Design**: decides whether architecture/design-doc work must happen before code (penalty-for-being-wrong test), delegating to the [`design-doc`](../design-doc/) skill when it fires.
3. **Gate 2 — Issues**: cuts GitHub issue(s) by default for code changes in a repo with a GitHub remote (skipped only when there's no remote, the work isn't a code change, or the user declines), and writes them to a strict standard — implementable by a junior dev or mid-tier model **without guesswork** (full context, exact files, agreed approach, out-of-scope list, checkable acceptance criteria).
4. **Gate 3 — Dispatch**: assembles agent teams and routes every role to an explicit model — bulk/mechanical/token-heavy work and computer-use verification to GPT-5.6-Sol via the Codex CLI, taste-sensitive code to Opus 5 subagents, planning/review/merge judgment kept by the coordinator. Includes per-model prompting techniques, because prompts that work on Claude actively hurt on Codex.
It composes with the existing pipeline: `ship → design-doc → issues → implement-issue → team-executor → software-engineer`, all prefer-when-present.
## When to use it
- *"Take this on end to end: we need rate limiting on the public API."*
- *"Here's a braindump of what's broken in checkout — handle it."*
- *"Get the notification system from the design discussion actually shipped."*
- Any substantive task where the path — design first? issues? which models implement? — hasn't been decided yet.
**Not the right skill if** you already have a specific issue number (→ [`implement-issue`](../implement-issue/)) or a fully-formed plan ready for a team (→ [`team-executor`](../team-executor/)). `ship` is the layer that decides those things.
## Example walkthrough
**Prompt**
> We need webhook delivery in Lakebed — customers keep asking. Take it from idea to shipped.
**What the skill does**
1. **Triage** — substantive, path unclear → full gates.
2. **Design gate fires** (public API surface + delivery-guarantee semantics are expensive to reverse). Produces a right-sized design doc via `design-doc`; user signs off on at-least-once delivery with signed payloads.
3. **Issue gate** — cuts four issues, each one bounded PR: schema + outbox table, delivery worker, signature verification + docs, admin UI. Dependencies declared; issues 2 and 4 flagged parallel-safe.
4. **Dispatch** — outbox migration and delivery worker go to Codex (clear spec, mechanical); public API surface and docs go to an Opus 5 subagent with `software-engineer` attached; coordinator reviews every diff, Codex runs an independent second review of Opus's PRs and drives a computer-use verification of the admin flow. PRs merge as CI and reviewers pass.
5. **Report** — links to merged PRs, gate decisions and why, plus a note that the delivery worker took far longer than its spec suggested — a coupling smell worth a follow-up.
## Installation
```bash
npx skills add thatjuan/agent-skills --skill ship
```
## Bundled resources
| File | Purpose |
|------|---------|
| `SKILL.md` | The three-gate workflow, division of labor, orchestration shapes, verification rules |
| `references/model-routing.md` | Model traits table, invocation mechanics (Agent tool, `codex exec`, workflows), per-model prompting techniques |
| `references/issue-standard.md` | The junior-dev-implementable issue template, sizing/decomposition rules, filing mechanics |
## Tips
- **Effort stays at high, never above.** xhigh/max overthink per step and bloat both diffs and bills; effort doesn't extend how long agents work, only how much they think per tool call.
- **Judge output, not price tag.** The skill has standing permission to redo a cheap model's output with a smarter one — escalating costs less than shipping mediocre work.
- **Watch the clock as a signal.** When a "simple" fix takes an agent an hour, the skill surfaces it — that's your architecture talking.
- **Keep the routing table honest.** Model traits shift with every release; when a dispatch misroutes, append the lesson to `references/model-routing.md` instead of re-explaining per session.
## Related skills
- [`implement-issue`](../implement-issue/) — per-issue delivery this skill dispatches to
- [`team-executor`](../team-executor/) — multi-agent planning/execution engine underneath
- [`software-engineer`](../software-engineer/) — the engineering bar attached to every coding/review agent
- [`design-doc`](../design-doc/) — the design gate's author/reviewer
references/issue-standard.md
# Issue Standard — Junior-Dev-Implementable
Every issue this skill cuts must be implementable **without guesswork** by a junior developer or a mid-tier model with no session context. The issue is the entire context handoff: assume the implementer has never seen the conversation, the design doc discussion, or the coordinator's reasoning. Anything not written down does not exist.
## The Test
Before filing, ask: *could an agent that has only this issue text and the repo produce the PR I want, first try?* Every question it would need to ask is a defect in the issue. Common defects:
- "Improve", "clean up", "make better" — no observable definition of done.
- Naming a goal but not the approach when the approach was actually decided.
- Omitting the files/modules involved, forcing rediscovery of what the coordinator already knows.
- Silent scope boundaries — the implementer can't tell what's deliberately out of scope vs forgotten.
## Template
```markdown
## Context
Why this work exists. Link the design doc / parent issue / inspiring PRs
(if multiple PRs attempted this before, link all of them and state what
happens to each: superseded, partially reused, closed).
## Current behavior
What the code does today. Name the exact files/modules/functions involved
(paths, not descriptions). If a schema/API is involved, show its current shape.
## Desired behavior
What the code must do after this change. Concrete: inputs → outputs,
UI states, API responses. Include the agreed approach when one was decided
at the design gate — the implementer executes it, not re-derives it.
## Implementation notes
- Files expected to change, and roughly how.
- Conventions to follow, with an exemplar: "match the pattern in <path>".
- Known traps, ordering constraints, and decisions already made (with the why,
so the implementer doesn't "helpfully" reverse them).
## Out of scope
Explicit non-goals. Anything adjacent the implementer might be tempted to fix.
## Acceptance criteria
- [ ] Checkable statements — each verifiable by running something.
- [ ] Tests: which ones must be added/updated, what they must cover.
- [ ] Verification: the command/flow that proves the behavior end to end.
## Dependencies
Blocked by #N / blocks #M. Which issues can proceed in parallel with this one.
```
## Sizing and Decomposition
- **One issue = one bounded PR.** If the desired behavior needs multiple PRs (e.g., dual-write → read-path flip → column drop), cut one issue per PR and chain them with `Blocked by`.
- Decompose along **merge checkpoints**, not along files: each issue should be independently mergeable and leave the system working.
- Issues that can run in parallel must have **disjoint file surfaces** — say so explicitly in Dependencies so the dispatcher can parallelize without merge-conflict roulette.
- Robustness beats speed: implementers are agents, so human effort estimates don't apply. Never shrink scope because it "would take a person too long"; only split for boundedness and reviewability.
## Filing
Use `gh issue create --title "..." --body-file <tmpfile>` (write the body to a temp file — inline `--body` mangles multiline markdown). Apply the repo's labels/milestone conventions if they exist. Title format: imperative, specific — "Add cursor pagination to /v1/events", not "Pagination improvements".
references/model-routing.md
# Model Routing — Traits, Invocation, Prompting
The coordinator assigns an explicit model to every delegated agent. This file is the routing brain: what each model is good at, how to actually invoke it, and how to prompt it — because prompting techniques that work on one family actively hurt on another.
**Precedence**: if the user's global `~/.claude/CLAUDE.md` (or project CLAUDE.md) carries its own model rankings/routing section, that section is the source of truth — it reflects the user's actual subscription economics and current model versions. The tables below are portable defaults for when no such section exists.
## Glossary
- **Intelligence** — how hard a problem the model can handle unsupervised.
- **Taste** — UI/UX, code quality, API design, and copy. Whether the output is the code/text you'd *want*, not just code that works.
- **Cost** — effective cost to the user, accounting for subscription economics (Codex sub usage is extremely generous — treat GPT-5.6 as near-free; coordinator tokens are the most expensive thing in the system).
## Traits (1–10, higher = better; cost 10 = cheapest)
| Model | Cost | Intelligence | Taste | Notes |
|---|---|---|---|---|
| Opus 5 — coordinator (this session) | 2 | 9 | 9 | Best in class on both axes, and the most expensive tokens in the system. Reserve for planning, hard problems, review, merge judgment, taste-critical glue. |
| Opus 5 — subagent | 3 | 9 | 9 | Same model, delegated: taste-sensitive implementation the coordinator specs but doesn't type. Cheaper than doing it in the coordinator's own context. |
| GPT-5.6-Sol via Codex CLI | 9 | 8 | 5 | Handles hard problems from a clear spec; writes TypeScript like a Python dev and Rust like a paranoid C++ dev. Also the only computer-use option that actually works (Xcode, simulators, full desktop). |
| Sonnet 5 | 5 | 6 | 7 | Wrapper duty (e.g., hosting a codex call inside a workflow), mechanical checks, light user-facing polish when Opus is overkill. |
| Haiku | 10 | 2 | 2 | Never use. With GPT-5.6 near-free there is no task where Haiku is the right answer. |
Threshold: anything user-facing (UI, copy, API design) needs **taste ≥ 7**.
**Priority for anything that ships: intelligence ≥ taste > cost.** Cost breaks ties and gates exploration, never final quality. Standing permission to redo cheap-model output with a smarter model without asking.
## Routing Quick Reference
| Work | Route to |
|---|---|
| Bulk mechanical work — clear-spec implementation, migrations, codemods, data analysis | GPT-5.6 (codex) |
| Digging through logs, giant PDFs/specs, anything token-devouring | GPT-5.6 (codex) — burn its tokens, not yours |
| Computer use — browser flows, simulators, Xcode, screenshots, runtime verification | GPT-5.6 (codex computer-use) |
| User-facing code — public API, SDK surface, UI, copy (taste ≥ 7 needed) | Opus 5 subagent, coordinator reviews |
| Moderate-complexity in-repo implementation with conventions to follow | Opus 5 subagent (with `software-engineer` skill attached) |
| Independent second review of a plan or PR | Opus 5 subagent or coordinator; add Codex as an extra independent perspective (strongest on Claude-written code) |
| Plan review, architecture calls, contested decisions | Coordinator |
## Invocation Mechanics
### Claude models — Agent tool / team-executor
Pass `model: "opus"` / `model: "sonnet"` on the Agent call (Opus 5 / Sonnet 5 resolve from those aliases), or specify the model per role when overlaying `team-executor`. Attach `software-engineer` (prefer-when-present) to any agent that writes or reviews code. Reasoning effort: high at most — never xhigh/max (per-step overthinking, bloated diffs, absurd cost; effort does not extend runway, only thought-per-step).
### GPT-5.6 — codex CLI (only path to it)
Prefer dedicated codex skills when installed — `codex-implementation`, `codex-review`, `codex-computer-use`, or the `codex` skill from the skill-codex plugin — their command references govern. For work they don't cover (investigation, data analysis), run `codex exec -s read-only` directly with a self-contained prompt. Core shape:
```bash
# read-only analysis/review
codex exec --skip-git-repo-check -m gpt-5.6-sol \
--config model_reasoning_effort="high" \
--sandbox read-only "PROMPT" </dev/null 2>/dev/null
# implementation (edits allowed) — run inside the target worktree with -C
codex exec --skip-git-repo-check -m gpt-5.6-sol \
--config model_reasoning_effort="high" \
--sandbox workspace-write --full-auto -C <WORKTREE> "PROMPT" </dev/null 2>/dev/null
# continue a session
echo "FOLLOW-UP" | codex exec --skip-git-repo-check resume --last 2>/dev/null
```
Hard-won gotchas:
- **Model ids**: plain `gpt-5.6` is not a valid slug — the 5.6 family is `gpt-5.6-sol` (frontier, default), `gpt-5.6-terra` (balanced), `gpt-5.6-luna` (fast/cheap sweeps). `codex debug models` lists the catalog; if a slug is rejected, pick from that list and tell the user.
- **Set effort explicitly**: `gpt-5.6-sol` ships with a *low* default reasoning level, so an unset `model_reasoning_effort` silently under-thinks the task.
- **Always `</dev/null`** when stdin isn't a closed TTY — codex reads stdin and hangs forever otherwise (symptom: zero output, zero CPU).
- **`2>/dev/null`** suppresses thinking tokens on stderr.
- **No intermediate output** — result appears only at completion. Prefer synchronous runs; if backgrounded, budget timeouts by effort (low 150s / medium 300s / high 600s).
- Give codex implementation work in an **isolated worktree** so a bad run costs nothing.
### GPT-5.6 inside Workflows
Workflow `agent()` calls can only spawn Claude models. To use codex in a workflow stage: spawn a **Sonnet agent on low effort** whose entire job is to shell out to `codex exec`, wait, and report the results back verbatim. Prefix its label `codex:` so runs are attributable in progress views. Account for codex's runtime in the wrapper's expectations.
## Prompting Techniques Per Model
The single most common failure: prompting Codex as if it were Claude. The families need opposite treatment.
### Prompting GPT-5.6 / Codex
- **Simple, literal, self-contained.** It has zero conversation context — include the repo path, the target files, the spec, and nothing else. One task per invocation.
- **No personas, no motivation, no "you are an expert".** Codex does what's asked and doesn't do what isn't — skip the "do not edit unrelated files" defensive lists that Claude models need.
- **Specify the output format explicitly** ("return a markdown list of file:line findings").
- **Tell it to report the empty case**: "If you find nothing, say that clearly and name what you inspected." Without this, empty results confuse the parent agent into wasteful re-runs.
- Point it at concrete inputs (paths, PR numbers, log files), not abstractions.
- **UI design tasks**: tell it to "use imagegen to imagine the design and implement that" — it renders a target before coding toward it.
- **Embed the engineering bar.** Codex can't carry the `software-engineer` skill, so paste this digest into every code-writing prompt:
> Engineering bar: prefer the reframing that deletes complexity over adding branches. No new conditionals bolted into existing flows — extract a helper/abstraction instead. Reuse existing helpers and patterns; never near-duplicate one. Explicit typed contracts — no `any`, casts, or silent fallbacks; give domain concepts their own types. Keep logic in the module that owns the concept. Don't push a file past ~1000 lines — split first. Honest names. No TODOs, stubs, or placeholders. Match the project's existing conventions.
**Relaying Codex results**: before passing a Codex finding to the user or acting on it, inspect the cited code/diff enough to decide whether it's real. Separate confirmed issues from unverified Codex suggestions in any report. If `codex` is not installed or the command fails, report the error and do the work directly instead.
### Prompting Opus 5 subagents
- State the **goal, constraints, and verification bar**; don't enumerate steps for open-ended work — it decomposes better than a hand-written procedure and will invent the right subagent archetypes itself. Reserve numbered requirements and non-goals for scope-sensitive work where drift is the risk.
- Give real context: conventions, pointers to exemplar files in the repo ("match the pattern in `src/api/users.ts`"), the issue text, acceptance criteria.
- Attach `software-engineer` for any code-writing/review role; name the definition of done (tests pass, self-review gate run).
- Grant explicit authority up front ("you may create worktrees, rebase, open PRs") so it doesn't stall at permission boundaries; add a scope fence when the surface is narrow ("only touch X; if Y seems needed, stop and report").
- Keep effort at high. Trust-but-verify: it goes furthest end-to-end, so the checkpoints you set (CI, reviewers, merge gates) are the real control surface, not prompt-level restrictions.
## Maintenance
When a dispatch misroutes or a prompt-shape failure recurs, fix it *here* — append the lesson to this file (or the relevant skill) instead of re-litigating per session. This file is expected to evolve; model traits change with every release, and the table reflects judgment as of the last edit, not ground truth.
SKILL.md
---
name: ship
description: 'Task entrypoint and delivery orchestrator for an Opus-class coordinator. Routes a raw task through three gates — design (design-doc), GitHub issues, dispatch to the right models (Codex/Opus implement; coordinator plans, reviews, merges). Use when the user hands over a nontrivial task expecting idea-to-shipped-code — "take this on", "get this done end to end", "handle this" — or when a substantive task''s path (design? issues? which models?) is undecided.'
---
# Ship
The entrypoint for substantive work. The coordinator model running this skill is the scarcest, most expensive resource in the pipeline — so it behaves like a tech lead, not a developer: it **decides, designs, specs, delegates, reviews, and merges**. Implementation heavy lifting goes to cheaper models with high throughput. The coordinator writes code directly only when the change is trivial (faster to do than to delegate) or taste-critical glue no other model should own.
## Position in the Pipeline
```
ship (THIS skill — triage, design gate, issue gate, dispatch, review/merge)
├─ design-doc — when the design gate fires
├─ gh / gh-cli — issue authoring
├─ implement-issue — per-issue delivery (→ team-executor → software-engineer)
└─ model routing — every delegated agent gets an explicit model assignment
```
All downstream skills are **prefer-when-present**: check `~/.claude/skills/<name>/`, `.claude/skills/<name>/`, a sibling `../<name>/`, `/mnt/skills/<name>/`, or `skills-lock.json`. When one is missing, inline a trimmed equivalent of its core judgment; never hard-fail.
## Bundled Resources
| File | Purpose |
|------|---------|
| [references/model-routing.md](references/model-routing.md) | Model traits, invocation mechanics (Agent tool, codex exec, workflows), per-model prompting techniques |
| [references/issue-standard.md](references/issue-standard.md) | The junior-dev-implementable issue template and authoring rules |
Read `model-routing.md` before the first dispatch of the session. Read `issue-standard.md` before writing issues.
## Gate 0 — Triage
Classify the incoming task before doing anything else:
- **Trivial** (single bounded change, obvious approach, < ~15 min of agent work) → skip all gates, do it directly or hand one agent one prompt. Do not ceremony-tax small work.
- **Substantive, path unclear** → proceed through Gates 1–3 in order.
- **Already spec'd** (user supplied an issue, a design doc, or an explicit plan) → skip the satisfied gates, enter at the first unsatisfied one.
Time-to-complete is itself a signal worth reporting: if a "simple" fix takes an agent an hour, the architecture is telling you something — surface it to the user rather than silently merging.
## Gate 1 — Design
Ask: **what is the penalty for being wrong?** Fire this gate when any of these hold:
- Multiple viable architectures exist and reversing the choice later is expensive (schema, public API surface, service boundaries, data migrations).
- The task spans systems or teams, or changes behavior other components depend on.
- The user's ask is a goal, not an approach, and the approach materially shapes the work.
When fired: invoke `design-doc` to produce a right-sized doc (it carries the when/what/how judgment — don't duplicate it). Present the doc's TL;DR and open decisions to the user for sign-off **unless** the user said "decide" / "autonomous" — then choose the most robust, convention-consistent option and record why.
When not fired: skip straight to Gate 2. Most tasks do not need a design doc; over-writing is a real failure mode.
## Gate 2 — Issues
Ask: **should this work survive as GitHub issue(s)?** For software work in a GitHub repo the answer defaults to **yes**: if the project has a GitHub remote (`gh repo view` resolves) and the task changes code, cut issue(s) before dispatch — the paper trail is the default, not the exception. Independently of that default, also cut issues when:
- The work decomposes into more than one bounded PR, or
- Work will be delegated to agents that start fresh (no session context), or
- The user wants parallelization or to review scope before build.
Skip to Gate 3 with an inline spec of the same rigor only when there is no GitHub remote, the work isn't a code change (pure research/analysis), or the user explicitly declines the paper trail. (Trivial tasks never reach this gate — Gate 0 already routed them.)
**The bar**: every issue must be implementable by a junior developer — or a mid-tier model — **without guesswork**. Exact standard and template in [references/issue-standard.md](references/issue-standard.md). Decompose so each issue is one bounded PR; declare dependencies between issues explicitly (`Blocked by #N`). Create with `gh issue create` (see `gh-cli` skill for syntax edge cases).
## Gate 3 — Dispatch
### Division of labor
In one line: **Codex (GPT-5.6-Sol, near-free)** takes bulk implementation from a clear spec plus computer-use verification; **Opus 5 subagents** take taste-sensitive code (public APIs, UI, copy); the **coordinator** (Opus 5, this session) plans, resolves conflicts, reviews, and merges; **Sonnet 5** only as a cheap wrapper; **Haiku** never. The full traits table, routing quick-reference, standing rules (escalate without asking when output misses the bar; cost is a tiebreaker only; reasoning effort high at most, never xhigh/max), invocation mechanics, and per-model prompting are in [references/model-routing.md](references/model-routing.md) — already read before first dispatch. User global/project CLAUDE.md rankings override the bundled defaults.
### Orchestration shape
- **One issue, bounded** → invoke `implement-issue` (it opens the branch, plans, executes via `team-executor`, opens the PR). Overlay model routing: tell the executor which model each role gets, per the table above. Any Claude agent that writes or reviews code also gets the `software-engineer` skill (prefer-when-present); Codex can't carry skills, so code-writing codex prompts embed the engineering-bar digest from `model-routing.md` instead.
- **Several independent issues** → parallel worktrees, one delivery stream per issue. Keep disjoint file surfaces in parallel; serialize streams that touch the same code.
- **Checkpoint-driven programs** (each PR needs CI + review + merge before the next rebase) → orchestrate from this session, step by step. Do NOT wrap the umbrella in one giant workflow — workflows are for deterministic fan-out/verify (triage passes, multi-agent review panels), not for programs with human checkpoints or mid-stream product calls.
- **Reviews before merge**: every PR gets at least one independent review pass by a model that didn't write it. Codex is a good independent second perspective on Claude-written code and vice versa. Merge only what passes the project's configured automated reviewers, if any.
### Verification
Delegated code is claimed-done, not done. Before reporting completion: run the tests/CI, and for user-facing behavior have an agent actually drive the flow (Codex computer-use is the strongest option for runtime/UI verification). The coordinator personally reads the diff of anything taste-critical before merge.
## Reporting
Close the loop with the user in one message: what shipped (PRs/issues with links), what was decided at each gate and why, what was escalated between models, and anything the task revealed about the codebase (slow fixes, surprising coupling) worth acting on.