Back to blog
Product

We made SpecShip smaller on purpose

A first install used to hand you 17 commands and a spec workflow you never asked for. Now it gives you just the wedge — the agent exploring the index instead of re-reading files — and the spec-driven depth is one opt-in flag away.

1 · retrieval /specship:explore 2 · code health specship maintainability 3 · intent (--sdd) /specship:spec · /specship:check

SpecShip had a problem most growing tools eventually get: it had become a firehose. You came to make Claude Code stop re-reading your files, ran specship install, and got seventeen slash commands, a "you must author a spec first" nudge hook, and a whole spec-driven-development workflow you never asked for. The thing that needed zero workflow change was buried under a stack of things that demanded one.

This release fixes that — not by removing power, but by ordering it.

The wedge is retrieval, and it needs nothing from you

SpecShip's one indisputable benefit is the cheapest to adopt: the agent explores a pre-built index instead of grepping and re-reading. No specs, no config, no new habits — you ask Claude Code a question and it stops thrashing. That's the wedge, and a first install should be only that.

So a default specship install now wires up the code-intelligence tools, the /specship:explore reads door, the status line, and the index. That's it. The MCP tools the agent actually uses are unchanged — what's gone from the default is the workflow tax.

The change is subtractive at the front and additive on demand. You meet a smaller surface, feel the benefit, and reach for depth when you want it.

Depth is one flag away

The spec-driven layer — authoring, implementing, the drift gate, the "spec first" steering — is the deliberate deep end, not the welcome mat. Turn it on when you're ready:

terminal
# default — retrieval only, zero workflow change
specship install

# opt in to the spec-driven layer when you want it
specship install --sdd

An existing spec-driven install is preserved on upgrade — turning the default into "retrieval only" never silently downgrades someone who already opted in.

Seventeen commands became three doors

The flat command list is gone. In its place are a few progressive doors, where sub-actions are chosen inside a door instead of cluttering your autocomplete:

  • /specship:explore — reads: explore an area, trace a flow, or get a change's blast radius.
  • /specship:spec — the whole intent loop: the funnel, a spec's detail, and new / fast / implement / review / triage / behaviour / domain.
  • /specship:check — the enforcement gate, the drift queue, link repair, and code health.

One of those sub-actions is new and aimed squarely at solo devs in a hurry: /specship:spec fast <description> records intent and heads straight to implementation, skipping the brainstorm-and-interview loop that /specship:spec new runs when the design isn't settled yet.

The second hit stopped lying

Once retrieval earns trust, the natural next step is read-only code health — it needs no specs and runs on any indexed repo. But specship maintainability used to bury you: a thousand dead-code guesses and a coupling list topped by artifacts (every method named set or now collapsed into one inflated hotspot). A gateway that floods you destroys the trust the wedge just built.

Now the default report leads with what's demonstrably accurate — oversized symbols, god-files, dependency cycles — ranked and capped. The noisier, lower-confidence signals (dead-code, raw coupling) move behind --deep, clearly labelled, and --json still returns everything tagged by tier so CI can choose what to gate on.

The shape of adoption now: install → the agent stops re-reading (wedge) → run specship maintainability for trustworthy code health (second hit) → specship install --sdd for specs, the gate, and generated tests when a team wants them (the deep end). Each rung is low-friction before the next.

None of the capability went away — the deep end is as deep as ever. What changed is that you no longer have to step into it to get the one thing you came for.

#adoption#onboarding#retrieval#dx
SE
Selva E.
Building SpecShip · graph, specs & harness
Works on the parsing, storage, and spec layers of SpecShip. Spends an unreasonable amount of time thinking about edges.