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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: project-kit-cli
-Version: 0.4.0
+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
@@ -14,14 +14,12 @@ 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 +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
 
@@ -91,6 +88,33 @@ pjkit status     # where you are and what comes next
 pjkit help       # a visual guide to the flow and the commands
 ```
 
+## You do not need to learn the skills
+
+You never have to know which skill fits which moment. Open your agent in the project and say
+what you want in your own words: *"continue"*, *"I already have a PRD"*, *"challenge this plan"*,
+*"the scope changed"*, *"is this feature really done?"*. The agent picks the skill.
+
+- `init` writes a block in `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` with a table of *what the user
+  wants → which skill*, refreshed as the project moves.
+- `/pk-next` is the conductor: it reads `pjkit next`, runs the phase that is due, offers
+  `pk-grill` before each approval, suggests `pk-skills` once the stack is chosen, `pk-amend`
+  when the plan changes and `pk-verify` when an issue seems finished. It never approves for you.
+- `pjkit next` and the end of `pjkit status` print what to tell your AI, in plain words, for
+  agents that have no `/` commands.
+- Claude Code can also be told the project's state at the start of each session
+  (`pjkit hook install`, asked in `init`, never without a yes).
+
+## Starting from documents you already have
+
+`pjkit import <folder or file>` (or `pjkit init --from <path>`) copies a PRD, notes or a wiki
+export into `docs/sources/` without touching the originals, and lists them in
+`docs/sources/INDEX.md` with how each can be read. Then `/pk-import` drafts the brief, the
+decisions (as *Proposed*), the roadmap and the backlog from them, citing the source of every
+claim, marking what they do not say as `[NEEDS CLARIFICATION]`, asking about contradictions, and
+reviewing the result with `pk-grill`. It never overwrites a document or approves a phase. Files
+that look like they contain secrets or personal data are not copied unless you say so
+(`--allow-sensitive`).
+
 ## The phases
 
 | # | Skill | What it does | Produces |
@@ -104,8 +128,8 @@ pjkit help       # a visual guide to the flow and the commands
 | 6 | `/pk-provision` | Creates milestones, labels, branches, the GitHub Project and the issues (skipped with `provider: none`) | GitHub |
 | 7 | `/pk-handoff` | Prepares the Spec Kit constitution; each issue becomes a spec; writes `CLAUDE.md` / `AGENTS.md` | `.project-kit/handoff/constitution-input.md` |
 
-Outside the sequence, three skills are always available: `/pk-grill` interviews you hard and
-cross-checks the project's documents for contradictions (it is offered before each approval),
+`/pk-next` runs the whole sequence for you (see above). Outside the sequence, three more
+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.
 
@@ -138,11 +162,16 @@ It never rewrites issues that already exist, and re-running it is always safe.
 | `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 next [--json]` | What comes next, in words you can give to your AI |
+| `pjkit import <path>` | Copy existing documentation to `docs/sources/` for `/pk-import` |
+| `pjkit hook install\|remove` | Tell Claude Code the project's state at the start of each session |
+| `pjkit mode [quick\|full]` | Show or change how many phases the project goes through |
+| `pjkit trace [--criteria] [--json]` | Show which issues have a spec, a decision and a test, and what is not linked |
 | `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),
+Useful `init` options: `--from <path>`, `--mode quick|full`, `--no-context`, `--project-name`, `--language` (language of the generated documents),
 `--agents claude,codex,...` (the AI agents you use; asked when there is a terminal),
 `--agent claude|none` (open the agent or not), `--provider github|gitlab|none` and
 `--ai-coauthor keep|remove`.
