Project Kit

Prereq 1 · A working Claude Code

claude --version

You need 2.x or newer. Whatever goes wrong, one of the three recipes below fixes it. Run them as written.

A. zsh: command not found: claude

Find out first whether it is missing or merely unreachable:

ls -l ~/.local/bin/claude /usr/local/bin/claude /opt/homebrew/bin/claude 2>/dev/null

If a path is listed, it is installed and your shell simply cannot see it. An already-open terminal keeps the PATH it started with, so a profile edit does not reach it. Put it somewhere every shell looks — /usr/local/bin is on the default system PATH and needs no sudo:

ln -sf ~/.local/bin/claude /usr/local/bin/claude
hash -r
claude --version

If nothing is listed, install it:

curl -fsSL https://claude.ai/install.sh | bash
hash -r
claude --version

B. Version below 2.0, or claude plugin prints generic help

An old build has no plugin command. Remove it before installing the new one, or the old binary keeps winning the PATH race and you end up with two installs:

which -a claude                              # every copy on your PATH
npm uninstall -g @anthropic-ai/claude-code   # if it came from npm
rm -f /usr/local/bin/claude /opt/homebrew/bin/claude   # stale symlinks

curl -fsSL https://claude.ai/install.sh | bash
hash -r
claude --version        # expect 2.x
claude plugin list      # expect plugin output, not the general help page

An old copy outside your current npm prefix is the usual culprit: a plain npm i -g installs to the prefix, which may lose the PATH race against it.

C. Invalid API key · Please run /login

A build predating subscription login, so it demands an API key it should not need. Do not supply an API key — Claude Code authenticates with your subscription. Apply recipe B, then if it still asks, sign in once:

claude
/login

If the installer produces nothing

It downloads to ~/.claude/downloads and can fail silently. If claude --version still fails afterwards and you have the VS Code extension installed, point a wrapper at the binary it already ships:

mkdir -p ~/.local/bin
cat > ~/.local/bin/claude <<'SH'
#!/bin/sh
b=$(ls -d "$HOME"/.vscode/extensions/anthropic.claude-code-*/resources/native-binary/claude 2>/dev/null | tail -1)
if [ ! -x "$b" ]; then echo "claude: no binary found" >&2; exit 127; fi
exec "$b" "$@"
SH
chmod +x ~/.local/bin/claude
ln -sf ~/.local/bin/claude /usr/local/bin/claude
claude --version

The glob picks the newest extension, so this survives extension upgrades. Replace it with a real install whenever the installer cooperates.

Prereq 2 · Python 3.9+

python3 --version     # or: python --version, py -3 --version

The gate and state logic is pure standard library, but it has to run. Windows usually has py -3 rather than python3; the launcher detects this, so it only matters if you call the scripts directly.

Prereq 3 · Install the plugin

claude plugin marketplace add miricoder/project-kit
claude plugin install project-kit

Then /reload-plugins, or start a new session. Confirm it loaded:

claude plugin details project-kit

If a later update seems not to arrive, refresh the marketplace as well as the plugin — claude plugin marketplace update project-kit then claude plugin update project-kit.

Prereq 4 · Check everything at once (optional)

If you cloned the repository rather than installing from the marketplace, one command reports every item above and changes nothing unless you ask:

./setup.sh            # macOS and Linux
.\setup.ps1           # Windows PowerShell
./setup.sh --fix      # apply the safe fixes

On Windows, if PowerShell refuses to run the file: Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned

Step 1 · Pick a home for the project

Project Kit writes pipeline.json and a docs/ folder into the directory you run it from. You do not have to create one by hand — if you are somewhere unsuitable, /ideate makes a subdirectory and tells you.

cd ~/projects        # or anywhere; an empty folder or a git repo is ideal
claude

It refuses to run inside the Project Kit plugin itself, which would write your project's files into the tool.

Step 2 · Describe the idea

/ideate an app that tracks my houseplants and tells me when to water them

What happens: it sets up state, researches prior art, works out who the user is and what job they are doing, then writes docs/research.md.

You will be asked up to five questions it cannot reasonably infer — platforms, whether it must work offline, what data is stored. Answer briefly; anything you leave it marks ASSUMED, and the judges test assumptions later.

Then it stops. This is checkpoint 1: confirm it understood the idea before more effort is spent on it.

A bare /ideate with no idea asks what you want to build and writes nothing.

Step 3 · Accept the scope

/proposal

What happens: it cuts v1 to the smallest thing that does the job end to end, lists what it explicitly will not do, phases the rest with acceptance criteria, and estimates build effort and running cost → docs/proposal.md.

Then it stops. Checkpoint 2, and the important one: this is the scope and money decision. Cut further or add back before continuing — everything downstream is bound by this.

Step 4 · Get the technical spec

/design

What happens: architecture, data model with migrations, interfaces, failure modes, rollback for code and data, plus executable Gherkin → docs/spec.md and docs/acceptance.feature. It also drafts the strongest case that its own design is wrong, which the judges are given to test.

No stop here — it flows straight on, because the next phase has its own checkpoint before spending anything.

Step 5 · The judge gate

/handover

What happens: builds the case and brief, sends them to three different model families, validates each verdict, and combines them mechanically into a ruling. /verdict then ranks the fixes and either opens the gate or sends you back.

It stops before sending. Checkpoint 3 — this spends real API credit, and there is no flag to skip it.