Metadata-Version: 2.4
Name: project-kit-cli
Version: 0.5.1
Summary: Project definition and dev-workflow kit that hands off to Spec Kit
Keywords: project-management,spec-kit,claude-code,workflow,github
Author: Miguel Tomás
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Dist: pyyaml>=6.0.3
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# project-kit

[![PyPI](https://img.shields.io/pypi/v/project-kit-cli)](https://pypi.org/project/project-kit-cli/)
[![License: MIT](https://img.shields.io/pypi/l/project-kit-cli)](https://pypi.org/project/project-kit-cli/)

**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](https://github.com/github/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](https://claude.com/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](https://docs.astral.sh/uv/) (it also fetches Python 3.12+ if you do not have it)
- `git`
- [Claude Code](https://claude.com/claude-code), to run the guided phases
- [`gh`](https://cli.github.com/), logged in with the `repo` and `project` scopes
  (`gh auth login`, then `gh auth refresh -s project`), to create things on GitHub; or
  [`glab`](https://gitlab.com/gitlab-org/cli) (`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

```bash
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 `pjkit docs upgrade`.

## Quick start

In your repository, new or existing:

```bash
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:

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

## You do not need to learn the skills

You never have to know which skill fits which moment. Open your agent in the project and say
what you want in your own words: *"continue"*, *"I already have a PRD"*, *"challenge this plan"*,
*"the scope changed"*, *"is this feature really done?"*. The agent picks the skill.

- `init` writes a block in `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` with a table of *what the user
  wants → which skill*, refreshed as the project moves.
- `/pk-next` is the conductor: it reads `pjkit next`, runs the phase that is due, offers
  `pk-grill` before each approval, suggests `pk-skills` once the stack is chosen, `pk-amend`
  when the plan changes and `pk-verify` when an issue seems finished. It never approves for you.
- `pjkit next` and the end of `pjkit status` print what to tell your AI, in plain words, for
  agents that have no `/` commands.
- Claude Code can also be told the project's state at the start of each session
  (`pjkit hook install`, asked in `init`, never without a yes).

## Starting from documents you already have

`pjkit import <folder or file>` (or `pjkit init --from <path>`) copies a PRD, notes or a wiki
export into `docs/sources/` without touching the originals, and lists them in
`docs/sources/INDEX.md` with how each can be read. Then `/pk-import` drafts the brief, the
decisions (as *Proposed*), the roadmap and the backlog from them, citing the source of every
claim, marking what they do not say as `[NEEDS CLARIFICATION]`, asking about contradictions, and
reviewing the result with `pk-grill`. It never overwrites a document or approves a phase. Files
that look like they contain secrets or personal data are not copied unless you say so
(`--allow-sensitive`).

## The phases

| # | Skill | What it does | Produces |
|---|---|---|---|
| 0 | `/pk-start` | Checks your setup and lets you choose: only initialise, or start now | `.project-kit/` |
| 1 | `/pk-discover` | Interviews you about the project: problem, users, scope, constraints | `docs/project/brief.md` |
| 2 | `/pk-decide` | Guides the technical decisions: monolith or monorepo, language, package manager, data, auth, hosting | `docs/adr/*.md` |
| 3 | `/pk-workflow` | Agrees how the team works: branches, reviews, quality gates | `docs/development-workflow.md` |
| 4 | `/pk-foundations` | Writes the project's own rules from its stack: code standards, testing, security, documentation | `docs/project/standards.md`, `testing.md`, `security.md`, `documentation.md` |
| 5 | `/pk-plan` | Derives phases, epics and a backlog from all of the above | `docs/project/roadmap.md`, `.project-kit/backlog.json` |
| 6 | `/pk-provision` | Creates milestones, labels, branches, the GitHub Project and the issues (skipped with `provider: none`) | GitHub |
| 7 | `/pk-handoff` | Prepares the Spec Kit constitution; each issue becomes a spec; writes `CLAUDE.md` / `AGENTS.md` | `.project-kit/handoff/constitution-input.md` |

`/pk-next` runs the whole sequence for you (see above). Outside the sequence, three more
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

| Command | What it does |
|---|---|
| `pjkit init` | Install the skills, templates and workflow in the current directory |
| `pjkit status` | Show the phases and what comes next |
| `pjkit upgrade [--apply] [--adopt] [--diff]` | Update the skills and templates a project already has |
| `pjkit help` | Show a visual guide (also what plain `pjkit` prints) |
| `pjkit doctor` | Check that git, gh, uv and Spec Kit are available |
| `pjkit approve <phase>` | Record your sign-off of a phase |
| `pjkit backlog validate` | Validate `.project-kit/backlog.json` |
| `pjkit provision [--dry-run] [--project X]` | Create milestones, branches, the Project and issues on GitHub |
| `pjkit handoff [--install-speckit]` | Generate the Spec Kit constitution input |
| `pjkit next [--json]` | What comes next, in words you can give to your AI |
| `pjkit import <path>` | Copy existing documentation to `docs/sources/` for `/pk-import` |
| `pjkit hook install\|remove` | Tell Claude Code the project's state at the start of each session |
| `pjkit mode [quick\|full]` | Show or change how many phases the project goes through |
| `pjkit trace [--criteria] [--json]` | Show which issues have a spec, a decision and a test, and what is not linked |
| `pjkit statusline [--install]` | One line for Claude Code's status bar: model, context, usage limits and the project phase |
| `pjkit context [--dry-run]` | Write or refresh the project block in `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` |
| `pjkit skills list\|show\|mark` | Recommended third-party skills, their install command, and what the project decided |

Useful `init` options: `--from <path>`, `--mode quick|full`, `--no-context`, `--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.

## Small projects: quick mode

Not every project needs seven phases. `pjkit init --mode quick` (or answer yes when `init` asks
whether it is a small project) skips *decide*, *workflow* and *foundations*: you go from the
brief to the plan, and the stack is taken from the brief. `pjkit mode full` brings the phases
back, `pjkit mode` shows where you are, and `pjkit status` says which phases are skipped and why.

## Checking that it is really done

The agent that built a feature should not be the only one to decide it is finished.
`/pk-verify` is a second opinion: it reads the issue's acceptance criteria, runs the project's
own tests and gives a verdict per criterion with evidence (`PASS`, `FAIL` or `INCOMPLETE`),
without touching any file. In Claude Code, `init` also installs the `pk-reviewer` subagent
(`.claude/agents/`), read-only, so the check runs in a context separate from the implementation.

`pjkit trace` shows the links between what was asked and what exists. Each acceptance criterion
has a stable name, `<issue id>#<position>` (`login#2`); write it in a test name or a spec and
`trace` lists the issues with no spec, the specs with no test, the criteria with no test, the
decisions nobody mentions and the references to things that do not exist. A link is a mention:
it shows what is missing, not that a test is any good, which is what `/pk-verify` is for.

`pjkit approve` refuses to sign off a phase whose documents still have
`[NEEDS CLARIFICATION]` markers (it asks if you are at a terminal; `--allow-open-questions`
approves anyway).

## 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 `pjkit docs statusline`.

## 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 `pjkit docs 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: `pjkit docs skills`.

## 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

The detailed guides ship with the program (in Spanish). `pjkit docs` lists them and
`pjkit docs <topic>` prints one: `upgrade`, `provisioning`, `handoff`, `backlog-schema`, `skills`,
`statusline` and `agents`.

## License

MIT.
