create-pathfinder 1.4.1 → 1.5.1

package/AGENTS.md

@@ -5,3 +5,7 @@ Read `CLAUDE.md` first.
 Project truth lives in `context/`. Follow the technology and delivery choices documented in `context/project-overview.md`; do not assume a framework, package manager, branch model, or release process.
 
 Use the smallest relevant context for the active task. Keep each delivery chunk stable, reviewable, and verifiable.
+
+Canonical skills live under `skills/` and are the only behavior contract; anything under `.claude/skills/` or `.agents/skills/` is a generated pointer to one, so edit the canonical file and regenerate the adapter.
+
+If this tool has no native skill discovery, invoke a skill by reading its canonical file directly: `Use skills/<name>/SKILL.md and follow it exactly.` That is the whole fallback — there is no launcher file, and no second copy of a skill to find.

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # Project Agent Guide
 
-This repository uses an AI-assisted, human-in-the-loop workflow. Project truth lives in `context/`, reusable behaviors live in `skills/`, and manual launchers live in `prompts/`.
+This repository uses an AI-assisted, human-in-the-loop workflow. Project truth lives in `context/`, and reusable behaviors live in `skills/`.
 
 ## Read only what is needed
 
@@ -48,6 +48,12 @@ Ask before actions identified in `context/ai-interaction.md`, especially depende
 - Prefer concrete verification over confident narration.
 - Report conflicts between specs, repository reality, and durable context.
 
+## Canonical skills and harness adapters
+
+Canonical Pathfinder skills are tool-neutral and live under `skills/`. Harness-specific representations — `.claude/skills/`, `.agents/skills/` — are generated integration artifacts and must not become independent behavior contracts. Edit the canonical file; regenerate the adapter.
+
+An adapter carries the canonical skill's frontmatter and a pointer to it, and nothing else. If an adapter and its canonical skill disagree, the canonical skill is correct.
+
 ## Available skills
 
 - `kickstart-pathfinder` — discover and initialize project context

package/README.md

@@ -2,7 +2,7 @@
 
 **An AI-assisted, human-in-the-loop workflow for building software — without giving up the decisions.**
 
