Deep dives on knowledge graphs, harness engineering, spec drift, token economics, and the workflow design behind SpecShip — written by the people building it.
Hands-on, start to finish: connect your board, pick a ticket into a spec, publish it back as a Story with Sub-tasks, implement it behind the plan gate, and let the board move itself to In Review and Done — then the advanced knobs: transition control, workflow validation, release stamping, corporate TLS, and headless secrets.
SpecShip’s first outbound integration turns a JIRA ticket into a real spec — summary to title, description to body, subtasks to acceptance criteria — implements it behind the plan gate, and raises a PR only when the tests pass, with the issue assigned, transitioned, and linked back. Local-first, secret-safe, one issue at a time.
The desktop dashboard shipped ~640 npm packages — bleeding-edge Angular, a 73 MB code editor, native build tooling — and choked behind locked-down enterprise registries. We replaced it with a server-rendered UI that ships inside the server itself: well under 250 mainstream packages, no native builds, the same look.
Explore an area, trace a flow across dynamic-dispatch hops grep can’t follow, or get a change’s blast radius — through a single door. You name the symbols; the graph hands back their source, already Read. Six tools, one entrance, and the agent never has to pick.
Browse the spec funnel, author or fast-path a requirement, implement it in an isolated worktree, review it against a rubric, triage a bug to the spec it belongs to, or capture a domain fact — all behind one door. Intent becomes a first-class artifact, and the spec is the contract.
Run the enforcement gate, work the drift queue, repair a broken spec↔code link, and read graph-derived code health — one door that keeps intent and code honest. Drift is a signal, not a failure, and the gate only bites when you ask it to.
Two prompts asking for the same change can cost 10× apart. SpecShip now grades every prompt in a session — does it name a concrete target, is it scoped, is it cache-friendly, did it go structural or brute-force — and hands you the one-line fix. Rule-based, no LLM, and it never invents a number it can’t measure.
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.
Your status line is prime real estate — so what earns a spot? SpecShip’s segment shows index sync state, drift, and how many times it was actually called. Not “tokens saved”: that number has no honest source at runtime, so we don’t fake it.
On a large codebase, the “why” lives in people’s heads — the ubiquitous language, the rules, the decisions. SpecShip captures it as you work, links it to the specs and code it governs, and keeps it honest with drift. New team members read the domain, not the tribe.
A file tree tells you where code lives. It says nothing about what calls what, which test covers which function, or which requirement a symbol satisfies — exactly where agents waste their time.
Branches and stashes share one working tree; clones and containers are heavyweight. A git worktree is the sweet spot — a real isolated checkout that shares the repo, so a failed agent run never touches yours.
Letting an agent write code is easy. Stopping it from quietly rotting your architecture is the hard part. SpecShip turns the graph into checks — coupling, god-files, cycles, layering rules — composed into one opt-in CI gate.
Specs are nodes with edges to the code that satisfies them. Rename that code and the edge breaks — which is exactly the signal you want, landing in a review queue instead of silently shipping.
A workflow that plans, implements, and tests in an isolated worktree — but pauses at a human gate before anything merges. Real control flow, not a one-shot prompt.
A "find the callers of this function" task, run two ways: grep-and-read versus one structured graph query. The token bill between them is not close.
Most of a long session’s token bill is cache reads, not fresh input — until your system prompt drifts and the hit rate falls off a cliff. Here’s how to see it.
Managed, user, project, and subdirectory memory all stack — with @imports resolving across them. When the agent surprises you, the answer is usually a line you forgot was in scope.
Occasional deep dives on what we’re building and why — graphs, specs, agents, and the economics of context. No noise.