Keel 🛳️

Lay the keel of your next project. Keel is a Claude Code skill that interviews you about a greenfield idea, then generates a tailored, cross-referenced suite of foundational documents you can build the whole product from.

In shipbuilding, the keel is the first structural member laid down — every other part of the vessel attaches to it. These documents are that keel for a software project: the load-bearing spec that you (working with Claude Code) then construct the actual product from.

Keel doesn't stamp out the same fifteen files every time. It brainstorms with you through a multi-persona interview, figures out what your project actually needs, and generates only those documents — wired together with traceable IDs and cross-references.

Documentation

Full documentation is available at achatt89.github.io/keel — installation guides, how it works, the document catalog, and contributing notes.

What it does

1. Interviews you. Keel adopts a rotating panel of expert personas — Business Analyst, Product Manager, Architect, Security/Compliance, Designer, Delivery/Ops — and asks targeted questions, adapting every follow-up to your answers. It challenges weak assumptions instead of just transcribing them.
2. Proposes a tailored doc set. Based on the interview, it recommends exactly which documents your project warrants (a weekend prototype and a multi-tenant regulated platform get very different sets), and tells you what it's deliberately leaving out and why.
3. Generates build-ready docs. It writes the agreed documents in dependency order, with stable requirement IDs, ADRs, cross-references, and a light CLAUDE.md index — optimized to hand straight to Claude Code as the source of truth for the build. The CLAUDE.md it produces bakes in your ways of working — git-from-commit-one, branch-per-feature, parallel agents in isolated git worktrees, and documentation kept in lockstep with code after every chunk/phase.
4. Threat-models and hardens the docs. Optionally, Keel runs an adversarial threat-modelling pass over the documents it just wrote and fixes the weaknesses directly in them — adding controls, security NFRs, ADRs, and exit gates so the spec itself is hardened, not just annotated with a risk to fix later.

The document suite

