ship-it
Take one change from request to merged pull request autonomously: explore the repository, implement the change, open a draft PR after local checks, run risk-selected gates alongside CI, address required feedback, and merge. The change can be a plain description, a GitHub issue, or a Jira ticket. An approved complex plan or an umbrella issue with implementation subissues runs as a coordinated set of separate issues.
The plugin is a portable Agent Plugin with one Agent Skill, so the same package works in Claude Code, Codex, Copilot CLI and opencode.
Its initial workflow contract stays below Codex's 8 KB prompt limit. Detailed instructions load from bundled references only when each workflow phase begins.
Every phase also has a versioned machine-readable capability contract. It selects one of four portable profiles (explore, build, review, or release), verifies requirements before side effects, preserves equivalent fallbacks across harnesses, and keeps destructive, secret-bearing, deployment, out-of-workspace, and unknown actions interactive.
Every task has a portable JSON checkpoint under ${XDG_DATA_HOME:-$HOME/.local/share}/sai/ship-it/checkpoints/. Claude Code, Codex, Copilot CLI, opencode and Sail use the same task identity, phase, revision, blocker and outcome fields, so another harness can safely reconcile Git and GitHub before resuming.
Gate input manifests make validation reuse observable: unchanged source, dependencies, invocation, runtime and policy return the verified completed result without another dispatch or counter increment. Changes record precise invalidation reasons. Unrelated integration carries passing local results to the current PR head with their original revision and output digest; failed, incomplete and unverifiable evidence never supplies a passing gate. Required hosted checks and approvals retain their own revision policy. See validation reuse.
GitHub work claims and revision evidence are optional bookkeeping features configured by .sai/ship-it-bookkeeping.json or the current user request; single-user runs default them off. Local telemetry defaults on and a repository may disable it in the same policy file. The durable checkpoint always remains enabled. When claims are on, renewal happens only before a GitHub write, never on a timer.
Telemetry writes privacy-safe workflow events to ${XDG_DATA_HOME:-$HOME/.local/share}/sai/ship-it/telemetry/events.ndjson and never transmits them. Idempotent phase and wait boundaries preserve one history across resume. The local report separates delivery elapsed time, primary active work, observed approval, hosted-service and resource-queue waits, and concurrent worker durations. It also reports repeated gates and user interruptions. Missing observations stay null; prompt text, source content, credentials and raw command output are never recorded.
Portable releases can replay the shared redacted environment-as-code workflow failure corpus through available Claude Code, Codex, OpenCode, Copilot CLI, and Sail adapters. The replay contract normalizes phase and observation traces, treats unavailable harnesses as skipped, blocks on supported-harness regressions, and compares accepted-task cost without storing task or source content.
The delivery performance benchmark compares baseline and candidate contracts against five public synthetic cases with fixed acceptance criteria and model settings. Its normalized report includes elapsed and active time, workflow waits, repeated gates, approval requests, user interruptions, defect blocking, and untested criteria without storing prompts, transcripts, source, or credentials.
With revision evidence enabled, each committed task revision has one portable evidence record under ${XDG_DATA_HOME:-$HOME/.local/share}/sai/ship-it/evidence/. Local checks permit draft PR creation; review and the single broad manual-test pass permit ready-for-review; passing CI for the same head permits merge.
Failed CI is triaged before escalation. The workflow deduplicates revision/workflow/job/attempt observations, exposes only bounded redacted failure sections, classifies failures with evidence, routes code faults back to their implementation owner, and preserves recurrence and resolution in checkpoint, evidence and privacy-safe telemetry. CI reruns need an explicit repository policy or user approval.
Portable role routing gives exploration, implementation, review, testing and CI triage the same meaning across harnesses. Every role records requested and actual provider, model and variant. Review and testing use fresh subagent contexts for every pass or attempt; they may use the implementation model. Reused or inline execution does not satisfy either gate. Under T3 Code, review, testing and CI triage run as delegate_task children on a different model provider than implementation (Codex when Claude implemented, Claude when Codex did), each in its own worktree; with no other provider available they fall back to a fresh same-provider child recorded as degraded.
Validation gates come from a portable risk policy. The bundled policy first classifies the change set: a diff that touches only docs, config or data files (*.md, *.json, *.yaml, *.toml, lock files, Brewfile, images and similar) is the docs class and starts at low; anything else, including a diff that mixes docs with code, is the code class and starts at the default medium. Each level then selects its gate set:
| Risk | Review | Manual test | Gates |
|---|---|---|---|
low | one review pass in a fresh subagent | none | local checks, inline review, CI |
medium | one adversarial review cycle | one adversarial test pass | local checks, adversarial review, adversarial test, CI |
high | one adversarial review cycle | one adversarial test pass | local checks, adversarial review, adversarial test, CI, hosted review |
Code diffs under 50 total added plus deleted lines use one fresh review and a manual test limited to changed behavior when no higher-risk path or policy floor applies. Exactly 50 lines, unknown size, binary or mode changes, security, migration and infrastructure risks retain ordinary gates. Every code change keeps its manual test; failed acceptance reproductions block delivery. Profile, measured size, exclusions and test scope are reported before validation. See risk selection for exact eligibility and monotonic policy rules.
Repositories can add .sai/ship-it-risk.json with their own low, medium and high policies plus deterministic changed-path rules that raise matched paths, for example plugins/** to medium when markdown is the product. A repository policy never lowers a diff below its class level and cannot redefine the classes; its default_risk raises every change set when higher. Agents may raise risk; lowering a policy or checkpoint floor needs explicit user authorization. Repository release requirements (required checks and reviewers) are added at every level. The run report and the completion report name the selected risk, the diff class and the resulting gate set.
Release controls come from .sai/ship-it-release.json, repository instructions, live GitHub rules and a conservative bundled default. The normalized policy is stored in the task checkpoint and names required human or automated reviewers, checks, merge mechanism and strategy, issue closure and branch cleanup. Repositories can require Copilot, another reviewer, human approval or no hosted review without changing the workflow.
Validation converges by default. One Code Adversary pass reviews the change; a Findings Adversary challenges it only when there are findings, and a CLEAN verdict ends the gate. Surviving findings get one batched fix pass, verified from the diff since the reviewed revision against the recorded findings rather than by another review; a second hunt happens only when the fix touches security, data loss or destructive concurrency, and a default-branch merge that leaves the reviewed files unchanged triggers none. The checkpoint counts review cycles, fix passes and full quality-gate runs; at the limit the run opens the PR with the remaining findings as follow-up issues, while delivery blockers still prevent merge. A confirmed acceptance failure triggers focused correction within your existing task authorization even after an internal limit. Your original request and clear approval of a concrete pending request survive handoff and resume with their scope and explicit limits; no special approval phrase is required. Optional expansion needs scoped approval, and coordinators or summaries cannot widen it.
ship-it replaces ship-issue. To upgrade, uninstall ship-issue@sai and install ship-it@sai.
Installation
Claude Code (Copilot CLI is the same with copilot in place of claude):
claude plugin marketplace add smykla-skalski/sai
claude plugin install ship-it@sai
Codex:
codex plugin marketplace add smykla-skalski/sai
codex plugin add ship-it@sai
opencode, or any agent that reads Agent Skills, loads skills/ship-it/ directly:
ln -s /path/to/sai/plugins/ship-it/skills/ship-it ~/.config/opencode/skills/ship-it
Local checkout: claude --plugin-dir /path/to/sai/plugins/ship-it/
Install adversarial-review and adversarial-test too: ship-it uses them when selected. Their default policy approves the equivalent portable capability fallbacks; any other unavailable required gate stops unless its policy names a compatible fallback.
Usage
In Claude Code and Copilot CLI use /ship-it, in Codex $ship-it:
/ship-it <task description>
/ship-it --risk high <task description>
/ship-it --issue <task description>
/ship-it https://github.com/owner/repo/issues/123
/ship-it https://your-site.atlassian.net/browse/KEY-123
| Input | What happens |
|---|---|
| Task description | Implements it and opens a PR. No issue is created |
--issue + description | Creates a GitHub issue first, then ships it and closes it on merge |
--risk low|medium|high + any source | Sets an explicit minimum risk; repository rules may raise it |
| GitHub issue URL | Ships the issue; the PR body has Closes #N, so merging closes it |
| Jira URL | Reads the ticket through Atlassian MCP tools, acli, or the jira CLI, whichever is available, and asks you to paste it when none is. The Jira key goes in the PR title or body. The ticket is never transitioned, commented on, or edited unless you ask |
| Approved complex plan or umbrella issue | Reuses or creates a ☂️ umbrella and independent subissues, then dispatches eligible workers up to available runtime capacity. Dependencies wait for prerequisite PRs to merge. The parent only coordinates |
Input it cannot recognize or read stops with a message before any code changes.
The skill pushes and merges, so Codex runs it only when invoked by name. Its allow_implicit_invocation: false policy intentionally omits it from Codex's default model-visible skill list; $ship-it loads it explicitly. Outside Sail, agents may use declared inline fallbacks for work that does not require review or testing. Every selected review and testing gate requires fresh subagent contexts. In Sail mode, unavailable required worker or gate subagents pause the run. A child completes only after all risk-selected gates pass, required threads resolve, its PR merges, and its issue closes.
It merges through the resolved repository mechanism (including exact bot comments and protected-branch flows), never substitutes another reviewer or bypasses a control, and uses a squash merge only as the documented default. After the first push it never force-pushes or rebases.
The skill owns the full lifecycle and stops only for genuine ambiguity, branch-protection requirements, persistent review/test failures, or product decisions that the request and repository cannot answer. It wakes coordinators only for meaningful worker or hosted-state events, deadlines and user input. Empty waits trigger no status reads or messages; duplicate terminal events cannot repeat a gate or delivery action. A harness without event waits uses one bounded ten-minute poller. Host progress updates report the last event without waking work. Each mandate is delivered once, and resumption loads only missing current-phase guidance.
License
MIT
Parallel issue execution
Umbrella runs fill available runtime capacity with independent issue workers in isolated worktrees before waiting. There is no fixed three-worker cap. Ready review/test gates receive capacity first, and at least one slot is reserved for selected nested gates. Each issue worker owns its full lifecycle; the coordinator schedules capacity and dependencies. Gate passes within one issue retain their required ordering. A host with four total slots supports two issue workers and one gate alongside the coordinator.
Copilot quota memory
Before requesting Copilot, inspect python3 <skill-dir>/scripts/copilot_quota.py status. After reading submitted reviews, run copilot_quota.py classify REVIEWS.json --previous PR_STATE.json and retain its returned PR state across snapshots. The wrapper preserves genuine reviews and remembers new refusal evidence for other runs by the same OS user. It never requests a review or bypasses configured fallback policy.
Memory expires at most 24 hours (86,400 seconds) after the refusal submission by default (first observation when a saved snapshot lacks a submission timestamp), so restored monthly quota is retried within a day. Override the lifetime when observing a refusal with classify --max-age SECONDS or Python classify_and_remember(..., max_age=SECONDS). The hosted waiter uses the same memory automatically and accepts --quota-max-age SECONDS. Use a positive integer; concurrent observations do not extend an active expiry. Expiry and clearing affect future requests on other PRs, never a refusal already retained in a PR decision.
- Inspect:
python3 <skill-dir>/scripts/copilot_quota.py status - Clear:
python3 <skill-dir>/scripts/copilot_quota.py clear - Storage:
${XDG_DATA_HOME:-$HOME/.local/share}/sai/ship-it/serviceability/copilot-quota.json
Clearing immediately enables future requests and retains a minimal cleared watermark, so replaying a historical refusal cannot recreate the cache. Expired records also act as watermarks. New refusals submitted after the watermark can be remembered; snapshots without submission timestamps never refresh an existing record.
The owner-only file contains only reviewer, reason, and Unix-seconds expiresAt. It contains no repository, PR, review body, or credentials. A stable lock file serializes inspect, clear, and write; atomic replacement prevents partial JSON. Corrupt state fails with an inspection/clear diagnostic instead of silently requesting review.