project-kit-cli 0.1.0__tar.gz → 0.3.0__tar.gz

project_kit_cli-0.3.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: project-kit-cli
+Version: 0.3.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: Topic :: Software Development
+Requires-Dist: pyyaml>=6.0.3
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/miguelmatg/project-kit
+Project-URL: Issues, https://github.com/miguelmatg/project-kit/issues
+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://github.com/miguelmatg/project-kit/blob/main/LICENSE)
+
+**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
+[upgrading](https://github.com/miguelmatg/project-kit/blob/main/docs/upgrade.md).
+
+## 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
+```
+
+## 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` |
+
+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
+
+| 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 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: `--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.
+
+## 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](https://github.com/miguelmatg/project-kit/blob/main/docs/provisioning.md).
+
+## 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](https://github.com/miguelmatg/project-kit/blob/main/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](https://github.com/miguelmatg/project-kit/blob/main/docs/design.md),
+[backlog schema](https://github.com/miguelmatg/project-kit/blob/main/docs/backlog-schema.md),
+[provisioning](https://github.com/miguelmatg/project-kit/blob/main/docs/provisioning.md) and
+[Spec Kit handoff](https://github.com/miguelmatg/project-kit/blob/main/docs/handoff.md).
+
+## Feedback
+
+Ideas and bug reports are welcome as
+[issues](https://github.com/miguelmatg/project-kit/issues). Pull requests are not accepted; see
+[CONTRIBUTING](https://github.com/miguelmatg/project-kit/blob/main/CONTRIBUTING.md).
+
+## License
+
+[MIT](https://github.com/miguelmatg/project-kit/blob/main/LICENSE)

project_kit_cli-0.3.0/README.md

@@ -0,0 +1,209 @@
+# 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://github.com/miguelmatg/project-kit/blob/main/LICENSE)
+
+**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
+[upgrading](https://github.com/miguelmatg/project-kit/blob/main/docs/upgrade.md).
+
+## 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
+```
+
+## 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` |
+
+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
+
+| 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 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: `--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.
+
+## 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](https://github.com/miguelmatg/project-kit/blob/main/docs/provisioning.md).
+
+## 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](https://github.com/miguelmatg/project-kit/blob/main/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](https://github.com/miguelmatg/project-kit/blob/main/docs/design.md),
+[backlog schema](https://github.com/miguelmatg/project-kit/blob/main/docs/backlog-schema.md),
+[provisioning](https://github.com/miguelmatg/project-kit/blob/main/docs/provisioning.md) and
+[Spec Kit handoff](https://github.com/miguelmatg/project-kit/blob/main/docs/handoff.md).
+
+## Feedback
+
+Ideas and bug reports are welcome as
+[issues](https://github.com/miguelmatg/project-kit/issues). Pull requests are not accepted; see
+[CONTRIBUTING](https://github.com/miguelmatg/project-kit/blob/main/CONTRIBUTING.md).
+
+## License
+
+[MIT](https://github.com/miguelmatg/project-kit/blob/main/LICENSE)

{project_kit_cli-0.1.0 → project_kit_cli-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "project-kit-cli"
-version = "0.1.0"
+version = "0.3.0"
 description = "Project definition and dev-workflow kit that hands off to Spec Kit"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -31,7 +31,7 @@ Repository = "https://github.com/miguelmatg/project-kit"
 Issues = "https://github.com/miguelmatg/project-kit/issues"
 
 [project.scripts]
-project-kit = "project_kit.cli:main"
+pjkit = "project_kit.cli:main"
 
 [tool.uv.build-backend]
 module-name = "project_kit"

{project_kit_cli-0.1.0 → project_kit_cli-0.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "project-kit-cli"
-version = "0.1.0"
+version = "0.3.0"
 description = "Project definition and dev-workflow kit that hands off to Spec Kit"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -25,7 +25,7 @@ Repository = "https://github.com/miguelmatg/project-kit"
 Issues = "https://github.com/miguelmatg/project-kit/issues"
 
 [project.scripts]
-project-kit = "project_kit.cli:main"
+pjkit = "project_kit.cli:main"
 
 [tool.uv.build-backend]
 # The distribution is project-kit-cli (the name free on PyPI); the package keeps its name.

project_kit_cli-0.3.0/src/project_kit/agents.py

@@ -0,0 +1,179 @@
+"""AI coding agents project-kit installs for, and can hand the terminal over to after ``init``.
+
+An agent is whatever reads the installed skills. Each one has a directory where it looks for
+skills and a context file it reads at the start of a session; several agents may share both
+(``.agents/skills`` and ``AGENTS.md`` are read by Codex, Cursor, Copilot and Gemini CLI).
+Only an agent with a ``prompt`` can be started by ``init``: the others are opened by the user,
+because how a skill is invoked differs between tools and project-kit does not guess it.
+Supporting another agent is a new entry in ``AGENTS``.
+"""
+
+import os
+import shutil
+import subprocess
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Agent:
+    id: str
+    name: str
+    executable: str
+    install_hint: str
+    skills_dir: str  # where the agent looks for skills, relative to the repository
+    context_file: str  # the file it reads for the project's context, relative to the repository
+    speckit_key: str = ""  # its name in `specify init --integration`
+    prompt: str = ""  # what it is started with (the entry-point skill); empty: not launchable
+    inside_env: str = ""  # environment variable it sets in the shells it opens, if any
+
+
+AGENTS = (
+    Agent(
+        id="claude",
+        name="Claude Code",
+        executable="claude",
+        install_hint="https://claude.com/claude-code",
+        skills_dir=".claude/skills",
+        context_file="CLAUDE.md",
+        speckit_key="claude",
+        prompt="/pk-start",
+        inside_env="CLAUDECODE",
+    ),
+    Agent(
+        id="codex",
+        name="Codex CLI",
+        executable="codex",
+        install_hint="https://developers.openai.com/codex/cli",
+        skills_dir=".agents/skills",
+        context_file="AGENTS.md",
+        speckit_key="codex",
+    ),
+    Agent(
+        id="gemini",
+        name="Gemini CLI",
+        executable="gemini",
+        install_hint="https://github.com/google-gemini/gemini-cli",
+        skills_dir=".agents/skills",  # the documented alias of .gemini/skills
+        context_file="GEMINI.md",
+        speckit_key="gemini",
+    ),
+    Agent(
+        id="copilot",
+        name="GitHub Copilot",
+        executable="copilot",
+        install_hint="https://docs.github.com/copilot",
+        skills_dir=".agents/skills",
+        context_file="AGENTS.md",
+        speckit_key="copilot",
+    ),
+    Agent(
+        id="cursor",
+        name="Cursor",
+        executable="cursor-agent",
+        install_hint="https://cursor.com/cli",
+        skills_dir=".agents/skills",
+        context_file="AGENTS.md",
+        speckit_key="cursor-agent",
+    ),
+)
+AGENT_IDS = tuple(a.id for a in AGENTS)
+DEFAULT_AGENTS = ("claude",)
+
+
+def get_agent(agent_id: str) -> Agent:
+    return next(a for a in AGENTS if a.id == agent_id)
+
+
+def launchable(selected: Sequence[Agent] | None = None) -> list[Agent]:
+    """The agents ``init`` can start, among ``selected`` (default: all)."""
+    return [a for a in (AGENTS if selected is None else selected) if a.prompt]
+
+
+def skills_dirs(agent_ids: Sequence[str]) -> list[str]:
+    """Where the skills go for these agents, without repeats, in order."""
+    return list(dict.fromkeys(get_agent(i).skills_dir for i in agent_ids))
+
+
+def context_files(agent_ids: Sequence[str]) -> list[str]:
+    """The context files of these agents, without repeats, in order."""
+    return list(dict.fromkeys(get_agent(i).context_file for i in agent_ids))
+
+
+def is_inside(agent: Agent, env: Mapping[str, str] | None = None) -> bool:
+    """True when we run from a shell opened by this agent: launching it again would nest."""
+    if not agent.inside_env:
+        return False
+    return bool((os.environ if env is None else env).get(agent.inside_env))
+
+
+def parse_ids(text: str) -> list[str]:
+    """Agent ids from a comma-separated list, validated; ``ValueError`` names the bad ones."""
+    ids = list(dict.fromkeys(p.strip().lower() for p in text.split(",") if p.strip()))
+    bad = [i for i in ids if i not in AGENT_IDS]
+    if bad:
+        raise ValueError(f"unknown agent(s): {', '.join(bad)}; choose from {', '.join(AGENT_IDS)}")
+    return ids
+
+
+def choose_many(
+    ask: Callable[[str], str] | None = None,
+    out: Callable[[str], None] = print,
+) -> list[str]:
+    """Ask which agents the project is used with (several allowed). Enter takes the default."""
+    out("\nWhich AI agents will you use in this project? Skills are installed for each one.")
+    for n, agent in enumerate(AGENTS, 1):
+        out(f"  {n}) {agent.name}")
+    try:
+        answer = (ask or input)("Numbers separated by commas [1]: ").strip()
+    except EOFError:  # no terminal attached: keep the default
+        return list(DEFAULT_AGENTS)
+    if answer == "":
+        return list(DEFAULT_AGENTS)
+    picked = [p.strip() for p in answer.split(",") if p.strip()]
+    if not all(p.isdigit() and 1 <= int(p) <= len(AGENTS) for p in picked):
+        out(f"Not understood; using the default ({', '.join(DEFAULT_AGENTS)}).")
+        return list(DEFAULT_AGENTS)
+    return list(dict.fromkeys(AGENTS[int(p) - 1].id for p in picked))
+
+
+def find_executable(agent: Agent) -> str | None:
+    return shutil.which(agent.executable)
+
+
+def choose(
+    ask: Callable[[str], str] | None = None,
+    out: Callable[[str], None] = print,
+    options: Sequence[Agent] | None = None,
+) -> Agent | None:
+    """Ask which agent to open now. Enter takes the first one. ``None``: the user declines."""
+    pool = launchable(options)
+    if not pool:
+        return None
+    out("\nOpen an AI agent now to continue with /pk-start?")
+    for n, agent in enumerate(pool, 1):
+        out(f"  {n}) {agent.name}")
+    none = len(pool) + 1
+    out(f"  {none}) No, I will do it myself")
+    try:
+        answer = (ask or input)("Choice [1]: ").strip()
+    except EOFError:  # no terminal attached: never launch anything
+        return None
+    if answer == "":
+        return pool[0]
+    if answer.isdigit() and 1 <= int(answer) <= len(pool):
+        return pool[int(answer) - 1]
+    return None
+
+
+def launch(agent: Agent, root: Path, run: Callable[..., object] = subprocess.run) -> int:
+    """Run the agent in the current terminal, in ``root``, started with its entry skill.
+
+    Returns the agent's exit code; the terminal is inherited, so it is interactive.
+    """
+    exe = find_executable(agent)
+    if exe is None:
+        raise FileNotFoundError(agent.executable)
+    result = run([exe, agent.prompt], cwd=root, check=False)
+    return getattr(result, "returncode", 0)

{project_kit_cli-0.1.0 → project_kit_cli-0.3.0}/src/project_kit/ai_attribution.py

@@ -60,6 +60,11 @@ def install_hook(root: Path) -> tuple[Path | None, str]:
     return HOOK, ""
 
 
+def hook_bytes() -> bytes:
+    """The shipped commit-msg hook, as it is installed."""
+    return (files("project_kit") / "assets" / "hooks" / "commit-msg").read_bytes()
+
+
 def hook_is_active(root: Path) -> bool:
     """True if git is already pointed at ``.githooks`` in this repository."""
     config = root / ".git" / "config"