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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: project-kit-cli
-Version: 0.4.0
+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
@@ -91,6 +91,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 +131,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 +165,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 +188,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`

{project_kit_cli-0.4.0 → project_kit_cli-0.5.0}/README.md

@@ -71,6 +71,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 +111,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 +145,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 +168,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`

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

@@ -1,6 +1,6 @@
 [project]
 name = "project-kit-cli"
-version = "0.4.0"
+version = "0.5.0"
 description = "Project definition and dev-workflow kit that hands off to Spec Kit"
 readme = "README.md"
 requires-python = ">=3.12"

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

@@ -1,6 +1,6 @@
 [project]
 name = "project-kit-cli"
-version = "0.4.0"
+version = "0.5.0"
 description = "Project definition and dev-workflow kit that hands off to Spec Kit"
 readme = "README.md"
 requires-python = ">=3.12"

{project_kit_cli-0.4.0 → project_kit_cli-0.5.0}/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.4.0 → project_kit_cli-0.5.0}/src/project_kit/assets/skills/pk-amend/SKILL.md

@@ -30,6 +30,8 @@ Read `.project-kit/templates/interview.md` first and follow it.
      `Superseded by ADR-NNNN`. Never edit an accepted ADR to say something else.
    - Backlog: add or change issues keeping their `id`; to drop one, remove it only if it was not
      provisioned yet, otherwise mark it for the user to close. Do not reuse an id.
+   - Acceptance criteria are named by position (`<issue id>#1`, `#2`...) and tests refer to
+     them that way: add new ones at the end, never reorder or delete one that has a test.
    - Keep the language of `config.yml`. Record the exchange under `## Clarifications` >
      `### Session YYYY-MM-DD`, as `- Q: ... -> A: ...`.
 4. **Validate.** Run `pjkit backlog validate` and fix every problem it reports.

project_kit_cli-0.5.0/src/project_kit/assets/skills/pk-import/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: pk-import
+description: Start the project from documentation the user already has (a PRD, notes, an exported wiki, a proposal, a long README) - read it, draft the brief, decisions, roadmap and backlog from it with sources, ask about contradictions and gaps, and review the drafts with pk-grill. Use when the user says they already have documents, or points at a folder of them.
+---
+
+# pk-import — start from what already exists
+
+Many projects do not start from nothing: there is a PRD, a client proposal, meeting notes, a
+wiki export. Making the user repeat all of it in an interview wastes it. This skill reads what
+exists and produces **drafts**, with the source of every claim, then asks about whatever does
+not add up. The user still reviews and approves each phase.
+
+Read `.project-kit/templates/interview.md` first and follow it.
+
+## Inputs
+
+- `docs/sources/INDEX.md`: the index that `pjkit import <path>` wrote, which lists each source
+  file, its format and whether it could be read. If it does not exist and the user gave a path,
+  run `pjkit import <path>` (it copies the files to `docs/sources/`; the originals are not
+  touched). If the user attached documents to the conversation instead, save nothing yourself:
+  ask them to put the files in a folder and run `pjkit import <folder>`.
+- Whatever already exists in `docs/project/` and `docs/adr/`. **Never overwrite it**: propose a
+  merge and ask.
+
+## Steps
+
+1. **Read the index and the sources.** Say which ones you could not read (a scanned PDF, a
+   format you cannot open) and what the user can do (export to text or Markdown). Read long
+   sources in parts. Say what did not fit.
+2. **Look for sensitive data first.** If a source seems to contain personal data, credentials or
+   keys, stop and tell the user before copying anything further or quoting it in a draft.
+3. **Draft, in this order,** only what the sources support. After each draft say its path:
+   - `docs/project/brief.md` from `.project-kit/templates/brief.md`: problem, users, scope,
+     non-goals, constraints, risks.
+   - `docs/adr/NNNN-*.md` for the technical decisions the sources already take, from
+     `.project-kit/templates/adr.md`, with `Status: Proposed` (the user accepts them).
+   - If the sources cover them: a draft of `docs/development-workflow.md` and of the project's
+     rules in `docs/project/` (standards, testing, security, documentation).
+   - A draft roadmap in `docs/project/roadmap.md` and `.project-kit/backlog.json`, with
+     acceptance criteria per issue. Validate it with `pjkit backlog validate`.
+4. **Sources and gaps.** Every claim that comes from a source ends with its provenance, for
+   example `(source: docs/sources/prd.md, section 3)`. What the sources do not say is written as
+   `[NEEDS CLARIFICATION: ...]`. **Invent nothing**: no users, figures, dates, stacks or
+   requirements that are not in the sources.
+5. **Contradictions.** List every place where two sources disagree, or a figure or date does not
+   add up, or a requirement has no owner. Ask them one at a time, each with your recommended
+   answer and the sources on both sides, and record the answer in the document it affects.
+6. **Review.** Run `pk-grill` on the drafts and resolve what it finds, exactly as it works for a
+   project written by interview.
+7. **Approval.** For each phase whose documents now exist, follow the usual gate with the user:
+   a selection list, and only an explicit "Approve it" allows `pjkit approve <phase>`. A phase
+   whose documents still have open `[NEEDS CLARIFICATION]` markers is not approved without the
+   user saying so. Then run `pjkit next` and offer what comes after.
+
+## Rules
+
+- The originals in `docs/sources/` are never edited. Drafts go in the project's own documents.
+- Never approve a phase for the user; never overwrite an existing document.
+- Be explicit about confidence: "stated in the PRD" is not the same as "inferred from the PRD".
+- Keep the language of `config.yml` for the drafts, even if the sources use another.
+- If the sources cover only part of the project (say, the product but not the stack), draft that
+  part and continue with the normal skill for the rest (`pk-decide`, ...).

