ballast

한국어 문서 → · 简体中文 →

ballast is a Claude Code plugin that takes a goal you have no expertise in, builds it up from the foundations, and carries it through — then keeps every solved path so the next goal starts further along.

A few weeks into working with Claude, this piles up:

• You give the same correction again next month
• A settled decision reopens, or quietly changes
• You act on an unsourced answer, and find out later
• Your copy names a feature nobody built yet
• "Done" turns out to mean Claude said so
• What you shipped stalls its first reader
• Another model's tidy summary lands as fact
• You re-research what the project already wrote down

All eight have one cause: the weight sits in the conversation and nowhere else. Ships fix this by loading weight low in the hull, under everything else — that weight is called ballast. Here, it is rules, decisions, and verified facts riding in files, under the conversation.

And it accumulates. A method you only found after dead ends, a fact that survived checking, a vague problem finally cut into pieces — each one stays, and the next goal starts on top of it. You do not dig the same hole twice.

The smallest piece of that, live in a session — the first symptom on the list, with a rule you set once, weeks ago:

> add a setup script — npm install and we're done

[ballast] Standing rules that apply to this request:
- Use pnpm here: This repo uses pnpm. npm install has broken the
  lockfile twice; write scripts and commands with pnpm.

Claude: Using pnpm — your rule says npm broke the lockfile twice.
The setup script runs pnpm install.

The [ballast] block is the guaranteed part: "npm" matched your rule, so its full text arrived with this message. The reply follows what Claude was handed, not what it remembered.

Install

/plugin marketplace add svy04/ballast
/plugin install ballast@ballast

Two lines in Claude Code and you are done. The hook runs on the node (≥ 18) already on your PATH; the other twelve pieces are markdown skills. (The install id reads plugin@marketplace — both happen to be named ballast here.)

Using Codex instead? No marketplace there — a short manual setup (clone + one AGENTS.md block + the example catalog) carries the twelve skills over: docs/CODEX.md. Interactive Codex sessions run on convention (instructions, no enforcement), and codex exec gets real rule delivery through a bundled wrapper (same guide).

• Zero dependencies, zero network — the hook is one script, imports only fs/os/path; it reads local files and prints. ballast itself sends nothing anywhere (the optional verifier/researcher commands are local CLIs you configure, and the separate verify script only spawns node to re-run the hook)
• One hook + twelve skills — only the hook is code-enforced, and the docs label which is which
• Ships empty — the hook stays silent until rules enter your catalog; Quick start is how they get there
• Hook verified on 6 cases — keyword inject, silence on no match, block, legacy input fields, broken catalog says so, broken catalog still never blocks; run node hooks/scripts/verify-hook.mjs in a clone of this repo to re-check
• MIT — the whole mechanism is readable in an afternoon

How it runs

Hand it something big — /ballast:goal ship the pricing page — and every piece attaches to that one goal, in order.

It starts from what is already held. At the session's first reply, the recall skill has swept the files brain-init scaffolded on day one: index, knowledge, decisions, rules, skills. All five, and it keeps going past the first hit. The goal skill then splits the objective into branches and judges each one against that inventory.

A covered branch must use its file. The pricing rule already in the catalog and the brand facts in memory/knowledge/ come along as they are; nothing already held gets re-researched. A bare branch makes learning its first task.

A bare branch starts with questions, not answers. In a field you have never worked in, your sense of what matters is the least reliable thing you have. So the terrain scan collects what is argued, what is settled, and where beginners get burned, and lays them out as a map.

Then the branch is cut top-down into a pyramid of atomic pieces: no overlaps, nothing missing, each leaf small enough to verify on its own. A sub-field exposed mid-work is registered by name the moment it appears. Unfilled is allowed; unnamed is not.

Leaves fill bottom-up, and nothing bears weight unverified. Collection can be handed to a second CLI (researcher); its findings arrive hearsay, because it can fetch but it cannot rule. Every leaf faces the verify gate — refuted first, sourced, labeled — and what survives lands in memory/knowledge/.

The skeleton itself lives in memory/goal/pricing-page.md: the tree, its gaps, the next leaf. Tomorrow's session resumes from that file.

The work runs on prepared ground. Quality is set before the work, not patched after it. Mid-work you correct Claude once — "prices include VAT" — and pin writes that into the rule catalog; the hook delivers it with every message that matches, and only those. A standing rule rides along just when its keywords appear.

Anything said about the product outside the repo passes proof-standard first. External claims come from a truth file — a record of what verifiably works, evidence attached. No entry, no claim.

Done is a claim, so done passes a check. A zero-context reader walks the deliverable cold (rehearsal); the check passes when a round comes back stall-free, and that round's log is the evidence. A passed check is a file that exists, a test that runs, an output actually inspected.

What the goal solved then stays. Decisions go to the ledger, changed only by supersede. A procedure that will recur becomes a skill (skill-forge). A pause becomes a thirty-second return (checkpoint). Next quarter's pricing page opens on the solved path.

The same loop, drawn — boxes are pieces, cylinders are files that outlive the session:

flowchart TD
    G["a goal arrives — /ballast:goal"] --> M{"mobilize:<br/>already held in rules,<br/>knowledge, skills?"}
    M -- "held → using it is mandatory" --> W["the work"]
    M -- "gap → learn first" --> L["terrain scan → top-down skeleton →<br/>bottom-up leaves, each verified"]
    L -. "collection delegated<br/>(optional) — returns hearsay" .-> X["researcher"] -.-> L
    L --> V["verify gate — refute first,<br/>a second model may argue back"] --> K[("memory/knowledge/<br/>labeled, sourced")]
    K --> W
    W -- "you correct Claude once" --> P["pin"] --> R[("rule catalog")]
    R -- "hook delivers on every<br/>matching message" --> W
    W -- "a solved path recurs" --> S["skill-forge →<br/>a skill file"] --> W
    W -- "pause" --> C[("CHECKPOINT.md")] -- "30-second return" --> W
    W --> RH["rehearsal — a zero-context<br/>reader executes it"] --> D["done = a check passed"]

Only the hook in all of this is code: a script that runs on every prompt, whether Claude cooperates or not. The twelve skills are conventions — markdown instructions that hold exactly as well as Claude follows them. Conventions drift: CLAUDE.md is read once and recedes as the work goes on, and a convention recedes the same way.

ballast does not pretend otherwise. Its route from convention to enforcement is pin: when a convention slips, you correct it once, pin writes the correction into the rule catalog, and the hook delivers it from then on.

The pieces