Keelokit

Keelokit the technical page

For developers: how it’s built.

The commands, the house rules, the guard and what runs on every commit. The same method as the plain page, in detail.

← Keelokit in plain words Orchestrating releases? How Harbor works →

This is the bottom: everything above is what you see, this is how it holds.

−20 m

From an idea to a monorepo that runs

/keelokit:project-new walks you through five gates and shows each one on a dashboard. Stage by stage, it stops wherever your decision matters; in automatic mode, only where a person is required. Everything gets written 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 and the rules they must keep, 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 --all▶ Up to date with origin/main (GIT-1)▶ Secret scan (gitleaks)▶ Prisma client▶ Format▶ Lint▶ Typecheck▶ Harness doctor  ✔ harness healthy▶ Unit tests▶ Throwaway PostgreSQL (migrated, seeded)▶ Integration tests (real PostgreSQL)▶ Build▶ End-to-end journeys▶ End-to-end on the real stack (./apps/web)▶ Dependency audit✔ verify passed

The stack it generates

  • pnpm
  • TypeScript
  • NestJS
  • Prisma
  • PostgreSQL
  • React
  • Vite
  • Expo
  • Astro
  • Zod
  • Vitest
  • GitHub Actions
  • Fly.io

Where to start

What you haveStart withWhat you get
An idea, nothing else/keelokit:project-newA monorepo that runs, with CI, context and a first backlog
A repo you already have/keelokit:project-adoptThe rules mapped to its checks, and the rest as dated debt
A story to build/keelokit:build-storyTests written first, code that passes them, a verified result
Bugs that keep slipping through/keelokit:check-bugbashRoot-cause fixes, and a check that covers the whole class of every bug that escaped
A project to follow/keelokit:project-dashboardNewA light, live page: the next step to copy, what waits for you, every wave and its stories
Someone to show it to/keelokit:project-reportNewThe complete status, read-only, as a page to share or a file to export
An app to try on your phone/keelokit:run-localNewYour app and its API running on a phone, an emulator or the simulator, in one command
A product ready for users/keelokit:ship-setupStaging and production set up and verified, then /keelokit:ship-release for each version

−22 m

Every command

Twelve commands and the entry point, grouped by what you’re doing. Open any of them to see what it does, step by step.

Project

Start one, bring one in, follow it

/keelokit

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

How it works

What it does

  1. Reads the repo: approved stages, open questions, stories done and ready, the harness version.
  2. Answers in ten lines: where you are, the one next step, what waits for you.
  3. Opens the dashboard when a stage waits for you or a paused run resumes.

When

Any time you open a session and wonder what to do.

/keelokit:project-new

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

How it works

What it does

  1. Asks once how it should work: stage by stage or automatic, one story at a time or in parallel.
  2. Interviews you about the product and writes the context, with open questions instead of guesses.
  3. Writes a short PRD and picks only the apps it needs; you approve scope and metrics.
  4. Generates the monorepo with CI, hooks and tests, green before any feature.
  5. Plans the backlog in development waves; the dashboard shows each stage as it goes.

When

You have an idea and an empty folder.

/keelokit:project-adopt

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

How it works

What it does

  1. Reads the repo without running or changing anything, and works out what it is: a product with screens and a database, a service, a library, a CLI, a plugin.
  2. Installs only .keelokit/ and applies only the house rules that fit that kind of project, mapped to checks the repo already has.
  3. What it can’t meet yet becomes a dated exception you approve, with a story to pay it off.
  4. Writes a diagnosis of the real code and seeds the backlog; the dashboard shows what it found.

When

You already have code and want the rules and checks without a rewrite.

/keelokit:project-dashboardNew

The page you work from: light, live, and rebuilt from the repo.

How it works

What it does

  1. Shows where the project is and the one next step, with its command ready to copy.
  2. Lists what waits for you: approvals, the decisions a bug bash or a security review left with the recommended option, environments still being set up.
  3. Shows every development wave with its stories, each linked to its file: done, ready to build, or waiting for another.
  4. Stays live: it’s published once, then each refresh updates the open page without sending it through the chat again, so it costs very few tokens.

