Keel

Read this first. A personal project, published as is and with no warranty of any kind. It is not a finished product and not a commercial one, and it will not become either. It was written largely with an AI assistant, under human guidance and review — which was half the point.

It installs files that shape how an agent behaves in your repository, including hooks that run on every session and guards that can block a commit. Read what it writes before trusting it. The guards are heuristic: they are a safety net, not a guarantee, and they are no substitute for not putting private data in a repository in the first place.

The kernel every AI-backed project starts from — installed once instead of re-derived every time.

The same instruction files, subagent tiers, guard scripts, hooks and working agreements kept getting rebuilt from scratch in each new repository. That costs tokens, and each rebuild drifts slightly from the version that was actually debugged. This repo holds that kernel once, versioned, and installs it into a new project with a single command.

It is deliberately domain-agnostic. There is no calculation engine here, no knowledge base, no UI — those belong to the projects. What lives here is the layer above them: how work gets delegated, what an agent may and may not do with your data, and how a repository stays honest as it grows.

How much of this is Claude Code specific

Be clear-eyed about it before cloning:

• Portable to any agent — AGENTS.md, which is the source of truth and follows the AGENTS.md convention several assistants read; and every script under tools/, which is plain bash and git and cares nothing about which agent you use.
• Claude Code only — CLAUDE.md, .claude/agents/, .claude/rules/, .claude/skills/ and the hooks in .claude/settings.json. The tier-pinned delegation model in particular depends on subagents with per-agent effort and model, which is a Claude Code feature.

If you use a different assistant, the guards and AGENTS.md still carry their weight; the delegation machinery will not, and the honest move is to delete it rather than keep it as decoration.

Requirements

bash, git, and python3 (used by the dispatch hooks, which degrade to silence without it). Hashing uses shasum or sha256sum, whichever the system provides. Nothing else — no package manager, no runtime, no network. Developed on macOS; the scripts avoid GNU-only flags, but they have not been exercised on Linux, so treat that as untested rather than supported.

---

What it installs