Keel selects adaptively from this catalog (it won't generate all of them for a small project):

Every ✅ in these docs carries an evidence level (code-read → unit → integration → local-browser → staging → prod-live) and an artefact. Deploy state (on-branch → merged → deployed vNN → live-verified) lives in one place. Living docs have byte budgets; doc-sync auto-archives past them.

How to use it

Once installed, just describe a new project to Claude Code:

I want to build <your idea>. Let's lay the foundations.

…or invoke it directly:

/keel

Once a project is documented, the ongoing modes are /keel phase new <slug> (scope a gated milestone), /keel change <slug> (a hotfix-weight unit), /keel closeout (sweep deferred items), /keel archive, /keel upgrade (including the 1.x → 2.0 format migration), and /keel version.

Keel takes it from there: intake → interview → proposed doc set → generation → handoff. Set aside a focused session — the interview is where the value is created.

Installation & setup

Prerequisites

• Claude Code installed and working (run claude --version). Plugin install requires a build with the /plugin command (run /plugin once to confirm it's available; if it isn't, update Claude Code or use the personal-skill method below).
• git on your PATH (git --version).
• For installing from this private repo: a GitHub account with access to it, authenticated either via the gh CLI (gh auth login) or an SSH key / credential helper that can clone achatt89/keel. (Once the repo is made public, no auth is needed.)

Method A — as a Claude Code plugin (recommended)

This repo doubles as a Claude Code plugin marketplace, so you can install it the first-class way. In a Claude Code session:

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

• marketplace add registers this repo as a source (achatt89/keel resolves to GitHub; you can also pass a full https://github.com/achatt89/keel.git URL or a local path). The catalog registers under its manifest name, thelogicatelier.
• install keel@thelogicatelier installs the keel plugin from the thelogicatelier marketplace — the syntax is <plugin>@<marketplace>.

Restart Claude Code (or reload the window) so the skill registers. Verify with Verify the install below.

Update later:

/plugin marketplace update thelogicatelier
/plugin install keel@thelogicatelier

Uninstall: /plugin uninstall keel@thelogicatelier (and optionally /plugin marketplace remove thelogicatelier).

Method B — as a personal skill

Prefer a plain skill install (no plugin system)? Clone the repo and symlink the skill into your personal skills directory:

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

A symlink means git pull in ~/code/keel keeps the installed skill up to date. Prefer a copy instead of a symlink? Swap the last line for:

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

Restart Claude Code so it picks up the new skill.

Project-scoped install (only inside one repo, e.g. to share with a team via version control): symlink/copy into that repo's .claude/skills/keel instead of ~/.claude/skills/keel.

Uninstall: rm ~/.claude/skills/keel (removes the symlink/copy; the cloned repo is untouched).

Verify the install

• Plugin method: run /plugin and confirm keel is listed and enabled.
• Either method: type /keel — the skill should be offered. Or simply tell Claude Code "I want to start a new project, let's lay the foundations" and Keel should activate.

First run

There's no configuration step — Keel is prompt-driven. When you run it:

1. Open the target project folder in Claude Code (Keel writes the generated docs into your working directory; it will confirm where if it's ambiguous).
2. Start the session and describe your idea. Keel runs: intake → multi-persona interview → proposed doc set → generation → optional threat-model & harden → handoff.
3. Set aside a focused block of time — the interview is where the value is created.

If you want Keel to also initialize git in the folder and follow the branch-per-feature / worktree workflow it documents, just say yes when it asks during the ways-of-working round.

Troubleshooting

How it's built

keel/
├── .claude-plugin/marketplace.json     # makes this repo an installable marketplace
└── plugins/keel/
    ├── .claude-plugin/plugin.json      # the plugin manifest
    └── skills/keel/
        ├── SKILL.md                    # the orchestrator: workflow + principles
        └── references/
            ├── interview-personas.md   # the persona panel + question banks
            ├── document-catalog.md     # adaptive doc-selection logic
            ├── conventions.md          # house style, ID schemes, cross-ref syntax
            ├── almanac-guide.md        # when & how to build an almanac
            └── templates/              # structural skeletons for every document

The templates are reverse-engineered from two real, hand-written project documentation sets, then stripped to reusable, placeholder-driven scaffolds.

Design principles

• Interview before you write. Doc quality is capped by interview quality.
• Adaptive scope. Match the paperwork to the project. No NFR suite for a static site.
• One fact, one home. Everything is referenced, never copy-pasted; IDs make it traceable.
• CLAUDE.md stays light. It's an index, not a dumping ground.
• Reference material, not narrative. Terse, scannable, table-first.

License

MIT — see LICENSE.

{
  "name": "thelogicatelier",
  "owner": {
    "name": "The Logic Atelier",
    "email": "admin@thelogicatelier.com",
    "url": "https://github.com/achatt89"
  },
  "metadata": {
    "description": "Keel — lay the foundational documentation suite for a greenfield software project through a guided, multi-persona interview.",
    "version": "2.0.0"
  },
  "plugins": [
    {
      "name": "keel",
      "source": "./plugins/keel",
      "description": "Interview the founder about a new project idea, then generate the right set of foundational docs (CLAUDE.md, BRD, PRD, ARCHITECTURE, LLD, ADR, NFR, and more) ready to build from with Claude Code. Then keeps building on them: /keel phase new, /keel change, /keel closeout, /keel upgrade (incl. 1.x → 2.0 format migration), /keel archive, /keel version. v2.0: evidence ladder, per-file table ADRs, DEPLOYMENT + CHANGELOG, byte-budgeted keystone with auto-archive.",
      "version": "2.0.0",
      "author": {
        "name": "Abhijit Chatterjee"
      },
      "keywords": [
        "documentation",
        "greenfield",
        "scaffolding",
        "brd",
        "prd",
        "architecture",
        "adr",
        "interview",
        "project-kickoff"
      ]
    }
  ]
}