When

To see where things are, approve a stage, or pick up after a pause.

/keelokit:project-reportNew

The complete status of the project, read-only, to share or export.

How it works

What it does

  1. Lays out every stage with its documents: context, open questions, the PRD’s scope and metrics, the stack, the backlog by wave and by epic.
  2. Adds every bug bash and security review with its findings, the environments, the decisions and the history.
  3. Publishes it as its own page you can share, or writes an HTML file that opens anywhere.
  4. It’s a snapshot for reading: no buttons that send requests, and a new one whenever you want to share a later state.

When

To show the project to a partner, a client or an investor, or keep a record of where it stood.

Plan

Know what to build

/keelokit:plan-intake

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

How it works

What it does

  1. Asks what already exists in writing and reads it first.
  2. Asks only what’s missing, at most four questions at a time, and only accepts measurable answers.
  3. Writes the context: product, domain and its invariants, constraints, environments, open questions.
  4. Every unknown stays a question with an owner.

When

A new product, or a new feature that needs context.

/keelokit:plan-backlog

Epics and stories with acceptance scenarios and the invariants they keep, in waves so parallel work never collides.

How it works

What it does

  1. Splits the PRD into epics and stories you can see working end to end.
  2. Writes acceptance scenarios for each story and the invariants it must keep.
  3. Groups stories in development waves that never touch the same files, so they can be built in parallel.
  4. Shows you the order; stories that came from a bug bash or a security review say so.

When

After the PRD, after a new feature intake, or to re-plan.

Build

Turn stories into working product

/keelokit:build-story

One story at a time, or a whole wave in parallel: tests first, then code, then people who didn’t write it try to break it.

How it works

What it does

  1. Writes the story’s contract: every scenario, invariant and dimension it can break.
  2. A verifier writes the acceptance tests before any code; they fail for the right reason.
  3. A builder makes them pass without touching the tests.
  4. A reviewer reads the diff cold and a breaker attacks it: double submits, parallel requests, other tenants.
  5. The verifier walks it in the running app; only then does it land.

When

A story is ready. One at a time, or several of the same wave at once.

Check

Find what slipped through, and keep it from coming back

/keelokit:check-bugbashNew

A bug hunt across data, API, integrity, UX, i18n, accessibility and security. Every escaped bug adds a check for its whole class.

How it works

What it does

  1. Looks at what the project is and hunts accordingly: data model, contracts and screens for a product; developer experience, docs and packaging for a library or plugin.
  2. Another agent tries to refute each finding; only reproducible ones stay.
  3. Fixes each one at its root, with a failing test first.
  4. Adds a check for the whole class, logs the escape, and turns what’s left into stories.

When

After each wave, and before a release.

/keelokit:check-security

Security and privacy in depth: personal data, the law of each market, abuse of the critical journeys, scans.

How it works

What it does

  1. Maps every piece of personal data: what, why, who sees it, for how long, where it goes.
  2. Names the privacy law of each market and what it asks of this product.
  3. Threat-models the critical journeys; scans dependencies, images and staging (OWASP ZAP).
  4. Checks personal data in logs, export and deletion, retention and encryption.
  5. Fixes with a test and a check per class; privacy choices and legal questions come to you.

When

Before the first production release, and when a release touches personal data, auth or payments.

/keelokit:check-health

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

How it works

What it does

  1. Checks that every house rule has a check that looks alive: a test, a lint rule, a CI job, a git hook.
  2. Checks exceptions, context, invariants, critical areas and the backlog.
  3. Adds a new rule with its check, or registers a dated exception with your approval.

When

When CI or the dashboard reports harness errors, or to add a rule.

Environments

From your phone to your users: local, staging and production, releases

/keelokit:run-localNew

Your app and its API on your phone, an Android emulator or the iOS simulator, in one command. Whatever your Mac is missing, it installs after one yes.

