create-pathfinder 1.6.0 → 1.8.0

package/CLAUDE.md

@@ -76,3 +76,5 @@ An adapter carries the canonical skill's frontmatter and a pointer to it, and no
 - `reflect` — review completed work, and the reflection itself, and propose reusable workflow improvements for human approval
 - `handoff` — preserve useful state between sessions or tools
 - `skillsmith` — teach and create small local skills
+- `setup-tracker` — configure an optional external work tracker
+- `sync-tracker` — publish approved feature specs to the configured tracker, one-way and idempotently

package/README.md

@@ -27,7 +27,7 @@ The installer copies five things into your repository and nothing else:
 | --- | --- |
 | `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 |
+| `skills/` | Skills covering discovery, specs, delivery, debugging, review, learning, and optional work tracking |
 | `templates/` | Starting points the project copies when it needs them |
 
 On request it also writes one thing it does not copy:
@@ -84,9 +84,17 @@ Every install ends by printing the one prompt that starts a session, and the pro
 In a terminal you are then asked whether to copy it, in a question that says what it replaces:
 
 ```text
-? Copy that prompt to your clipboard? This replaces what is on it now. [Y/n]
+? Copy that prompt to your clipboard? This replaces what is on it now.
+
+❯ Yes
+  No
+
+  ↑↓ move   enter confirm
 ```
 
+`y` and `n` still answer it in one keystroke, and under
+`PATHFINDER_PROMPT=classic` it asks as `[Y/n]` on one line.
+
 - **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.
 - **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.
@@ -95,8 +103,8 @@ In a terminal you are then asked whether to copy it, in a question that says wha
 
 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`
