Skip to content
orchestrator

from tickets to features. leveraging concurrency.

ship-it drives issue tracker tickets (or local changes) through plan, implement, review, and PR, concurrently across a batch, keeping living docs in step and enforcing rules. Every stage is also a standalone skill you can call on its own.

get started see the pipeline
8  skills concurrent  lanes git  worktrees code-only  verify
claude code

> ship all the todo issues_

resolve  2 work-units from Linear · FRA-144, FRA-145

plan    2 comprehensive plans (Plan agents), posted as proposals

lanes   2 concurrent · no file overlap

checkpoint review on the tracker, then approve

FRA-144

#224 green

FRA-145

#225 green

one prompt · two issues · two reviewed PRs

get started in three steps

01

install the plugin

Add the marketplace, then enable ship-it. Refresh the marketplace clone first to get the latest version.

claude plugin marketplace add pricklywiggles/fractally-claude-marketplace
claude plugin install ship-it@fractally-claude-marketplace
02

adapt it to your project

Run init. It detects what it can, asks only the gaps, writes .claude/ship-it/config.json, and self-verifies on disk.

> /ship-it:init

  detect · interview · write config
  validate · verify-init OK
03

ship

Run a batch, or any stage skill standalone. Review at the checkpoint, then approve. Each PR carries a followable QA checklist.

> ship all the todo issues

  // after merge
$ scripts/cleanup-worktrees.sh --all-merged

For development, point Claude at the live repo with --plugin-dir to skip the install dance entirely.

three layers, kept strictly apart

The engine is project-agnostic. A generic orchestrator drives reusable stage skills over a universal currency, the work-unit. Everything project-specific lives in one config file, produced by init. The flow never hard-codes a stack.

01
Orchestrator · ship-issues. Lane grouping, the concurrent fan-out, worktrees, post-PR watchers.
02
Stage skills · each operates on one work-unit and is callable on its own.
03
Per-project config · values, commands, and adapter refs at .claude/ship-it/config.json.
ship-issues orchestrator lanes · fan-out · worktrees · watchers planfix · cleanup reviewaddress open-prci-fix stage skills · reusable, standalone ship-it.config .claude/ship-it/config.json produced + validated by init

A piece is concurrent when it is per-work-unit; serial only when it touches shared state.

eight phases, one prompt

All human interaction is front-loaded into init and the Phase 3 checkpoint, so the workers run non-interactively and parallelize.

resolvesources planPlan agents lanesoverlap graph checkpointyou approve worktreeslane heads run batchimplement to PR docsliving docs watchersCI · merge
fix-one-issue comment-cleanup if comments fix-one-issue comment-cleanup if comments review-and-address author-reconcile docs rides the PR open-pr

the vocabulary of a run

Six recurring nouns. A run is just these, arranged: work-units fanned into concurrent lanes, each in its own worktree, gated once before anything ships.

work-unit

the currency

One shape every stage speaks, wherever the work came from. It rides through implement, review, and PR unchanged.

{ id, title, desc, branch, base,
  worktree, url, prNumber, plan }

lanes

the concurrency

Two work-units collide only if they touch the same file. Independent ones run as concurrent lanes off main; overlapping ones stack on dependent branches inside one lane. Capped by maxLanes (default 4).

concurrent, off main FRA-144 FRA-145 stacked, one lane parent child, off parent

worktrees

the isolation

Each lane runs in its own git worktree, made runnable by a project-owned prepare hook. The main checkout is never touched, and each tree is left runnable afterward for your QA.

.claude/worktrees/<id>

the Phase 3 checkpoint

human gate

The one place the run waits for you. Read the plans and lanes, posted to the tracker as proposals, then steer. Nothing is pushed until you approve.

approve give feedback nothing pushed yet

safety rails

the constraints

Hard constraints carried verbatim into every worker prompt, so a parallel run cannot drift past them.

code-only verify no personal data house rules

sources

the inputs

Where a run gets its work-units. A tracker for a batch, or local state for the change in front of you.

tracker

linear github-issues custom resolver

local

working-tree branch pr describe

a deliberate planning phase

Before any code, each work-unit gets a comprehensive plan, written by the built-in Plan agent running plan-one-issue concurrently. The plan is the spec the implement stage builds against, and it sharpens the lane grouping.

comprehensive, not a sketch

Context, approach with alternatives, per-file changes and reuse, key decisions, edge cases, verification, risks. Depth scales: light / adaptive / full.

propose, review, update on the tracker

