Knowledge Encoded Engineering Lifecycle
KEEL
Feature spec in, PR out. Sixteen agents, five phases, gated handoffs. Your robot squad handles the rest — and the repo gets sharper with every run.
keel-pipeline — F42-user-auth
$ /keel-pipeline F42-user-auth docs/product-specs/user-auth.md
› reading CLAUDE.md... pipeline variant: backend
› git status --porcelain ... clean ✓
› git checkout -b keel/F42-user-auth
[1/11] pre-check routing: standard-backend ✓
[2/11] roundtable-0 3/3 models: approve ✓
[3/11] backend-designer interfaces, types, data ✓
[4/11] roundtable-1 3/3 models: approve ✓
[5/11] test-writer 12 tests written (RED) ✓
[6/11] implementer 12/12 passing (GREEN) ✓
[7/11] code-reviewer quality: PASS ✓
[8/11] spec-reviewer no drift detected ✓
[9/11] safety-auditor 0 invariant violations ✓
[10/11] landing-verifier final check ✓
[11/11] doc-gardener drift swept, debt logged ✓
› git add -A && git commit -m "feat(auth): F42 user-auth"
› git push -u origin keel/F42-user-auth
› gh pr create --fill
✓ PR ready for review https://github.com/TejGandham/keel/pull/42
elapsed: 8m 41s · 0 human interrupts · ratchet: +2 invariants, +1 debt
$
Phase 0 · the messy-input gate
Got a PRD? Skip writing the specs.
/keel-refine reads your PRD, wireframes, and pasted screenshots — via Claude vision, shallow-read only — then drafts a full backlog with dependency edges, frontend/backend tags, and design-asset refs. You review it as editable cards in chat. Type commit when it looks right.
›PRD files (.md, .pdf)
›wireframes & hi-fi comps
›pasted screenshots
›prose / bullets
›bundle directories
keel-refine — auth-redesign PRD
$ /keel-refine docs/product-specs/auth-redesign-PRD.md \
docs/design-assets/auth/
› reading PRD (8 pages) + 3 wireframes + 2 screenshots
› analyzing scope... 12 candidate features, 5 dependency edges
› drafting backlog entries...
┌─ DRAFT (editable in chat) ──────────────────────┐
│ F40 OAuth provider plumbing [backend] │
│ F41 Session token rotation [backend] │
│ F42 Password reset flow depends on F40 │
│ F43 Login UI [frontend] │
│ ↳ see wireframe-1.png │
│ F44 2FA opt-in depends on F41 │
│ F45 Admin: revoke sessions [backend] │
│ │
│ ? unresolved — answer in chat: │
│ — rate limit policy for password reset │
│ — keep legacy SSO endpoint, or deprecate? │
└────────────────────────────────────────────────────┘
you> split F42 into backend + frontend, move wireframe-2 to F43
you> keep legacy SSO — it's load-bearing
you> commit
✓ 13 entries written to docs/product-specs/feature-backlog.md
✓ 3 wireframes moved to docs/design-assets/auth/
✓ commit: "refine(backlog): F40-F52 from auth-redesign PRD"
next: pick a feature, run /keel-pipeline, get a PR.
Phase 0 — Refine
How the refine pass works under the hood — three stops, one commit.
PRD, bundle, or paste
Hand over a PRD file, a bundle directory of README + wireframes, prose, or paste hi-fi comps and screenshots directly in chat. No backlog entry required yet.
Draft backlog entries
Reads your PRD, architecture doc, the existing backlog, and any design assets (via Claude vision, shallow-read only). Drafts candidate feature entries with dependency edges and design refs on UI features. Marks gaps with clear human-answer markers.
Chat review, type 'commit'
Drafts appear as editable cards in chat. Edit fields in plain English, drop entries you don't want, answer the human-marker questions. Type commit and the skill writes the backlog, moves pasted images into your repo, and commits with a deterministic message. Type abort to discard.
↻ re-run /keel-refine with a bigger PRD or more assets
Phase 1 — Intake & design
Feature spec
Hand-written or edited from a backlog-drafter draft. Either way, it's yours. Run /keel-pipeline on it to kick off.
Classify & route
Reads intent, gauges complexity, decides the path forward.
Routing review
The squad pressure-tests the routing call. Misclassified? Back to Pre-check.
↻ concerns loop back to Pre-check
Interfaces & data
Defines the contracts, structures, and shapes of the solution.
Design review
The squad debates the design. Approved or bounced back.
↻ concerns loop back to Designer
Phase 2 — Build
RED tests
Writes failing tests straight from the spec. If it ain't red, it ain't right.
GREEN code
Writes code until every test goes green. The workhorse of the squad.
Quality gate
Checks code quality. Changes needed? Back to Implementer.
↻ changes loop back
⚠ escalates to you after 1 retry
Phase 3 — Verification
Spec conformance
Obsessively compares code against the original spec. No drift allowed.
↻ deviation → findings → fix
⚠ escalates after 2 retries
Invariant check
Checks for invariant violations. The paranoid one. Rightfully so.
↻ violation → findings → fix
⚠ escalates after 3 retries
Architecture sound?
Arch-tier only. The wise one returns to bless (or reject) the build.
⚠ escalates after 1 retry
Phase 4 — Landing
Final check
Last verification before the landing review.
Landing review
Final squad huddle. Approved or kicked back to Implementer.
↻ concerns loop back
Encode lessons
Sweeps drift, logs any shortcuts to tech-debt-tracker, folds what the squad learned this run back into the repo. Next feature inherits it all.
Ship it
Commit, push, open the PR. Almost there.
PR ready for review
KEEL delivered. Back to you.
The ratchet
This run changed the repo — not just the feature.
Every pipeline run encodes what was learned back into the codebase. The next feature inherits everything — sharper invariants, logged debt, tightened prompts, archived reasoning.
repo diff
since last pipeline run
+5 files
-
+
core-beliefs.md
safety-auditor+1 invariant "never retry on 5xx without idempotency key"
-
+
docs/exec-plans/tech-debt.md
F42+1 deferred: "pagination on /search — quick win, not required"
-
~
ARCHITECTURE.md
doc-gardenerrefreshed auth-flow diagram, killed 3 dead refs
-
~
.claude/agents/test-writer.md
prompttightened: "never assert on log strings"
-
↳
docs/exec-plans/completed/handoffs/F42.md
11 gate verdicts · 3 roundtable rounds · full reasoning trail
Escalation thresholds
2 spec-reviewer retries
3 safety-auditor retries
1 arch-advisor retry
1 code-reviewer retry