keel ⚓

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/hero.svg">
  <source media="(prefers-color-scheme: light)" srcset="docs/assets/hero-light.svg">
  <img src="docs/assets/hero-light.svg" alt="keel — drive every issue to merged on one fixed backbone: 13 steps, 28 extension slots, 16 /keel commands, 100% covered">
</picture>

# keel ⚓

[![CI](https://github.com/berkayturanci/keel/actions/workflows/ci.yml/badge.svg)](https://github.com/berkayturanci/keel/actions/workflows/ci.yml)
[![coverage](https://img.shields.io/endpoint?url=https://berkayturanci.github.io/keel/coverage-badge.json)](https://berkayturanci.github.io/keel/coverage/)
[![CodeQL](https://github.com/berkayturanci/keel/actions/workflows/codeql.yml/badge.svg)](https://github.com/berkayturanci/keel/actions/workflows/codeql.yml)
[![PyPI](https://img.shields.io/pypi/v/keel-workflow)](https://pypi.org/project/keel-workflow/)
[![Python](https://img.shields.io/pypi/pyversions/keel-workflow)](https://pypi.org/project/keel-workflow/)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)

> **Keel turns coding agents into work owners.** It is a project-neutral,
> multi-agent **workflow backbone** that drives a unit of work — a GitHub issue —
> from intake to done: understand readiness, branch, implement, wait on CI, review,
> test, merge safely, close, and run capture hooks. Projects never fork the
> backbone: they set per-project **values** in `project.yaml` and snap their own
> **Lego pieces** into named extension slots.

The keel is a ship's backbone — the fixed spine every project builds on. The flagship
command is `keel:ship`; keel is where ships are built.

Keel is based on the work pattern of a strong teammate in a real engineering team:
take an issue from the queue, decide whether it is ready, own the implementation,
get it reviewed, keep the quality gates green, merge inside policy, and leave useful
memory behind for the next session. keel focuses on one agent owning work end to end.

> keel uses a thin-consumer model: the core is installed + pinned, never copied, so the
> drift/overwrite class of bug is structurally gone. Background:
> [`docs/proposals/keel-architecture.md`](docs/proposals/keel-architecture.md).

## Three layers

```
Layer 3  EXTENSIONS   project-owned Lego pieces, ADD-ONLY into named slots
Layer 2  CONFIG       project.yaml — per-project values (branch, build cmd, globs, agents…)
Layer 1  BACKBONE     keel-core — fixed ordered step machine + invariants (this package)
```

Changing the backbone is a keel-core change. Projects only ever touch layers 2–3.

### What you get

- **One backbone, every agent** — install once; `/keel:<command>` runs as native Claude commands
  *and* as a single shared skill set every other agent (Codex, Antigravity, Gemini) reads.
- **Project Lego + policy packs** — snap gates/steps into named hooks (`guard`, `tester`,
  `pre-merge`, …) and keep labels, path policy, health sources, local commands, and
  workflow preferences in `policy_pack` data instead of packaged command prose.
- **Opt-in `jury` gate** — runs the [ai-jury](https://github.com/berkayturanci/ai-jury) multi-agent
  reviewer on the diff when installed; a fail-soft no-op otherwise.
- **Safe merges by construction** — the core-owned `keel merge` path (resource claim,
  window re-check, live CI rollup, and evidence verification before the merge), timezone-aware
  night no-merge window, risk-tier → reviewer count, hotfix bypass with an audit line,
  vendor+model attribution. The PR evidence gate arms from ship provenance by default —
  only the operator-applied `keel:evidence-waived` label disarms it.

### How Keel compares

Keel sits between three established tool categories:

| category | examples | where they usually stop | what Keel adds |
|---|---|---|---|
| Coding agents | OpenHands, SWE-agent, Copilot coding agent, Devin | create or update a PR | intake, review gates, merge policy, closeout, capture hooks |
| PR reviewers | CodeRabbit, Qodo / PR-Agent, Greptile, Cursor Bugbot | review an existing PR | implementation loop, tests, merge lock/window, closeout capture |
| Merge queues | GitHub Merge Queue, Mergify, Graphite, Trunk | serialize tested PRs | issue ownership before the PR exists |

Keel is not trying to replace those tools. It is the work-ownership backbone that can use
coding agents, reviewers, gates, and merge policy in one lifecycle. See
[`docs/keel/comparison.md`](docs/keel/comparison.md) for the source-backed comparison and
the ideas Keel should borrow.

### The backbone

| step | name | primary hooks | |
|---|---|---|---|
| s0 | config | `after:config` | |
| s1 | select | `before:select`, `select`, `after:select` | |
| s2 | branch | `before:branch`, `after:branch` | |
| s3 | guard | `guard` | |
| s4 | implement | `before:implement`, `after-implement` | agent |
| s5 | classify | `classify`, `after:classify` | agent |
| s6 | ci | `before:ci`, `after:ci` | |
| s7 |

... (truncated)