Why Keel?

Most documentation tools either dump a template on you, or generate docs from a one-line description. Keel does neither.

• Interview-first Never generates a document from a one-line idea. The interview is where the value is created by surfacing what you haven't thought through yet.
• Adaptive scope A weekend prototype and a multi-tenant regulated platform get very different doc sets. Keel proposes only what your project actually needs.
• One fact, one home No copy-paste between documents. Every fact lives once and is cross-referenced by a stable requirement ID from every document that depends on it.
• Threat-modeled Optionally hardens the generated spec before you write a line of code. Weaknesses are fixed in the design documents, not just noted in a risk register.
• Optimised for Claude Code The output is the source of truth for the AI builder. CLAUDE.md is the keystone; every other document hangs off it by stable reference.

When to use Keel

Keel is designed for the very start of a greenfield project, before you've written code, chosen a stack, or committed to a structure. It's also useful when a project has grown organically and you need to reconstruct the foundational spec retroactively.

It is not a substitute for ongoing documentation practices, sprint planning, or production runbooks, though it generates the initial versions of those artefacts too.

Quick Start

Two commands and you're ready to lay the keel of any new project.

Install via plugin marketplace

/plugin marketplace add achatt89/keel
/plugin install keel@thelogicatelier

Restart Claude Code after installation. Then, in any project folder, tell Claude Code:

What happens next

Keel will run an intake to understand your idea and set an ambition tier (Prototype, MVP, or Platform), then move through a staged panel of expert personas, each one building on what was said before. At the end, it proposes a doc set, generates everything with cross-references wired in, and optionally runs a threat-modeling pass.

Set aside a focused session: the interview is where the value is created.

Prerequisites

Before installing Keel, make sure the following are available in your environment.

• Claude Code: installed and working. Verify with claude --version in your terminal.
• git: on your PATH. Verify with git --version.
• GitHub access: for plugin marketplace install, you'll need either gh auth login or an SSH key configured for GitHub. This requirement goes away once the repository is public.

Plugin Install

Method A, recommended for most users. The plugin marketplace handles installation, updates, and uninstallation.

Install

/plugin marketplace add achatt89/keel
/plugin install keel@thelogicatelier

Restart Claude Code after running these commands. Verify the install with /plugin.

Update

/plugin marketplace update thelogicatelier
/plugin install keel@thelogicatelier

marketplace update fetches the latest manifest from GitHub and refreshes the local cache. plugin install alone reads from that cache; running it without the update step first will reinstall the version Claude Code already knows about, not the latest one.

Uninstall

/plugin uninstall keel@thelogicatelier

Personal Skill Install

Method B: install directly from the repository. A symlink keeps the skill updated when you pull.

User-global install (symlink)

git clone https://github.com/achatt89/keel.git ~/code/keel
mkdir -p ~/.claude/skills
ln -s ~/code/keel/plugins/keel/skills/keel ~/.claude/skills/keel

The symlink approach means a git pull inside ~/code/keel automatically updates the skill, no reinstall needed. Restart Claude Code after cloning.

Update

git -C ~/code/keel pull

Then restart Claude Code.

Copy instead of symlink

cp -R ~/code/keel/plugins/keel/skills/keel ~/.claude/skills/keel

You'll need to re-copy to pick up updates.

Project-scoped install (team use)

To make Keel available only within a specific project (useful for teams where not everyone has it installed globally): symlink or copy into the project's own skills directory:

mkdir -p .claude/skills
ln -s ~/code/keel/plugins/keel/skills/keel .claude/skills/keel

Commit the .claude/skills/keel directory (not the symlink) if you want the skill to travel with the repo.

Verify & First Run

Verify installation

Open Claude Code and type /keel. If the skill is installed correctly, it should appear as an available command. Alternatively, say:

Claude Code will route this to Keel automatically.

First run

Open your target project folder (or an empty folder for a new project) in Claude Code, then describe your idea. Keel will run through its full flow:

1. Intake: reflect the idea back, establish ambition tier
2. Interview: six staged persona interviews (see The Interview)
3. Proposed doc set: tailored to your project's complexity
4. Generation: documents written with cross-references wired in
5. Threat-model pass (optional)
6. Handoff: reading order, open decisions, first build step

