{"id":50758421,"url":"https://github.com/berkayturanci/keel","last_synced_at":"2026-06-16T09:00:58.004Z","repository":{"id":362765078,"uuid":"1247429532","full_name":"berkayturanci/keel","owner":"berkayturanci","description":"Keel turns coding agents into work owners: a project-neutral issue-to-done workflow backbone.","archived":false,"fork":false,"pushed_at":"2026-06-11T07:24:51.000Z","size":1279,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T07:32:49.485Z","etag":null,"topics":["ai-agents","ai-workflows","automation","ci","code-review","coding-agents","developer-tools","github-actions","issue-to-done","merge-queue","multi-agent","python","workflow","workflow-automation"],"latest_commit_sha":null,"homepage":"https://berkayturanci.github.io/keel/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/berkayturanci.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-23T09:57:02.000Z","updated_at":"2026-06-11T07:24:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/berkayturanci/keel","commit_stats":null,"previous_names":["berkayturanci/keel"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/berkayturanci/keel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berkayturanci%2Fkeel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berkayturanci%2Fkeel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berkayturanci%2Fkeel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berkayturanci%2Fkeel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/berkayturanci","download_url":"https://codeload.github.com/berkayturanci/keel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berkayturanci%2Fkeel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34398408,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-workflows","automation","ci","code-review","coding-agents","developer-tools","github-actions","issue-to-done","merge-queue","multi-agent","python","workflow","workflow-automation"],"created_at":"2026-06-11T07:31:46.489Z","updated_at":"2026-06-16T09:00:57.998Z","avatar_url":"https://github.com/berkayturanci.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/assets/hero.svg\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"docs/assets/hero-light.svg\"\u003e\n  \u003cimg 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\"\u003e\n\u003c/picture\u003e\n\n# keel ⚓\n\n[![CI](https://github.com/berkayturanci/keel/actions/workflows/ci.yml/badge.svg)](https://github.com/berkayturanci/keel/actions/workflows/ci.yml)\n[![coverage](https://img.shields.io/endpoint?url=https://berkayturanci.github.io/keel/coverage-badge.json)](https://berkayturanci.github.io/keel/coverage/)\n[![CodeQL](https://github.com/berkayturanci/keel/actions/workflows/codeql.yml/badge.svg)](https://github.com/berkayturanci/keel/actions/workflows/codeql.yml)\n[![PyPI](https://img.shields.io/pypi/v/keel-workflow)](https://pypi.org/project/keel-workflow/)\n[![Python](https://img.shields.io/pypi/pyversions/keel-workflow)](https://pypi.org/project/keel-workflow/)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n\n\u003e **Keel turns coding agents into work owners.** It is a project-neutral,\n\u003e multi-agent **workflow backbone** that drives a unit of work — a GitHub issue —\n\u003e from intake to done: understand readiness, branch, implement, wait on CI, review,\n\u003e test, merge safely, close, and run capture hooks. Projects never fork the\n\u003e backbone: they set per-project **values** in `project.yaml` and snap their own\n\u003e **Lego pieces** into named extension slots.\n\nThe keel is a ship's backbone — the fixed spine every project builds on. The flagship\ncommand is `keel:ship`; keel is where ships are built.\n\nKeel is based on the work pattern of a strong teammate in a real engineering team:\ntake an issue from the queue, decide whether it is ready, own the implementation,\nget it reviewed, keep the quality gates green, merge inside policy, and leave useful\nmemory behind for the next session. keel focuses on one agent owning work end to end.\n\n\u003e keel uses a thin-consumer model: the core is installed + pinned, never copied, so the\n\u003e drift/overwrite class of bug is structurally gone. Background:\n\u003e [`docs/proposals/keel-architecture.md`](docs/proposals/keel-architecture.md).\n\n## Three layers\n\n```\nLayer 3  EXTENSIONS   project-owned Lego pieces, ADD-ONLY into named slots\nLayer 2  CONFIG       project.yaml — per-project values (branch, build cmd, globs, agents…)\nLayer 1  BACKBONE     keel-core — fixed ordered step machine + invariants (this package)\n```\n\nChanging the backbone is a keel-core change. Projects only ever touch layers 2–3.\n\n### What you get\n\n- **One backbone, every agent** — install once; `/keel:\u003ccommand\u003e` runs as native Claude commands\n  *and* as a single shared skill set every other agent (Codex, Antigravity, Gemini) reads.\n- **Project Lego + policy packs** — snap gates/steps into named hooks (`guard`, `tester`,\n  `pre-merge`, …) and keep labels, path policy, health sources, local commands, and\n  workflow preferences in `policy_pack` data instead of packaged command prose.\n- **Opt-in `jury` gate** — runs the [ai-jury](https://github.com/berkayturanci/ai-jury) multi-agent\n  reviewer on the diff when installed; a fail-soft no-op otherwise.\n- **Safe merges by construction** — the core-owned `keel merge` path (resource claim,\n  window re-check, live CI rollup, and evidence verification before the merge), timezone-aware\n  night no-merge window, risk-tier → reviewer count, hotfix bypass with an audit line,\n  vendor+model attribution. The PR evidence gate arms from ship provenance by default —\n  only the operator-applied `keel:evidence-waived` label disarms it.\n\n### How Keel compares\n\nKeel sits between three established tool categories:\n\n| category | examples | where they usually stop | what Keel adds |\n|---|---|---|---|\n| Coding agents | OpenHands, SWE-agent, Copilot coding agent, Devin | create or update a PR | intake, review gates, merge policy, closeout, capture hooks |\n| PR reviewers | CodeRabbit, Qodo / PR-Agent, Greptile, Cursor Bugbot | review an existing PR | implementation loop, tests, merge lock/window, closeout capture |\n| Merge queues | GitHub Merge Queue, Mergify, Graphite, Trunk | serialize tested PRs | issue ownership before the PR exists |\n\nKeel is not trying to replace those tools. It is the work-ownership backbone that can use\ncoding agents, reviewers, gates, and merge policy in one lifecycle. See\n[`docs/keel/comparison.md`](docs/keel/comparison.md) for the source-backed comparison and\nthe ideas Keel should borrow.\n\n### The backbone\n\n| step | name | primary hooks | |\n|---|---|---|---|\n| s0 | config | `after:config` | |\n| s1 | select | `before:select`, `select`, `after:select` | |\n| s2 | branch | `before:branch`, `after:branch` | |\n| s3 | guard | `guard` | |\n| s4 | implement | `before:implement`, `after-implement` | agent |\n| s5 | classify | `classify`, `after:classify` | agent |\n| s6 | ci | `before:ci`, `after:ci` | |\n| s7 | review | `reviewers`, `after:review` | agent |\n| s8 | test | `tester`, `test`, `after:test` | |\n| s9 | fixloop | `before:fixloop`, `fixloop`, `after:fixloop` | |\n| s10 | merge | `pre-merge`, `after:merge` | |\n| s11 | capture | `capture`, `post-merge` | |\n| s12 | close | `before:close`, `on-close`, `after:close` | |\n\nInvariants the backbone always preserves: merge lock, night no-merge window, fail-soft,\norchestrator-only-writes, vendor+model attribution.\n\nThe capture step has a core marker/verifier contract:\n`compound-learning: pr=\u003cN\u003e status=\u003capplied|deferred|skipped:reason\u003e`. Projects provide\ncapture content and destinations through `capture` / `post-merge` extensions; keel owns the\nmarker, fail-soft semantics, redaction-before-durability, offline `capture-verify`, and the\nlearning-quality decision recorded in `capture.learning`. Durable learning is optional:\npolicy can choose `create-learning`, `marker-only`, or `defer`, while duplicate candidates\nare suppressed by stable fingerprints so routine merges do not flood the learning surface.\n\n## Install\n\nkeel runs on Linux, macOS, and Windows — a Python (≥3.11) package with one runtime\ndependency, PyYAML. (On Windows it also installs `tzdata`, which supplies the timezone\ndatabase the standard library has no system source for there.)\n\n```bash\npip install keel-workflow                                     # from PyPI (provides the `keel` command)\npip install \"git+https://github.com/berkayturanci/keel@v1.6.4\"  # or pin an existing git tag\n```\n\nIn a cloud agent session, install it from a `SessionStart` hook (or add keel to the\nsession's repo scope) so the selected core ref is available before a run.\n\nRelease maintainers should follow [`docs/keel/release.md`](docs/keel/release.md) and run\n`python scripts/release_smoke.py` before tagging or announcing a package.\n\n## Quickstart\n\n```bash\nkeel setup --root .                                  # add keel config + adapters to a project\nkeel validate projects/example-flutter.yaml          # validate a config against the schema\nkeel plan      projects/example-flutter.yaml          # show the backbone plan for a project\nkeel version\n```\n\n`keel setup` wraps first-run onboarding (`init` + `install-adapter` + strict `validate` +\n`plan`) for a consumer project. `keel plan` renders the fixed backbone with each project's\ngates/extensions slotted in — exactly what a dry-run executes:\n\n```\nkeel plan — example-flutter\n  base_branch: main   core_version: ^1.0\n  backbone:\n     s4  implement  [agent]\n     ...\n     s8  test\n           - gate: build\n           - gate: lint\n           - gate: design-parity\n    s10  merge\n           - gate: design-parity-gate\n```\n\n## Invocation (`/keel:\u003ccommand\u003e`)\n\nThe agentic workflows ship **with the package** as project-neutral adapters and install into\nthe **two surfaces** agents actually read — so the same `/keel:\u003ccommand\u003e` works in every\nproject; only that project's `.keel/project.yaml` + extensions change the behaviour:\n\n```bash\nkeel install-adapter claude   # native Claude commands → /keel:ship, /keel:regression, …\nkeel install-adapter skills   # one shared keel-\u003ccmd\u003e skill set under .agents/skills/\n#                               (read by every non-Claude agent: Codex, Antigravity, Gemini)\nkeel install-adapter all      # both surfaces\n```\n\n### Claude Code plugin\n\nThe same `/keel:\u003ccommand\u003e` flows are also packaged as a **Claude Code plugin**, so you can\nadd them to a session without `pip install` — straight from this repo's built-in marketplace:\n\n```text\n/plugin marketplace add berkayturanci/keel   # register the keel marketplace (this repo)\n/plugin install keel                          # install the keel plugin → /keel:ship, /keel:regression, …\n```\n\nThe plugin ships the same project-neutral command bodies as `keel install-adapter`; the two\nflows are additive. The plugin's command files under `commands/` are generated from\n`src/keel/adapters/commands/` (the single source of truth) by `make plugin` /\n`keel install-adapter plugin`, and a test fails on any drift. The `pip install keel-workflow`\n+ `keel install-adapter` path is unchanged.\n\n**16 shipped commands** — `ship` (flagship, with a `--compound` profile flag), `implement`,\n`review-cycle`, `review-all-day`, `pr-loop`, `regression`, `triage`, `morning`, `work-block`,\n`overnight`, `wrap`, `ci-check`, `coverage`, `deps-audit`, `flake-audit`, `stale-prs`.\nEach is described in\n[`docs/keel/commands.md`](docs/keel/commands.md). The `keel` CLI does the deterministic work;\nthe adapters are the agentic flows (per-round review, inline comments, delegation).\n\n## Dogfooding\n\nkeel drives **itself** from `.keel/project.yaml` using the latest `^1.0` core contract\n(Python, `make test` + `make lint` gates), and CI runs keel on keel-core on every push.\n`projects/keel.yaml` remains a seed copy and is tested to stay in sync with the dogfood\nconfig.\n\n```bash\nkeel plan      .keel/project.yaml --root . # render keel's own backbone\nkeel run-gates .keel/project.yaml --root . # keel runs its own test + lint gates\nkeel ship      .keel/project.yaml --root . # full dry assessment: tier, window, gates, decision\n#   risk tier     : TIER-3  → 3 reviewer(s)\n#   decision      : MERGE — clear to merge\n```\n\nIf a step's gate fails, keel blocks its own merge — the same backbone every consumer gets.\n\n## Docs\n\n- 🌐 **[Website + live coverage report](https://berkayturanci.github.io/keel/)** — the\n  published site is live at \u003chttps://berkayturanci.github.io/keel/\u003e (deployed via the\n  `pages.yml` workflow). Locally, `make site` builds the coverage HTML into\n  `website/coverage/` and serves it at \u003chttp://localhost:8000\u003e.\n- [`docs/keel/configuration.md`](docs/keel/configuration.md) — `project.yaml` reference\n- [`docs/keel/parameter-reference.md`](docs/keel/parameter-reference.md) — exhaustive per-flag reference for every CLI command and the `/keel:ship` adapter arguments\n- [`docs/keel/onboarding.md`](docs/keel/onboarding.md) — one-command consumer setup and follow-up checks\n- [`docs/keel/keel-visual.md`](docs/keel/keel-visual.md) — the live run board (`dash`/`render`/`serve`, the per-run 2D/3D drawer, `--all` multi-project, the auto-stamped `keel activity` channel)\n- [`docs/keel/extensions.md`](docs/keel/extensions.md) — authoring Lego extensions\n- [`docs/keel/consumer-neutrality.md`](docs/keel/consumer-neutrality.md) — core vs project policy boundary\n- [`docs/keel/parity-matrix.md`](docs/keel/parity-matrix.md) — legacy-to-keel command parity status and owning issues\n- [`docs/keel/runtime-capabilities.md`](docs/keel/runtime-capabilities.md) — runtime capability detection and requirement declarations\n- [`docs/keel/github-transport.md`](docs/keel/github-transport.md) — GitHub transport selection and normalized operation capabilities\n- [`docs/keel/command-contracts.md`](docs/keel/command-contracts.md) — structured JSON plan/result contracts for adapters\n- [`docs/keel/operator-consent.md`](docs/keel/operator-consent.md) — live-run operator consent scopes and delegated-agent scope rules\n- [`docs/keel/cli.md`](docs/keel/cli.md) — CLI reference\n- [`docs/keel/commands.md`](docs/keel/commands.md) — the 16 `/keel:\u003ccommand\u003e` workflows (plus the `keel status` progress command), each with its description\n- [`docs/keel/cutover.md`](docs/keel/cutover.md) — staged guide to retire a project's copied command bodies (install → verify → retire), losing nothing\n- [`docs/keel/comparison.md`](docs/keel/comparison.md) — competitive landscape (Mergify, GitHub merge queue, Qodo/PR-Agent, CodeRabbit, Sweep, OpenHands, Danger, …) + ranked borrow-ideas\n- [`docs/keel/github-actions.md`](docs/keel/github-actions.md) — run keel live on GitHub's free runner (the `keel-ship` workflow)\n- [`docs/keel/release.md`](docs/keel/release.md) — PyPI/TestPyPI release runbook and package smoke test\n- [`docs/proposals/keel-architecture.md`](docs/proposals/keel-architecture.md) — full design\n\n## Development\n\nStdlib-first, pure-core + thin-I/O, deterministic, fully covered (ai-jury ethos).\n\n```bash\nmake test       # offline unit suite (no network, no credentials)\nmake lint       # ruff\nmake coverage   # coverage gate (fail_under in pyproject)\nmake validate   # validate projects/*.yaml and .keel/project.yaml\nmake site       # build the coverage report + serve the website at localhost:8000\n```\n\nThe pure core (`config`, `model`, `extensions`, `findings`, `gates`, `orchestrator`,\n`cli`) is held at **100% line + branch coverage**; the coverage gate (`fail_under = 100`)\nruns in CI.\n\n## Companion: keel-visual\n\n[`keel-visual`](https://pypi.org/project/keel-visual/) is an **optional, separately\ninstallable** animated run visualizer (`pipx install keel-visual`). It *renders* a\nkeel run from the ledger/checkpoint keel already writes — it never drives one — for\n**any of the 16 command flows** (`ship` is the s0–s12 backbone; every other command\nrenders its own phases).\n\nFour surfaces:\n\n- **`play`** — the run animates in the terminal (flow + wave ribbon, `--loop` for a\n  demo, live `--follow`; `--theater` hands off to [ai-jury](https://github.com/berkayturanci/ai-jury)'s\n  deliberation theater at the review step, then resumes).\n- **`dash`** — a terminal board of every active run; **`dash --all`** aggregates every\n  keel project under a parent folder into one board. It shows `ship` runs *and*\n  non-ship commands (triage, morning, pr-loop …) live via the `keel activity`\n  channel — each with its own phases.\n- **`render`** — a self-contained web page: a **2D flow** and a **3D scene** with five\n  selectable styles (`plexus`/`comet`/`aurora`/`combined`/`line`); **`render --all`**\n  writes a multi-project board with a **2D grid / 3D scene** toggle, automatic\n  **light/dark** theme, and an **all / active** filter that fades finished runs.\n- **`serve` / `serve --all`** — a **live** localhost web dashboard (polls every ~0.5s):\n  a filterable board, and per-run a detail drawer with a **2D / 3D switch** (a live\n  per-run scene with `curve · helix · ring · line · plexus · aurora · comet` styles,\n  drag-orbit + scroll/pinch zoom, theme-aware) and the run's command / phase / status.\n\nAs of **keel 1.6.4**, the deterministic backbone commands (`keel plan` at Step 0, `keel\nrun-gates` at s8, `keel merge` at s10) auto-stamp the `keel activity` board when given a\n`--run-id`, so a run shows up **and advances** even if the agent skips the per-phase\n`keel activity` calls.\n\nDepends on this core (`keel-workflow \u003e= 1.6.0`); the core never depends on it (it only\nreads records, and probes `shutil.which(\"jury\")` — never imports ai-jury). See\n[`keel-visual/README.md`](keel-visual/README.md).\n\n## Repo layout\n\n```\nsrc/keel/            the core package (config, model, extensions, findings, gates, orchestrator, cli)\nsrc/keel/schema/     project.schema.json (bundled)\n.keel/project.yaml   keel's own dogfood consumer config\nprojects/*.yaml      example configs and the keel seed copy\nsrc/keel/adapters/   the packaged /keel:\u003ccommand\u003e bodies (install-adapter: claude commands + shared skills)\nkeel-visual/         optional companion: animated 2D/3D run visualizer (separate package)\nwebsite/             static site + coverage report (make site)\ntests/               unit suite\ndocs/                docs + proposals\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fberkayturanci%2Fkeel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fberkayturanci%2Fkeel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fberkayturanci%2Fkeel/lists"}