Choose a direction, judge a proposal, or govern an existing system
Keel
Make Architecture Decisions with Evidence
Make reasoned calls about module boundaries, interface changes and architecture over time. Compare viable directions, assess a fixed design, and examine drift with clear decision rights and evidence gaps.
Entry point used here
- Codex CLI / IDE: select $keel
- Claude Code or native plugins: choose the author’s alternative setup
- Repository stars
- 196
- Checked
- Categories
- EngineeringProduct & Project
Make one consequential choice clearer
Start with the export exercise below. Compare synchronous and background processing, separating what supports a recommendation from what still needs measurement. A useful next evidence step matters more than an elaborate system diagram.
Pick a task and get started
Install only keel from your project root, confirm Codex discovers it, then ask one bounded architecture question. You can paste the first design exercise as written. For real work, replace its assumptions with your own material.
Compare synchronous export with a background job, then identify the cheapest evidence that could change the choice.
Install Keel for this project
Run in a terminal at the project root and confirm keel and Codex. With no -g, this uses project scope. The installer is pinned to the checked 1.7.4 release (Node.js 22.20+); Keel content still comes from the repository at install time. Inspect any existing same-name entry, then check the installation summary and complete directory.
Read the author’s installation guidenpx [email protected] add lencx/skills --skill keel -a codexCheck the complete skill before using it
Confirm that .agents/skills/keel/ in the project contains SKILL.md and all six documents in references/. Open Codex in that project and use /skills or type $ to select keel; restart Codex if it has not appeared. Attach the material and state whether you need a decision, judgment or governance. Choose either standalone skills or the native plugin: the author warns that installing both duplicates the entries.
Read Codex discovery and invocation rulesGive your AI this first task
These are editorial usage examples based on the author’s rules, not executed runs. The first is a hypothetical scenario with deliberate unknowns; attach the listed evidence for the others. Decision, Judgment and Governance are working states, not shell flags or separate commands.
$keel Make an architecture Decision for order CSV export. This is an unimplemented design exercise. These are discussion assumptions, not code findings or measurements: a monolithic application already queries orders and enforces authorization; it only supports synchronous export and has no background-job framework; the new feature must preserve tenant isolation and field permissions. The team wants larger exports but has no measured row-count, duration, memory or concurrency baseline. Return analysis only; create no files and run no experiment. Compare retaining the synchronous endpoint with adding background jobs. Surface a simpler supported direction if one exists, without expanding the system merely to fill an options list. State the criteria, assumptions and decision rights needed to introduce job infrastructure; do not invent named owners. Map only the entry, state, visible result and recovery boundaries that affect the choice. For a background direction, consider duplicate requests, interrupted jobs and uncertain status. Explain inapplicable concerns. Do not treat “retry” as closed recovery or invent load-test results. Give the strongest bounded recommendation currently supported. If workload or permission facts could change the decision, finish Open with the unknown, its owner or ownership gap, and the next measurement or approval needed. Check that both directions use the same criteria, a simpler option remains visible, and assumptions are separated from evidence.
Check what you receive
- A small set of viable directions compared on the same criteria, with a conditional recommendation.
- Applicable ownership and recovery boundaries, including explicit ownership gaps.
- An Open result with decision-changing unknowns and the next measurement or approval, without claiming verification has occurred.
More about this skill
Keel addresses choices that shape future changes: where a capability belongs, what makes a state authoritative, whether an interface can be replaced, or whether a frequently bypassed rule still earns its cost. It starts from your goals, code and constraints, then inspects what could change the answer. A private module can qualify; the evidence and ceremony should fit its impact.
It separates three jobs. Decision chooses or changes an arrangement. Judgment holds your supplied design fixed and assesses it. Governance considers what to restore, retain, migrate or retire in existing boundaries, controls and records. An infeasible proposal should end with evidence and the decision authority needed; selecting a replacement requires authorization to enter Decision. Once the architecture is feasible and settled, Keel exits implementation and testing work.
A useful answer needs more than a preferred diagram. Keel asks which behaviors consumers depend on, what determines accepted truth, who can approve a change, and who will restore which condition after failure. A material unknown that could change the choice keeps the result Open, with a bounded recommendation and a next evidence step. Closed describes the architecture judgment; it does not mean the software has been built or tested.
The current skill contains one main instruction file and six references loaded as needed. It includes no architecture scanner, background monitor or checking scripts. Execution and specialist workflows retain ownership of code changes, domain judgment and verification. Keel carries no preferred microservices, event-sourcing or framework blueprint, and small decisions need not produce migration tables or governance archives.
Sources and verification
Sources checked
The pinned main skill, all six references, installation and plugin materials were read in full, alongside installer and Codex documentation. No installation, architecture task or third-party script was run. This page describes intended use.