Keel Downstream Project Contracts

Installing Keel into a repository gives you the engine. Authoring AGENTS.md and INSTRUCTIONS.md inside that repository is what turns the engine on for day-to-day work.

Those two files are the downstream operating contract. They tell humans and AI harnesses how to use the board, which commands are canonical in this repo, what proof counts, and which local wrappers or validation surfaces matter here.

Operating Layer

Keel becomes the project-management engine

A repo does not adopt Keel just by installing the binary. It adopts Keel when every human and agent is taught to orient, pull work, prove work, and close work through the board.

Canonical Core

Keep the engine discipline recognizable

The tactical loop, evidence bar, health checks, and lifecycle rules should stay recognizable across downstream repos so the board behaves consistently.

Project Surface

Adapt only what the repo actually owns

Command wrappers, proof contracts, project overviews, and local workflow helpers belong in the downstream copies because they depend on the actual repository.

Start with keel new

The preferred bootstrap is now keel new:

keel new my-project
cd my-project

That scaffold gives you:

• the board in .keel/
• git hook installation at the commit boundary
• a starter keel.toml with workflow defaults, roles, and lanes
• root-level downstream foundation docs such as CONSTITUTION.md, POLICY.md, ARCHITECTURE.md, USER_GUIDE.md, AGENTS.md, INSTRUCTIONS.md, GEMINI.md, and CLAUDE.md

If one of those foundational docs already exists, keel new asks before replacing it. That makes it safe to adopt Keel inside an existing codebase without silently erasing local operating language.

The two-file operating contract

File	Job	Why it matters
AGENTS.md	Short, high-authority entry contract	It sets priorities, points to the right command surfaces, names the foundational documents, and tells an agent how to behave before it does anything clever.
INSTRUCTIONS.md	Detailed procedural manual	It defines the tactical loop, role-specific workflows, hygiene rules, lifecycle sequencing, and the exact command vocabulary that should be used in the repo.

AGENTS.md should be easy to scan. INSTRUCTIONS.md should be the place where ambiguity goes to die.

One example of upstream intent worth preserving exactly is heartbeat semantics: the pacemaker is derived from Git/worktree activity, keel heartbeat is the inspection surface, and dirty repository energy is warning-level loop debt that should be closed at the commit boundary. Downstream copies should preserve that contract instead of inventing repo-local heartbeat files or wake rituals. See Heartbeat And Pacemaker for the canonical public explanation.

If a downstream repo participates in a Mission Stack, preserve that contract too: cross-repo work should enter through mission requests and reactor negotiation, and any outside execution in that repo should use a managed git worktree on stack/<id> instead of the repo's primary checkout.

What stays upstream and what changes downstream

Upstream Keel

Canonical engine contract

• Core principles such as gardening first, derived-heartbeat hygiene, and notification discipline.
• The tactical loop, role separation, lifecycle expectations, and doctor-first hygiene.
• Canonical board operations such as mission, voyage, story, bearing, flow, doctor, and pulse.
• The resolution hierarchy that points back to ADRs, policy, architecture, and planning artifacts.

Downstream seam

Copy first, adapt second

Do not rewrite the engine contract from memory. Start from upstream Keel, then change only the repo-facing seams that must describe your codebase, wrappers, proof requirements, or local workflow tooling.

Downstream Repository

Local operating surface

• A repo-specific opening that makes it clear Keel is the project-management engine for this codebase.
• Repo-local wrapper commands such as direct `keel ...` usage or helper recipes like `just mission` and `just screen`.
• Proof contracts tied to the project outcome, runtime, or deployment shape the repo is trying to validate.
• Project overview, directory map, delegation rules, and harness-specific helpers that belong to the codebase rather than the engine.

This is the key distinction: upstream Keel owns the board discipline, while the downstream repository owns the local operating surface.

The port adaptation pattern

The port repository is a good example of a downstream adoption that preserves the engine while changing the project-facing seams.

Surface	Upstream Keel	port adaptation	Why it changes
Opening frame	"Keel is an engine with strict constraints."	"This repository uses Keel as its project management engine."	The downstream copy needs to center the project repo, not the Keel repo itself.
Command path	just keel ... for board work inside the Keel source tree	direct keel ..., plus wrappers such as just mission, just screen, and just port	Downstream repos choose the command surface that matches their own shell and wrapper conventions.
Proof guidance	generic board integrity and verification expectations	a repo-specific Mission Proof Contract tied to Port's runtime claim	Downstream proof must answer the repo's actual product question, not just the board's health.
Delegation rules	general engine guidance	mission steward and worker-context guidance tuned for Port	Repos can add coordination rules when their harness or workflow needs stricter separation.
Repo context	Keel foundational docs and architecture map	project overview, board directory, and repo-local command tables	Agents need to know what this repository is and where its important surfaces live.

The shape to copy is not the literal wording. The shape to copy is:

1. Keep the engine contract recognizable.
2. Rename or reframe only the parts that must describe this repo.
3. Add project-specific sections only when they govern real operating behavior.

How to adopt the contract in your own repo

1. Start from keel new . or keel new <repo-name> instead of authoring the contract from a blank page.
2. Rewrite the opening frame so it clearly says your repository uses Keel as its project-management engine.
3. Replace command paths with the repo's real command surface, including just wrappers, dev-shell commands, or runtime helpers.
4. Add project-specific proof rules only when the repo has a real claim to validate, such as a runtime path, deployment check, or artifact contract.
5. Add project overview and directory maps so new agents can orient without searching the entire tree.
6. Keep harness-specific extras such as CLAUDE.md or GEMINI.md adjacent to this contract, not in place of it.

tip

keel new scaffolds AGENTS.md and INSTRUCTIONS.md with PROJECT-SPECIFIC blocks on purpose. Those are the seams you preserve when you sync newer upstream Keel versions.

tip

If a downstream repo supports multiple AI harnesses, keep AGENTS.md and INSTRUCTIONS.md as the canonical repo-wide contract. Put harness-specific setup in separate files that point back to the same board rules.

The failure mode to avoid

The common mistake is to "customize" the files so heavily that the downstream repo no longer behaves like Keel at all.

When that happens, the board model becomes optional, lifecycle commands drift, and every agent ends up re-learning the repo from scratch. Keel stops being the project-management engine and collapses back into a disconnected CLI.

The safer pattern is narrower: preserve the engine, adapt the seam.

Next step

Once a repo has adopted the contract, the next responsibility is maintenance. Read Upgrade Keel And Sync Upstream Instructions for the safe way to absorb upstream changes without deleting downstream intent.