ship-code

Anti-slop agentic coding workflow for Claude Code and Codex. 3 agents, no enterprise theater.

Core philosophy: Slop is an engineering problem, not an LLM problem. If an agent produces bad code, fix the environment — never patch the output.

Install

npx ship-code@latest

Prompts you to install globally (all projects) or locally (this project only). Then restart Claude Code and type /ship-code: to see all commands.

By default, the npm installer keeps the existing Claude Code behavior. For Codex, install the bundled Codex skill:

npx ship-code@latest --codex --global

Or install both Claude Code commands and the Codex skill:

npx ship-code@latest --all --global

Codex can also install directly from GitHub with its skill installer. Ask Codex:

Install the Codex skill from https://github.com/aliprogrammin/ship-code/tree/main/skills/ship-code

Then restart Codex and ask it to use $ship-code.

Flags:

npx ship-code@latest --global    # global, no prompt
npx ship-code@latest --local     # project-only, no prompt
npx ship-code@latest --codex     # install Codex skill
npx ship-code@latest --claude    # install Claude Code commands (default)
npx ship-code@latest --all       # install Claude Code + Codex
npx ship-code@latest --uninstall # remove selected target

Upgrading from an older version

v4+ removed the loop, run, plan, and queue commands — they're all absorbed into state-aware ship. The installer now cleans stale command/agent files on upgrade, so:

npx ship-code@latest          # global
# or
npx ship-code@latest --local  # this project only

Then restart Claude Code so slash commands reload. After that, /ship-code: should show only five commands.

If you upgraded before v4.0.3 and still see old commands, the installer didn't clean up. Do it manually once:

# Globally installed
rm -rf ~/.claude/commands/ship-code
rm -f  ~/.claude/agents/ship-*.md

# Or project-local
rm -rf .claude/commands/ship-code
rm -f  .claude/agents/ship-*.md

# Then reinstall
npx ship-code@latest

Also wipe any pre-v4 runtime cruft from your project (the old prompt-staging folder):

rm -rf .ship/_prompts

Your .ship/plan.md, config.json, HARD_BLOCKS.md, and issues.md stay — they're your project's state, not plugin files.

Upgrading from v4.3 or earlier: v4.4 reshapes .ship/issues.md from a "blockers table" (that nobody wrote to) into an append-only ship ledger that captures every shipped feature — including the ad-hoc work that used to silently drift out of plan.md. Existing issues.md files keep working: new entries follow the new schema and the old table at the top is left untouched. v4.4 also drops dead fields from .ship/config.json (gates.* and issue_log) — they were never read by any agent. You can leave them in or delete them; ship-code ignores them either way.

Behavior change to be aware of: shipped feature briefs are now pruned from plan.md when they ship — the richer history lives in issues.md. If you used to scroll through plan.md to see what shipped, scroll through issues.md instead (or grep "^## f" .ship/issues.md for a one-line-per-feature view). plan.md is now strictly the forecast — only pending, in-progress, and blocked work.

/ship-code:quick also now produces two commits per task: the fix itself, then a chore(ledger): f<N> commit that records it in the ledger. If you don't want quick tasks in the ledger, skip step 7 in commands/quick.md for that invocation.

Commands

Claude Code gets five slash commands. ship is state-aware and absorbs the old loop, run, plan, queue.

| Command | What it does | |---|---| | /ship-code:init | Set up hooks, gates, config, hard blocks (works on empty repos) | | /ship-code:ship | State-aware workflow — interview, plan, execute, or resume | | /ship-code:quick <desc> | Small ad-hoc task — gates still enforced | | /ship-code:verify | Run graded quality evaluation standalone | | /ship-code:help | Show the guide |

ship takes optional arguments:

• /ship-code:ship 3 — run just feature 3
• /ship-code:ship add "OAuth" — add a feature to the plan
• /ship-code:ship --plan-only — plan without executing

In Codex, there are no slash commands. Use natural language:

• use $ship-code to init this project
• use $ship-code to ship this feature: ...
• use $ship-code quick to fix ...
• use $ship-code verify

How It Works

You describe what to build
        │
        ▼
  Interview — checkpointed to .ship/draft.md (survives /clear)
        │
        ▼
  Planner:
   - Prior-art sweep → .ship/prior-art.md
   - Scaffolds stack if repo is empty
   - Writes feature briefs → .ship/plan.md
        │
        ▼
  For each feature, Generator-Evaluator loop (max 3 rounds):
   - Generator builds, runs gates, commits
   - Evaluator scores 1-5 on 5 dimensions
   - <3 on any dimension → revise
   - >=3 on all → ship
        │
        ▼
  You review. Push when ready.

ship is state-aware — no plan means interview, pending plan means resume, shipped plan means prompt to add features.

The 3 Agents

| Agent | Role | |---|---| | Planner | Creates feature briefs — what + why, never how | | Generator | Autonomous builder — explores, decides, implements | | Evaluator | Adversarial reviewer — graded rubric, not pass/fail |

Why only 3?

Modern AI models don't need micro-managed specs with line numbers and step-by-step instructions. They need:

• Clear goals (Planner)
• Autonomy to implement (Generator)
• Adversarial quality checks (Evaluator)

Everything else — complex queue systems, XML task specs, separate research agents, wave orchestration, sprint contracts — is dead weight that actually limits the model's ability to self-correct.

Evaluator Rubric

Every feature gets scored 1-5 on:

| Dimension | What it measures | |---|---| | Correctness | Does it meet requirements? | | Design | Does it fit existing patterns? | | Code quality | Is it clean and readable? | | Test quality | Are tests meaningful? | | Security | Is it safe? |

• All >= 3 → SHIP
• Any = 2 → REVISE (generator gets specific feedback)
• Any = 1 → REJECT (generator redoes from scratch)

Config

.ship/config.json:

{
  "workflow": {
    "parallel_features": true,
    "max_eval_rounds": 3,
    "skip_permissions": true
  }
}

The Golden Rules

1. Never fix bad output. Reset and fix the brief — not the code.
2. 3 agents, 3 roles. Planner plans, generator builds, evaluator reviews.
3. Gates before everything. Lint + types + tests pass 100% before any commit.
4. Quality is graded, not binary. Passing gates is the floor, not the ceiling.
5. Generator decides the how. Briefs say what and why. Implementation is autonomous.
6. Escalate, don't improvise. If stuck, stop and ask.

File Structure

.ship/
├── config.json        # Settings + stack
├── HARD_BLOCKS.md     # Defaults + rules ingested from CLAUDE.md (agents read this before every commit)
├── issues.md          # Ship ledger — append-only history of every shipped feature (f1, f2, … fN)
├── draft.md           # Interview checkpoint (transient — deleted when plan.md is written)
├── prior-art.md       # Competitor/OSS sweep (written once by planner)
└── plan.md            # Forecast — pending/in-progress/blocked feature briefs (shipped entries are pruned to the ledger)

plan.md vs issues.md — plan.md is the forecast: what's coming next. When a feature ships, its entry is moved to issues.md and removed from the plan. This keeps plan.md a clean to-do list and makes issues.md the single source of truth for project history — including /ship-code:quick tasks and any ad-hoc work that never went through the planner.

Each ledger entry records the title, date, source (plan/quick/adhoc), commit hash, status, evaluator scores, files touched, and any non-obvious decisions. Full entry format lives in commands/ship.md (Step 4a).

License

MIT