How it works

What it does

  1. Checks what the Mac is missing (Node, Docker, the JDK, the Android SDK, Xcode…), shows it all at once and installs it after one yes.
  2. Starts the database and the API, asks whether to load the sample data, and shows the test users to sign in with.
  3. Launches the app on the phone, emulator or simulator you choose, without rebuilding what is already installed.
  4. When a step fails it keeps the error, so Claude reads it, fixes it and tries again. It never stops a process, a container or an emulator without asking.

When

You want to see and touch what you are building. macOS, for projects with a mobile app.

/keelokit:ship-setup

Staging and production for people who have never deployed: a guide, the automation, and proof for each step.

How it works

What it does

  1. Writes a deploy guide with a checklist per environment, in plain words.
  2. Does what needs none of your credentials: Fly.io apps, config, GitHub environments with production approval, deploy tokens.
  3. Walks you through accounts, logins, payment and your own keys; it never types a credential.
  4. Verifies each step for real and shows it on the dashboard.

When

After the skeleton, before the first release, or when an environment isn’t ready.

/keelokit:ship-release

A version of your product people can name, read about and roll back to.

How it works

What it does

  1. Picks the next version from what landed: new things, fixes, breaking changes.
  2. Writes release notes users understand, each line tied to its story or finding.
  3. Tags vX.Y.Z on main, only after your yes.
  4. Production deploys only after a person approves it in GitHub; it follows the deploy to the end.

When

A wave is done and the last bug bash is clean.

Harness

Keep the harness itself up to date

/keelokit:harness-upgrade

Maintenance of the harness, not of your app: brings Keelokit’s newer rules and checks into your project.

How it works

What it does

  1. Compares the harness version your project runs with the new one.
  2. Merges the template’s changes on a branch: rules, doctor and guard, CI, hooks, base configs.
  3. Never rewrites your product code: apps, migrations, end-to-end tests and translations stay as they are.
  4. Resolves conflicts, runs the full checks, and asks you about any new rule that fails.

When

After updating the plugin, or when the dashboard says the harness is behind.

−24 m

New in 0.8

One page to work from, one report to share

/keelokit:project-dashboard builds a short page from your repo, in your language: where the project is, the next step, what waits for you. It stays live, and it’s light: published once, then each refresh updates the open page without sending it through the chat again, so following a project costs very few tokens. For someone else, /keelokit:project-report generates the complete status, read-only, to share or export.

Fleetly, a sample mobile app for delivery fleets, halfway through its buildOpen full size
One page to work from, one report to share: Fleetly, a sample mobile app for delivery fleets, halfway through its build
Where you are, and what comes next
01

Where you are, and what comes next

The stages as one line of progress, the run decisions you took once, and the one next step with its command ready to copy.

What waits for you
02

What waits for you

Approvals, the decisions a bug bash or a security review left with the option it recommends, environments still being set up, harness updates. Each links to its source and has its request ready.

Every wave, every story
03

Every wave, every story

Stories under their development wave, each linked to its file in the repo: done, ready to build (copy its command), or waiting for another. Finished waves fold away.

Health and environments at a glance
04

Health and environments at a glance

The doctor, the last bug bash and security review with what they fixed, staging and production step by step — and the project’s documents one click away.

Copy it, or send it to Claude
05

Copy it, or send it to Claude

Every button copies its request and fills this box: complete it, then send it to the Claude session watching the dashboard, or paste it into any chat.

The full report, to share or export
06

The full report, to share or export

/keelokit:project-report lays out every stage with its documents, every finding, the decisions and the history. Read-only, as a page you can share or an HTML file that opens anywhere.

Light or dark, one click, with contrast tested to WCAG AA in both
Light or dark, one click, with contrast tested to WCAG AA in both

−26 m

New in 0.9

Your app on your phone, in one command

