project-kit-cli 0.2.0__tar.gz → 0.4.0__tar.gz

{project_kit_cli-0.2.0 → project_kit_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: project-kit-cli
-Version: 0.2.0
+Version: 0.4.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
@@ -33,13 +33,15 @@ idea ──▶ brief ──▶ decisions (ADRs) ──▶ workflow ──▶ bac
          /pk-discover   /pk-decide       /pk-workflow   /pk-plan   /pk-provision  /pk-handoff
 ```
 
-The conversations run in your AI agent (today, [Claude Code](https://claude.com/claude-code)) as
+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. GitLab and other agents are
-> planned.
+> **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
 
@@ -47,24 +49,26 @@ written by hand instead.
 - `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
+  (`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`
 
-`project-kit doctor` checks all of this for you. Spec Kit is installed for you at the end, if
+`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 `project-kit` command
+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 `project-kit`. To try it without
-installing: `uvx --from project-kit-cli project-kit help`.
+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 `project-kit upgrade` inside it to see what is out of date, and `project-kit upgrade --apply`
+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).
 
@@ -74,7 +78,7 @@ In your repository, new or existing:
 
 ```bash
 cd my-project
-project-kit init
+pjkit init
 ```
 
 `init` copies the skills and templates into the repository and then offers to open Claude Code
@@ -83,8 +87,8 @@ right there, already running `/pk-start` (press Enter to accept). `/pk-start` as
 whether to continue or stop. You can leave at any point and come back later:
 
 ```bash
-project-kit status     # where you are and what comes next
-project-kit help       # a visual guide to the flow and the commands
+pjkit status     # where you are and what comes next
+pjkit help       # a visual guide to the flow and the commands
 ```
 
 ## The phases
@@ -95,11 +99,17 @@ project-kit help       # a visual guide to the flow and the commands
 | 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-plan` | Derives phases, epics and a backlog from all of the above | `docs/project/roadmap.md`, `.project-kit/backlog.json` |
-| 5 | `/pk-provision` | Creates milestones, labels, branches, the GitHub Project and the issues | GitHub |
-| 6 | `/pk-handoff` | Prepares the Spec Kit constitution; each issue becomes a spec | `.project-kit/handoff/constitution-input.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` |
 
-Each phase ends with an explicit approval (`project-kit approve <phase>`), and a phase cannot be
+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`.
 
@@ -119,18 +129,70 @@ It never rewrites issues that already exist, and re-running it is always safe.
 
 | Command | What it does |
 |---|---|
-| `project-kit init` | Install the skills, templates and workflow in the current directory |
-| `project-kit status` | Show the phases and what comes next |
-| `project-kit upgrade [--apply] [--adopt] [--diff]` | Update the skills and templates a project already has |
-| `project-kit help` | Show a visual guide (also what plain `project-kit` prints) |
-| `project-kit doctor` | Check that git, gh, uv and Spec Kit are available |
-| `project-kit approve <phase>` | Record your sign-off of a phase |
-| `project-kit backlog validate` | Validate `.project-kit/backlog.json` |
-| `project-kit provision [--dry-run] [--project X]` | Create milestones, branches, the Project and issues on GitHub |
-| `project-kit handoff [--install-speckit]` | Generate the Spec Kit constitution input |
+| `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 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: `--project-name`, `--language` (language of the generated documents),
-`--agent claude|none` (open the agent or not) and `--ai-coauthor keep|remove`.
+`--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](https://github.com/miguelmatg/project-kit/blob/main/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](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
 
@@ -153,7 +215,7 @@ From there Spec Kit does the work. Each issue of the backlog is one spec: its te
 
 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, `project-kit approve handoff` deletes
+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_cli-0.2.0 → project_kit_cli-0.4.0}/README.md

@@ -13,13 +13,15 @@ idea ──▶ brief ──▶ decisions (ADRs) ──▶ workflow ──▶ bac
          /pk-discover   /pk-decide       /pk-workflow   /pk-plan   /pk-provision  /pk-handoff
 ```
 
-The conversations run in your AI agent (today, [Claude Code](https://claude.com/claude-code)) as
+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. GitLab and other agents are
-> planned.
+> **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
 
@@ -27,24 +29,26 @@ written by hand instead.
 - `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
+  (`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`
 
-`project-kit doctor` checks all of this for you. Spec Kit is installed for you at the end, if
+`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 `project-kit` command
+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 `project-kit`. To try it without
-installing: `uvx --from project-kit-cli project-kit help`.
+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 `project-kit upgrade` inside it to see what is out of date, and `project-kit upgrade --apply`
+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).
 
@@ -54,7 +58,7 @@ In your repository, new or existing:
 
 ```bash
 cd my-project
-project-kit init
+pjkit init
 ```
 
 `init` copies the skills and templates into the repository and then offers to open Claude Code
@@ -63,8 +67,8 @@ right there, already running `/pk-start` (press Enter to accept). `/pk-start` as
 whether to continue or stop. You can leave at any point and come back later:
 
 ```bash
-project-kit status     # where you are and what comes next
-project-kit help       # a visual guide to the flow and the commands
+pjkit status     # where you are and what comes next
+pjkit help       # a visual guide to the flow and the commands
 ```
 
 ## The phases
@@ -75,11 +79,17 @@ project-kit help       # a visual guide to the flow and the commands
 | 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-plan` | Derives phases, epics and a backlog from all of the above | `docs/project/roadmap.md`, `.project-kit/backlog.json` |
-| 5 | `/pk-provision` | Creates milestones, labels, branches, the GitHub Project and the issues | GitHub |
-| 6 | `/pk-handoff` | Prepares the Spec Kit constitution; each issue becomes a spec | `.project-kit/handoff/constitution-input.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` |
 
-Each phase ends with an explicit approval (`project-kit approve <phase>`), and a phase cannot be
+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`.
 
@@ -99,18 +109,70 @@ It never rewrites issues that already exist, and re-running it is always safe.
 
 | Command | What it does |
 |---|---|
-| `project-kit init` | Install the skills, templates and workflow in the current directory |
-| `project-kit status` | Show the phases and what comes next |
-| `project-kit upgrade [--apply] [--adopt] [--diff]` | Update the skills and templates a project already has |
-| `project-kit help` | Show a visual guide (also what plain `project-kit` prints) |
-| `project-kit doctor` | Check that git, gh, uv and Spec Kit are available |
-| `project-kit approve <phase>` | Record your sign-off of a phase |
-| `project-kit backlog validate` | Validate `.project-kit/backlog.json` |
-| `project-kit provision [--dry-run] [--project X]` | Create milestones, branches, the Project and issues on GitHub |
-| `project-kit handoff [--install-speckit]` | Generate the Spec Kit constitution input |
+| `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 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: `--project-name`, `--language` (language of the generated documents),
-`--agent claude|none` (open the agent or not) and `--ai-coauthor keep|remove`.
+`--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](https://github.com/miguelmatg/project-kit/blob/main/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](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
 
@@ -133,7 +195,7 @@ From there Spec Kit does the work. Each issue of the backlog is one spec: its te
 
 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, `project-kit approve handoff` deletes
+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_cli-0.2.0 → project_kit_cli-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "project-kit-cli"
-version = "0.2.0"
+version = "0.4.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.entry:main"
 
 [tool.uv.build-backend]
 module-name = "project_kit"

{project_kit_cli-0.2.0 → project_kit_cli-0.4.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "project-kit-cli"
-version = "0.2.0"
+version = "0.4.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.entry: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.4.0/src/project_kit/__init__.py

@@ -0,0 +1,14 @@
+"""project-kit: define, plan and set up a project before handing off to Spec Kit."""
+
+
+def __getattr__(name: str) -> str:
+    """``__version__`` is looked up on first use: reading package metadata costs more than the
+    whole status line command, which runs at every update of the agent's status bar."""
+    if name == "__version__":
+        from importlib.metadata import PackageNotFoundError, version
+
+        try:
+            return version("project-kit-cli")
+        except PackageNotFoundError:  # running from a source tree that was never installed
+            return "0.0.0"
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

project_kit_cli-0.4.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.2.0 → project_kit_cli-0.4.0}/src/project_kit/assets/hooks/commit-msg

@@ -5,7 +5,8 @@
 file="$1"
 tmp="$file.pk-tmp"
 grep -v -i -E \
-  -e '^co-authored-by:.*(claude|anthropic|copilot|openai|chatgpt|codex|gemini|cursor|aider|devin)' \
+  -e '^co-authored-by:.*<[^>]*(@anthropic\.com|@openai\.com|@cursor\.com|@aider\.chat|\[bot\]@users\.noreply\.github\.com|copilot@users\.noreply\.github\.com|copilot@github\.com)>' \
+  -e '^co-authored-by: *((github )?copilot|chatgpt|codex|cursor( agent)?|claude( code| (opus|sonnet|haiku)[0-9. ]*)?|aider( \([^)]*\))?) *<' \
   -e '^.*generated with.*(claude|copilot|codex|gemini|cursor)' \
   "$file" > "$tmp"
 # grep exits 1 when nothing is left (an empty message): keep that case valid and silent.