@@ -156,6 +185,31 @@ writes the context file each one reads (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`).
 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.
 
+## Small projects: quick mode
+
+Not every project needs seven phases. `pjkit init --mode quick` (or answer yes when `init` asks
+whether it is a small project) skips *decide*, *workflow* and *foundations*: you go from the
+brief to the plan, and the stack is taken from the brief. `pjkit mode full` brings the phases
+back, `pjkit mode` shows where you are, and `pjkit status` says which phases are skipped and why.
+
+## Checking that it is really done
+
+The agent that built a feature should not be the only one to decide it is finished.
+`/pk-verify` is a second opinion: it reads the issue's acceptance criteria, runs the project's
+own tests and gives a verdict per criterion with evidence (`PASS`, `FAIL` or `INCOMPLETE`),
+without touching any file. In Claude Code, `init` also installs the `pk-reviewer` subagent
+(`.claude/agents/`), read-only, so the check runs in a context separate from the implementation.
+
+`pjkit trace` shows the links between what was asked and what exists. Each acceptance criterion
+has a stable name, `<issue id>#<position>` (`login#2`); write it in a test name or a spec and
+`trace` lists the issues with no spec, the specs with no test, the criteria with no test, the
+decisions nobody mentions and the references to things that do not exist. A link is a mention:
+it shows what is missing, not that a test is any good, which is what `/pk-verify` is for.
+
+`pjkit approve` refuses to sign off a phase whose documents still have
+`[NEEDS CLARIFICATION]` markers (it asks if you are at a terminal; `--allow-open-questions`
+approves anyway).
+
 ## Status bar
 
 Claude Code can show a line of your choosing at the bottom of the screen. `pjkit statusline`
@@ -170,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
 
@@ -191,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
 
@@ -230,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.4.0 → project_kit_cli-0.5.1}/README.md

@@ -1,7 +1,7 @@
 # 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 +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
 
@@ -71,6 +70,33 @@ pjkit status     # where you are and what comes next
 pjkit help       # a visual guide to the flow and the commands
 ```
 
+## You do not need to learn the skills
+
+You never have to know which skill fits which moment. Open your agent in the project and say
+what you want in your own words: *"continue"*, *"I already have a PRD"*, *"challenge this plan"*,
+*"the scope changed"*, *"is this feature really done?"*. The agent picks the skill.
+
+- `init` writes a block in `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` with a table of *what the user
+  wants → which skill*, refreshed as the project moves.
+- `/pk-next` is the conductor: it reads `pjkit next`, runs the phase that is due, offers
+  `pk-grill` before each approval, suggests `pk-skills` once the stack is chosen, `pk-amend`
+  when the plan changes and `pk-verify` when an issue seems finished. It never approves for you.
+- `pjkit next` and the end of `pjkit status` print what to tell your AI, in plain words, for
+  agents that have no `/` commands.
+- Claude Code can also be told the project's state at the start of each session
+  (`pjkit hook install`, asked in `init`, never without a yes).
+
+## Starting from documents you already have
+
+`pjkit import <folder or file>` (or `pjkit init --from <path>`) copies a PRD, notes or a wiki
+export into `docs/sources/` without touching the originals, and lists them in
+`docs/sources/INDEX.md` with how each can be read. Then `/pk-import` drafts the brief, the
+decisions (as *Proposed*), the roadmap and the backlog from them, citing the source of every
+claim, marking what they do not say as `[NEEDS CLARIFICATION]`, asking about contradictions, and
+reviewing the result with `pk-grill`. It never overwrites a document or approves a phase. Files
+that look like they contain secrets or personal data are not copied unless you say so
+(`--allow-sensitive`).
+
 ## The phases
 
 | # | Skill | What it does | Produces |
@@ -84,8 +110,8 @@ pjkit help       # a visual guide to the flow and the commands
 | 6 | `/pk-provision` | Creates milestones, labels, branches, the GitHub Project and the issues (skipped with `provider: none`) | GitHub |
 | 7 | `/pk-handoff` | Prepares the Spec Kit constitution; each issue becomes a spec; writes `CLAUDE.md` / `AGENTS.md` | `.project-kit/handoff/constitution-input.md` |
 
-Outside the sequence, three skills are always available: `/pk-grill` interviews you hard and
-cross-checks the project's documents for contradictions (it is offered before each approval),
+`/pk-next` runs the whole sequence for you (see above). Outside the sequence, three more
+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.
 
@@ -118,11 +144,16 @@ It never rewrites issues that already exist, and re-running it is always safe.
 | `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 next [--json]` | What comes next, in words you can give to your AI |
+| `pjkit import <path>` | Copy existing documentation to `docs/sources/` for `/pk-import` |
+| `pjkit hook install\|remove` | Tell Claude Code the project's state at the start of each session |
+| `pjkit mode [quick\|full]` | Show or change how many phases the project goes through |
+| `pjkit trace [--criteria] [--json]` | Show which issues have a spec, a decision and a test, and what is not linked |
 | `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),
+Useful `init` options: `--from <path>`, `--mode quick|full`, `--no-context`, `--project-name`, `--language` (language of the generated documents),
 `--agents claude,codex,...` (the AI agents you use; asked when there is a terminal),
 `--agent claude|none` (open the agent or not), `--provider github|gitlab|none` and
 `--ai-coauthor keep|remove`.