The Interview

Keel conducts a staged multi-persona interview before writing a single document. Each persona adapts every question to what was just said; it challenges weak assumptions instead of transcribing them.

• Phase 0 Intake: reflect the idea back, establish ambition tier (Prototype / MVP / Platform), and set expectations for the session ahead.
• Phase 1 Business Analyst: the real problem, who pays, why now, and what success looks like in concrete metrics.
• Phase 2 Product Manager: user personas, key journeys, the MVP cut, and what is explicitly out of scope.
• Phase 3 Architect: stack choice, data model, integrations, and the hard technical bets that will be difficult to reverse later.
• Phase 4 Security / Compliance: data sensitivity, tenancy model, authentication approach, and regulatory exposure.
• Phase 5 Designer: surfaces, key user flows, tone, accessibility needs, and brand feel (only if the project has a UI).
• Phase 6 Delivery / Ops: phasing, deployment environment, git workflow, worktree parallelism, doc-sync strategy, and how a stuck build task should be handled.

Document Tailoring

Keel does not stamp out the same fifteen files every time. It proposes a doc set matched to your project's real complexity.

By ambition tier

• Weekend prototype: CLAUDE.md + README, possibly a lightweight PRD if the idea needs clarifying before building.
• Product / MVP: full requirements suite (BRD, PRD), architecture, engineering design, and an implementation plan with concrete exit gates.
• Platform / regulated: everything above plus NFR, COMPLIANCE, THREAT_MODEL, RUNBOOK, and optionally an almanac/ knowledge base.

Cross-references and stable IDs

Every document is generated with stable requirement IDs (e.g., REQ-001, ADR-003). When a requirement from the BRD drives a design decision in the architecture, the architecture document references the requirement ID, not a paraphrase of its content. This means the doc set stays coherent as individual documents evolve.

Threat Modeling

After generating the doc suite, Keel offers an opt-in threat-modeling pass that hardens the spec before any code is written.

What it models

The threat-modeling pass works adversarially across seven dimensions:

• Data exposure: what data could leak and to whom
• Tenant isolation: whether multi-tenant boundaries are enforced at every layer
• Untrusted input: all attack surfaces that accept external data
• Secrets and auth: key management, token lifetimes, privilege escalation paths
• Abuse and DoS: rate limiting, resource exhaustion, quota enforcement
• Privacy and regulatory: PII handling, consent flows, retention limits
• Availability: single points of failure, disaster recovery, RTO/RPO

How it mitigates

Weaknesses identified during the threat-modeling pass are fixed directly in the design documents, not just annotated in a separate risk register. The architecture document and engineering design are updated in place, and each threat is recorded in THREAT_MODEL.md with a pointer to where it was mitigated.

Handoff

After generation (and optional threat-model), Keel delivers a structured handoff so you know exactly where to start building.

What the handoff covers

• What was generated: a list of every document created, with a one-line summary of each
• Recommended reading order: the sequence in which a new collaborator (human or AI) should read the docs to build context efficiently
• Open decisions: all [NEEDS DECISION] markers surfaced from across the doc set, so nothing is forgotten
• First build step: a concrete starting point, typically "open this folder in Claude Code and start at IMPLEMENTATION_PLAN.md Phase 0"

How building proceeds

Alongside the docs, Keel generates one workflow script per IMPLEMENTATION_PLAN phase. Running a phase script checks out a dedicated phase branch off main, then fans out its divisible tasks as parallel agents, each in its own git worktree branched off that phase branch. Every task agent opens with /goal — a completion condition covering the implementation, its tests, lint, and an end-to-end verify pass (plus a manual in-browser check via claude-in-chrome for UI work) — so it won't end its turn early. Task branches merge back into the phase branch, then a Verify stage runs every suite once and writes an evidence record (.keel/evidence/phase-N.json) that the doc-sync step cites — it never re-runs or re-narrates. Only the phase branch, carrying the doc-sync commit, ever merges to main.

What happens if a task's goal isn't being met is a choice you make during the Delivery / Ops interview round: bounded retries then escalate to you (the default), persistent until met, or escalate on the first failure.