Each plan is posted to its issue as a proposal (idempotent, marker-keyed), updated in place on your feedback, then finalized as approved. Review it in the terminal or on Linear.

verify every API against the installed version

No planning or coding from training-data memory. Package and service-shape calls are confirmed against what the project actually has, checking node_modules, ~/.cargo/registry/src, site-packages, and context7. Unconfirmable calls are flagged, not asserted.

Plan agentreads real code + docs proposal on the tracker<!-- ship-it-plan --> marker checkpointapprove · or give feedback update in place fix-one-issueimplements against the plan PR

one orchestrator, six stages, one setup

Every stage skill is callable on its own. Run just the review, just the CI fix, or push the current diff through the whole flow without a tracker.

orchestrator

ship-issues

Drives the whole batch: resolve, plan, lanes, checkpoint, the per-unit pipeline, docs, watchers. Trigger: "ship all the todo issues", "knock out FRA-111 through 120".

setup

init

Detect-first, ask-second. Detects the package manager, verify command, CI, tracker, doc tools, and reviewers; asks only the gaps; writes and self-verifies the config. Trigger: "set up ship-it here".

stage

plan-one-issue

A comprehensive, read-only plan grounded in the real code, with verified APIs. Trigger: "plan this issue", "draft a plan for FRA-123".

stage

fix-one-issue

Implements the smallest correct change against the plan, verifies, commits. Guards the sync-to-async signature ripple. Trigger: "implement FRA-123 and verify it".

stage

comment-cleanup

Audits the diff's comments: keeps the non-obvious why, drops narration. Runs only if comments changed. Trigger: "clean up the comments in this change".

stage

review-and-address

Fans out your configured reviewers over the diff in parallel, merges findings, applies the warranted ones. Trigger: "review my diff with main and fix what matters".

stage

open-pr

Pushes and opens the PR with a two-part QA-ready body: automated checks run, plus a followable checklist with exact commands. Trigger: "open a PR for my branch".

stage

ci-fix

Watches a PR's CI and fixes failures, bounded and cause-only. Trigger: "watch and fix the CI on this PR".

docs kept current, three ways

Each configured doc job runs in parallel and is one of three mechanics. Built-ins for OpenSpec, graphify, and impeccable; init generates a job for any other doc.

mechanic 01

regenerate

Re-derive the doc from merged code, no authoring. Runs post-merge. If the target is gitignored (e.g. graphify-out/) it is just a local refresh, no PR.

built-in: graphify

mechanic 02

author-reconcile

Author the artifact on-branch before open-pr so it rides the same PR; archive into canonical docs after merge. The spec ships with the code.

built-in: openspec

mechanic 03

curate-serial

Update a shared prose doc once. One triggering work-unit, it rides that PR; several, one consolidated pass on a docs branch.

built-in: impeccable · DESIGN.md

one file adapts the engine

Produced by init, validated against a schema. validate-config.sh checks shape; verify-init.sh checks the generated files on disk.

// .claude/ship-it/config.json
{
  "source": { "tracker": {
    "type": "linear",
    "idPrefix": "FRA-" } },
  "planning": { "enabled": true,
    "postBack": true, "depth": "adaptive" },
  "verify": [
    "node_modules/.bin/biome check {changedFiles}",
    "node_modules/.bin/tsc --noEmit" ],
  "concurrency": { "maxLanes": 4 }
}
repomainBranch · mergeStrategy · slug
sourcedefault + tracker (type, project, team, idPrefix)
houseRulestext, or @AGENTS.md, injected into every worker
safetyhard rails carried into every worker prompt
verifycommands run in the worktree · {changedFiles}
worktreeenabled · root · prepare · qaNotes
concurrencymaxLanes · the parallel lane cap
planningenabled · postBack · depth (light/adaptive/full)
reviewreviewers[] (name, kind, ref) · applyWarranted
ciwatch · fixAttempts
docsenabled · jobs[] (name, mechanic, ref, target, appliesWhen)
prTemplatesections · verification (two-part QA rule)

say what you want shipped

ship all the todo issues plan this issue review my diff with main fix the CI on this PR ship all the todo issues plan this issue review my diff with main fix the CI on this PR

Run tokens, anywhere in the trigger

skip confirmno Phase 3 checkpoint, proceed straight through

no docsturn off the whole documentation phase for this run

skip planfall back to a thin scope pass instead of full plans

The checkpoint conversation

At the gate you can reply approve, or give feedback on any plan ("use per-child attributes, not the deep value") and the proposal is revised in place before anything is built.