+- **One found** — a Yes/No naming it: `? Open this project in VS Code?`
+- **Several found** — a 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. There is no way to name an editor or pass a path. The launch is detached: the installer hands over the project directory and exits immediately.
@@ -118,6 +126,15 @@ Neither editor is a Pathfinder requirement, and the alphabetical order is not a
 | `--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 |
 
+### Environment
+
+| Variable | Effect |
+| --- | --- |
+| `PATHFINDER_PROMPT=classic` | Ask every question as a numbered list and `y`/`n` rather than an arrow-key selector |
+| `NO_COLOR` | Print no colour. It does not disable the selector |
+
+**Both prompt styles are supported.** By default a terminal answers questions with `↑`/`↓`, `Space`, and `Enter`. `PATHFINDER_PROMPT=classic` asks for typed numbers and `y`/`n` instead — the right choice for a screen reader, for a script driving the installer's stdin, and for anyone who simply prefers it. A terminal narrower than 49 columns and `TERM=dumb` select it on their own, and `y`/`n` keep working at a Yes/No question either way.
+
 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

package/bin/create-pathfinder.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { run } from "../src/cli.mjs";
 import { createPrompter } from "../src/prompt.mjs";
+import { createTheme } from "../src/theme.mjs";
 
 // 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
@@ -13,10 +14,30 @@ import { createPrompter } from "../src/prompt.mjs";
 // is a run whose stdout is a pipe.
 const interactive = Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
 
+// One theme for the whole run, built here because this is the only file allowed
+// to read the process, and threaded into both consumers rather than built twice.
+// Two themes over the same terminal would be two opinions about it, and they
+// would differ in exactly the value that decides how a question is asked: `run`
+// is handed no stdin, so a theme it built for itself would answer no to
+// `selection` while the prompter's answered yes.
+//
+// Note what the capability is told about stdin and what it is not. Whether
+// `setRawMode` exists is asked of the stream; it is never called, here or
+// anywhere in this package — readline owns raw mode for the whole run.
+const theme = createTheme({
+  env: process.env,
+  platform: process.platform,
+  isTTY: Boolean(process.stdout.isTTY),
+  inputIsTTY: Boolean(process.stdin.isTTY),
+  setRawMode: typeof process.stdin.setRawMode === "function",
+  columns: process.stdout.columns,
+});
+
 const prompter = createPrompter({
   input: process.stdin,
   output: process.stdout,
   interactive,
+  theme,
 });
 
 try {
@@ -27,6 +48,7 @@ try {
     env: process.env,
     platform: process.platform,
     stdoutIsTTY: Boolean(process.stdout.isTTY),
+    theme,
     prompter,
   });
 } finally {

package/context/ai-interaction.md

@@ -20,6 +20,7 @@ Follow the project's documented policy. Unless explicitly pre-approved, ask befo
 - Git history rewriting
 - commits, merges, releases, or deployments
 - adopting prototype code into production
+- writes that leave this repository, such as creating or editing items on a shared work tracker — writing files inside the repository is an ordinary file edit and is not covered
 
 ## Git and Delivery
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pathfinder",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Install the Pathfinder AI-assisted, human-in-the-loop workflow kit into a Git repository.",
   "keywords": [
     "pathfinder",

package/skills/complete-feature/SKILL.md

@@ -11,7 +11,8 @@ description: Close an accepted feature through final verification, records, deli
 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.
+7. If `context/tracker.md` exists, reconcile this feature's tracked item with `sync-tracker` after the merge.
+8. Offer or invoke `learn-feature` when learning is enabled.
+9. Produce a compact completion summary.
 
 Do not claim completion when checks failed, evidence is missing, or the feature remains unaccepted.

package/skills/load-feature/SKILL.md

@@ -12,6 +12,7 @@ description: Prepare one feature for implementation by checking readiness, conte
 5. Assess whether the feature fits a focused LLM context window.
 6. Split or revise it before implementation if the context is too broad.
 7. Populate `context/current-feature.md` with the feature, first delivery chunk, context boundary, assumptions, Git state, definition of done, and out-of-scope work.
-8. Present a short readiness summary.
+8. If `context/tracker.md` exists, note this feature's tracked item, or that it has none yet. The lookup is best-effort: an unreachable tracker is reported and never blocks loading.
+9. Present a short readiness summary.
 
 Do not implement, create Git history, or resolve `TBD` decisions silently.

package/skills/setup-tracker/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: setup-tracker
+description: Configure an optional external work tracker by interviewing the human and writing context/tracker.md from the shipped template.
+---
+
+# Setup Tracker
+
+Use this skill to describe, in prose, which tracker a project uses and how
+Pathfinder's work items project onto it. The result is `context/tracker.md`.
+
+Work Tracking is **optional**. A project that never runs this skill is
+unaffected: no file, no prompt, no behaviour change anywhere. Do not run this
+skill unasked, and do not propose it as a missing step.
+
+This skill configures. It never contacts a tracker.
+
+## Rules
+
+- Do not write `context/tracker.md` without human approval.
+- Do not add code, dependencies, or an adapter for any tracker.
+- Do not invent a taxonomy the team did not ask for.
+- Keep the model section backend-neutral; vendor vocabulary belongs only under
+  the projection heading.
+- Never remove the work-item marker block. It is the one machine-stable token in
+  a prose contract, and identity depends on it.
+
+## Interview
+
+Ask progressively, in small groups. Ask only what the config cannot be written
+without:
+
+1. Which tracker, and where it lives.
+2. How an agent reaches it — a CLI, a path, or a described manual step.
+3. Which tag namespaces the project actually uses. `area`, `type`, `priority`,
+   and `agent` are available; a project needing none of them says so.
+4. What the tracker already carries. **List its existing labels, fields, or
+   conventions before proposing any tag value.** If something already means the
+   same thing, reuse it and record the mapping rather than creating a
+   near-duplicate.
+5. Anything about the projection that the shipped starting points do not cover.
+
+## Process
+
+1. Check whether `context/tracker.md` already exists. If it does, read it, and
+   treat this run as a revision — show what would change and change nothing
+   else. Never overwrite a working config wholesale.
+2. Read `templates/tracker.template.md`.
+3. Run the interview.
+4. Choose the projection:
+   - **GitHub Issues via `gh`** and **local Markdown files** ship as starting
+     points, both proven.
+   - Any other tracker is supported by the human describing it in prose, using a
+     shipped projection as the shape to follow. **That is the mechanism, not a
+     gap** — do not report an unsupported tracker as a blocker.
+5. Fill the placeholders and keep **one** projection block. Delete, in the
+   written config:
+   - the template's guidance blockquote at the top;
+   - the projection block you did not keep;
+   - the `pathfinder:model-start` and `pathfinder:projection-boundary` markers;
+   - the italic *"Keep this block for…"* line under the projection you kept — it
+     is an instruction to you, not content for the project to read.
+
+   **The model — everything between the two markers — is kept byte-for-byte.**
+   The tracker-identity paragraph above it is the one part you rewrite, because
+   it names the tracker and how to reach it.
+6. Present the proposed file and request approval.
+7. Write `context/tracker.md` only after the human approves.
+8. Report what was configured, and say plainly that nothing has been published.
+
+## Stop Condition
+
+Stop once the config is written. Publishing to a tracker is `sync-tracker`, not
+this skill. If `sync-tracker` is not installed, say so rather than publishing by
+hand.

package/skills/start-feature/SKILL.md

@@ -23,3 +23,4 @@ Restate goal, chunk, files/areas, context, risks, assumptions, verification, exc
 - Stop on conflicts between spec, durable context, and repository reality.
 - Do not add dependencies, expand scope, adopt prototype code, commit, merge, or deploy without the documented approval.
 - Do not hide multiple features inside one delivery chunk.
+- Do not publish to a work tracker, even when `context/tracker.md` exists — the repository is canonical and a chunk boundary is not a tracker event.

package/skills/sync-tracker/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: sync-tracker
+description: Publish approved feature specs to the configured work tracker, one-way and idempotently, writing nothing when nothing has changed.
+---
+
+# Sync Tracker
+
+Use this skill to project the project's approved feature specs onto the tracker
+described in `context/tracker.md`.
+
+The repository is canonical. This is a **one-way projection** of work that
+already exists. Nothing here reads tracker state back into a spec,
+`context/current-feature.md`, or `context/history.md`.
+
+## The off switch comes first
+
+**If `context/tracker.md` does not exist, do nothing at all.** Report that work
+tracking is not configured for this project, and stop.
+
+Do not create the config, do not propose configuring one, and do not describe
+its absence as a gap. Work Tracking is optional, and a project without it is
+behaving correctly.
+
+## The config is the contract
+
+Read `context/tracker.md` in full and follow its prose. It states the model, the
+projection, and the publishing rules for this project.
+
+There is **no adapter code, no vendor branch, and no required tool** beyond what
+the config itself names. If the config describes a tracker this skill has never
+heard of, that is the design working, not a blocker.
+
+Where the config is silent on something a run needs, **ask the human**. Do not
+fill the gap with a convention of your own — the next run would fill it
+differently, and every item would look modified.
+
+## What gets published
+
+**Approved feature specs only**, from `to-specs` onward — one work item per spec.
+Never debate notes, kickstart output, or prototypes. The one exception is a
+prototype that gates a decision, published as a single item phrased as the
+decision it resolves, never as a deliverable.
+
+**Do not decompose a feature.** Choosing units of execution inside a feature is a
+judgement about how work will be shared out, and it belongs to a human or to a
+skill written for it. Publish the feature.
+
+## Process
+
+1. Check for `context/tracker.md`. If it is absent, report and stop.
+2. Read the config. Read the approved specs. Read nothing else.
+3. Build the work items: key, kind, title, body, blocked-by edges, tags, and
+   chunks, derived and composed exactly as the config's model section says. Every
+   field comes from the spec — **tags only from its optional `## Tags` section,
+   never inferred.** A spec without one has no tags, which is correct and common.
+4. Order them by dependency, blockers first. If the edges contain a cycle,
+   report it and publish nothing — a guessed order is a wrong order that looks
+   fine.
+5. **Ask the human before the first write that leaves this repository.** See
+   below.
+6. Publish, following the config's *Publishing, and re-publishing* section
+   exactly: index existing items by key, create what is missing, compare
+   normalized, and leave an unchanged item completely alone.
+7. Report what was created, what was edited, and what was left alone.
+
+## The approval gate
+
+**Ask before the first write to a tracker outside this repository in a session.**
+Creating items on a shared board is outward-facing and is not covered by ordinary
+file-edit approval. One approval covers the run; do not ask per item.
+
+**A projection onto files inside this repository is not gated.** It is an
+ordinary file edit and reaches nothing outside the repository. The gate is about
+leaving the repository, not about writing.
+
+## Idempotency is the whole feature
+
+A second run over unchanged specs must **create nothing, change nothing, and
+issue zero writes**. Not writes that happen to be no-ops — no writes.
+
+- **Compare normalized, never raw bytes.** A tracker is not obliged to hand a
+  body back exactly as it was sent, and APIs differ in whether they adjust
+  trailing whitespace. Where that happens, a naive byte comparison reports every
+  item as changed on every run and rewrites all of them forever, which looks like
+  working sync and is not. Strip trailing whitespace from each line and collapse
+  trailing blank lines at the end, **on both sides**, before comparing. It costs
+  nothing when the round-trip is exact.
+- **Compare tag sets as sets**, not as ordered lists. Application order is not
+  preserved.
+- Never close, reopen, delete, or recreate an item. Edit in place.
+- Never touch an item whose key is absent from the current set. It belongs to
+  work outside this run.
+- Match on the key alone, never on the title.
+
+**Report writes, not final state.** "The tracker looks right" is satisfied by a
+run that rewrote every item, which is the specific failure this skill exists to
+avoid. `3 items, 0 changes` is the expected result of a second run and the most
+important line of output.
+
+## Rules
+
+- Do not add code, dependencies, or an adapter for any tracker.
+- Do not branch on `kind`.
+- Do not infer tags, and do not apply a value the config's mapping table does not
+  carry. A spec naming an unmapped tag is a question for the human, not a
+  judgement call.
+- Do not drop an edge that resolves outside the published set, and do not invent
+  an item for it. Resolve it against the tracker as a whole: render the item's
+  identifier if the key already has one, and name the key as untracked only when
+  it genuinely has none.
+- Do not read anything back. A ticked checkbox means nothing to Pathfinder and
+  never advances any state.
+- Do not close, reopen, or delete anything, ever.
+- Stop and report when the config, the specs, and the tracker disagree.
+
+## Stop Condition
+
+Stop once the run is reported. Configuring a tracker is `setup-tracker`, not this
+skill. If a spec set is not ready to publish, say so rather than publishing part
+of it.

package/skills/to-specs/SKILL.md

@@ -36,8 +36,12 @@ Create only the coherent MVP roadmap in `context/features/`, using `templates/fe
 
 Each spec must include Context Boundary, Delivery Chunks, and Learning Targets.
 
+Write a `## Tags` section only when the project has configured work tracking and its `context/tracker.md` defines tag namespaces. Use the values that config already lists, never invented ones. No tags is a valid and common answer — omit the section rather than guessing.
+
 After creation, summarize file, outcome, dependency, visible/verifiable win, context risk, and recommended first feature.
 
+If `context/tracker.md` exists, offer to publish the new specs with `sync-tracker`. If it does not, say nothing about tracking.
+
 ## Rules
 
 - Do not implement or install packages.