Building On: Phases & Changes

Keel 2.0 is shaped by what four production projects taught over ~2,000 commits: docs stay trustworthy only when every claim carries evidence, and they stay readable only when the journal lives somewhere other than the keystone file.

Two units of work

• Phase A gated milestone. /keel phase new <slug> scopes it: a plan block with an exit-gate table, reserved ADR stubs (so parallel worktrees never collide on numbers), a workflow script, and a CHANGELOG line. Insert with --after N, split with --split N; existing numbers never change.
• Change Hotfix-weight work. /keel change <slug> gives it a chg/ branch, a CHG-xxx row, and a CHANGELOG line — no phase block, no fan-out script. Phases stop being the unit for one-line fixes.
• Closeout /keel closeout generates a phase whose scope is exactly the open deferred items, once the table grows past a threshold or every N phases.

Claims carry evidence

A ✅ is never bare. Every exit gate records its evidence level — code-read < unit < integration < local-browser < staging < prod-live — and the artefact behind it (commit, test report, CI run, browser transcript). Deploy state is tracked separately, in one place: on-branch → merged → deployed vNN → live-verified, flipped by the merge step and the deploy procedure, never by prose. A gate whose evidence falls short of what the gate demands stays partial; the phase stays open.

Where things live now

• AGENTS.md The canonical keystone (cross-tool standard); CLAUDE.md is @AGENTS.md plus Claude-specific sections. Status is a two-row table. Hard budget: 12 KB — doc-sync auto-archives past it.
• docs/adr/ One table-based file per decision. Lifecycle Proposed → Accepted → Built → Superseded; a single Build deviation row is the only post-acceptance edit. No addenda — incidents are postmortems, deploys are log rows.
• DEPLOYMENT.md One doc for every environment: the env matrix, promotion path, build-time vs runtime config table, pre/post-deploy checklists, rollback per component, and the deploy log.
• CHANGELOG.md What shipped and in what deploy state, one line per Phase or Change. The journal that used to bloat the keystone.
• RUNBOOK.md postmortems Incidents get a PM-xxx row: trigger, root cause, fix, and where the prevention landed. Playbooks are Symptom · Check · Fix · Escalate tables.

Checking Your Version

/keel version answers three questions in one line each: what version of the keel skill is installed, what version last touched this project's docs, and whether a newer keel is published.

It's read-only — no permission prompt, no edits, nothing written. Run it any time you're unsure whether your docs are current, or before deciding whether to run /keel upgrade.

Upgrading Existing Projects

If a project already has keel-generated docs, /keel upgrade audits them against the current keel standard, reports what has drifted or gone missing, and applies only the fixes you approve.

When to run it

Run /keel upgrade on any project that was documented with an earlier version of keel, or that has accumulated manual edits that may have diverged from the conventions keel expects. Keel detects an upgradeable project automatically when it finds three or more of the standard documents present.

How it runs

• Phase U1 Discover: inventory the existing doc set, identify which keel documents are present, and determine project type and whether the project has a UI.
• Phase U2 Audit: run each present document through the upgrade checklist: required sections, stable IDs, standing rules, skill integration hooks, workflow script references, and placeholder fill status.
• Phase U3 Report and permission: present a gap report grouped by severity. You choose which gaps to fix; Keel does nothing until you approve.
• Phase U4 Update: apply the approved fixes surgically: add missing sections, fill placeholders, append new standing rules, install missing skills, update .keel/meta.json.
• Phase U5 Codebase audit: generate a checklist of implementation gaps derived from the now-current docs, or save it as CODEBASE_AUDIT.md for later.

Moving a project to the 2.0 format

A project documented by keel 1.x is detected as format 1 (a single ADR.md with addenda, a prose status section, bullet exit gates, no DEPLOYMENT.md). /keel upgrade then offers a FORMAT_MIGRATION path that runs as one reviewable commit per step on a keel-upgrade-2.0 branch: archive first, audit, classify every ADR addendum and status paragraph (build deviation, deploy state, incident, client round) and relocate it verbatim to its new home, reformat ADRs into docs/adr/ in parallel worktrees, rebuild the plan and keystone with evidence levels set to what the prose actually claimed (never upgraded), seed DEPLOYMENT.md from what's on disk and CHANGELOG.md from git history, regenerate the scripts, and write an UPGRADE_REPORT.md listing every relocation source → destination. IDs never change; nothing is deleted; anything unclassifiable is left in an Unclassified (review) row rather than guessed.