project_kit_cli-0.5.0/src/project_kit/assets/skills/pk-next/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: pk-next
+description: Conduct the project - find where it is and do the right next thing, choosing the skill so the user does not have to. Use whenever the user says "continue", "keep going", "what now?", "next", "where are we?", or is unsure which skill applies.
+---
+
+# pk-next — the conductor
+
+The user should not have to learn which skill fits which moment. This skill looks at the
+project, picks the right skill and runs it, and asks only what a person must decide.
+
+## Steps
+
+1. Run `pjkit next --json` (or `pjkit next` for text). It gives the phase that comes next, its
+   skill, and hints: documents of the phase that already exist, `[NEEDS CLARIFICATION]` markers
+   that are still open, whether skills were recommended yet.
+2. Say in one sentence where the project is and what you are about to do.
+3. **Decide by situation**, in this order:
+   - **The user brought documents** (a folder, attachments, "I already have a PRD") and the
+     project has no brief yet: follow `pk-import`.
+   - **There is a phase to do** (`phase` is not null): follow that phase's skill (`pk-discover`,
+     `pk-decide`, `pk-workflow`, `pk-foundations`, `pk-plan`, `pk-provision`, `pk-handoff`).
+     If the hints say its documents already exist, do not start the interview again: review
+     what is there and complete what is missing.
+   - **Before any approval**, offer `pk-grill` (a hard review that cross-checks the documents)
+     with a selection list: **Review it with pk-grill** / **Approve without it** /
+     **I want changes**. Approval is always the user's call.
+   - **The stack was just decided** and `skills.yml` does not exist: offer `pk-skills`.
+   - **Every phase is done** (`phase` is null): ask what the user wants. A change to the plan, a
+     decision or the process is `pk-amend`; building an issue is Spec Kit's job
+     (`/speckit-specify`); an issue that seems finished is checked with `pk-verify` (in Claude
+     Code, the `pk-reviewer` subagent), by someone other than whoever wrote it.
+   - **The user changes direction mid-way** ("actually the plan changed", "I decided to use X
+     instead"): `pk-amend` if the plan was approved, otherwise edit the current phase's document.
+4. When the skill you ran finishes, run `pjkit next` again and offer to continue or stop. Never
+   chain more than one phase without asking.
+
+## Rules
+
+- Never run `pjkit approve` yourself, and never treat "continue" as approval of a phase.
+  Approval needs an explicit yes to "Approve it" in this conversation.
+- Do not skip a phase that `pjkit next` returns; if the user wants fewer phases, that is
+  `pjkit mode quick` (they decide), not something to do silently.
+- Say the skill you are using by name, once, so the user learns what exists without having to.
+- Use the language of `.project-kit/config.yml` with the user.
+- If `pjkit` is missing or `.project-kit/` does not exist, tell the user to run `pjkit init` in a
+  terminal; do not create the files by hand.

{project_kit_cli-0.4.0 → project_kit_cli-0.5.0}/src/project_kit/assets/skills/pk-plan/SKILL.md

@@ -14,6 +14,11 @@ that happens later, in the provision phase.
   `docs/development-workflow.md` (process). The plan is **derived** from them: scope becomes
   epics, constraints and decisions become issues (repository setup, CI, the chosen
   infrastructure) in the first phase.
+- **In quick mode** (`mode: quick` in `config.yml`) there are no ADRs, workflow or rules
+  documents: take the stack and constraints from `docs/project/brief.md` and ask about whatever
+  the plan depends on that the brief does not say.
+- **Acceptance criteria are named by position** (`<issue id>#1`, `#2`...); tests and specs
+  refer to them by that name (`pjkit trace`). Never reorder them: add new ones at the end.
 - **Run `pjkit status` first.** If an enabled earlier phase is not done, stop and tell
   the user which skill to run (`/pk-discover`, `/pk-decide`, `/pk-workflow`). Do not
   improvise a brief. If they want to skip a phase, they set `enabled: false` on it in

{project_kit_cli-0.4.0 → project_kit_cli-0.5.0}/src/project_kit/assets/skills/pk-start/SKILL.md

@@ -5,6 +5,9 @@ description: Start here. Check that project-kit is ready in this repository, set
 
 # pk-start — phase 0
 
+> The user never has to know the skills. After this one, `pk-next` takes them through the rest:
+> they say "continue" and it chooses.
+
 Entry point of project-kit. The files are already in the repository (`pjkit init` put
 them there); this skill checks them, settles the basics and lets the user choose how far to go
 now. Nothing is created in GitHub or GitLab here.
@@ -33,7 +36,13 @@ now. Nothing is created in GitHub or GitLab here.
    whether to show the model, the usage limits and the project phase in the status bar. Only on
    a yes run `pjkit statusline --install`; it keeps any status bar the user already has and
    runs it first. Never set it up without that yes. `pjkit statusline --remove` undoes it.
-5. **Ask how far to go now**, with a selection list (`AskUserQuestion`, see
+   In the same way, if `pjkit doctor` shows the session hook as not set up, offer it (**Yes,
+   let Claude know the project's state at each session** / **No, thanks**) and only on a yes run
+   `pjkit hook install`; `pjkit hook remove` undoes it.
+5. **Size of the project.** `config.yml` has `mode: full` (every phase) or `mode: quick`
+   (skips decide, workflow and foundations, for a small project). If the user wants the other
+   one, run `pjkit mode quick` or `pjkit mode full`; `pjkit status` shows what is skipped.
+6. **Ask how far to go now**, with a selection list (`AskUserQuestion`, see
    `.project-kit/templates/interview.md`) and exactly these two options. Put B first with
    `(Recommended)` unless the user said they are in a hurry:
 
@@ -41,8 +50,10 @@ now. Nothing is created in GitHub or GitLab here.
    |--------|--------------|
    | **B. Start defining the project** | Continue now with the discovery interview |
    | **A. Only initialise** | Stop here. The user comes back later with `/pk-discover` |
-6. **If A:** run `pjkit status`, show it, and explain that `/pk-discover` is next. Done.
-7. **If B:** ask for a short description of the project in the user's own words, a few
+7. **If A:** run `pjkit status`, show it, and explain that `/pk-discover` is next. Done.
+8. **If B:** if the user has documents to start from (a PRD, notes, a proposal), or
+   `docs/sources/INDEX.md` exists, follow `pk-import` instead (`pjkit import <folder>` copies
+   them). Otherwise ask for a short description of the project in the user's own words, a few
    sentences, a pasted note or "nothing yet, ask me". Then follow the `pk-discover` skill
    (`.claude/skills/pk-discover/SKILL.md`) using that description as the starting point.
 

project_kit_cli-0.5.0/src/project_kit/assets/skills/pk-verify/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: pk-verify
+description: Verify, independently of whoever implemented it, that a feature meets its acceptance criteria - read the issue, run the project's tests and give a verdict per criterion with evidence. Use when a feature or issue is said to be finished, before merging, or when the user asks "is this really done?". Never edits code.
+---
+
+# pk-verify — is it really done?
+
+The agent that implements a feature should not be the only one to decide it is finished. This
+skill is the second opinion: it checks the work against **what was asked**, not against what the
+implementer says it did. It reads, runs the project's checks and reports. It changes nothing.
+
+Run it in a separate context from the implementation: in Claude Code, hand it to the
+`pk-reviewer` subagent (`.claude/agents/pk-reviewer.md`); in another agent, in a fresh session.
+
+## Inputs
+
+1. **Which issue.** The issue number (`#34`) or backlog id (`login`). If the user does not say,
+   find it from the current branch name (`NNN-name`) or from the open spec in `specs/`.
+2. **The criteria.** The "Acceptance criteria" list of the issue: `gh issue view <n>` (or
+   `glab issue view <n>`) when there is a provider, otherwise the entry in
+   `.project-kit/backlog.json`. Number them `<id>#1`, `<id>#2`... in the order they appear; that
+   is how `pjkit trace` names them. If the issue has none, stop and say that nothing can be
+   verified until it has some.
+3. **The spec and plan**, if Spec Kit produced them: `specs/<NNN-name>/spec.md` and `plan.md`.
+4. **How to check.** `docs/project/testing.md` (the commands and where tests live) and
+   `docs/project/standards.md` (lint, format, types). If they do not exist, look for the project's
+   own test command (`package.json`, `pyproject.toml`, `Makefile`) and say you guessed it.
+
+## Steps
+
+1. Read the inputs. Do not read the implementer's summary or commit messages as evidence.
+2. Run the checks that the project defines, in this order, and keep their output: tests, then
+   lint and type checks. A failing or missing run is a finding.
+3. For **each criterion**, look for evidence in the code and the tests:
+   - a test that exercises it (name it, say whether it passed, and whether it really asserts
+     the criterion or only touches the code);
+   - the code that implements it (file and line);
+   - for what cannot be checked by reading or running tests (a look, a flow in the browser), say
+     "not verified" and what would verify it.
+4. Look for what was **not** asked but changed: files outside the issue's scope, removed tests,
+   skipped or weakened assertions, new dependencies, secrets. Report them.
+5. Give the verdict.
+
+## Report format
+
+```
+Verdict: PASS | FAIL | INCOMPLETE
+Issue: <id / #n> <title>
+
+Checks
+- tests: <command> -> <result>
+- lint/types: <command> -> <result>
+
+Criteria
+- <id>#1 <text>: PASS - <evidence>
+- <id>#2 <text>: FAIL - <what is missing or wrong, with file/line>
+- <id>#3 <text>: NOT VERIFIED - <why, and what would verify it>
+
+Outside the scope of the issue
+- <anything else that changed, or "nothing found">
+```
+
+`PASS` only if every criterion passes with evidence and the checks are green. Any `FAIL` makes it
+`FAIL`. A criterion that is not verified makes it at best `INCOMPLETE`.
+
+## Rules
+
+- Do not edit, create or delete files; do not commit, push or change branches; do not install
+  anything; do not write to the provider (no comments, labels, closing issues, moving cards).
+  Report, and let the user or the implementer act.
+- Do not fix a failing test to make the verdict pass. Do not lower a criterion.
+- Never claim a pass you did not see. If a command could not run, say so.
+- Do not run `pjkit approve` or merge anything.
+- Be specific and brief. The reader wants to know what to fix, not a review of the style.

project_kit_cli-0.5.0/src/project_kit/assets/subagents/pk-reviewer.md

@@ -0,0 +1,26 @@
+---
+name: pk-reviewer
+description: Independent reviewer. Use proactively after a feature has been implemented, and before it is called done, to check it against its acceptance criteria and the project's tests. It never wrote the code it reviews and never edits it.
+tools: Read, Grep, Glob, Bash
+---
+
+You are the independent reviewer of a project set up with project-kit. Someone else
+implemented the work you are asked about; your job is to decide, with evidence, whether it
+meets what was asked. You are not there to help it pass.
+
+Start by reading `.claude/skills/pk-verify/SKILL.md` and follow it exactly.
+
+Ground rules:
+
+- You work in a clean context: do not rely on the implementer's summary. Read the issue, the
+  spec and the code yourself.
+- You may read files and run the project's own test, lint and type-check commands (the ones in
+  `docs/project/testing.md` and `docs/project/standards.md`). You may read issues with the
+  provider's CLI (`gh issue view`, `glab issue view`).
+- You must not edit, create or delete project files, change branches, commit, push, install
+  packages, or run anything that writes to the provider. If a command would do any of that, do
+  not run it and say so.
+- Every verdict cites evidence: a test name and its result, a file and line, a command and its
+  output. A criterion you could not check is reported as "not verified", never as "passes".
+- Report in the format the skill asks for. If everything passes, say so plainly; if not, list
+  what fails first.

{project_kit_cli-0.4.0 → project_kit_cli-0.5.0}/src/project_kit/assets/templates/interview.md

@@ -68,8 +68,10 @@ for the whole project.
    hard interview that cross-checks the project's documents), or **I want changes** (the user
    says what).
 3. Approval gate: only an explicit choice of "Approve it" in this conversation allows running
-   `pjkit approve <phase>`. Never approve on the user's behalf, and never because an
-   earlier question was answered.
+   `pjkit approve <phase>`. If it refuses because documents still have `[NEEDS CLARIFICATION]`
+   markers, resolve them with the user first. Add `--allow-open-questions` only if the user
+   explicitly says to approve with them open, and say which ones stay open. Never approve on
+   the user's behalf, and never because an earlier question was answered.
 4. After approving, run `pjkit status` and ask, again with a list, whether to **Continue
    with the next phase** now or **Stop here** and come back later with its skill. Respect the
    answer.