/keelokit:run-local starts the database and the API and opens your app on an Android phone, an emulator or the iOS simulator. It is the first step of the environments: local, then staging and production with /keelokit:ship-setup, then versions with /keelokit:ship-release.

  1. It sets up the Mac for you

    It checks what is missing, shows it all at once and installs it after one yes. Nothing gets installed behind your back.

  2. The second run is instant

    If the app is already installed and nothing native changed, it skips the build and just opens it.

  3. Ready to try

    It asks whether to load the sample data and shows the test users to sign in with.

  4. When something breaks, Claude fixes it

    Each step leaves its log and the last error; Claude reads it, repairs it and runs it again. It never stops a process, a container or an emulator without asking.

Your app on an Android phoneExample output
pnpm run:local android▶ Diagnosis  ✓ Node v22.12.0  ✓ pnpm 10.33.0  ✓ Docker running  ! JDK 17▶ I am going to install/configure:    JDK 17 (brew install --cask zulu@17)   [y/N] y▶ Database and API  ✓ database on port 5432  ✓ API on port 3000 (log: .local-dev/logs/api.log)▶ Android: Galaxy S20 (USB)  ✓ already installed, nothing native changed: no rebuild  ✓ Metro running, app opened

macOS for now. Launched on a Galaxy S20 over USB and on the iOS simulator.

−28 m

The part you don’t see

In my experience, agents tend to close stories and leave a trail of bugs behind them, bugs they neither write down nor mention. That’s where these four ideas came from.

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, a breaker attacks the branch, and only the verifier can call a story done.

IV

Bugs come in classes

What must always hold (totals add up, a notice goes out once, a limit holds with two requests at once) is written as an invariant and proven with property, concurrency and replay tests. Critical code gets mutation testing, so its tests can actually fail.

Proof, not promises

  • Built with itself. Keelokit runs on its own harness. A bug bash of its own repo found 50 root causes, and every fix came with a check for its class.
  • Findings reproduced, fixes reviewed. In a bug bash, an agent that didn’t report a finding has to reproduce it (two, for the serious ones), and one that didn’t write a fix reviews it. A rejected fix is undone; a run cut short picks up where it stopped.
  • Repo text is data, not orders. The bug bash’s agents get what the repository says marked as data, so an instruction planted in a file can’t steer them.
  • Not only apps. It looks at what the project is: a web or mobile product, or a library, CLI or plugin, and checks what matters for it: screens and data, or developer experience, docs and packaging.
The doctor, in a projectExample output
pnpm doctorKeelokit doctor  Gates: intake ✓ → product ✓ → stack ✓ → skeleton ✓ → backlog ✓  Rules: 34 · Context gaps: 2 (0 blocking)  Invariants: 6 · Critical areas: 1 · Escapes logged: 2  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
  • INV-1Every invariant proven by a testdoctor, in CI
  • MUT-1Tests of critical code that can failmutation score in CI

−30 m

What runs on its own

  1. Before every agent action

    A guard stops secrets (AWS, GitHub, Stripe, Anthropic, npm, GitLab, JWT keys and more, even split across two edits), 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 and against the real API, mutation testing of critical code, 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

Where everything happens.

Keelokit has no server of its own and collects nothing. Everything stays on your computer and in your accounts.

Your computer

Where the work happens

Claude Code runs there with Keelokit. That’s where the code is written and the app is tried out while it’s built.

GitHub

Keeps it and checks it

  • Keeps the code in a private repository in your name, with the history of every change.
  • On every change, a robot runs all the tests and checks. If something fails, it doesn’t go in.
  • Asks a person to approve before anything reaches production.

Fly.io

Where the app lives

The server on the internet for the back of the app, the part that handles requests, and its database.

StagingA test copy. It updates itself with every approved change.
your OK
ProductionThe one your customers use. It only changes when you approve.
Web hostingThe one you choose. Your web app and your landing page go there.
DockerA test database on your computer, so real data is never touched.
Sentry (optional)Tells you when the app throws errors at your users.
claude.aiWhere the project dashboard is published, private to your account.

−34 m

Ideas I learned from, and a note on the pictures

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.