Keelokit

Open source · a personal Claude Code harness

The keel under my apps.

The harness I use to turn ideas into first versions with coding agents: my stack, my rules, the way I like to work. I maintain it on weekends and late nights, with music on, and share it in case it helps you too.

 claude plugin marketplace add leosimini/keelokit claude plugin install keelokit@keelokit

View on GitHub Dive in

What you build rides on top. What keeps it on course sits underneath.

−2 m

From an idea to a monorepo that runs

/keelokit:kickstart walks you through five gates. It stops only where your decision matters, and writes everything down as it goes.

  1. 01

    Intake

    An interview that reads what you already have first, then asks only what’s missing. What nobody knows yet stays written as an open question, with an owner.

  2. 02

    Product

    A short PRD: the problem, who it’s for, what’s in and, explicitly, what’s out.

  3. 03

    Stack

    The house stack. Anything that deviates from it is recorded as a decision, not improvised.

  4. 04

    Skeleton

    A generated monorepo with CI, git hooks and tests, green before you write a feature.

  5. 05

    Backlog

    Epics and stories with acceptance scenarios, grouped in waves that never touch the same files.

What you get
  • my-app/
  • apps/
  • api/NestJS · Prisma · PostgreSQL
  • web/Vite · React
  • mobile/Expo · iOS & Android
  • site/Astro
  • packages/
  • shared/zod contracts · i18n
  • ui-tokens/one source for the look
  • docs/context/what’s known, what’s open
  • backlog/stories with scenario ids
  • .keelokit/rules, checks, guard, doctor

You pick which apps a product needs.

The skeleton, checked end to end
pnpm verify▶ Format▶ Lint▶ Typecheck▶ Harness doctor  ✔ harness healthy▶ Unit tests▶ Integration tests (throwaway PostgreSQL)▶ Build▶ End-to-end journeys▶ Dependency audit✔ verify passed

Where to start

What you haveStart withWhat you get
An idea, nothing else/keelokit:kickstartA monorepo that runs, with CI, context and a first backlog
A repo you already have/keelokit:adoptThe rules mapped to its checks, and the rest as dated debt
A story to build/keelokit:buildTests written first, code that passes them, a verified result
Bugs that keep slipping through/keelokit:bugbashRoot-cause fixes, and a new check for every bug that escaped

−8 m

Every command

Nine skills. You can run them one by one, or let /keelokit tell you what comes next.

  • /keelokit:kickstart

    From an idea to a working skeleton: intake, PRD, stack, generated monorepo with CI, first backlog.

  • /keelokit:adopt

    Adds only the harness to a repo you already have. What it doesn’t meet yet becomes a dated exception.

  • /keelokit:intake

    Reads briefs, notes or a repo, then asks only what’s missing. Never fills a gap with a guess.

  • /keelokit:backlog

    Epics and stories with acceptance scenarios, in waves so parallel work never collides.

  • /keelokit:build

    One story at a time: the verifier writes the tests first, a builder makes them pass, a reviewer reads the diff.

  • /keelokit:bugbash

    A bug hunt across data, API, UX, i18n, accessibility and security. Every escaped bug adds a check.

  • /keelokit:doctor

    Is every rule still backed by a check that works? Adds rules, registers exceptions.

  • /keelokit:upgrade

    Brings a project to a newer template without touching its product code.

  • /keelokit

    Where the project stands, what comes next, what’s waiting for your decision.

−15 m

The part you don’t see

Agents kept telling me “done” and leaving bugs behind. These three ideas are what came out of fixing that, project after project.

I

A rule needs a check

Each rule points to something that verifies it: a test, a lint rule, a git hook, a CI job. The doctor tells you when a rule has lost its check.

II

Unknowns stay questions

What nobody knows yet is written down with an owner and the exact question. Plausible defaults don’t get invented.

III

The builder doesn’t grade itself

A verifier writes the acceptance tests before the code, a reviewer reads the diff cold, and only the verifier can call a story done.

The doctor, in a projectExample output
pnpm doctorKeelokit doctor  Gates: intake ✓ → product ✓ → stack ✓ → skeleton ✓ → backlog ✓  Rules: 26 · Context gaps: 2 (0 blocking)  Backlog: 4/11 done · next: AUTH-005, PAY-001  warn  exception for UI-1 until 2026-12-01: map SDK needs a literal colour  ERROR rule QA-1: CI job 'unit' has continue-on-error
A few house rules, and what enforces them
  • SEC-1No secrets in the reposecret scan in CI · guard · pre-commit
  • CFG-1Every config key documenteda test that compares schema, .env files and README
  • AUTHZ-1Every route has an access decisiona test that reads the real router
  • I18N-1Text only through translationslint rule · locale parity test
  • QA-4No silenced testsguard · pre-commit
  • TRACE-1Every scenario has a testdoctor, in CI

−24 m

What runs on its own

  1. Before every agent action

    A guard stops secrets, edits to .env files and to applied migrations, skipped hooks, silenced tests and production deploys.

  2. When a session starts

    A short status: where the project is and which stories are ready.

  3. On every commit and push

    The same guard as a git hook, then the full local check before anything reaches the remote.

  4. In CI

    Secret scan, lint and types, unit and integration tests on a real PostgreSQL, end-to-end journeys with an accessibility scan, static analysis, a staging deploy.

The guard, stopping an agent
git commit -m "wip" --no-verifyBlocked by Keelokit — QA-2: never bypass git hooks echo "API_KEY=…" > apps/api/.envBlocked by Keelokit — SEC-2: don't write .env files from the shell;edit .env.example, real values go in the secret store

−32 m

Good to know

It’s opinionated

It’s built around my preferences and my stack. It won’t fit every project or every team. If your stack is different, /keelokit:adopt still gives you the rules and the checks.

It uses tokens

build and bugbash run several agents per story. /keelokit:build --light exists for small changes.

The guard is a speed bump

It stops agents from the obvious mistakes, but it isn’t a sandbox. Git hooks and CI are the real backstop.

The doctor sees presence, not quality

It can tell a check exists and is switched on, not that it’s a good check. Reviews and bug hunts cover that.

Ideas I learned from. Spec-driven development (OpenSpec, Spec Kit), Superpowers for separating who builds from who reviews, Copier for templates that can be upgraded, and a lot of trial and error on my own projects.

−40 m

Try it

 claude plugin marketplace add leosimini/keelokit claude plugin install keelokit@keelokit

In an empty folder run /keelokit:kickstart. In a repo you already have, /keelokit:adopt.

You need Node 22 with pnpm 10, Python 3.11+, uv, Docker and git. macOS or Linux.

Code, docs and license on GitHub