project-kit

Everything that happens before the first line of code. project-kit guides you, with an AI agent, through defining a project, deciding its stack and architecture, agreeing how the team works and planning the backlog. It then sets up GitHub and hands the project over to Spec Kit, which specifies and builds each feature.

idea ──▶ brief ──▶ decisions (ADRs) ──▶ workflow ──▶ backlog ──▶ GitHub ──▶ Spec Kit
         /pk-discover   /pk-decide       /pk-workflow   /pk-plan   /pk-provision  /pk-handoff

The conversations run in your AI agent as /pk-… skills: one question at a time, a recommended answer for each, and everything written to documents in your repository. Every phase ends with your approval, and every document can be written by hand instead.

Status: alpha. It works end to end on GitHub with Claude Code. Codex, Gemini, Copilot and Cursor get their skills and context files but have not been tried and are started by hand (the levels per agent: pjkit docs agents). GitLab support is experimental: reading a project was checked against the real gitlab.com API, but creating things (labels, milestones, board, issues) has only been tried against a simulated API. Read the --dry-run before applying; what was and was not checked is in pjkit docs provisioning.

Install

uv tool install project-kit-cli      # installs the `pjkit` command
uv tool upgrade project-kit-cli      # later, to update the program
pjkit doctor                         # checks git, gh/glab, uv and your PATH

You need uv (it fetches Python 3.12+), git, and an AI agent (Claude Code is the tested one). For GitHub, gh logged in with the repo and project scopes; for GitLab, glab; or neither, with --provider none. The package is called project-kit-cli; the command is pjkit. To try it without installing: uvx --from project-kit-cli pjkit help.

pjkit not found, or No pyvenv.cfg file. The skills and hooks call pjkit by name, so it must be on the PATH of the terminal that starts your agent. Install it with uv tool install (not inside a project's virtual environment) and run uv tool update-shell once. pjkit doctor points at the cause.

Quick start

cd my-project
pjkit init          # copies the skills and templates, then offers to open Claude Code on /pk-start
pjkit status        # where you are and what comes next, at any time

/pk-start asks whether to only initialise or to start defining the project now, and after every phase it asks whether to continue or stop. You can leave at any point and come back later. You never have to know which skill fits: open your agent and say what you want in your own words ("continue", "I already have a PRD", "the scope changed").

New here? Read the guides, which ship with the program (in Spanish):

The phases

Outside the sequence: /pk-next (runs the sequence for you), /pk-grill (hard questions and contradictions, offered before each approval), /pk-import (start from existing documents), /pk-skills, /pk-amend, /pk-verify and /pk-quiet (runs long commands and reads long logs through pjkit run, logs and peek so that only what failed reaches the AI; it pays off with long output, see pjkit docs quiet). Each phase ends with pjkit approve <phase>, which only you run. A small project can skip three phases with pjkit init --mode quick.

Commands

Useful init options: --from <path>, --mode quick|full, --no-context, --project-name, --language (of the generated documents), --agents claude,codex,..., --agent claude|none, --provider github|gitlab|none and --ai-coauthor keep|remove.

What it adds to your repository

.project-kit/          config.yml, state.json, workflow.yml, templates/, handoff/
.claude/skills/pk-*/   the skills (.agents/skills for the other agents)
docs/project/          brief.md, roadmap.md        (created by the phases)
docs/adr/              one file per decision       (created by the phases)
.githooks/commit-msg   only if you removed the AI co-author

init never overwrites a file, so it is safe in a repository that already has code. A new version of the program does not change an existing project: pjkit upgrade shows what is out of date and pjkit upgrade --apply brings it up to date without touching what you edited.

Documentation

pjkit docs lists every guide: quickstart, example, session, flow, quiet, upgrade, provisioning, handoff, backlog-schema, skills, statusline and agents.

License

MIT.