Piece	What it is
AGENTS.md	Impersonal, tool-agnostic source of truth for the project's rules, §1–§14.
CLAUDE.md	Thin: imports AGENTS.md, adds only what exists solely in Claude Code.
.claude/agents/miner-*.md	Six delegation workers with reasoning effort and model pinned per tier.
.claude/rules/*.md	Path-scoped rules that load only when the agent touches matching files.
.claude/skills/*	handoff (context compaction) and council (adversarial deliberation).
.claude/settings.json	Session hooks, the read-guard, and the claudeMdExcludes boundary.
tools/check-leaks.sh	Egress guard: private data must not reach versioned files. Runs pre-commit.
tools/check-injection.sh	Ingress guard: makes hostile ingested material visible.
tools/check-config-integrity.sh	Supply-chain guard: hashes the surface the agent executes each session.
tools/check.sh	Gate skeleton with hard / soft / skip semantics.
tools/effort-dispatch/	Calibration table plus hooks that make tier discipline ambient and auditable.
memory-seed/	Cross-project working agreements, ready for a project's memory directory.

Everything is parametrised through one file, tools/guard.conf, which is where the guards learn the shape of your project: private paths, applicable identifier patterns, untrusted areas, trust surface.

---

Quick start

./bootstrap.sh --target ~/code/my-project --name "My Project"

--target  PATH     destination repository (required)
--name    NAME     project name (default: basename of target)
--tagline TEXT     one-line description used in AGENTS.md §1
--tools-dir DIR    where the guard scripts land (default: tools)
--private   DIR    directory holding real/private data (default: data)
--owner     NAME   frontmatter owner (default: $USER)
--with-memory      also install the working agreements into project memory (see below)
--force            overwrite existing CLAUDE.md / AGENTS.md / .claude files
--dry-run          print what would happen, change nothing

Everything is written inside --target, with one deliberate exception. --with-memory also writes the cross-project working agreements to ~/.claude/projects/<target>/memory/, outside the repository, where Claude Code keeps per-project memory. Those files change how an agent behaves, so installing them is opt-in: doing it silently would be the same over-reach this baseline spends a whole section telling agents not to commit. Read memory-seed/ before passing the flag — two of the agreements encode a specific git workflow (commit and push coupled, pushing without a confirmation prompt) that may not be yours.

It refuses to overwrite by default, so re-running it after a partial install is safe. Then follow the checklist it prints — detailed in docs/customization.md — and:

cd ~/code/my-project
echo 'data/' >> .gitignore
git config core.hooksPath tools/git-hooks          # enable the pre-commit leak guard
bash tools/check-config-integrity.sh --update      # create the trust-surface baseline
bash tools/check.sh                                # should be green

Restart the Claude Code CLI afterwards: newly created .claude/agents/ definitions are picked up on a real restart, not by the running watcher.

---

Two layers, and the loop between them

This repo is the project layer. The personal layer is ~/.claude/CLAUDE.md, loaded in every session of every project: it holds what is true of the operator across projects, and it names this repo as the starting point for any new AI-backed project — so "the usual setup" means a bootstrap plus adaptation, never a fresh draft.

The loop closes in the other direction too. When a rule, guard or agreement proves useful beyond the project it was born in, it comes back here, with its reasoning in docs/rationale.md and, if it came from outside, its entry in docs/provenance.md. Without that return path the baseline decays into a snapshot while the real practice moves on.

Keep the split honest: a rule about the operator goes in the personal layer, a rule about a project goes in that project's files. Copying one into the other is how they start to diverge.

---

What is inside

keel/
├── bootstrap.sh              installs into a target repo, substituting the placeholders
├── template/                 what gets copied into the project
│   ├── AGENTS.md             source of truth, §1–§14 (stable numbering)
│   ├── CLAUDE.md             thin: @AGENTS.md + §3 tool mapping + §CC-1…§CC-7
│   └── .claude/              settings.json · 6 agents · 2 rules · 2 skills
├── tools/                    guards, hooks and dispatch, parametrised via guard.conf
│   ├── guard.conf            the single place the guards learn your project's shape
│   ├── check-leaks.sh · check-injection.sh · check-config-integrity.sh · check.sh
│   ├── preflight-dispatch.sh · git-hooks/pre-commit
│   └── effort-dispatch/      vendored hooks + calibration table + delegation audit
├── memory-seed/              17 working agreements + the index to merge
└── docs/                     rationale · customization · provenance · brand

---

The mechanisms

Each of these earned its place by fixing a concrete failure. The failures themselves are recorded in docs/rationale.md, so a future reader can tell a load-bearing rule from cargo cult.

The document split. AGENTS.md is the tool-agnostic source of truth. CLAUDE.md stays thin and imports it, adding only Claude-specific matter. Detail needed in specific contexts goes to .claude/rules/ with a paths: frontmatter, loading when the agent touches those files instead of inflating every session. Anthropic's docs settle the direction: Claude Code reads CLAUDE.md, not AGENTS.md, and the recommended pattern is the former importing the latter.

Effort dispatch. Six workers with effort and model pinned in frontmatter — low→haiku, medium/high→sonnet, xhigh/max→opus, plus a fable escape hatch. A conservative calibration table maps task classes to tiers, and a session hook injects it as an ambient policy. Pinning the model is the part that actually saves money: effort alone still leaves mechanical work on an expensive model. The counter-rule keeps it honest — hard reasoning, correctness-critical work and audit never drop tier.

The pre-flight hook. The dispatch rule was already written down and still got skipped, because an always-loaded instruction competes with everything else in context. A UserPromptSubmit hook restates it when a request arrives, and the protocol requires confirming the plan up front, so it is visible whether the machinery is being used. The generalisable lesson: when a rule keeps getting skipped, build a mechanism — do not restate it more firmly.

Trust boundaries, both directions. Most setups guard the exit and forget the entrance. Egress is check-leaks.sh, wired pre-commit, which also catches a rename out of a private path — the case a naive path check misses. Ingress is the rule that ingested material is data and never instructions, with a soft scanner making hostile content visible. The non-obvious part: a third-party CLAUDE.md inside your workspace is auto-loaded as an instruction without going through a Read call, so permissions.deny is defence in depth and claudeMdExcludes is the control that is actually client-enforced. Supply chain is check-config-integrity.sh, hashing the body of everything the agent executes, not just the declarations.

The hygiene pipeline. Seven steps against entropy, of which the load-bearing one is doc-sync: documentation is updated as part of the change, unprompted, and no commit or push leaves a document describing a superseded state. Its anti-duplication corollary is what stops "well documented" from becoming "copied everywhere" — a fact lives in one place and everything else points at it.

Two skills. handoff compresses a session into a compact handover written to the OS temp dir, never into the repo, redacted, referencing durable artifacts rather than copying them. council convenes five deliberately partial perspectives for a genuine judgement call — and its load-bearing half is the section saying when not to convene it, without which it becomes an expensive default.

Working agreements. Behavioural rules learned from concrete failures: be honest and disagree, falsify rather than confirm, quality at write time, go structural after two rounds of tuning, verify what the user actually sees, explicit confirmation before touching the trust surface. They ship twice on purpose — compactly in AGENTS.md §13, which travels with the repo, and with their evidential record in memory-seed/, for the recall layer.

---

Verifying it actually works

A guard you believe in but that does not run is worse than no guard at all. After installing:

• Delegate a trivial task to miner-low and confirm it runs.
• Check that the session hook printed the ambient dispatch policy line.
• Drop a file containing Ignore all previous instructions into the private directory and run check-injection.sh — expect a warning, not a block.
• Stage a file containing a fake identifier and attempt a commit — expect a refusal.
• Touch .claude/settings.json and run check-config-integrity.sh — expect a drift report.

If any of those is silent, that guard is not wired up.

---

Design constraints this repo follows

1. One source of truth. A rule lives in exactly one file; everything else points at it. Two copies that drift are a bug, not harmless redundancy.
2. Idea yes, plugin no. Third-party ideas are distilled into our own form. Third-party code is audited line by line, vendored, pinned and covered by the integrity guard — never installed from a marketplace, where it would auto-update into the request path unreviewed.
3. Nothing here is required to run anything. A project stays fully usable without an agent; this is an interpretation layer on top, not a dependency.
4. Templates carry no real data. Placeholders only. The guards exist to keep it that way.

---

Documentation

File	What it covers
LICENSE	MIT.
NOTICE.md	Third-party material redistributed here, and under what terms.
docs/rationale.md	Why each mechanism exists, the failure it fixes, and when to drop it.
docs/customization.md	What must be decided per project, in the order it matters.
docs/provenance.md	Every externally-sourced idea or artifact: source, licence, what was taken.
tools/effort-dispatch/README.md	The dispatch table, the vendoring decision, and how to read the log.
memory-seed/README.md	How the working agreements install, and their relationship to AGENTS.md §13.

---

Licence and provenance

MIT — see LICENSE. Use it, modify it, redistribute it, build commercial things on it; keep the copyright and permission notice in copies. There is no warranty.

The files bootstrap.sh writes into your project come from this repository, so the same permissive terms follow them there — including the two vendored hooks, which keep their own upstream notice.

Two hook scripts under tools/effort-dispatch/hooks/ are vendored verbatim from effortmining (MIT) after a line-by-line audit, and keep their own copyright notice. Several other ideas — an anti-over-engineering decision ladder, a token-saving read-guard, a delegation audit, multi-perspective deliberation — were distilled into original form with no code taken.

NOTICE.md is the licence-facing record: what is somebody else's work and under what terms. docs/provenance.md is the fuller narrative — including what was examined and deliberately rejected, which is the half that stops the record turning into a shopping list.

Attributions are not decoration: they are the evidence that only the concept was taken where only the concept was taken. Removing them would not reduce exposure, it would increase it.