Keel

Keel keeps a way of building software in one place, and carries it into every project that uses it.

The way of working came from four projects: isocan, ledger, duo and cajones. Each one copied it from the one before, by hand, and the copies drifted. Keel makes it one versioned thing. It does three jobs:

1. It is the source of the practice. Ways of working, each with the failure it prevents, live in practices/.
2. It carries changes out to projects. keel init and keel adopt install the practice. keel update and keel fleet update bring each new practice version as a pull request a person reads, or a local diff with keel update --local.
3. It is where lessons come home. A project sends what it learned (keel lessons). Keel turns that into proposals (keel learn), a person decides, and the next release carries the change to everyone.

A project never depends on keel at runtime. Its workflows run from its own repo, with its own copies of the scripts they need.

If you are an agent, run keel --agent-help first. It prints a cold start: what keel is, every verb on one line, and the rules that bite. keel --agent-help opens the details, and all prints everything. It ships with the CLI, so it always matches the keel you have. The rest of this page is the same story, told for people, and the guides tell it one situation at a time.

Every keel project carries a short keel skill at .agents/skills/keel/SKILL.md (linked from .claude/skills/keel). An agent working there finds keel and runs keel --agent-help without being told.

Install

Node 24.21.0 or later, and git. No registry, no build step.

git clone https://github.com/dalmaer/keel ~/code/keel
npm install -g ~/code/keel

Then keel --version prints the CLI’s version, its commit, and the practice version it carries. The global install is a link to the checkout, so updating keel is a git pull there, and keel update does that for you first when the checkout can fast-forward cleanly.

The CLI version moves with every release. The practice version moves only when practices, migrations or the lessons catalogue change; a CLI-only release leaves projects current. See Keep the fleet current.

What a project gets

A project that uses keel carries .keel/keel.json, which records:

• its name;
• the gate command that must pass (check);
• the practice version it is on;
• the practices it has switched on;
• where its nightly health page goes (health, default docs/health; keel doctor flags a directory the project git-ignores);
• how the test ledger judges a slower test (tests: window 20, factor 2, floorMs 200);
• anything it does its own way, as a local variant with a reason.

Existing agent guides are preserved: adoption selects AGENTS.md, then CLAUDE.md, or an explicit --guide . See the adoption guide.

Projects can also keep GitHub milestones as their plan with "phases": {"source": "milestones"}. Keel projects them into next, the board and the night without editing GitHub or claiming acceptance from closure. Local phase-homing in Loop and proof writeback are inactive for that source; archived phase files remain unchanged.

The practices:

Who owns which file. Every file keel writes is one of three kinds:

• Managed files are keel’s. They are re-rendered on update. .keel/lock.json records what keel wrote.
• Blocks are the `` regions of the selected agent guide. The rest of that file is the project’s.
• Seeded files (your phases, goals and lessons) are written once, and are yours from then on.

If you change a managed file, keel treats it as signal, not an error. keel render refuses to overwrite it. keel doctor shows the diff and offers three moves: keep yours (eject), take keel’s (restore), or send yours home as a lesson.

An edit that keel has since made too, such as Renovate bumping an action in your copy of a keel workflow before keel ships the same bump, is not treated as yours: the next update simply takes keel’s file.

The loop

1. Start. keel init in an empty directory, or keel adopt in an existing repo. Adopt switches on only what the repo already satisfies. Everything else is recorded as a local variant with a proposal, never overwritten and never faked.
2. Work. Phases are the plan. keel next lists the phases that are ready, and which of them another session already holds. A session takes one with keel phase claim before it builds, so two sessions never build the same phase. In Claude Code, /conduct walks them: one phase at a time, claimed first, proof verified, one commit each.
3. Review. A reviewer reads the PR (with the cross-review practice on, the other provider does), and keel review makes sure every comment is validated and answered. A review that is still drawing findings after three rounds stops there: keel review hands you the choice (merge with the rest tracked, split, or close) with the open findings sorted. See Conduct a phase for the whole path.
4. Overnight. The project’s own nightly runs scripts/keel/improve.mjs. It writes a dated health page, opens one PR with it, and proposes one change. You read it in the morning.
5. Lessons go home. keel lessons files the project’s new lessons, its edits to keel’s files, and practice-shaped commits as issues on keel’s inbox (a private repo, so a private project’s lessons stay private), each exactly once.
6. At home. keel learn turns those issues, and any upstream source that moved, into proposals. A person decides. keel release cuts a version.
7. Out again. keel fleet update opens the update PR in each project that’s behind. keel update runs it: the CLI first, then migrations, re-render, the project’s own gate, and a byte-for-byte restore if anything fails.

keel fleet shows every project at once: practice version, health, CI, unsent lessons, and open machine PRs.

Guides

Each guide starts from a situation, says why keel does what it does there, then gives the commands and every flag by the reason you’d pass it.

The verbs

Every verb takes --json. Exit codes are the same everywhere:

• 0: done.
• 1: it ran and found something.
• 2: usage error, or not where it can run.
• 3: it needs a yes. Run it again with --yes.

In a project:

At home, in keel’s own checkout:

Across projects:

Where a person decides

Keel stops and asks, with the price, before anything that:

• creates a repo;
• sets a secret or changes a repo setting;
• opens a PR or an issue elsewhere;
• spends money or model tokens on a schedule.

Outward verbs print their plan and exit 3 until they get --yes.

Judgements are a person’s too. An agent may propose a lesson, a rank or a fix, and keel learn decide and Loop’s decide are a person’s. Nothing marks a phase lived-in except someone who used the thing.

Working on keel itself

Keel is built with its own practice. AGENTS.md is the working guide, docs/design.md is the argument, and docs/ROADMAP.md is where it stands.

npm run next     # next phase and action
npm run check    # tests, roadmap, rendered practices and inbox views
npm ci --ignore-scripts  # development-only type tooling
npm run typecheck        # checked JSDoc, no emitted JavaScript

In Claude Code, /conduct walks the phases.

The CLI still runs directly from its .mjs source with zero runtime dependencies. Type checking covers selected production evidence contracts; it does not compile the CLI or change what adopted projects must install. See measuring CLI cost and checking contracts.

Lineage and license

The practice was invented in isocan, ported to ledger, then to duo and cajones. Keel adapts isocan’s conduct skill and its measurement ideas under Apache-2.0, and credits them in NOTICE and in each adapted file’s header. Keel itself is Apache-2.0.

keel time --weeks 8 --json shows retained gate/test timing, machine load coverage and local worked-around counts. Timing and the night.

Adoption previews include monthly weighted-minute estimates for newly added workflows, with history and coverage. keel improve reports ci_minutes; ci.gateWorkflow can reuse completed CI on the exact clean default-branch SHA. These usage estimates are not invoices. CI usage and reuse.