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 (Claude Code, Codex CLI, Gemini CLI, GitHub Copilot or Cursor) 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. Other agents get their skills and context files but are started by hand. GitLab support is new and has only been tried against a simulated API, not a real GitLab project: read the --dry-run before applying.

Requirements

• uv (it also fetches Python 3.12+ if you do not have it)
• git
• Claude Code, to run the guided phases
• gh, logged in with the repo and project scopes (gh auth login, then gh auth refresh -s project), to create things on GitHub; or glab (glab auth login) for GitLab; or neither, with --provider none

pjkit doctor checks all of this for you. Spec Kit is installed for you at the end, if you want it.

Install

uv tool install project-kit-cli      # installs the `pjkit` command
uv tool upgrade project-kit-cli      # later, to update the program

The package is called project-kit-cli; the command is pjkit. To try it without installing: uvx --from project-kit-cli pjkit help.

Updating a project. init copies the skills and templates into your repository and never overwrites them, so a new version of the program does not change a project that already exists. Run pjkit upgrade inside it to see what is out of date, and pjkit upgrade --apply to bring it up to date. Files you edited are never overwritten; see upgrading.

Quick start

In your repository, new or existing:

cd my-project
pjkit init

init copies the skills and templates into the repository and then offers to open Claude Code right there, already running /pk-start (press Enter to accept). /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:

pjkit status     # where you are and what comes next
pjkit help       # a visual guide to the flow and the commands

The phases

Outside the sequence, three skills are always available: /pk-grill interviews you hard and cross-checks the project's documents for contradictions (it is offered before each approval), /pk-skills recommends third-party skills that fit the project, and /pk-amend brings a change after the plan (a new epic, a decision that replaces another) into the documents and the backlog.

Each phase ends with an explicit approval (pjkit approve <phase>), and a phase cannot be approved while an earlier one is still open. The phases are listed in .project-kit/workflow.yml; for a small project, switch one off with enabled: false.

To fill a document by hand instead, copy the matching template from .project-kit/templates/ (brief.md, adr.md, development-workflow.md). The skills read what is already there and only ask about what is missing.

Existing repositories and Projects

init never overwrites a file, so it is safe in a repository that already has code, documents or a .claude/ folder. Before creating a GitHub Project, provision looks at the ones already linked to the repository: with one it asks whether to use it, with several it lists them, and with none it asks for a name. Use --project <number or title> to choose without being asked. It never rewrites issues that already exist, and re-running it is always safe.

Commands

Useful init options: --project-name, --language (language of the generated documents), --agents claude,codex,... (the AI agents you use; asked when there is a terminal), --agent claude|none (open the agent or not), --provider github|gitlab|none and --ai-coauthor keep|remove.

AI agents

Like Spec Kit, init asks which agents you use, and you can pick several: Claude Code, Codex CLI, Gemini CLI, GitHub Copilot and Cursor. The skills are installed where each one reads them (.claude/skills for Claude Code, .agents/skills for the rest) and, at the end of the handoff, project-kit writes the context file each one reads (CLAUDE.md, AGENTS.md, GEMINI.md). Only the block between its markers is managed; the rest of the file is yours. Only Claude Code is started by init; for the others, open the agent and ask it to run the pk-start skill.

Status bar

Claude Code can show a line of your choosing at the bottom of the screen. pjkit statusline fills it with the model, the context in use, the 5-hour and 7-day usage limits (Pro and Max plans) and where the project is in the flow:

[Opus · high] · ctx 23% · 5h 41% (↻ 17:00) · 7d 12% · ~$1.23 · fase: decide → /pk-decide

init asks whether you want it, and pjkit statusline --install sets it up in .claude/settings.json (--remove undoes it). It is never turned on without a yes. If you already have a status bar, yours is kept and runs first. It is one line: when the terminal is narrow, the cost goes first, then the 7-day limit, the effort and the context. The cost is an estimate at list price. More in docs/statusline.md.

GitLab

pjkit init --provider gitlab makes provision use glab: phases become milestones, kind, priority, size and status become labels, and an issue board named project-kit is built from the status labels. Details in provisioning.

Generating a project without GitHub

pjkit init --provider none generates everything that lives in files (brief, decisions, workflow, rules, roadmap, backlog, constitution input, context files) and skips provision; doctor does not ask for gh either.

Recommended skills

project-kit keeps a catalog of third-party skills (UI/UX, motion, accessibility, SEO, security, architecture, browser testing, grill-me, find-skills...) in .project-kit/skills-catalog.yml. /pk-skills recommends the ones that fit your brief and decisions, warns when a task would benefit from one you do not have, and records the answer in .project-kit/skills.yml. project-kit never installs a skill: it shows the command and you run it; pjkit skills detect records the ones you already have. How the entries were chosen is in docs/skills.md.

AI co-author

init asks whether AI assistants may appear as co-authors of your commits and pull requests. If not, it configures Claude Code to stop signing them and installs a commit-msg hook that strips the co-author trailer of other assistants. Switch the hook on once per clone with git config core.hooksPath .githooks.

After the handoff

/pk-handoff leaves a text file for Spec Kit's constitution and tells you the next step:

/speckit-constitution @.project-kit/handoff/constitution-input.md

From there Spec Kit does the work. Each issue of the backlog is one spec: its text is the input of /speckit-specify, followed by /speckit-clarify, /speckit-plan, /speckit-tasks and /speckit-implement. project-kit never writes inside .specify/ and does not write specs.

The constitution is generated from your own rules: the branch pattern and merge strategy you agreed, the decisions on record, and an index of where each kind of rule lives (including the GitHub Project used for tasks). Once the constitution is written, pjkit approve handoff deletes the temporary input files; from then on the constitution is the single source.

What it adds to your repository

.project-kit/          config.yml, state.json, workflow.yml, templates/, handoff/
.claude/skills/pk-*/   the skills
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

Documentation

More detail lives in the repository (in Spanish): design, backlog schema, provisioning and Spec Kit handoff.

Feedback

Ideas and bug reports are welcome as issues. Pull requests are not accepted; see CONTRIBUTING.

License

MIT