Kickstart — five gates from idea to a working skeleton

Rules for the whole run:

• Interview in the user's language; write files in English unless the user asks otherwise.
• The user may be a founder who has never run a software project, let alone agents. The first time a term of art comes up (PRD, stack, epic, story, development wave, worktree, invariant, gap, staging), explain it in one plain sentence. In Spanish, waves are olas de desarrollo.
• The dashboard (/keelokit:project-dashboard) is the user's view of the whole run: show it at the start, refresh it when a gate's output is ready and after each approval.
• Never ask for an approval without showing what is being approved. At each gate: refresh the dashboard, give its link and the section (#stage-<gate>), and summarise in the chat what the approval covers (the lists below). Then ask.
• After each approval, record it in .keelokit/state.toml under [gates] as <gate> = "<YYYY-MM-DD>" ("<YYYY-MM-DD> auto" when automatic mode approved it). That file holds the approvals, the run decisions ([run]), the dashboard's settings ([dashboard]: lang, url) and, only when the project uses Harbor, [landing] policy = "convoy" (absent = direct, see .keelokit/harness/agent-brief.md) and [verify] shared_seals / wip_branches (docs/verify.md), nothing else.
• Between gates report progress in one line and continue; stop only at the approvals above — and in automatic mode, only where a person is required (below).
• Resume: if .keelokit/state.toml exists, continue from the first gate without a date, and open the dashboard first so the user sees where the run stopped.

0. Where

Ask for the product's name and one sentence of what it is, and propose the folder ~/Development/<slug>, where the slug is the name as the template derives it: lowercase ASCII (accents folded: "Peña S.A." → pena-s-a), anything else a dash, and app- in front when it would start with a digit or be empty ("3D Store" → app-3d-store). Create it (empty) once the user agrees. If it exists and is not empty, ask before using it.

Create .keelokit/state.toml with [dashboard] lang = "<the user's language code>".

Then settle the two run decisions — once per project, with the multiple-choice tool and a recommendation, explained in plain words:

1. Run mode. Stage by stage (recommended for a first project): Keelokit stops at the end of every stage for the user to review and approve it, and between stories. Automatic: it goes on alone and stops only where a person is required — the questions only the user can answer (the interview, blocking gaps), approving the PRD's scope and metrics or a stack deviation, accounts and credentials, and everything .keelokit/harness/execution-protocol.md reserves for the human (production, money, legal, deleting data, paid services). Every automatic approval is recorded and stays reviewable on the dashboard.
2. How stories are built. One at a time or in parallel, up to N at once (2–4); see Close for how to explain it.

Record them:

[run]
mode = "step"        # or "auto"
build = "serial"     # or "parallel"
parallel = 3         # only with build = "parallel"
decided = "<YYYY-MM-DD>"

These are fixed: no skill asks them again or changes them on its own. Only an explicit request from the user changes one (update the value and decided, and say so in one line).

Open the dashboard: it shows the stages ahead and these decisions, so the user knows the whole road before the first question.

Automatic mode approves, by itself, the gates no rule reserves for a person — context (only with no blocking gap open), stack (only with no deviation from the house stack), skeleton and backlog — records them as "<date> auto", refreshes the dashboard, reports in one line and goes on. The PRD is always the user's approval. After the backlog it continues straight into /keelokit:build-story with the recorded build mode.

1. Intake

Run /keelokit:plan-intake in the new folder. When it finishes, refresh the dashboard and show in the chat: the problem and users in two lines, the invariants (rules that must never break), and the open gaps with who answers each, blocking first. Then ask for approval. Blocking gaps can stay open only if the user explicitly accepts them.

2. Product (PRD)

Before writing it, say what a PRD is: the Product Requirements Document — what the first version builds, what it deliberately leaves out, and which numbers will say it worked; what isn't in it doesn't get built.

Write docs/prd.md from the context using references/prd-template.md. Every metric has a number and a date; every scope line is either in or out. Anything the context doesn't support becomes a gap in docs/context/gaps.md, not an assumption. Refresh the dashboard and show in the chat the scope (every in and out line) and the metrics (metric, target, date). Then ask for approval.

3. Stack

First, what kind of project this is, from the PRD: a product people use (web, mobile, an API others call), or something developers use (a library, a CLI, a plugin, a template). The template builds products. For a developer-facing kind it would only add apps, a database and hosting the project doesn't need: say so, and instead start a minimal repo (git init, README, the context and PRD already written) and bring the harness in with /keelokit:project-adopt, which writes the profile and applies only the rules that fit.

For a product, the house stack is fixed (${CLAUDE_PLUGIN_ROOT}/template/.keelokit/harness/stack.md). Decide only:

• apps — any of api, web, mobile, site, justified from the PRD's users and channels;
• postgis — only if the domain has geospatial queries. If a requirement truly can't be met by the house stack, write docs/decisions/0001-<title>.md (Status, Context, Decision, Consequences) and get approval. "Would be nicer" is not a reason.

Nothing more than the PRD needs: no API if nothing is stored or shared, no mobile app if the web works on phones, no public site if there's nothing to say before sign-up. The skeleton writes .keelokit/profile.toml from the apps; add personal-data and payments to its traits when the context says so.

Write docs/stack.md: the apps chosen, one line each on why (citing the PRD's users and channels), the apps left out and why, PostGIS yes/no, and any decision record. Refresh the dashboard, show the same in the chat in plain words (what each app is for the user: "a web app the receptionist opens on the phone", not "Vite + React"), and ask for approval.

4. Skeleton

1. Template source: $KEELOKIT_TEMPLATE if set (a fork: gh:<you>/keelokit), otherwise gh:leosimini/keelokit, at the plugin's version tag (v + version from ${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json). If git can't reach it (offline), use ${CLAUDE_PLUGIN_ROOT} and warn that the project can't /keelokit:harness-upgrade until its .keelokit/answers.yml _src_path points at a git source.
2. Generate into the product folder (existing docs/ is kept):

   uvx copier==9.18.2 copy --defaults --vcs-ref v<version> --data project_name="<name>" \
     --data description="<one sentence>" --data 'apps=["api","web"]' --data postgis=false \
     "${KEELOKIT_TEMPLATE:-gh:leosimini/keelokit}" <folder>

   Copier derives the package slug from the name (as in step 0). Add --data project_slug=<slug> only for one the user chose, and only if it starts with a letter and has nothing but lowercase letters, digits and dashes: --defaults never asks again, so copier stops with a traceback on any other.
3. git init -b main, pnpm install, then pnpm verify and pnpm mutation --all. Fix until green — the fix belongs in the generated project only if it is product-specific; if the template itself is wrong, say so: it must be fixed in Keelokit.
4. First commit, of everything (git add -A: pnpm-lock.yaml included, or pnpm verify can't compare it with origin/main): chore: skeleton from Keelokit v<version>. With a mobile app, the template writes [local] in .keelokit/profile.toml and a run:local script: mention that /keelokit:run-local (or pnpm run:local) launches the app and its API on a phone or a simulator, and offer it once the skeleton is green.
5. Ask whether to create a private GitHub repo (gh repo create <slug> --private --source . --push).
6. Staging: the API deploys to Fly.io from CI. Offer /keelokit:ship-setup now: it writes the deploy guide, does what needs none of the user's credentials and verifies each step. The Fly account, logins, payment and third-party keys stay the user's; never type credentials yourself. Record the gate even if staging setup is deferred, and add a non-blocking gap "staging not configured" (owner: user).

5. Backlog

Run /keelokit:plan-backlog. Refresh the dashboard: it shows the stories by development wave and by epic. In the chat, list the epics and, per wave, its stories (id and title), plus any story waiting for a gap. Ask for approval of the epics and the wave order.

Close

Report in five lines: what exists, pnpm verify status, open gaps by owner, the first ready story, and what needs the user (accounts, approvals). Refresh the dashboard. Mention once that the project carries a small "Built with Keelokit" credit (README badge, a line at the foot of the public site) and that the dashboard's footer turns it down or off.

Then, in stage-by-stage mode, offer to start building with the recorded build mode; in automatic mode, start. When explaining the build modes (at step 0), use plain words (the dashboard's "How to build" section says the same):

• One at a time (/keelokit:build-story): one story is built, tested and lands before the next. Slower; the user follows every step and Claude usage is spread out. Recommend it for the first wave, for sensitive stories and for a first project with agents.
• In parallel (/keelokit:build-story <N>): N ready stories of the same wave at once, each in its own copy of the repo (a worktree) with its own agents. Faster, more Claude usage at the same time, several results to review together. Safe because stories in a wave never touch the same files.