Gap categories

• FORMAT_MIGRATION The doc set is in the 1.x layout; the 2.0 migration path above applies.
• BUDGET_EXCEEDED A living doc is over its byte budget and doc-sync found nothing archivable — a human raises the budget or trims by hand.
• MISSING_DOC A document that should exist for this project type is absent entirely.
• MISSING_SECTION A required section within an existing document is absent.
• OUTDATED_CONVENTION A section exists but uses an older format; for example, a phase block missing an exit gate or a workflow script reference.
• MISSING_FEATURE A capability added in a later version of keel (such as the impeccable lifecycle table in DESIGN.md) is not present.
• UNFILLED_PLACEHOLDER A generated placeholder marked [TBD] or [NEEDS DECISION] that was never filled in.
• MISSING_SKILL A skill referenced in the docs (impeccable, modern-web-guidance) is not installed in the project.

Archiving & Trimming

/keel archive relocates finished or superseded detail out of AGENTS.md, IMPLEMENTATION_PLAN.md, CHANGELOG.md, RUNBOOK.md, and docs/adr/ into PHASE_ARCHIVE.md — keeping the docs a fresh session reads light on tokens, without deleting anything.

When to run it

Long-running projects accumulate real detail in the living docs: completed phase write-ups, resolved deferred items, superseded decisions. That detail is worth keeping — it gets revisited — but it costs context on every session start. You mostly don't have to: every living doc has a byte budget in .keel/meta.json (keystone 12 KB by default), and the doc-sync workflow measures each one after every sync and runs the archive automatically when a budget is breached — one commit per file, so a bad relocation reverts alone. Run /keel archive by hand at natural checkpoints, or when doc-sync reports BUDGET_EXCEEDED and you'd rather trim than raise the budget.

How it runs

• Phase X1 Discover: inventory the living docs and measure how far each has drifted past its target size.
• Phase X2 Identify: scan for archive candidates — completed phases, resolved deferred items, superseded decisions, stale sections — against a strict never-archive list (nothing open, active, or unresolved is ever eligible).
• Phase X3 Report and permission: present the archive plan with a before/after size projection per doc. You choose to archive everything, a subset, or nothing; Keel does nothing until you approve.
• Phase X4 Archive: relocate the approved content to PHASE_ARCHIVE.md verbatim, leave a one-line summary + link behind, and never renumber or move an ID in the process.
• Phase X5 Verify: confirm every new link resolves, every ID is still unique, and report the size reclaimed.

What's eligible

• Completed phases A ✅ phase's full Goal/Scope/Deliverables/Exit-gates block in IMPLEMENTATION_PLAN.md — the phase-status table row always stays.
• Resolved deferred items Deferred-items table rows already marked ✅ resolved.
• Merged changes Changes-table rows already merged or deployed, beyond the most recent ten.
• Superseded decisions An ADR marked superseded keeps its ID and index row; its body moves.
• Keystone drift Anything in AGENTS.md beyond the keystone-index job — stacked status history, sections duplicating a doc they point at.
• Old releases & closed postmortems CHANGELOG sections older than the last three releases; postmortems whose prevention has landed and are older than 90 days.

The Full Catalog

Every document Keel can generate, and the question it answers.

Contributing

Keel is open source. Contributions (whether new templates, interview persona improvements, or bug fixes) are welcome.

Plugin structure

Adding a document template

1. Create a Markdown file in skills/keel/references/templates/.
2. Follow the conventions in conventions.md: stable IDs, status markers, and cross-reference syntax.
3. Register the document in catalog.md with a clear description of when it should be generated.
4. If the document introduces a new persona question, add it to the relevant phase in personas.md.

Pull requests

• Branch off main.
• Keep changes focused: one concern per PR.
• Update CHANGELOG.md with a brief entry under the appropriate version.

Questions or ideas? Open an issue on GitHub or reach out via The Logic Atelier.