Metadata-Version: 2.4
Name: project-kit-cli
Version: 1.0.0
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: Programming Language :: Python :: 3.14
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 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

```bash
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](https://docs.astral.sh/uv/) (it fetches Python 3.12+), `git`, and an AI agent
([Claude Code](https://claude.com/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

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

| Guide | What it is |
|---|---|
| `pjkit docs quickstart` | From zero to the first approved phase in 5 minutes, with and without GitHub |
| `pjkit docs example` | A finished project, file by file, with comments |
| `pjkit docs session` | A real, unedited conversation with Claude Code, from `/pk-start` to the decisions |
| `pjkit docs flow` | The whole flow in detail: phases, existing documents, quick mode, verification |

## The phases

| # | Skill | Produces |
|---|---|---|
| 0 | `/pk-start` | `.project-kit/` |
| 1 | `/pk-discover` | `docs/project/brief.md` |
| 2 | `/pk-decide` | `docs/adr/*.md` |
| 3 | `/pk-workflow` | `docs/development-workflow.md` |
| 4 | `/pk-foundations` | `docs/project/standards.md`, `testing.md`, `security.md`, `documentation.md` |
| 5 | `/pk-plan` | `docs/project/roadmap.md`, `.project-kit/backlog.json` |
| 6 | `/pk-provision` | milestones, labels, branches, the Project and the issues (skipped with `--provider none`) |
| 7 | `/pk-handoff` | the Spec Kit constitution input; `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` |

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

| Command | What it does |
|---|---|
| `pjkit init` | Install the skills, templates and workflow in the current directory |
| `pjkit status` / `pjkit next` | The phases and what comes next / what to tell your AI |
| `pjkit approve <phase>` | Record your sign-off of a phase |
| `pjkit backlog validate` | Validate `.project-kit/backlog.json` |
| `pjkit provision [--dry-run]` | Create milestones, branches, the Project and issues on GitHub |
| `pjkit handoff [--install-speckit]` | Generate the Spec Kit constitution input |
| `pjkit import <path>` | Copy existing documentation to `docs/sources/` for `/pk-import` |
| `pjkit trace` | Which issues have a spec, a decision and a test, and what is not linked |
| `pjkit upgrade [--apply]` | Update the skills and templates a project already has |
| `pjkit update [--check]` | Update project-kit itself (the status bar says `update available`; `PJKIT_NO_UPDATE_CHECK=1` turns that off) |
| `pjkit uninstall [--apply] [--purge]` | Undo `init`: remove what project-kit installed and you did not edit |
| `pjkit run -- <command>` | Run a command and print a small report instead of all its output (`logs`, `peek` and `stats` go with it) |
| `pjkit mode [quick\|full]` | Show or change how many phases the project goes through |
| `pjkit context` | Write or refresh the project block in `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` |
| `pjkit skills list\|show\|mark` | Recommended third-party skills and what the project decided |
| `pjkit statusline [--install]` | A line for Claude Code's status bar: model, context, limits, project phase |
| `pjkit hook install\|remove` | Tell Claude Code the project's state at the start of each session |
| `pjkit docs [topic]` | The guides |
| `pjkit doctor` / `pjkit help` | Check the tools / a visual guide |

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.
