project-kit-cli 0.1.0__tar.gz

project_kit_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miguel Tomás
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

project_kit_cli-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: project-kit-cli
+Version: 0.1.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
+
+Herramienta para el **antes** de un proyecto: definirlo, planificarlo, decidir su
+arquitectura y montar su flujo de desarrollo y gestión (GitHub primero, GitLab después).
+Al terminar entrega el relevo a [Spec Kit](https://github.com/github/spec-kit), que define e
+implementa cada spec.
+
+> Estado: diseño y esqueleto del paquete (v0.1 en desarrollo). Ver [`docs/design.md`](docs/design.md).
+
+## Instalación y uso
+
+Requisitos: [uv](https://docs.astral.sh/uv/), `git`, y [`gh`](https://cli.github.com/) con
+sesión iniciada y los scopes `repo` y `project` (`gh auth refresh -s project`) para publicar en
+GitHub. [Claude Code](https://claude.com/claude-code) es el agente que guía las fases.
+
+```
+# Instalar (ahora, desde un clon; cuando se publique será `uv tool install project-kit-cli`; el comando es `project-kit`)
+uv tool install --editable <ruta-a-este-clon>
+
+# En el repositorio del proyecto (puede estar vacío)
+project-kit doctor     # comprueba las herramientas
+project-kit init       # instala skills y plantillas; pregunta si la IA firma commits y si abrir Claude
+project-kit help       # guía visual del flujo y los comandos (también: `project-kit` a secas)
+```
+
+`init` copia los ficheros y, al terminar, muestra los agentes de IA soportados (hoy solo Claude
+Code) y ofrece abrirlo en esa misma terminal ya con **`/pk-start`** (Intro acepta). Se puede
+evitar con `--agent none`; sin terminal no pregunta ni lanza nada, y dentro de Claude Code no
+abre otro. Si lo prefieres, ábrelo tú y ejecuta `/pk-start`. Pregunta si quieres **solo
+inicializar** o **empezar a definir el proyecto**, y al terminar cada fase ofrece continuar o
+parar. `project-kit status` muestra en qué fase estás y cuál toca.
+
+| Fase | Skill | Qué hace | Salida |
+|---|---|---|---|
+| 0 | `/pk-start` | Comprueba el entorno y elige: solo inicializar o empezar | `.project-kit/` |
+| 1 | `/pk-discover` | Entrevista sobre qué es el proyecto | `docs/project/brief.md` |
+| 2 | `/pk-decide` | Guía las decisiones de stack y arquitectura | `docs/adr/*.md` |
+| 3 | `/pk-workflow` | Acuerda el flujo de trabajo del equipo | `docs/development-workflow.md` |
+| 4 | `/pk-plan` | Deriva fases, épicas y backlog | `roadmap.md`, `backlog.json` |
+| 5 | `/pk-provision` | Crea milestones, ramas, Project e issues | GitHub |
+| 6 | `/pk-handoff` | Relevo a Spec Kit (una spec por issue) | `constitution-input.md` |
+
+Cada fase termina con una aprobación (`project-kit approve <fase>`) y puede rellenarse a mano
+a partir de las plantillas de `.project-kit/templates/`. Las fases se listan en
+`.project-kit/workflow.yml`, con el mismo estilo que el de Spec Kit; para un proyecto pequeño se
+desactiva una con `enabled: false`.
+
+## Documentación
+
+- [Diseño](docs/design.md): alcance, fases, proveedor, relevo a Spec Kit, decisiones abiertas.
+- [Publicación](docs/publishing.md): qué hace falta para `uv tool install project-kit-cli` público.
+- [Esquema de `backlog.json`](docs/backlog-schema.md): formato del backlog y reglas de validación.
+- [Relevo a Spec Kit](docs/handoff.md): qué genera `handoff`, cómo instala Spec Kit y qué viene después.
+- [Provisionado en GitHub](docs/provisioning.md): qué crea `provision`, idempotencia y protección de ramas.
+- [Referencia: playbook del flujo](docs/references/template-repo-playbook.md): receta de origen
+  (extraída de otro proyecto).
+
+## Licencia y contribuciones
+
+MIT ([`LICENSE`](LICENSE)). Las issues con ideas y mejoras son bienvenidas; el código lo
+desarrolla solo su autor y las pull requests están desactivadas ([`CONTRIBUTING.md`](CONTRIBUTING.md)).
+
+## Ramas
+
+`main` (estable), `release` (pruebas) y `develop` (desarrollo). Todo entra por PR.
+
+## Desarrollo
+
+Requiere [uv](https://docs.astral.sh/uv/).
+
+```
+uv sync                 # entorno y dependencias
+uv run project-kit --version
+uv run pytest           # tests
+uv run ruff check .     # lint
+uv run ruff format .    # formato
+```

project_kit_cli-0.1.0/README.md

@@ -0,0 +1,77 @@
+# project-kit
+
+Herramienta para el **antes** de un proyecto: definirlo, planificarlo, decidir su
+arquitectura y montar su flujo de desarrollo y gestión (GitHub primero, GitLab después).
+Al terminar entrega el relevo a [Spec Kit](https://github.com/github/spec-kit), que define e
+implementa cada spec.
+
+> Estado: diseño y esqueleto del paquete (v0.1 en desarrollo). Ver [`docs/design.md`](docs/design.md).
+
+## Instalación y uso
+
+Requisitos: [uv](https://docs.astral.sh/uv/), `git`, y [`gh`](https://cli.github.com/) con
+sesión iniciada y los scopes `repo` y `project` (`gh auth refresh -s project`) para publicar en
+GitHub. [Claude Code](https://claude.com/claude-code) es el agente que guía las fases.
+
+```
+# Instalar (ahora, desde un clon; cuando se publique será `uv tool install project-kit-cli`; el comando es `project-kit`)
+uv tool install --editable <ruta-a-este-clon>
+
+# En el repositorio del proyecto (puede estar vacío)
+project-kit doctor     # comprueba las herramientas
+project-kit init       # instala skills y plantillas; pregunta si la IA firma commits y si abrir Claude
+project-kit help       # guía visual del flujo y los comandos (también: `project-kit` a secas)
+```
+
+`init` copia los ficheros y, al terminar, muestra los agentes de IA soportados (hoy solo Claude
+Code) y ofrece abrirlo en esa misma terminal ya con **`/pk-start`** (Intro acepta). Se puede
+evitar con `--agent none`; sin terminal no pregunta ni lanza nada, y dentro de Claude Code no
+abre otro. Si lo prefieres, ábrelo tú y ejecuta `/pk-start`. Pregunta si quieres **solo
+inicializar** o **empezar a definir el proyecto**, y al terminar cada fase ofrece continuar o
+parar. `project-kit status` muestra en qué fase estás y cuál toca.
+
+| Fase | Skill | Qué hace | Salida |
+|---|---|---|---|
+| 0 | `/pk-start` | Comprueba el entorno y elige: solo inicializar o empezar | `.project-kit/` |
+| 1 | `/pk-discover` | Entrevista sobre qué es el proyecto | `docs/project/brief.md` |
+| 2 | `/pk-decide` | Guía las decisiones de stack y arquitectura | `docs/adr/*.md` |
+| 3 | `/pk-workflow` | Acuerda el flujo de trabajo del equipo | `docs/development-workflow.md` |
+| 4 | `/pk-plan` | Deriva fases, épicas y backlog | `roadmap.md`, `backlog.json` |
+| 5 | `/pk-provision` | Crea milestones, ramas, Project e issues | GitHub |
+| 6 | `/pk-handoff` | Relevo a Spec Kit (una spec por issue) | `constitution-input.md` |
+
+Cada fase termina con una aprobación (`project-kit approve <fase>`) y puede rellenarse a mano
+a partir de las plantillas de `.project-kit/templates/`. Las fases se listan en
+`.project-kit/workflow.yml`, con el mismo estilo que el de Spec Kit; para un proyecto pequeño se
+desactiva una con `enabled: false`.
+
+## Documentación
+
+- [Diseño](docs/design.md): alcance, fases, proveedor, relevo a Spec Kit, decisiones abiertas.
+- [Publicación](docs/publishing.md): qué hace falta para `uv tool install project-kit-cli` público.
+- [Esquema de `backlog.json`](docs/backlog-schema.md): formato del backlog y reglas de validación.
+- [Relevo a Spec Kit](docs/handoff.md): qué genera `handoff`, cómo instala Spec Kit y qué viene después.
+- [Provisionado en GitHub](docs/provisioning.md): qué crea `provision`, idempotencia y protección de ramas.
+- [Referencia: playbook del flujo](docs/references/template-repo-playbook.md): receta de origen
+  (extraída de otro proyecto).
+
+## Licencia y contribuciones
+
+MIT ([`LICENSE`](LICENSE)). Las issues con ideas y mejoras son bienvenidas; el código lo
+desarrolla solo su autor y las pull requests están desactivadas ([`CONTRIBUTING.md`](CONTRIBUTING.md)).
+
+## Ramas
+
+`main` (estable), `release` (pruebas) y `develop` (desarrollo). Todo entra por PR.
+
+## Desarrollo
+
+Requiere [uv](https://docs.astral.sh/uv/).
+
+```
+uv sync                 # entorno y dependencias
+uv run project-kit --version
+uv run pytest           # tests
+uv run ruff check .     # lint
+uv run ruff format .    # formato
+```

project_kit_cli-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "project-kit-cli"
+version = "0.1.0"
+description = "Project definition and dev-workflow kit that hands off to Spec Kit"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "project-management",
+    "spec-kit",
+    "claude-code",
+    "workflow",
+    "github",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development",
+]
+dependencies = ["pyyaml>=6.0.3"]
+
+[[project.authors]]
+name = "Miguel Tomás"
+
+[project.urls]
+Repository = "https://github.com/miguelmatg/project-kit"
+Issues = "https://github.com/miguelmatg/project-kit/issues"
+
+[project.scripts]
+project-kit = "project_kit.cli:main"
+
+[tool.uv.build-backend]
+module-name = "project_kit"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+]
+
+[build-system]
+requires = ["uv_build>=0.13.1,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff>=0.8",
+]

project_kit_cli-0.1.0/pyproject.toml.orig

@@ -0,0 +1,52 @@
+[project]
+name = "project-kit-cli"
+version = "0.1.0"
+description = "Project definition and dev-workflow kit that hands off to Spec Kit"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Miguel Tomás" }]
+keywords = ["project-management", "spec-kit", "claude-code", "workflow", "github"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development",
+]
+dependencies = [
+    "pyyaml>=6.0.3",
+]
+
+[project.urls]
+Repository = "https://github.com/miguelmatg/project-kit"
+Issues = "https://github.com/miguelmatg/project-kit/issues"
+
+[project.scripts]
+project-kit = "project_kit.cli:main"
+
+[tool.uv.build-backend]
+# The distribution is project-kit-cli (the name free on PyPI); the package keeps its name.
+module-name = "project_kit"
+
+[build-system]
+requires = ["uv_build>=0.13.1,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff>=0.8",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

project_kit_cli-0.1.0/src/project_kit/__init__.py

@@ -0,0 +1,8 @@
+"""project-kit: define, plan and set up a project before handing off to Spec Kit."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("project-kit-cli")
+except PackageNotFoundError:  # running from a source tree that was never installed
+    __version__ = "0.0.0"

project_kit_cli-0.1.0/src/project_kit/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from project_kit.cli import main
+
+sys.exit(main())

project_kit_cli-0.1.0/src/project_kit/agents.py

@@ -0,0 +1,81 @@
+"""AI coding agents project-kit can hand the terminal over to after ``init``.
+
+An agent is whatever reads the installed skills and runs ``/pk-start``. Today that is Claude
+Code only; supporting another one is a new entry in ``AGENTS``.
+"""
+
+import os
+import shutil
+import subprocess
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Agent:
+    id: str
+    name: str
+    executable: str
+    prompt: str  # what the agent is started with: the entry-point skill
+    install_hint: str
+    inside_env: str  # environment variable the agent sets in the shells it opens
+
+
+AGENTS = (
+    Agent(
+        id="claude",
+        name="Claude Code",
+        executable="claude",
+        prompt="/pk-start",
+        install_hint="https://claude.com/claude-code",
+        inside_env="CLAUDECODE",
+    ),
+)
+AGENT_IDS = tuple(a.id for a in AGENTS)
+
+
+def get_agent(agent_id: str) -> Agent:
+    return next(a for a in AGENTS if a.id == agent_id)
+
+
+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."""
+    return bool((os.environ if env is None else env).get(agent.inside_env))
+
+
+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,
+) -> Agent | None:
+    """Ask which agent to open now. Enter takes the first one. ``None``: the user declines."""
+    out("\nOpen an AI agent now to continue with /pk-start?")
+    for n, agent in enumerate(AGENTS, 1):
+        out(f"  {n}) {agent.name}")
+    none = len(AGENTS) + 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 AGENTS[0]
+    if answer.isdigit() and 1 <= int(answer) <= len(AGENTS):
+        return AGENTS[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/src/project_kit/ai_attribution.py

@@ -0,0 +1,69 @@
+"""Keep AI assistants out of the commit history when the project asks for it.
+
+Two layers, because each assistant removes itself in its own way:
+
+* Claude Code has its own setting (``attribution`` in ``.claude/settings.json``), which stops
+  it from adding the co-author trailer and the "Generated with" line.
+* For any other assistant, and as a safety net, a ``commit-msg`` git hook strips co-author
+  trailers that name a known AI tool. It lives in ``.githooks/`` so it is versioned and the
+  whole team gets it; it is switched on with ``git config core.hooksPath .githooks``.
+
+Both only ever add what is missing; nothing the user wrote is overwritten.
+"""
+
+import contextlib
+import json
+import os
+from importlib.resources import files
+from pathlib import Path
+
+from project_kit.fsutil import atomic_write_text
+
+CLAUDE_SETTINGS = Path(".claude") / "settings.json"
+HOOK = Path(".githooks") / "commit-msg"
+HOOKS_PATH_COMMAND = "git config core.hooksPath .githooks"
+
+
+def configure_claude(root: Path) -> tuple[Path | None, str]:
+    """Make Claude Code stop signing commits and PRs. Returns (changed file or None, note)."""
+    path = root / CLAUDE_SETTINGS
+    data: dict = {}
+    if path.exists():
+        try:
+            loaded = json.loads(path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            return None, f"{CLAUDE_SETTINGS.as_posix()} is not valid JSON; left alone."
+        if not isinstance(loaded, dict):
+            return None, f"{CLAUDE_SETTINGS.as_posix()} is not a JSON object; left alone."
+        data = loaded
+
+    attribution = data.get("attribution")
+    attribution = dict(attribution) if isinstance(attribution, dict) else {}
+    if attribution.get("commit") == "" and attribution.get("pr") == "":
+        return None, ""
+    attribution["commit"] = ""
+    attribution["pr"] = ""
+    data["attribution"] = attribution
+    atomic_write_text(path, json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+    return CLAUDE_SETTINGS, ""
+
+
+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
+    if dest.exists():
+        return None, ""
+    script = (files("project_kit") / "assets" / "hooks" / "commit-msg").read_text("utf-8")
+    atomic_write_text(dest, script)
+    with contextlib.suppress(OSError):  # no executable bit on some filesystems (Windows)
+        os.chmod(dest, 0o755)
+    return HOOK, ""
+
+
+def hook_is_active(root: Path) -> bool:
+    """True if git is already pointed at ``.githooks`` in this repository."""
+    config = root / ".git" / "config"
+    if not config.is_file():
+        return False
+    text = config.read_text(encoding="utf-8", errors="replace")
+    return any("".join(line.split()).lower() == "hookspath=.githooks" for line in text.splitlines())

project_kit_cli-0.1.0/src/project_kit/approval.py

@@ -0,0 +1,36 @@
+"""Approval gates: record that the user signed off on a phase."""
+
+from pathlib import Path
+
+from project_kit.backlog import load_backlog
+from project_kit.config import load_config
+from project_kit.state import PHASES, State, StateError, load_state, save_state
+from project_kit.workflow import load_workflow
+
+
+def approve_phase(root: Path, phase: str) -> State:
+    """Record the approval of ``phase`` in the project state.
+
+    A gate refuses to open while an earlier enabled gate of ``workflow.yml`` is still open,
+    so the plan cannot be approved before the brief. The ``plan`` gate also refuses to open
+    unless the backlog on disk is valid, so an approval always refers to a backlog that
+    provisioning can use.
+    """
+    if phase not in PHASES:
+        raise StateError(f"Unknown phase {phase!r}. Phases: {', '.join(PHASES)}")
+    load_config(root)  # the project must have been initialised
+    state = load_state(root)
+    open_gates = load_workflow(root).open_gates_before(phase, state)
+    if open_gates:
+        names = ", ".join(f"{s.id} (/{s.skill})" for s in open_gates)
+        raise StateError(
+            f"Cannot approve {phase!r} yet: approve first {names}. "
+            "To skip a phase, set `enabled: false` on it in .project-kit/workflow.yml."
+        )
+    if phase == "plan":
+        load_backlog(root)
+    state.approve(phase)
+    if PHASES.index(phase) > PHASES.index(state.phase):
+        state.phase = phase
+    save_state(root, state)
+    return state

project_kit_cli-0.1.0/src/project_kit/assets/hooks/commit-msg

@@ -0,0 +1,14 @@
+#!/bin/sh
+# project-kit: keep AI assistants out of the commit history.
+# Removes "Co-authored-by:" trailers added by AI tools, and their "Generated with" lines.
+# Enable with:  git config core.hooksPath .githooks
+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 '^.*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.
+cat "$tmp" > "$file"
+rm -f "$tmp"
+exit 0

project_kit_cli-0.1.0/src/project_kit/assets/project/workflow.yml

@@ -0,0 +1,63 @@
+# project-kit workflow: the phases a project goes through before it is handed to Spec Kit.
+# Safe to edit by hand. Same idea as Spec Kit's workflow.yml: an ordered list of steps with
+# review gates, read by the skills to know what comes next.
+#
+#   gate: true       the phase ends with an explicit approval (`project-kit approve <id>`)
+#   enabled: false   skip the phase (small projects); later gates stop waiting for it
+#
+# The order is fixed and the ids are the ones project-kit knows; only `enabled`, `gate`,
+# `title` and `produces` are meant to be changed.
+schema_version: "1.0"
+workflow:
+  id: "project-kit"
+  name: "Project definition flow"
+  description: "From an idea to a provisioned repository and a Spec Kit handoff"
+
+steps:
+  - id: init
+    title: "Set up project-kit in the repository"
+    skill: pk-start
+    gate: false
+    produces:
+      - .project-kit/config.yml
+
+  - id: discover
+    title: "Define what the project is: problem, users, scope, constraints"
+    skill: pk-discover
+    gate: true
+    produces:
+      - docs/project/brief.md
+
+  - id: decide
+    title: "Decide the stack and the architecture"
+    skill: pk-decide
+    gate: true
+    produces:
+      - docs/adr/
+
+  - id: workflow
+    title: "Agree how the team will work: branches, reviews, quality gates"
+    skill: pk-workflow
+    gate: true
+    produces:
+      - docs/development-workflow.md
+
+  - id: plan
+    title: "Turn it all into phases, epics and a backlog"
+    skill: pk-plan
+    gate: true
+    produces:
+      - docs/project/roadmap.md
+      - .project-kit/backlog.json
+
+  - id: provision
+    title: "Create milestones, labels, branches, the Project and the issues"
+    skill: pk-provision
+    gate: false
+
+  - id: handoff
+    title: "Hand over to Spec Kit: constitution, then one spec per issue"
+    skill: pk-handoff
+    gate: true
+    produces:
+      - .project-kit/handoff/constitution-input.md

project_kit_cli-0.1.0/src/project_kit/assets/skills/pk-decide/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: pk-decide
+description: Guide the user through the technical and architectural decisions of the project (repository structure, language, framework, package manager, data, auth, hosting, CI) and record each one as an ADR in docs/adr/. Use when the user wants to choose the stack or architecture, or to revisit a decision.
+---
+
+# pk-decide — phase 2
+
+Turn the brief into **decisions**: one ADR per decision, with the options considered and the
+reason for the choice. project-kit does not choose for the user; it makes the choice
+explicit, argued and written down. The ADRs feed the plan and, later, the Spec Kit
+constitution.
+
+Read `.project-kit/templates/interview.md` first and follow it. ADRs use
+`.project-kit/templates/adr.md`, are named `docs/adr/NNNN-short-title.md` (next free number)
+and can also be written by hand.
+
+## Inputs
+
+- `docs/project/brief.md`, especially "Constraints" and "Technical preferences already
+  stated". Preferences are proposals to confirm, not decisions.
+- Existing `docs/adr/*.md`: never decide twice. To change a decision, write a new ADR and mark
+  the old one `Superseded by ADR-NNNN`.
+
+## Steps
+
+1. **List the decisions this project needs**, from this checklist and from the brief; leave
+   out whatever does not apply (a command-line tool has no auth or hosting question):
+   - Repository: single repository, monorepo or several repositories; monolith or separate
+     services.
+   - Language and runtime; framework(s).
+   - Package manager and, for monorepos, workspace and build tooling (for example pnpm, npm,
+     yarn, uv, cargo workspaces, turborepo, nx).
+   - Data: storage, migrations, backups.
+   - Authentication and authorisation.
+   - API style and integrations with external services.
+   - Hosting, environments and deployment; CI.
+   - Testing approach and tools; observability.
+   - Anything the brief marks as legal or compliance-driven.
+2. **Show the list** and ask which ones are *critical* now (they block planning) and which
+   can wait. In "light" mode, only decide the critical ones. Deferred decisions are written
+   as `Status: Proposed` or left for a later `pk-decide`.
+3. **For each decision, one at a time:**
+   1. Ask the question in the interview format: options with pros and cons for *this*
+      project, a recommendation with the reason, and what depends on the answer. Use the
+      brief's constraints (team skills, budget, scale, compliance) as the drivers.
+   2. If a decision follows from an earlier one (a framework implies a language), do not ask:
+      state it and record it in the ADR as a consequence.
+   3. After the answer, write the ADR immediately (`Status: Accepted`, today's date) and tell
+      the user its path.
+4. **Check consistency** across ADRs: no contradictory choices (for example a package manager
+   that the chosen framework does not support). Raise any conflict as a question.
+5. **Present** the list of ADRs with their status and anything still undecided.
+6. **Approval gate.** When the critical ADRs are accepted and the user explicitly approves,
+   run `project-kit approve decide`.
+7. Run `project-kit status` and offer `pk-workflow` next: continue now, or stop here.
+
+## Rules
+
+- Do not decide on the user's behalf and do not present your recommendation as settled.
+- Never invent versions, prices or benchmarks; if a fact matters and you are not sure, say so
+  and mark it `[NEEDS CLARIFICATION]`.
+- Keep each ADR to one decision. Write them in the language of `config.yml`.
+- The `Status:` line matters: the handoff reads it to build the constitution.