project-kit-cli 0.5.0__tar.gz → 0.5.1__tar.gz

project_kit_cli-0.5.0/README.md → project_kit_cli-0.5.1/PKG-INFO

@@ -1,7 +1,25 @@
+Metadata-Version: 2.4
+Name: project-kit-cli
+Version: 0.5.1
+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
+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)
+[![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
@@ -49,8 +67,7 @@ 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).
+to bring it up to date. Files you edited are never overwritten; see `pjkit docs upgrade`.
 
 ## Quick start
 
@@ -207,14 +224,13 @@ plans) and where the project is in the flow:
 `.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).
+estimate at list price. More in `pjkit docs statusline`.
 
 ## 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).
+status labels. Details in `pjkit docs provisioning`.
 
 ## Generating a project without GitHub
 
@@ -228,8 +244,7 @@ project-kit keeps a catalog of third-party skills (UI/UX, motion, accessibility,
 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).
+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: `pjkit docs skills`.
 
 ## AI co-author
 
@@ -267,18 +282,10 @@ docs/adr/              one file per decision       (created by the phases)
 
 ## 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).
+The detailed guides ship with the program (in Spanish). `pjkit docs` lists them and
+`pjkit docs <topic>` prints one: `upgrade`, `provisioning`, `handoff`, `backlog-schema`, `skills`,
+`statusline` and `agents`.
 
 ## License
 
-[MIT](https://github.com/miguelmatg/project-kit/blob/main/LICENSE)
+MIT.

project_kit_cli-0.5.0/PKG-INFO → project_kit_cli-0.5.1/README.md

@@ -1,27 +1,7 @@
-Metadata-Version: 2.4
-Name: project-kit-cli
-Version: 0.5.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)
+[![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
@@ -69,8 +49,7 @@ 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).
+to bring it up to date. Files you edited are never overwritten; see `pjkit docs upgrade`.
 
 ## Quick start
 
@@ -227,14 +206,13 @@ plans) and where the project is in the flow:
 `.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).
+estimate at list price. More in `pjkit docs statusline`.
 
 ## 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).
+status labels. Details in `pjkit docs provisioning`.
 
 ## Generating a project without GitHub
 
@@ -248,8 +226,7 @@ project-kit keeps a catalog of third-party skills (UI/UX, motion, accessibility,
 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).
+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: `pjkit docs skills`.
 
 ## AI co-author
 
@@ -287,18 +264,10 @@ docs/adr/              one file per decision       (created by the phases)
 
 ## 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).
+The detailed guides ship with the program (in Spanish). `pjkit docs` lists them and
+`pjkit docs <topic>` prints one: `upgrade`, `provisioning`, `handoff`, `backlog-schema`, `skills`,
+`statusline` and `agents`.
 
 ## License
 