-This package installs [Pathfinder](https://github.com/rikilamadrid/pathfinder) into a Git repository you already have.
+This package installs [Pathfinder](https://github.com/rikilamadrid/pathfinder) into a Git repository — one you already have, or one it offers to create for you.
 
 ```bash
 npx create-pathfinder
@@ -17,16 +17,21 @@ Do not install packages or write product code yet.
 
 ## What it installs
 
-Pathfinder is a kit of context files and skills — not a framework. There is no runtime, no dependency, and nothing to build. The installer copies six things into your repository and nothing else:
+Pathfinder is a kit of context files and skills — not a framework. There is no runtime, no dependency, and nothing to build. The installer copies five things into your repository and nothing else:
 
 | Path | What it is |
 | --- | --- |
 | `AGENTS.md`, `CLAUDE.md` | Entry files that tell an agent how to work in the project |
 | `context/` | Project truth — overview, standards, interaction rules, current feature |
 | `skills/` | Twenty skills covering discovery, specs, delivery, debugging, review, and learning |
-| `prompts/` | Manual launchers for tools that do not discover local skills |
 | `templates/` | Starting points the project copies when it needs them |
 
+On request it also writes one thing it does not copy:
+
+| Path | What it is |
+| --- | --- |
+| `.claude/skills/`, `.agents/skills/` | **Generated** — a small adapter per skill, derived from `skills/` at install time, so your coding tool discovers them natively. Not part of the five above; see [Native skills for your coding tool](#native-skills-for-your-coding-tool) |
+
 It never copies Pathfinder's own `README.md`, `CHANGELOG.md`, CI configuration, or brand assets. Your repository gets the workflow, not the project that maintains it.
 
 ## What it will not do to your repository
@@ -34,22 +39,105 @@ It never copies Pathfinder's own `README.md`, `CHANGELOG.md`, CI configuration,
 This runs once, in real code, so it is deliberately timid:
 
 - **It never overwrites.** Files that already exist are left exactly as they are and listed by name in the summary. Pass `--force` if you actually want them replaced.
-- **It refuses to run outside a Git repository**, so whatever it writes is reviewable and undoable.
-- **`--dry-run` reports the same plan the real install would carry out**, without writing anything.
+- **It will not install outside a Git repository**, so whatever it writes is reviewable and undoable. In an empty directory it offers to run `git init` for you — and that is the only Git command it will ever run. No `add`, no `commit`, no config, no branch. If you say no, nothing is written.
+- **It never touches an existing history.** A directory that is already a repository, or inside one, is never asked about and never initialized.
+- **`--dry-run` reports the same plan the real install would carry out**, including any `git init`, without writing anything.
+- **It owns a generated adapter, and nothing else in your tool's directory.** A file at `.claude/skills/<name>/SKILL.md` or `.agents/skills/<name>/SKILL.md` belongs to the installer only if that name is a Pathfinder skill *and* the file carries the `pathfinder:adapter` marker it wrote. Your `settings.json`, `settings.local.json`, agents, commands, hooks, and any skill of your own are never read and never written, a file you wrote at an adapter path is left alone and named in the summary, and nothing is ever deleted.
+
+**Re-running `npx create-pathfinder` in a project that already has Pathfinder is safe, requires no flags, and is idempotent.** Canonical files you have edited are skipped and listed; files new in this version are written; adapters are regenerated, byte-identical if nothing changed; anything you own is untouched. That is how a project installed before v1.5.0 gains adapters — one ordinary run, no migration command.
+
+## Native skills for your coding tool
+
+Pathfinder's skills are tool-neutral files at `skills/<name>/SKILL.md`. Some coding tools discover skills natively from their own directory, and the installer can generate small adapters there so you get `/reflect` instead of pasting a path.
+
+```bash
+npx create-pathfinder --agents claude-code,codex
+```
+
+| Id | Writes to | Invoked as |
+| --- | --- | --- |
+| `claude-code` | `.claude/skills/<name>/SKILL.md` | `/reflect` |
+| `codex` | `.agents/skills/<name>/SKILL.md` | `/skills`, or `$reflect` |
+
+Each adapter is a few lines long: it carries the skill's name and description, and tells the tool to read the canonical file. Both harnesses get the same bytes at a different path — the behavior lives in one place, and the adapter never restates it.
+
+Pick one, both, or neither. Choosing one never generates, removes, or claims anything under the other's directory, and Pathfinder never writes to a personal skills directory such as `$HOME/.agents/skills`.
+
+In a terminal you are asked instead of passing the flag — a numbered list, comma-separated, `Enter` for the tools found on your machine, `0` for none. Each option shows the directory it writes to before you choose it.
+
+The list has a third entry, **Something else…**, and it generates nothing. Name your tool and the summary says so plainly, because a `.mdc` file Cursor half-reads or a `SKILL.md` in a directory nothing scans would be a file your tool ignores under a summary claiming success. Two things do work for any tool: the kit installs `AGENTS.md` at the repository root, which Codex, Cursor, and several others read, and any agent can be given the line the adapters delegate to anyway — `Use skills/<name>/SKILL.md and follow it exactly.`
+
+Nothing is configured unless you choose it. Detection only sets the default, a piped or scripted run configures nothing at all unless `--agents` says so, and `--agents` accepts only the ids in the table above — an unknown one exits 2 rather than quietly installing nothing.
+
+**What the installer owns, and what it will not touch:**
+
+- **It owns a file at `<tool>/skills/<name>/SKILL.md` only if that name is a Pathfinder skill *and* the file carries the `pathfinder:adapter` marker it wrote.** Those it regenerates freely, with no flag — that is how an older install gains adapters by re-running.
+- **A file you wrote at one of those paths is left alone** and listed by name in the summary. `--force` replaces it; nothing else does.
+- **Everything else under that directory is never read and never written** — your `settings.json`, `settings.local.json`, agents, commands, hooks, and any skill of your own.
+- **Nothing is ever deleted.** An adapter for a skill a newer version no longer ships is reported and left in place.
+
+Re-running is idempotent: the second run writes the same bytes and reports the adapters as already up to date.
 
-Re-running it is safe, and fills in only what is missing.
+## The Kickstart prompt, and your clipboard
+
+Every install ends by printing the one prompt that starts a session, and the prompt follows the tool you chose:
+
+| Configured | Prompt |
+| --- | --- |
+| `claude-code` | `/kickstart-pathfinder` |
+| `codex` | `$kickstart-pathfinder` |
+| both, or neither | `Use skills/kickstart-pathfinder/SKILL.md. Help me initialize this project. Do not install packages or write product code yet.` |
+
+Two harnesses fall back to the neutral form because one clipboard cannot hold two syntaxes, and picking a favorite would quietly decide which of your tools is the real one.
+
+In a terminal you are then asked whether to copy it. The question says what it replaces, because your clipboard is yours:
+
+```text
+? Copy that prompt to your clipboard? This replaces what is on it now. [Y/n]
+```
+
+- **Nothing is copied without an explicit yes.** Declining, an unanswered question, `--no-clipboard`, `--yes`, `--dry-run`, and any run without a terminal on both ends all leave your clipboard exactly as it was.
+- **The prompt is printed either way.** Copying is a convenience, never the only way to get it, which is what lets every failure be a non-event.
+- **No dependency, and no clipboard is ever read.** The copy uses whatever your system already has — `pbcopy`, `clip.exe` including under WSL, or `wl-copy`, `xclip`, or `xsel` — chosen by what is actually installed rather than by your platform's name. If none of them is there, or one of them fails, the installer says so in one line and still exits 0.
+
+## Opening the project
+
+The last question is whether to open the project, and it is only ever about an editor you already have. The installer looks for `code` (VS Code) and `cursor` (Cursor) on your `PATH`:
+
+- **One found** — a yes/no naming it: `? Open this project in VS Code? [Y/n]`
+- **Several found** — a numbered list, alphabetical, ending in `Don't open`
+- **None found** — no question at all
+
+Neither editor is a Pathfinder requirement, and the alphabetical order is not a recommendation. Nothing else can be launched: there is no way to name an editor or pass a path, because an editor the installer did not find is one it cannot honestly offer.
+
+The launch is detached — the installer hands over the project directory and exits immediately, so it never waits for your editor and never prints your editor's output as its own.
+
+- **Nothing is launched without an explicit yes.** Declining, an unanswered question, `Don't open`, `--no-open`, `--yes`, `--dry-run`, and any run without a terminal on both ends all leave your screen alone.
+- **A failed launch is not a failed install.** If the binary is there but cannot be run, the installer says so in one line, tells you the directory to open yourself, and still exits 0. The install already succeeded; opening it was a convenience.
 
 ## Options
 
 | Option | Effect |
 | --- | --- |
-| `--dry-run` | Report what would be written; change nothing |
-| `--force` | Overwrite files that already exist |
+| `--agents <ids>` | Generate skill adapters for these tools, comma-separated. Valid ids: `claude-code`, `codex`. Alias: `--agent` |
+| `--dry-run` | Report what would be written, and any `git init` that would run first; change nothing |
+| `--force` | Overwrite files that already exist, and replace a file you wrote at a path an adapter would occupy |
+| `--git-init` | Run `git init` here if this is not a repository yet |
+| `--no-git-init` | Never run `git init`; refuse instead |
+| `--no-clipboard` | Never offer to copy the Kickstart prompt. The prompt is printed either way |
+| `--no-open` | Never offer to open the project in an editor |
+| `--yes`, `--no-input` | Take the defaults and ask nothing. It does not authorize `git init`, configure any tool, touch your clipboard, or open an editor — pass `--git-init` and `--agents` for the first two |
 | `-h`, `--help` | Show usage |
 
+Questions are asked only when stdin and stdout are both terminals. Piped, redirected, or in CI, nothing is asked and nothing is prompted for — so a directory that is not a repository needs `--git-init`, or the install is refused, no tool is configured without `--agents`, the clipboard is never touched at all, and no editor is ever launched.
+
 ## Requirements
 
-Node 18 or newer, and a Git repository. No dependencies — this package installs nothing into your project's `node_modules`, and has none of its own.
+Node 18 or newer, and a Git repository — though the installer will offer to create one for you.
+
+The `git` binary is only needed to *create* that repository. Inside one that already exists, the installer finds it by walking the filesystem for `.git` and never runs Git at all, so it works on a machine where `git` is not on your `PATH`.
+
+No dependencies — this package installs nothing into your project's `node_modules`, and has none of its own.
 
 ## Links
 

package/bin/create-pathfinder.mjs

@@ -1,8 +1,36 @@
 #!/usr/bin/env node
 import { run } from "../src/cli.mjs";
+import { createPrompter } from "../src/prompt.mjs";
 
-process.exitCode = run(process.argv.slice(2), {
-  cwd: process.cwd(),
-  out: (text) => process.stdout.write(text),
-  err: (text) => process.stderr.write(text),
+// Everything the CLI learns about the outside world arrives through this call.
+// `run` reads no globals of its own, so a test can hand it a synthesized
+// environment — a Windows PATH, an absent $HOME, a terminal that is not one —
+// without touching the process it runs in.
+//
+// The TTY guard is decided here, once, and both ends must be terminals: a
+// question needs somewhere to be printed *and* someone able to answer it.
+// `create-pathfinder < /dev/null` in a terminal is not interactive, and neither
+// is a run whose stdout is a pipe.
+const interactive = Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+
+const prompter = createPrompter({
+  input: process.stdin,
+  output: process.stdout,
+  interactive,
 });
+
+try {
+  process.exitCode = await run(process.argv.slice(2), {
+    cwd: process.cwd(),
+    out: (text) => process.stdout.write(text),
+    err: (text) => process.stderr.write(text),
+    env: process.env,
+    platform: process.platform,
+    stdoutIsTTY: Boolean(process.stdout.isTTY),
+    prompter,
+  });
+} finally {
+  // An open reader holds stdin open, and a process with an open stdin does not
+  // exit. Closed on every path, including the ones that refused.
+  prompter.close();
+}

package/context/coding-standards.md

@@ -53,6 +53,25 @@ Choose tests by behavior and risk:
 
 Avoid tests that only reproduce implementation detail.
 
+## Verification Evidence
+
+These apply to any claim that something works — a test, a manual check, or a
+verification step in a feature's acceptance criteria.
+
+- **Exercise the artifact a user receives, the way a user exercises it.** A
+  hand-written sample of generated output, a local imitation of an external
+  system, or the working tree in place of the built and published thing is
+  evidence about the stand-in, not about the artifact. Prefer one check against
+  the real artifact over several against convenient substitutes.
+- **When a mechanism can fail by doing nothing, observe that the right thing
+  happened.** A clean exit says the command ran. It does not say the effect
+  occurred, and a step that silently does nothing usually reports success.
+- **Beware a check whose every input it supplied itself.** If the test chose the
+  fixtures, the environment, and the trigger, it has confirmed its own
+  assumptions. Name which inputs came from the real system.
+- State what was verified and what was only reasoned about. An unobserved
+  criterion is recorded as unobserved, not as passed.
+
 ## Dependencies
 
 Before adding one, assess necessity, maintenance, security, runtime cost, licensing, portability, and simpler alternatives. Follow the approval policy in `context/ai-interaction.md`.

package/context/project-overview.md

@@ -12,11 +12,23 @@
 
 ## Decision States
 
+These four words describe a decision:
+
 - `TBD` — human decision required
 - `None` — intentionally excluded
 - `N/A` — not applicable
 - `Deferred` — intentionally postponed
 
+## Record Status
+
+A `Status` column describes the record, not the decision:
+
+- `proposed` — written down, not yet approved by the human
+- `accepted` — approved by the human
+- `superseded` — replaced by a later decision, kept for history
+
+The two answer different questions. `TBD` says nobody has decided yet. `proposed` says something was recorded for the human to approve. A recorded proposal is not an approved decision.
+
 ## Product Vision
 
 - Problem:
@@ -56,9 +68,9 @@ starting state -> action/process -> useful result -> reason to return or continu
 
 ## Recommended and Approved Technology
 
-Recommendations may be proposed by `debate-me`; approved choices belong here.
+Recommended and approved choices both live here. `debate-me` and `kickstart-pathfinder` may record a choice before the human approves it; that row is marked `proposed` in `Status` and stays that way until it is `accepted`. Leave `Status` empty while the choice is still `TBD`.
 
-| Layer | Approved choice | Reason | Status |
+| Layer | Choice | Reason | Status |
 | --- | --- | --- | --- |
 | Platform/runtime | `TBD` | | |
 | Language(s) | `TBD` | | |

package/copy-list.json

@@ -4,7 +4,6 @@
     "AGENTS.md",
     "CLAUDE.md",
     "context",
-    "prompts",
     "skills",
     "templates"
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pathfinder",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "description": "Install the Pathfinder AI-assisted, human-in-the-loop workflow kit into a Git repository.",
   "keywords": [
     "pathfinder",
@@ -34,11 +34,11 @@
     "AGENTS.md",
     "CLAUDE.md",
     "context",
-    "prompts",
     "skills",
     "templates"
   ],
   "scripts": {
+    "test": "node --test",
     "stage": "node scripts/stage-kit.mjs",
     "unstage": "node scripts/stage-kit.mjs --clean",
     "prepack": "node scripts/stage-kit.mjs",

package/skills/complete-feature/SKILL.md

@@ -8,8 +8,8 @@ description: Close an accepted feature through final verification, records, deli
 1. Confirm review findings are resolved or explicitly accepted.
 2. Run final project-appropriate verification.
 3. Confirm each acceptance criterion with evidence.
-4. Follow the approved commit, PR, merge, changelog, versioning, release, and deployment policy—requesting approval where required.
-5. Append the durable outcome to `context/history.md`.
+4. Follow the approved commit, PR, merge, changelog, versioning, release, and deployment policy—requesting approval where required. After the merge, verify the merged mainline and clean up the merged branch as that policy requires.
+5. Append the durable outcome to `context/history.md` while completing the feature, not afterwards. If the feature was merged without this skill running, still write the entry and record that it was written after the fact.
 6. Mark/reset `context/current-feature.md` and identify the next action.
 7. Offer or invoke `learn-feature` when learning is enabled.
 8. Produce a compact completion summary.