@@ -136,6 +167,31 @@ writes the context file each one reads (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`).
 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.
 
+## Small projects: quick mode
+
+Not every project needs seven phases. `pjkit init --mode quick` (or answer yes when `init` asks
+whether it is a small project) skips *decide*, *workflow* and *foundations*: you go from the
+brief to the plan, and the stack is taken from the brief. `pjkit mode full` brings the phases
+back, `pjkit mode` shows where you are, and `pjkit status` says which phases are skipped and why.
+
+## Checking that it is really done
+
+The agent that built a feature should not be the only one to decide it is finished.
+`/pk-verify` is a second opinion: it reads the issue's acceptance criteria, runs the project's
+own tests and gives a verdict per criterion with evidence (`PASS`, `FAIL` or `INCOMPLETE`),
+without touching any file. In Claude Code, `init` also installs the `pk-reviewer` subagent
+(`.claude/agents/`), read-only, so the check runs in a context separate from the implementation.
+
+`pjkit trace` shows the links between what was asked and what exists. Each acceptance criterion
+has a stable name, `<issue id>#<position>` (`login#2`); write it in a test name or a spec and
+`trace` lists the issues with no spec, the specs with no test, the criteria with no test, the
+decisions nobody mentions and the references to things that do not exist. A link is a mention:
+it shows what is missing, not that a test is any good, which is what `/pk-verify` is for.
+
+`pjkit approve` refuses to sign off a phase whose documents still have
+`[NEEDS CLARIFICATION]` markers (it asks if you are at a terminal; `--allow-open-questions`
+approves anyway).
+
 ## Status bar
 
 Claude Code can show a line of your choosing at the bottom of the screen. `pjkit statusline`
@@ -150,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
 
@@ -171,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
 
@@ -210,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.4.0 → project_kit_cli-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "project-kit-cli"
-version = "0.4.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.4.0 → project_kit_cli-0.5.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "project-kit-cli"
-version = "0.4.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.4.0 → project_kit_cli-0.5.1}/src/project_kit/approval.py

@@ -1,5 +1,6 @@
 """Approval gates: record that the user signed off on a phase."""
 
+import re
 from pathlib import Path
 
 from project_kit.backlog import load_backlog
@@ -8,6 +9,47 @@ from project_kit.handoff import CONSTITUTION, INPUT_FILE, constitution_ready
 from project_kit.state import PHASES, State, StateError, load_state, save_state
 from project_kit.workflow import load_workflow
 
+_MARKER = re.compile(r"\[NEEDS CLARIFICATION\b[^\]]*\]?")
+_COMMENT = re.compile(r"<!--.*?-->", re.DOTALL)
+_MAX_SHOWN = 8
+
+
+def open_questions(root: Path, phase: str) -> list[tuple[str, int, str]]:
+    """Unresolved ``[NEEDS CLARIFICATION: ...]`` markers in the documents the phase produces.
+
+    Returns (file, line, text). A marker inside an HTML comment is a template's instruction, not
+    a question, and is ignored. Files that do not exist are skipped.
+    """
+    step = next((s for s in load_workflow(root).steps if s.id == phase), None)
+    if step is None:
+        return []
+    paths: list[Path] = []
+    for produced in step.produces:
+        target = root / produced
+        if target.is_dir():
+            paths += sorted(target.rglob("*.md"))
+        elif target.is_file() and target.suffix == ".md":
+            paths.append(target)
+    found = []
+    for path in paths:
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        text = _COMMENT.sub(lambda m: "\n" * m.group(0).count("\n"), text)  # keep line numbers
+        for number, line in enumerate(text.splitlines(), 1):
+            if match := _MARKER.search(line):
+                found.append((path.relative_to(root).as_posix(), number, match.group(0)[:100]))
+    return found
+
+
+def describe_open_questions(found: list[tuple[str, int, str]]) -> str:
+    shown = [f"  {path}:{line}  {text}" for path, line, text in found[:_MAX_SHOWN]]
+    more = len(found) - _MAX_SHOWN
+    if more > 0:
+        shown.append(f"  ... and {more} more")
+    return f"{len(found)} unresolved [NEEDS CLARIFICATION] marker(s):\n" + "\n".join(shown)
+
 
 def approve_phase(root: Path, phase: str) -> State:
     """Record the approval of ``phase`` in the project state.

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.