-[MIT](https://github.com/miguelmatg/project-kit/blob/main/LICENSE)
+MIT.

{project_kit_cli-0.5.0 → project_kit_cli-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "project-kit-cli"
-version = "0.5.0"
+version = "0.5.1"
 description = "Project definition and dev-workflow kit that hands off to Spec Kit"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -26,10 +26,6 @@ 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]
 pjkit = "project_kit.entry:main"
 

{project_kit_cli-0.5.0 → project_kit_cli-0.5.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "project-kit-cli"
-version = "0.5.0"
+version = "0.5.1"
 description = "Project definition and dev-workflow kit that hands off to Spec Kit"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -20,10 +20,6 @@ dependencies = [
     "pyyaml>=6.0.3",
 ]
 
-[project.urls]
-Repository = "https://github.com/miguelmatg/project-kit"
-Issues = "https://github.com/miguelmatg/project-kit/issues"
-
 [project.scripts]
 pjkit = "project_kit.entry:main"
 

project_kit_cli-0.5.1/src/project_kit/assets/docs/agents.md

@@ -0,0 +1,20 @@
+# Agentes de IA
+
+`pjkit init --agents claude,codex,...` instala las skills donde cada agente las lee y, al
+terminar el handoff, escribe su fichero de contexto. Esta tabla recoge lo que **dice la
+documentación oficial** (comprobada el 2026-10-18) y lo que no pudo confirmarse.
+
+| Agente | Skills del proyecto | Contexto | Lo que se confirmó |
+|---|---|---|---|
+| Claude Code | `.claude/skills` | `CLAUDE.md` | Rutas conocidas del propio producto |
+| Codex CLI | `.agents/skills` | `AGENTS.md` | Skills: documentación de Codex. `AGENTS.md`: su documentación lo enlaza, pero la página consultada no explica la relación |
+| Gemini CLI | `.agents/skills` (alias de `.gemini/skills`) | `GEMINI.md` | Skills y `GEMINI.md`: documentación oficial. `.agents/skills` gana a `.gemini/skills` si hay conflicto |
+| GitHub Copilot | `.agents/skills` (también lee `.github/skills` y `.claude/skills`) | `AGENTS.md` | Skills: documentación oficial. `AGENTS.md`: anuncio oficial para el agente de código; **no se pudo confirmar para Copilot CLI** |
+| Cursor | `.agents/skills` (también `.cursor/skills`) | `AGENTS.md` | Skills: documentación oficial. **`AGENTS.md` no pudo confirmarse en la documentación de Cursor**; hay fuentes de terceros que sí lo afirman |
+
+Como Codex, Gemini, Copilot y Cursor comparten `.agents/skills`, las skills se instalan una vez.
+Solo Claude Code se arranca desde `init`: cada herramienta invoca las skills de forma distinta y
+project-kit no lo adivina.
+
+Si una herramienta no lee `AGENTS.md`, el bloque que escribe `pjkit context` no le llega; en ese
+caso añade a mano una línea que lo referencie en el fichero que sí lee.

project_kit_cli-0.5.1/src/project_kit/assets/docs/backlog-schema.md

@@ -0,0 +1,81 @@
+# Esquema de `backlog.json`
+
+Fuente de verdad del backlog del proyecto. Lo genera la skill `pk-plan`, lo valida
+`pjkit backlog validate` y lo consume `provision` para crear milestones, labels,
+issues y los campos del Project. Vive en `.project-kit/backlog.json` del proyecto destino.
+
+Un ejemplo completo y válido se instala en `.project-kit/templates/backlog.example.json`
+(fuente: `src/project_kit/assets/templates/backlog.example.json`).
+
+## Estructura
+
+```json
+{
+  "version": 1,
+  "phases": [ ... ],
+  "labels": [ ... ],
+  "issues": [ ... ]
+}
+```
+
+Los campos desconocidos son un error (protege de erratas). La versión actual del formato es `1`.
+
+### `phases` — fases
+
+Cada fase es un milestone en el proveedor y una opción del campo `Phase` del Project. El orden
+de la lista es el orden de entrega.
+
+| Campo | Obligatorio | Descripción |
+|---|---|---|
+| `id` | sí | Identificador estable: minúsculas, dígitos y guiones (`mvp`, `v1-launch`) |
+| `title` | sí | Nombre visible (`v0.1 MVP`). No puede repetirse |
+| `description` | no | Texto del milestone |
+
+### `labels` — labels propios (opcional)
+
+Solo los labels **extra**. Los de tipo (`type:feature`…) y prioridad (`P0`…`P3`) los deriva
+`provision` de cada issue y no hay que declararlos.
+
+| Campo | Obligatorio | Descripción |
+|---|---|---|
+| `name` | sí | Nombre del label. No puede repetirse |
+| `color` | no | 6 dígitos hexadecimales sin `#` (por defecto `ededed`) |
+| `description` | no | Descripción |
+
+### `issues` — épicas y tarjetas
+
+| Campo | Obligatorio | Valores / descripción |
+|---|---|---|
+| `id` | sí | Identificador estable y único. Es la clave en `state.json` (`provider_ids.issues`), así que **no debe cambiar** una vez aprovisionado |
+| `type` | sí | `epic`, `feature`, `adr`, `chore`, `bug`, `docs` (campo `Kind` del Project) |
+| `phase` | sí | `id` de una fase existente |
+| `title` | sí | Título de la issue |
+| `priority` | sí | `P0` (crítica) a `P3` (baja) |
+| `size` | sí | `XS`, `S`, `M`, `L`, `XL` |
+| `parent` | no | `id` de una épica. Una épica no puede tener padre |
+| `body` | no | Contexto en Markdown |
+| `acceptance` | según tipo | Lista de criterios de aceptación (texto, sin `- [ ]`). **Obligatoria** (al menos uno) en `feature`, `bug` y `chore` |
+| `labels` | no | Nombres de labels declarados en `labels` |
+
+Las épicas enlazan a sus hijas por `parent`; `provision` genera la checklist de la épica a
+partir de ellas.
+
+## Reglas de validación
+
+Se comprueban todas a la vez y se informa de cada problema:
+
+- JSON válido, `version` soportada, sin campos desconocidos y con los tipos correctos.
+- Ids con formato válido y sin duplicados (fases, labels e issues).
+- `type`, `priority` y `size` dentro de los valores permitidos.
+- Toda `phase` referenciada existe.
+- Todo `parent` existe y es una épica; una épica no puede tener padre.
+- Todo label usado en una issue está declarado en `labels`.
+- Las `feature`, `bug` y `chore` tienen criterios de aceptación.
+
+## Flujo de aprobación
+
+1. `pk-plan` escribe `.project-kit/backlog.json`.
+2. `pjkit backlog validate` debe pasar.
+3. La persona usuaria aprueba el plan de forma explícita.
+4. `pjkit approve plan` registra la aprobación en `state.json` (con fecha) y avanza la
+   fase. Se niega a hacerlo si el backlog no existe o no es válido.

project_kit_cli-0.5.1/src/project_kit/assets/docs/handoff.md

@@ -0,0 +1,128 @@
+# Relevo a Spec Kit
+
+`pjkit handoff` cierra el trabajo de project-kit y deja el proyecto listo para que
+[Spec Kit](https://github.com/github/spec-kit) defina e implemente cada spec.
+
+```
+pjkit handoff [--install-speckit] [--dry-run] [--yes]
+```
+
+El único contrato con Spec Kit es **un fichero de texto** y sus comandos públicos. project-kit
+**no escribe nunca dentro de `.specify/`**: Spec Kit es el dueño de
+`.specify/memory/constitution.md`.
+
+## Qué hace
+
+1. **Detecta Spec Kit**: el ejecutable `specify` (y su versión) y el directorio `.specify/`
+   (y la versión con la que se inicializó).
+2. **Genera `.project-kit/handoff/constitution-input.md`**: el texto que se pasa a
+   `/speckit-constitution`, en el orden que usa su plantilla (principios, restricciones, flujo
+   de trabajo y puertas de calidad, gobierno). Es determinista: con las mismas entradas sale
+   siempre lo mismo.
+3. **Instala Spec Kit si falta** (solo con `--install-speckit` y tras confirmar).
+4. **Indica los pasos siguientes**, sin ejecutarlos: el comando de la constitución y la
+   relación entre las issues del backlog y las specs.
+
+## De dónde salen los datos
+
+| En la constitución | Origen |
+|---|---|
+| Nombre, idioma y nombres de las ramas | `.project-kit/config.yml` |
+| Patrón de rama de una spec y estrategia de fusión por rama | `workflow:` de `.project-kit/config.yml` (lo escribe `/pk-workflow`) |
+| Principios y Definition of Done | Plantilla genérica (ver abajo) |
+| Decisiones registradas | `docs/adr/*.md`: título y, si lo tienen, el estado (`Status: Accepted`) |
+| Documentos y fases | `docs/project/brief.md`, `docs/project/roadmap.md` y las fases del backlog, si existen |
+| Dónde viven las reglas (índice) | Lo que existe en el proyecto: ver "Índice de reglas" |
+| Reglas propias del proyecto | `.project-kit/handoff/constitution-extra.md`, si existe |
+| Stack | "Definido por las decisiones" si hay ADRs; si no, "pendiente de un ADR" |
+
+El patrón de rama y la estrategia de fusión salen de datos, no de la prosa de
+`docs/development-workflow.md`, así que `/pk-workflow` los guarda en `config.yml` además de en
+el documento:
+
+```yaml
+workflow:
+  spec_branch: "spec/<name>"   # por defecto NNN-name
+  merge:                       # squash | merge | rebase
+    develop: squash
+    release: merge
+    main: merge
+```
+
+### Índice de reglas
+
+La constitución incluye una sección **"Where the project's rules live"** que dice dónde mirar
+para cada cosa en lugar de repetirlo en cada spec. Solo aparecen las fuentes que el proyecto
+tiene:
+
+- **Tareas y seguimiento**: el GitHub Project (título y URL, guardados al hacer `provision`) y
+  las issues son la fuente de verdad; una issue es una spec y su PR la cierra (`Closes #N`); no
+  hay una lista de tareas paralela; la tarjeta pasa a In progress, In review y Done.
+- **Backlog** (`.project-kit/backlog.json`), **alcance** (`brief.md`), **hoja de ruta**
+  (`roadmap.md`), **decisiones** (`docs/adr/`), **proceso** (`docs/development-workflow.md`) y
+  las **plantillas** de PR e issues.
+
+### Ficheros temporales
+
+`constitution-input.md` y `constitution-extra.md` solo existen para alimentar
+`/speckit-constitution`. Cuando la constitución real está escrita, la fuente única es ella, y
+**`pjkit approve handoff` los borra**. Para poder aprobar, `.specify/memory/constitution.md`
+tiene que existir y no ser ya la plantilla de Spec Kit (la plantilla vacía está llena de
+marcadores `[EN_MAYÚSCULAS]`; una constitución escrita no tiene ninguno). Si se vuelve a ejecutar
+`handoff` después, avisa de que ya está hecho y no recrea el fichero. Para cambiar las reglas
+desde entonces se enmienda la constitución con `/speckit-constitution`.
+
+### Fichero regenerable y reglas propias
+
+`constitution-input.md` lleva la cabecera `<!-- project-kit:managed -->`: se **regenera** cada
+vez que cambian las entradas, hasta que se aprueba el relevo. Para añadir reglas del proyecto
+(seguridad, cumplimiento normativo, convenciones del equipo) no se edita ese fichero: se
+escriben en **`constitution-extra.md`**, que project-kit nunca toca y se añade al final como
+"Project-specific rules". Solo contenido de gobierno: Spec Kit rechaza peticiones de construir
+funcionalidades. Ya no hace falta usarlo para corregir el flujo de ramas: eso sale de
+`config.yml`.
+
+Si alguien borra la cabecera de `constitution-input.md`, el fichero pasa a ser suyo y deja de
+regenerarse (se avisa; para volver a generarlo basta borrarlo).
+
+### Plantilla sobrescribible
+
+El texto base se instala con `init` en `.project-kit/templates/constitution-input.md` y puede
+editarse. Usa variables `{{...}}` (`project_name`, `language`, `provider`, `branches.main`,
+`branches.release`, `branches.develop`, `spec_branch`, `merge_summary`, `stack`, `references`,
+`decisions`, `rules_index`, `extra`). Una variable desconocida (una errata) es un error, no se
+cuela en el resultado.
+
+## Instalar Spec Kit
+
+Con `--install-speckit`, project-kit muestra lo que va a ejecutar y pregunta antes (`--yes`
+omite la pregunta):
+
+| Situación | Comando |
+|---|---|
+| No hay CLI de Spec Kit | `uv tool install specify-cli` |
+| No está inicializado en el repositorio | `specify init --here --integration claude --force --non-interactive` |
+
+- Necesita `uv`. Si falta, lo dice y propone instalar el paquete `specify-cli` por otro medio.
+- `specify init` **fusiona** sus ficheros con los existentes. Se ha comprobado que respeta los
+  del proyecto y los de project-kit; lo único que toca es `.claude/settings.json`, que
+  reformatea conservando su contenido.
+- Si tras instalar el CLI no está en el PATH, indica `uv tool update-shell`.
+- Un fallo en cualquier paso detiene el proceso.
+
+## Versiones
+
+project-kit se ha probado con Spec Kit **1.2.x**. Ante otra versión **avisa y continúa**:
+como solo depende del fichero de entrada, debería seguir funcionando.
+
+## Después del relevo
+
+1. En Claude Code: `/speckit-constitution @.project-kit/handoff/constitution-input.md`
+2. Opcional: mencionar `docs/project/` y `docs/adr/` en `CLAUDE.md` o `AGENTS.md`, para que
+   `/speckit-specify` y `/speckit-plan` los lean.
+3. Cada issue del backlog es candidata a una spec; su texto sirve de entrada a
+   `/speckit-specify`.
+4. Cuando la constitución esté creada: `pjkit approve handoff` (borra los ficheros
+   temporales del relevo).
+
+Las skills `pk-handoff` y `pk-provision` guían estos pasos desde Claude Code.

project_kit_cli-0.5.1/src/project_kit/assets/docs/provisioning.md

@@ -0,0 +1,136 @@
+# Provisionado en GitHub
+
+`pjkit provision` crea en el repositorio lo que el backlog necesita: milestones, labels,
+ramas permanentes, el Project con sus campos y las issues.
+
+```
+pjkit provision [--repo owner/nombre] [--project número|título] [--dry-run] [--yes]
+```
+
+## Cómo funciona
+
+1. **Planifica** leyendo GitHub (solo lectura): qué existe ya.
+2. **Muestra el plan**: lo que se va a crear y lo que ya está.
+3. **Pide confirmación** (`[y/N]`). Sin terminal o con cualquier respuesta distinta de `y`,
+   no hace nada. `--yes` omite la pregunta.
+4. **Aplica**, en este orden: milestones, labels, ramas, Project y campos, issues, enlaces de
+   las épicas y tarjetas del Project.
+
+`--dry-run` hace solo los pasos 1 y 2 y no modifica nada, ni en GitHub ni en `state.json`.
+Para aplicar hay que haber aprobado el plan (`pjkit approve plan`).
+
+## Qué se crea
+
+| Elemento | Origen | Detalle |
+|---|---|---|
+| Milestones | Una por fase del backlog | El id se guarda en `state.json` (`provider_ids.milestones`) |
+| Labels | Derivados de las issues y declarados en `labels` | `type:epic`, `type:feature`, `type:adr`, `type:chore`, `type:docs`, `bug`, `P0`–`P3`; solo los que el backlog usa, más los declarados |
+| Ramas | `config.yml` → `branches` | `release` y `develop` si faltan, creadas desde `main` |
+| Project | El que ya tengas (ver abajo) o uno nuevo, `<project_name> Roadmap` por defecto | Vinculado al repositorio |
+| Campos | Del backlog | `Phase` (una opción por fase), `Kind` (Epic, Feature, ADR, Chore, Bug, Docs), `Priority` (P0–P3), `Size` (XS–XL) y `Status` (Backlog, Ready, In progress, In review, Done) |
+| Issues | Una por entrada del backlog | Milestone de su fase, labels de tipo y prioridad más los suyos, y un cuerpo con contexto, criterios de aceptación y una marca oculta (`<!-- project-kit:id=… -->`) |
+| Épicas | Las issues con `parent` | La épica lleva una checklist de sus hijas; cada hija dice `Part of #N` |
+| Tarjetas | Cada issue en el Project | Con `Status`, `Phase`, `Kind`, `Priority` y `Size` |
+
+Las épicas se crean antes que sus hijas, para poder enlazarlas.
+
+## Idempotencia y reanudación
+
+- Solo se crea lo que **falta**. Lo que ya existe no se toca, aunque su color, descripción o
+  contenido sean distintos: nunca se pisan ediciones manuales.
+- Ejecutarlo dos veces seguidas no cambia nada y la segunda no pregunta. Si el estado local se
+  perdió pero todo existe en GitHub, esa ejecución lo reconstruye sin escribir en GitHub.
+- Cada issue se reconoce por su marca oculta, además de por `state.json`: perder el estado no
+  duplica issues.
+- Si algo falla a mitad (GitHub da 502 o limita las peticiones), el progreso queda guardado y
+  basta con repetir el comando. Cada ejecución vuelve a leer GitHub, no confía en un plan
+  anterior.
+
+## Qué no se pisa nunca
+
+- **Issues existentes:** no se reescriben el título ni el cuerpo. La única excepción es el
+  bloque de hijas de una épica (entre `project-kit:children:start` y `end`), que es de
+  project-kit: se actualiza al añadir hijas y **conserva las casillas que ya marcaste**.
+- **Campos del Project:** solo se rellenan los **vacíos**. Una tarjeta que moviste de columna
+  o a la que cambiaste la prioridad se queda como la dejaste. `Status` se pone a `Backlog` una
+  sola vez, al añadir la tarjeta.
+- **Opciones de campo:** al añadir una fase nueva se añade su opción a `Phase` conservando las
+  existentes (y los valores ya asignados).
+- **`Status` personalizado:** solo se sustituye si es el que trae GitHub por defecto
+  (`Todo`, `In Progress`, `Done`) **y** el Project no tiene tarjetas todavía, porque
+  sustituirlo reinicia el estado de las tarjetas existentes. En cualquier otro caso se deja
+  tal cual y se avisa de las opciones que faltan.
+
+## Condiciones que bloquean
+
+Se informan con `BLOCKING` y no se aplica nada:
+
+- `branches.main` de `config.yml` no es la rama por defecto del repositorio.
+- El repositorio no tiene commits: las ramas nuevas se crean a partir de `main`, así que hace
+  falta un commit inicial.
+
+## Límite de peticiones de GitHub
+
+Con backlogs grandes GitHub puede limitar las peticiones. project-kit lo detecta, lo explica
+("espera un minuto y repite") y **no reintenta a ciegas**; como el progreso está guardado,
+repetir el comando continúa donde se quedó.
+
+## Protección de ramas
+
+Los repositorios **privados con plan gratuito no permiten** proteger ramas ni crear rulesets.
+project-kit lo detecta consultando el endpoint de rulesets (GitHub responde un 403 con
+"Upgrade to GitHub Pro or make this repository public") y, en ese caso:
+
+- **no intenta** proteger ninguna rama,
+- lo indica en cada ejecución,
+- y la política de ramas debe cumplirse **por disciplina**: todo entra por PR hacia `develop`,
+  y `release` y `main` solo por promoción.
+
+Cuando el repositorio sea público o el plan lo permita, project-kit lo reconoce y lo indica,
+pero **todavía no configura la protección**: hay que activarla a mano.
+
+## Qué Project se usa
+
+Antes de crear nada, `provision` busca los Projects **ya vinculados al repositorio** (y uno con
+el título por defecto, aunque no esté vinculado), de modo que funciona igual en un repositorio
+nuevo que en uno que ya tiene su tablero:
+
+| Encuentra | Con terminal | Sin terminal o con `--yes` |
+|---|---|---|
+| Ninguno | Pregunta el nombre (Intro: `<project_name> Roadmap`) y lo crea | Lo crea con el nombre por defecto |
+| Uno | Pregunta si usarlo (Intro: sí); si no, pide el nombre de uno nuevo | Lo usa |
+| Varios | Los lista para elegir, con la opción de crear uno nuevo | Se detiene y pide `--project` |
+
+`--project` acepta el número o el título exacto de un Project abierto del propietario, o un
+título nuevo para crearlo. Lo elegido se guarda en `.project-kit/state.json` y las siguientes
+ejecuciones lo reutilizan sin preguntar; un `--project` explícito lo sustituye. Un `--dry-run`
+pregunta pero no guarda nada. Los Projects cerrados se ignoran.
+
+## Vistas del Project
+
+La API de GitHub no permite crear vistas (Board, Roadmap, tabla). Hay que crearlas a mano una
+vez en la interfaz del Project.
+
+## GitLab
+
+Con `provider: gitlab` en `.project-kit/config.yml`, `pjkit provision` usa `glab api` (la API REST
+de GitLab, también en instancias propias) y sigue las mismas reglas: planifica leyendo, enseña,
+pide confirmación y solo crea lo que falta; las issues se reencuentran por su marca
+`project-kit:id` si se pierde el estado.
+
+GitLab no tiene los campos de un Project de GitHub, así que:
+
+| GitHub | GitLab |
+|---|---|
+| Fase (campo) | Milestone |
+| Tipo y prioridad (labels y campos) | Labels `type:…` y `P0`…`P3` |
+| Tamaño (campo) | Label `size::M` |
+| Estado (campo) | Label `status::Backlog`, `status::In progress`… |
+| Project con vistas | Tablero de issues `project-kit` con una lista por label de estado |
+| Épica con hijas | Issue padre con la lista de hijas (`#N`) |
+
+`--project` no se aplica. `doctor` comprueba `glab` y su sesión (`glab auth login`, ámbito
+`api`). Las plantillas de merge request e issues están en `.project-kit/templates/gitlab/`.
+
+**Aviso:** esta parte solo se ha probado contra una API simulada, no contra un proyecto GitLab
+real. Lee con atención el `--dry-run` la primera vez y abre una issue si algo no coincide.

project_kit_cli-0.5.1/src/project_kit/assets/docs/skills.md

@@ -0,0 +1,63 @@
+# Skills recomendadas
+
+project-kit no instala skills de terceros: las **recomienda**. El catálogo vive en
+`.project-kit/skills-catalog.yml` (se actualiza con `pjkit upgrade`), la skill `pk-skills` elige
+las que encajan con el proyecto y `.project-kit/skills.yml` guarda qué se decidió con cada una.
+
+```
+pjkit skills list --traits web-ui      # lo que ayuda a un proyecto con interfaz
+```
+
+Los rasgos (`--traits`) son: `any`, `web-ui`, `react`, `public-site`, `backend`, `api`,
+`microservices`, `mobile`, `mcp`. Las áreas: `ui-ux`, `motion`, `accessibility`, `seo`,
+`security`, `architecture`, `process`, `testing`, `browser`, `mcp`, `discovery`.
+
+## Criterio de selección (issue #51)
+
+Una skill entra en el catálogo si cumple todo esto:
+
+1. **Fuente leída.** Se abrió el repositorio y se anotó la fecha (`checked`). Lo que el
+   repositorio no confirma se dice en `notes` o en `license`.
+2. **Licencia conocida.** Una licencia de compartir igual (CC BY-SA) obliga a instalarla, no a
+   copiarla al repositorio del proyecto.
+3. **Formato `SKILL.md`**, instalable con un comando que el usuario ejecuta.
+4. **Cubre un trabajo concreto** y declara cuándo conviene (`when`).
+5. **Sin riesgos silenciosos.** Si una herramienta de análisis marcó la skill, o ejecuta un
+   navegador o comandos, se dice antes de instalarla.
+
+Se descartó copiar skills dentro de project-kit (*vendoring*): obliga a mantenerlas y a cumplir
+cada licencia. Tampoco se escriben skills propias cuando ya hay una buena; las propias (`pk-*`)
+cubren lo que depende del proyecto: sus reglas, la entrevista crítica y la recomendación.
+
+## Resultado
+
+| Área | Skill | Fuente | Licencia | Estado |
+|---|---|---|---|---|
+| process | grill-me | mattpocock/skills | MIT | leída |
+| discovery | find-skills | vercel-labs/skills | MIT | leída; el comando se infiere del patrón `npx skills add` |
+| ui-ux | frontend-design | anthropics/skills | Apache-2.0 según un aviso derivado | **pendiente**: el repositorio no la lista por nombre |
+| ui-ux | Impeccable | pbakaus/impeccable | Apache-2.0 | leída |
+| accessibility | web-design-guidelines | vercel-labs/agent-skills | MIT | leída |
+| architecture | react-best-practices, composition-patterns | vercel-labs/agent-skills | MIT | leída |
+| motion | Emil Kowalski (animate, review-animations...) | emilkowalski/skills | MIT | leída |
+| mcp | mcp-builder | anthropics/skills | sin verificar | **pendiente**: no aparece por nombre |
+| architecture | DDD, hexagonal, clean, microservicios | kayaman/skills | CC0-1.0 | leída |
+| testing | tdd | kayaman/skills | CC0-1.0 | leída |
+| seo | Claude SEO | AgriciDaniel/claude-seo | MIT | leída |
+| security | insecure-defaults, supply-chain-risk-auditor, differential-review, open-sourcing | trailofbits/skills | CC BY-SA 4.0 | leída |
+
+Quedan **sin candidata verificada**: marketing, privacidad y cumplimiento, datos y migraciones,
+diseño de API, observabilidad y rendimiento. `accessibility` tiene solo las reglas de Vercel;
+`fixing-accessibility` (ibelick/ui-skills) no pudo confirmarse en el repositorio. Para esos
+huecos, `pk-foundations` escribe las reglas del proyecto y `find-skills` ayuda a buscar.
+
+Las reglas de código, testing, seguridad preventiva y documentación **no** se piden a terceros:
+`pk-foundations` las genera con el stack decidido, porque una regla genérica no se cumple.
+Las revisiones de código y de seguridad que ya trae Claude Code (`/code-review`,
+`/security-review`) se enlazan, no se reescriben.
+
+## Cómo se añade una skill al catálogo
+
+Edita `src/project_kit/assets/project/skills-catalog.yml` con los campos `id`, `name`, `area`,
+`source`, `install`, `license`, `summary`, `when`, `checked` y, si hace falta, `notes`. Los
+tests validan el formato. Abre antes el repositorio de la skill y anota lo que viste.

project_kit_cli-0.5.1/src/project_kit/assets/docs/statusline.md

@@ -0,0 +1,58 @@
+# Barra de estado
+
+`pjkit statusline` escribe **una línea** para la barra de estado del agente: modelo, esfuerzo,
+contexto, límites de uso y la fase del proyecto.
+
+```
+[Opus · high] · ctx 23% · 5h 41% (↻ 17:00) · 7d 12% · ~$1.23 · fase: decide → /pk-decide
+```
+
+## Activarla
+
+```
+pjkit statusline --install      # escribe statusLine en .claude/settings.json
+pjkit statusline --install --dry-run
+pjkit statusline --remove
+```
+
+`init` (en un proyecto nuevo y con terminal) pregunta si la quieres; `/pk-start` también. Sin un
+sí no se toca nada. Con `init --statusline` / `--no-statusline` se decide sin preguntar.
+
+Si ya tienes una barra (la del proyecto o la de tu `~/.claude/settings.json`), **se conserva**: se
+configura `pjkit statusline --wrap "<tu comando>"`, que ejecuta primero el tuyo y añade el nuestro
+detrás. `--remove` restaura tu comando. Si prefieres incrustar solo el trozo de project-kit en
+otra barra, usa `pjkit statusline --segment`, que imprime únicamente la fase.
+
+## Qué se muestra y qué se recorta
+
+| Parte | Origen |
+|---|---|
+| `[Opus · high]` | modelo y esfuerzo que entrega el agente |
+| `ctx 23%` | contexto usado |
+| `5h 41% (↻ 17:00)`, `7d 12%` | límites de uso de las ventanas de 5 horas y 7 días, con la hora de reinicio (solo planes Pro y Max) |
+| `~$1.23` | coste de la sesión, **estimado** a precio de lista; puede diferir de la factura |
+| `fase: decide → /pk-decide` | `.project-kit/state.json` y `workflow.yml`; no depende del agente |
+
+Si la línea no cabe (anchura de `$COLUMNS`, 120 por defecto, o `--width`), se quita primero el
+coste, luego el límite de 7 días, el esfuerzo y el contexto; el límite de 5 horas y la fase son lo
+último en desaparecer. Verde por debajo del 60 %, ámbar hasta el 85 %, rojo a partir de ahí.
+`NO_COLOR` o `--no-color` quitan los colores.
+
+Todo es opcional: un campo que falta, un documento que no es JSON o un directorio que no es un
+proyecto no producen errores, solo una línea más corta.
+
+## Rendimiento
+
+El comando se ejecuta con cada actualización del agente, así que se despacha desde
+`project_kit/entry.py` antes de cargar el resto del programa. En la máquina donde se midió
+(Windows, con el lanzador de `uv`) tarda unos 140 ms fuera de un proyecto y unos 180 ms dentro de
+uno, que es el coste de leer el YAML del flujo. No usa la red.
+
+## Otros agentes
+
+Solo Claude Code tiene hoy una barra de estado documentada
+([documentación](https://code.claude.com/docs/en/statusline)), así que solo existe su adaptador.
+La lectura de los datos está aislada en `ADAPTERS` (`statusline.py`): un adaptador recibe el
+documento que entrega el agente y devuelve `Metrics`. Para Copilot, Codex, Gemini o Cursor basta
+con escribir su adaptador y registrarlo cuando se confirme que tienen un mecanismo equivalente; la
+parte de project-kit no cambia.

project_kit_cli-0.5.1/src/project_kit/assets/docs/upgrade.md

@@ -0,0 +1,47 @@
+# Actualizar un proyecto: `pjkit upgrade`
+
+`uv tool upgrade project-kit-cli` actualiza el **programa**. Pero `pjkit init` copia al
+repositorio ficheros que después viven allí por su cuenta (las skills de `.claude/skills/pk-*`,
+las plantillas de `.project-kit/templates/` y `.project-kit/workflow.yml`) y no los sobrescribe
+nunca. Por eso un proyecto ya creado se queda con la versión con la que nació. `upgrade` lo pone
+al día sin pisar lo que hayas editado.
+
+```
+pjkit upgrade             # muestra qué cambia; no escribe nada
+pjkit upgrade --diff      # además, las diferencias de cada fichero
+pjkit upgrade --apply     # lo aplica
+pjkit upgrade --apply --adopt
+```
+
+## Cómo decide
+
+`init` y `upgrade` guardan en `.project-kit/installed.json` la huella (SHA-256) de cada fichero tal
+como lo instalaron. Se versiona con el repositorio. Con ella, para cada fichero:
+
+| Situación | Resultado |
+|---|---|
+| Idéntico a la versión actual | Nada que hacer |
+| No lo editaste y el paquete trae una versión nueva | **update**: se reemplaza |
+| Falta (es nuevo en esta versión, o lo borraste) | **add**: se crea |
+| Lo editaste y el paquete no lo cambió | Se deja; no hay nada nuevo |
+| Lo editaste **y** el paquete lo cambió | **conflict**: se queda el tuyo y la versión nueva se deja en `.project-kit/upgrade/new/` para que la mezcles |
+| Difiere y no hay huella registrada (proyecto anterior a esta función) | **unknown**: igual que un conflicto, salvo con `--adopt` |
+| Estaba instalado y ya no se distribuye | **obsolete**: se avisa, nunca se borra |
+
+Los saltos de línea CRLF de un checkout de Git en Windows no cuentan como edición.
+
+## Proyectos anteriores al registro
+
+Un proyecto creado con una versión que no guardaba huellas no permite saber si un fichero distinto
+es una versión antigua o una edición tuya, y `upgrade` no lo adivina. Los marca `unknown` y, sin
+`--apply --adopt`, no los toca (deja la versión nueva en `.project-kit/upgrade/new/`). Si sabes que
+no los editaste, `--adopt` los reemplaza. Revisa antes el resultado de `pjkit upgrade --diff`.
+
+## Seguridad
+
+- Sin `--apply` no se escribe nada.
+- Todo fichero que se reemplaza se copia antes a `.project-kit/upgrade/backup/`.
+- Nunca se pisa un fichero que hayas editado (ni con `--adopt`).
+- `.project-kit/upgrade/` es temporal: cuando hayas revisado o mezclado, bórralo o añádelo a
+  `.gitignore`.
+- `config.yml`, `state.json`, el backlog y tus documentos no se tocan.

{project_kit_cli-0.5.0 → project_kit_cli-0.5.1}/src/project_kit/backlog.py

@@ -1,6 +1,6 @@
 """.project-kit/backlog.json: the project backlog, source of truth for provisioning.
 
-Shape (see docs/backlog-schema.md for the full description)::
+Shape (see ``pjkit docs backlog-schema`` for the full description)::
 
     {
       "version": 1,

{project_kit_cli-0.5.0 → project_kit_cli-0.5.1}/src/project_kit/cli.py

@@ -23,6 +23,7 @@ from project_kit import (
     statusline,
     trace,
     upgrade,
+    userdocs,
 )
 from project_kit import (
     help as help_guide,
@@ -134,6 +135,9 @@ def build_parser() -> argparse.ArgumentParser:
     )
     im.add_argument("--dry-run", action="store_true", help="show what would be copied")
 
+    dc = sub.add_parser("docs", help="the user guides that ship with the program")
+    dc.add_argument("topic", nargs="?", help="a guide to print (omit to list them)")
+
     nx = sub.add_parser("next", help="what comes next, in words you can give to your AI")
     nx.add_argument("--json", action="store_true", help="machine-readable output")
 
@@ -289,6 +293,18 @@ def _import(path: str, *, allow_sensitive: bool, dry_run: bool) -> int:
     return 1 if result.sensitive else 0
 
 
+def _docs(topic: str | None) -> int:
+    if topic is None:
+        print(userdocs.render_list())
+        return 0
+    try:
+        print(userdocs.read(topic))
+    except userdocs.UnknownTopic as exc:
+        print(f"pjkit docs: {exc.args[0]}", file=sys.stderr)
+        return 1
+    return 0
+
+
 def _next(as_json: bool) -> int:
     try:
         nxt = next_step.compute(Path.cwd())
@@ -728,6 +744,8 @@ def main(argv: Sequence[str] | None = None) -> int:
         return _handoff(args)
     if args.command == "import":
         return _import(args.path, allow_sensitive=args.allow_sensitive, dry_run=args.dry_run)
+    if args.command == "docs":
+        return _docs(args.topic)
     if args.command == "next":
         return _next(args.json)
     if args.command == "hook":

{project_kit_cli-0.5.0 → project_kit_cli-0.5.1}/src/project_kit/help.py

@@ -32,6 +32,7 @@ TERMINAL_COMMANDS = (
         "recommended skills for this project and what was decided",
     ),
     ("pjkit import <path>", "copy existing documentation for the project to start from"),
+    ("pjkit docs [topic]", "read the guides that ship with the program"),
     ("pjkit next", "what comes next, in words you can give to your AI"),
     ("pjkit hook install", "let Claude Code know the project's state at each session start"),
     ("pjkit trace [--criteria]", "link issues, decisions, specs and tests; show the gaps"),

project_kit_cli-0.5.1/src/project_kit/userdocs.py

@@ -0,0 +1,41 @@
+"""``pjkit docs``: the user guides that ship with the program.
+
+The package page on PyPI shows only the README, and the repository may not be public, so the
+detailed guides travel inside the package and are read with ``pjkit docs <topic>``.
+"""
+
+from importlib.resources import files
+
+_DIR = files("project_kit") / "assets" / "docs"
+
+
+class UnknownTopic(KeyError):
+    """No guide with that name."""
+
+
+def topics() -> list[tuple[str, str]]:
+    """(name, title) of every guide, by name. The title is the guide's first heading."""
+    found = []
+    for node in _DIR.iterdir():
+        if node.name.endswith(".md"):
+            text = node.read_text(encoding="utf-8")
+            title = next(
+                (line.lstrip("# ").strip() for line in text.splitlines() if line.startswith("#")),
+                node.name,
+            )
+            found.append((node.name[: -len(".md")], title))
+    return sorted(found)
+
+
+def read(topic: str) -> str:
+    node = _DIR / f"{topic}.md"
+    if not node.is_file():
+        known = ", ".join(name for name, _ in topics())
+        raise UnknownTopic(f"No guide called {topic!r}. Available: {known}")
+    return node.read_text(encoding="utf-8")
+
+
+def render_list() -> str:
+    lines = ["Guides (pjkit docs <topic>):", ""]
+    lines += [f"  {name:<16} {title}" for name, title in topics()]
+    return "\n".join(lines)