project-kit-cli 0.5.2__tar.gz → 0.6.0__tar.gz

project_kit_cli-0.6.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: project-kit-cli
+Version: 0.6.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.

project_kit_cli-0.6.0/README.md

@@ -0,0 +1,137 @@
+# 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.

{project_kit_cli-0.5.2 → project_kit_cli-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "project-kit-cli"
-version = "0.5.2"
+version = "0.6.0"
 description = "Project definition and dev-workflow kit that hands off to Spec Kit"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -19,6 +19,7 @@ classifiers = [
     "Intended Audience :: Developers",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development",
 ]
 dependencies = ["pyyaml>=6.0.3"]

{project_kit_cli-0.5.2 → project_kit_cli-0.6.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "project-kit-cli"
-version = "0.5.2"
+version = "0.6.0"
 description = "Project definition and dev-workflow kit that hands off to Spec Kit"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -14,6 +14,7 @@ classifiers = [
     "Intended Audience :: Developers",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development",
 ]
 dependencies = [

{project_kit_cli-0.5.2 → project_kit_cli-0.6.0}/src/project_kit/agents.py

@@ -15,6 +15,10 @@ from collections.abc import Callable, Mapping, Sequence
 from dataclasses import dataclass
 from pathlib import Path
 
+# How far an agent has been tried with the whole flow (see `pjkit docs agents`).
+TESTED = "tested"  # the flow has been run with it from start to end
+UNTESTED = "untested"  # skills and context are installed where it reads them; never tried
+
 
 @dataclass(frozen=True)
 class Agent:
@@ -27,6 +31,7 @@ class Agent:
     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
+    support: str = UNTESTED
 
 
 AGENTS = (
@@ -40,6 +45,7 @@ AGENTS = (
         speckit_key="claude",
         prompt="/pk-start",
         inside_env="CLAUDECODE",
+        support=TESTED,
     ),
     Agent(
         id="codex",
@@ -86,6 +92,23 @@ def get_agent(agent_id: str) -> Agent:
     return next(a for a in AGENTS if a.id == agent_id)
 
 
+def untested(agent_ids: Sequence[str]) -> list[Agent]:
+    """Those of these agents the flow has not been tried with."""
+    return [a for a in map(get_agent, agent_ids) if a.support != TESTED]
+
+
+def untested_note(agent_ids: Sequence[str]) -> str:
+    """What to tell the user who chose agents the flow has not been tried with, or empty."""
+    names = ", ".join(a.name for a in untested(agent_ids))
+    if not names:
+        return ""
+    return (
+        f"Untested with {names}: project-kit installs their skills and context files where "
+        "they read them, but the flow has not been tried with them. Claude Code is the tested "
+        "one. What is known about each agent: `pjkit docs agents`."
+    )
+
+
 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]

{project_kit_cli-0.5.2 → project_kit_cli-0.6.0}/src/project_kit/ai_attribution.py

@@ -48,6 +48,30 @@ def configure_claude(root: Path) -> tuple[Path | None, str]:
     return CLAUDE_SETTINGS, ""
 
 
+def remove_claude(root: Path, *, dry_run: bool = False) -> bool:
+    """Undo ``configure_claude``: drop the empty commit/pr attribution. True if it changed."""
+    path = root / CLAUDE_SETTINGS
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+    attribution = data.get("attribution") if isinstance(data, dict) else None
+    if not (
+        isinstance(attribution, dict)
+        and attribution.get("commit") == ""
+        and attribution.get("pr") == ""
+    ):
+        return False
+    rest = {k: v for k, v in attribution.items() if k not in ("commit", "pr")}
+    if rest:
+        data["attribution"] = rest
+    else:
+        del data["attribution"]
+    if not dry_run:
+        atomic_write_text(path, json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+    return True
+
+
 def install_hook(root: Path) -> tuple[Path | None, str]:
     """Copy the commit-msg hook unless the project already has one. Returns (new file, note)."""
     dest = root / HOOK