create-pathfinder 1.7.0 → 2.0.0

package/skills/learning-review/SKILL.md

@@ -12,11 +12,12 @@ The goal is to turn isolated feature lessons into a coherent learning path.
 
 ## Read First
 
-1. `context/learning/learner-profile.md`
-2. `context/learning/progress.md`
-3. Recent lessons under `context/learning/lessons/`
-4. Recent completed feature specs and history
-5. Quiz or challenge evidence available in the repo
+1. `context/learning/progress.md`
+2. Recent lessons under `context/learning/lessons/`
+3. Recent completed feature specs and history
+4. Quiz or challenge evidence available in the repo
+
+Skip any of these that does not exist. Pathfinder creates these files only when a workflow first needs them, so their absence is normal and is not an error. Do not create them just to satisfy this list.
 
 ## Review Modes
 
@@ -66,7 +67,9 @@ At most three, ordered by value.
 
 ## Progress Changes
 
-Update `context/learning/progress.md` conservatively.
+Update `context/learning/progress.md` conservatively, using the confidence scale
+defined in its `## Confidence Scale` section. If the file does not exist,
+`quiz-me` carries the header to create it with.
 
 ## Rules
 

package/skills/load-feature/SKILL.md

@@ -1,17 +1,28 @@
 ---
 name: load-feature
-description: Prepare one feature for implementation by checking readiness, context size, dependencies, and delivery chunks.
+description: Load one approved Feature and the minimum context needed to work on it.
 ---
 
 # Load Feature
 
-1. Select the requested or next approved feature spec.
-2. Read its dependencies and the smallest relevant durable context.
-3. Check repository reality without scanning unrelated areas.
-4. Identify contradictions, missing decisions, stale paths, and prototype dependencies.
-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.
+1. Select the requested approved Feature. Its spec is
+   `NN-feature-name.md` in the spec source, and `NN` is its Feature number.
+2. Read the Feature spec.
+3. Read only the files or context needed for the current work.
+4. Inspect the current Git state.
+5. Stop if a required human decision or explicit dependency blocks the work.
+6. Create or update `context/current-feature.md` — it does not ship, so the
+   first load writes it — with:
+   - Feature number, name, and spec path
+   - active delivery chunk
+   - Git state
+   - blocker, if any
+   - next action
+7. If `context/tracker.md` exists, name the tracked item for this Feature —
+   its key is that Feature number. Do nothing here if it does not.
 8. Present a short readiness summary.
 
-Do not implement, create Git history, or resolve `TBD` decisions silently.
+Do not implement the Feature.
+
+Do not scan unrelated repository areas, load history or roadmap by default,
+rewrite the Feature, or silently resolve `TBD` decisions.

package/skills/prototype/SKILL.md

@@ -16,7 +16,9 @@ Use this skill after debate recommends validation or when the human asks to see
 5. Create only the prototype; avoid production architecture unless the task is explicitly a technical proof.
 6. Present focused review questions.
 7. On feedback, revise the same direction, replace it, approve it, or stop.
-8. Record approved direction, rejected assumptions, and explicit production exclusions in `context/project-overview.md`.
+8. Record approved direction, rejected assumptions, and explicit production exclusions
+   under `## Durable Decisions` in `context/project-overview.md`, creating the file
+   from `templates/project-overview.template.md` if it does not exist yet.
 
 ## Supported Forms
 

package/skills/quiz-me/SKILL.md

@@ -12,11 +12,12 @@ The goal is retrieval and diagnosis, not entertainment and not a long exam.
 
 ## Read First
 
-1. `context/learning/learner-profile.md`
-2. The relevant lesson in `context/learning/lessons/`
-3. `context/current-feature.md`
-4. Only the implementation or tests needed to verify answers
-5. `context/learning/progress.md`
+1. The relevant lesson in `context/learning/lessons/`
+2. `context/current-feature.md`
+3. Only the implementation or tests needed to verify answers
+4. `context/learning/progress.md`
+
+Skip any of these that does not exist. Pathfinder creates these files only when a workflow first needs them, so their absence is normal and is not an error. Do not create them just to satisfy this list.
 
 ## Quiz Shape
 
@@ -67,9 +68,34 @@ Do not use a percentage unless every question had a clear scoring basis.
 
 Update `context/learning/progress.md` with demonstrated evidence.
 
-Use the confidence scale already defined there.
+The file does not ship. If it is missing, create it with this header, then add
+the entry:
+
+```markdown
+# Learning Progress
+
+Demonstrated understanding, not feature completion.
+
+## Confidence Scale
+
+- `introduced` — explained once; no evidence of recall yet
+- `practiced` — answered or applied with help
+- `independent` — applied correctly without meaningful help
+- `transferable` — applied correctly in a different context
+- `review-needed` — misunderstanding or weak recall was observed
+
+## Concepts
+
+| Concept | Confidence | Evidence | Last reviewed |
+| --- | --- | --- | --- |
+```
+
+This block is the scale's only definition. The other learning skills read it
+from the file rather than restating it.
 
-A correct answer with heavy hints is `practiced`, not `independent`.
+Record one confidence value per concept, and record uncertainty honestly. A
+correct answer with heavy hints is `practiced`, not `independent`. Passive
+reading is never `independent`.
 
 ## Scope
 

package/skills/review-feature/SKILL.md

@@ -1,25 +1,33 @@
 ---
 name: review-feature
-description: Review an implemented feature against its spec, repository standards, regressions, and project quality priorities.
+description: Verify implemented work against its Feature and report findings.
 ---
 
 # Review Feature
 
-Review the actual diff and behavior, not only a summary.
+Review the actual diff and behavior, not only the developer's summary.
 
 ## Check
 
-- acceptance criteria and missed requirements
-- regressions, logic errors, edge/failure states
-- security/privacy and data boundaries
-- accessibility, performance, compatibility, and operations when applicable
-- tests and verification quality
-- scope creep and unrelated churn
-- consistency with approved architecture and prototype direction
+- acceptance criteria
+- regressions and important edge cases
+- security/privacy when relevant
+- accessibility, performance, compatibility, and operations when relevant
+- tests and verification
+- scope creep
 - documentation accuracy
 
+Use the project's quality priorities and existing standards where relevant.
+
 ## Output
 
-List findings by severity with file/location, impact, and practical fix. Then list verification performed, residual risk, and whether it is ready to complete.
+Report:
+
+- `PASS`, or findings by severity
+- file/location and impact for each finding
+- what was actually verified
+- anything important that remains unverified
+
+Do not modify the implementation unless the human explicitly asks.
 
-Do not modify code unless the user asks for fixes. Do not manufacture findings to fill a template.
+Do not invent findings or treat passing tests as automatic acceptance.

package/skills/role/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: role
+description: Activate one named Pathfinder role for the current session.
+---
+
+# Role
+
+Activate exactly one role.
+
+The human names it, for example:
+
+`/role planner`
+`/role developer`
+`/role tester`
+
+## Process
+
+1. Take the role name from the invocation.
+   If none was given, list the available files in `roles/` and stop.
+2. Read only `roles/<name>.md`.
+   If it does not exist, say so, list the available role names, and stop.
+3. Confirm in one line and wait for work:
+
+   `Active role: <name>`
+
+## Rules
+
+- Activate only the role the human named.
+- Read only that role file.
+- Do not start the role's work.
+- Do not write project state just to remember the role.
+- The role applies only to the current session/conversation context.
+- A role narrows responsibility. It never grants human authority.

package/skills/setup-tracker/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: setup-tracker
+description: Configure optional work tracking for the project.
+---
+
+# Setup Tracker
+
+Configure a work tracker only when the human asks.
+
+Pathfinder works normally without one.
+
+## Process
+
+1. Ask where work should be tracked:
+   - GitHub Issues
+   - local Markdown files
+   - another tracker the human describes
+2. Ask only for the information needed to use that tracker.
+3. Check where the approved Feature specs live. Ask only when they are not in
+   `context/features/`; when the default is what the repository has, record it
+   and move on.
+4. Create a proposed `context/tracker.md` naming, at minimum:
+   - the tracker and how an agent reaches it
+   - the spec source
+   - how a published item records its Pathfinder key, so a later run
+     recognises the item it published last time
+5. Show it to the human.
+6. Write it only after approval.
+
+If `context/tracker.md` already exists, modify only the requested settings.
+
+## Rules
+
+- Do not publish or create work items.
+- Do not create labels, tags, or tracker conventions unless requested.
+- Do not add dependencies or tracker-specific code.
+- Feature specs remain canonical.
+- Tracking is always optional.
+
+Publishing belongs to `sync-tracker`.
+
+Stop after configuration.

package/skills/start-feature/SKILL.md

@@ -1,25 +1,29 @@
 ---
 name: start-feature
-description: Implement the active feature one stable delivery chunk at a time under the project's approved workflow.
+description: Implement the active Feature in small, stable increments.
 ---
 
 # Start Feature
 
-## Before Coding
+Implement the active delivery chunk.
 
-Restate goal, chunk, files/areas, context, risks, assumptions, verification, exclusions, Git state, and intended Git action.
-
-## Process
-
-1. Follow the project's documented Git and approval policy.
-2. Read only the active chunk's context.
-3. Implement the smallest complete change.
-4. Verify the chunk with relevant checks.
-5. Keep the project stable.
-6. Update current-feature state and move to the next chunk only when appropriate.
+1. Read only the context needed for the current work.
+2. Restate the pre-implementation summary the project's agent guide requires,
+   and wait for it to be answered where it names a human decision. Do not edit
+   any file before this step is done.
+3. Follow the Feature and existing project conventions.
+4. Make the smallest complete change.
+5. Verify the behavior you changed.
+6. Keep the repository stable.
+7. Create or update `context/current-feature.md` with the current state and next action.
 
 ## Rules
 
-- 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.
+- Stay inside the approved scope.
+- Stop if implementation requires a human decision or material scope change.
+- Do not silently add dependencies or adopt prototype code.
+- Follow the project's approval and Git rules.
+- Do not decide that your own work is accepted.
+
+When the chunk is done, report what changed, what was verified, and anything
+unresolved.

package/skills/sync-tracker/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: sync-tracker
+description: Project Feature specs onto the configured work tracker.
+---
+
+# Sync Tracker
+
+Sync project Features to the tracker configured in `context/tracker.md`.
+
+The repository is canonical.
+Tracker state never changes Pathfinder state.
+
+## Process
+
+1. If `context/tracker.md` does not exist, report that tracking is not
+   configured and stop. Do not propose configuring one.
+2. Read the tracker configuration. It names the tracker, how to reach it, the
+   spec source, and how a published item records its Pathfinder key. Stop if it
+   does not say how the key is recorded — without it a re-run cannot recognise
+   what it published last time, and would duplicate every item.
+3. Read the approved Feature specs from the spec source. A config that names
+   none means `context/features/`. If the named source does not exist, report
+   it and stop rather than falling back.
+4. Build one item per Feature: key, title, and body, composed only from the
+   spec.
+5. Show the proposed writes.
+6. Ask before the first write that leaves this repository. One approval covers
+   the run. A projection onto files inside the repository is an ordinary file
+   write and is not gated.
+7. Create or update only the items that changed.
+8. Report created, updated, and unchanged as counts of writes, not as final
+   tracker state.
+
+## Identity
+
+Each Feature has one stable key derived from the number in its spec filename.
+`to-specs` names every spec `NN-feature-name.md`, so
+`27-export-saved-searches.md` is `pathfinder:feature/27` in whichever directory
+it sits — moving specs orphans nothing.
+
+Read the number from the basename only. Never from the directory above it, the
+title inside it, or the order the specs happen to be read in.
+
+Match published items on that key alone. Titles are edited by humans.
+
+Skip a spec whose filename carries no number and report it by name. Do not
+assign one — numbering is `to-specs`' job, and inventing one here would publish
+an item that the next run cannot recognise.
+
+## Idempotency
+
+A second run over unchanged Features must issue **zero writes** — not writes
+that happen to be no-ops.
+
+- Compose the body as a pure function of the spec: fixed section order, no
+  timestamps, no counters, nothing derived from the run.
+- Compare normalized, never raw bytes. Strip trailing whitespace per line and
+  collapse trailing blank lines, on both sides. A tracker is not obliged to
+  return a body byte-for-byte, and a naive comparison then rewrites every item
+  forever while looking like working sync.
+- Where the config defines tags, compare them as sets, not ordered lists.
+- Edit in place. Never close, reopen, delete, or recreate an item.
+- Leave any item whose key is absent from this run completely alone.
+
+`3 items, 0 changes` is the expected second run and the most important line of
+output.
+
+## Rules
+
+- Do not decompose Features into tickets.
+- Do not derive dependency edges, ordering, or a graph from a spec. A Feature
+  may mention a dependency under `## Notes / Decisions` for a human to read;
+  it is prose, not structure, and this skill does not parse or orchestrate it.
+- Do not infer labels, tags, status, or other metadata.
+- Do not modify Feature specs from tracker state.
+- Do not read tracker state back into anything.
+- Do not delete tracker items automatically.
+- Do not rewrite unchanged items.
+- Local Markdown tracking is an ordinary repository/file write.
+- External trackers require human approval before writing.
+- Stop and report when the config, the specs, and the tracker disagree.

package/skills/teach-architecture/SKILL.md

@@ -13,11 +13,12 @@ The goal is to connect implementation details to system boundaries, ownership, s
 ## Read First
 
 1. `context/project-overview.md`
-2. `context/learning/learner-profile.md`
-3. Relevant completed feature specs and lessons
-4. Architecture-relevant source files only
-5. Data contracts, API boundaries, stores, routing, and deployment configuration relevant to the requested scope
-6. Existing ADRs, if present
+2. Relevant completed feature specs and lessons
+3. Architecture-relevant source files only
+4. Data contracts, API boundaries, stores, routing, and deployment configuration relevant to the requested scope
+5. Existing ADRs, if present
+
+Skip any of these that does not exist. Pathfinder creates these files only when a workflow first needs them, so their absence is normal and is not an error. Do not create them just to satisfy this list.
 
 Do not infer services or infrastructure that do not exist. Clearly distinguish current architecture from likely future architecture.
 

package/skills/teach-feature/SKILL.md

@@ -13,13 +13,14 @@ The goal is not to produce generic documentation. The goal is to help the learne
 
 Read only the smallest useful context:
 
-1. `context/learning/learner-profile.md`
-2. `context/current-feature.md`
-3. The source feature spec under `context/features/`
-4. `context/project-overview.md`
-5. The current branch, working tree status, and focused diff
-6. Tests and implementation files touched by the feature
-7. Relevant ADR, coding standard, or design-system guidance only when it materially affects the feature
+1. `context/current-feature.md`
+2. The source feature spec under `context/features/`
+3. `context/project-overview.md`
+4. The current branch, working tree status, and focused diff
+5. Tests and implementation files touched by the feature
+6. Relevant ADR, coding standard, or design-system guidance only when it materially affects the feature
+
+Skip any of these that does not exist. Pathfinder creates these files only when a workflow first needs them, so their absence is normal and is not an error. Do not create them just to satisfy this list.
 
 Do not read the entire repository by default.
 
@@ -57,7 +58,9 @@ Explain:
 
 ## Adaptation
 
-Use `context/learning/learner-profile.md`.
+Pitch the lesson at what the learner has already demonstrated, using
+`context/learning/progress.md` when it exists and what the human tells you when
+it does not. Ask rather than assume.
 
 For an experienced engineer:
 

package/skills/to-specs/SKILL.md

@@ -1,45 +1,61 @@
 ---
 name: to-specs
-description: Convert approved project context into small sequential feature specs optimized for focused LLM context and reliable delivery.
+description: Turn approved direction into small, clear Feature specs.
 ---
 
 # To Specs
 
-## Readiness Check
+Turn approved direction into the minimum Feature specs needed to implement it.
 
-Confirm:
+## Process
 
-- MVP and first useful flow are defined
-- critical stack and workflow choices are approved or deliberately deferred
-- required prototype direction is approved
-- known verification methods exist or are explicitly deferred
-- no material context contradictions remain
+1. Read the approved project context and relevant existing Features.
+2. Stop if a required human decision is still `TBD`.
+3. Decide whether the work is one Feature or needs a small number of Features.
+4. Create `context/features/` if it does not exist.
+5. Create each Feature from `templates/feature-spec.template.md`, named
+   `NN-feature-name.md` — see Naming below.
+6. Fill only information that materially helps implementation and review.
+7. Present the created Features and recommend which one to start first.
+8. If `context/tracker.md` exists, offer to publish them with `sync-tracker`.
+   Do nothing here if it does not.
 
-If not ready, report the blockers instead of inventing decisions.
+## Naming
 
-## Sizing Principles
+A Feature spec is named `NN-feature-name.md` in the spec source, for example
+`context/features/27-export-saved-searches.md`.
 
-Each feature should:
+`NN` is the Feature number: the next unused number in the spec source, counting
+every spec already there whatever its status. Numbers are never reused and never
+renumbered, because a published tracker item is matched on that number and
+renumbering would orphan it.
 
-- create one visible or system-verifiable outcome
-- fit one focused branch/change set under the project's workflow
-- be independently reviewable and verifiable
-- require a coherent, bounded set of context
-- state dependencies, assumptions, and exclusions
-- contain stable delivery chunks
+The number lives in the filename and nowhere else. The Feature template carries
+no number field, and nothing else in the spec records one.
 
-Split a feature when it mixes several systems, requires a repo-wide mental model, combines infrastructure with unrelated UX/polish, or cannot be verified independently.
+## Sizing
 
-## Output
+Prefer one Feature when the work is coherent.
 
-Create only the coherent MVP roadmap in `context/features/`, using `templates/feature-spec.template.md` and project-selected naming/delivery policies.
+Split only when separate outcomes:
 
-Each spec must include Context Boundary, Delivery Chunks, and Learning Targets.
+- can be implemented or reviewed independently
+- depend on meaningfully different context
+- have a real dependency between them
+- would make one Feature unnecessarily difficult to understand
 
-After creation, summarize file, outcome, dependency, visible/verifiable win, context risk, and recommended first feature.
+Prefer fewer Features and fewer artifacts.
+
+Use delivery chunks inside a Feature before creating additional Features.
 
 ## Rules
 
-- Do not implement or install packages.
-- Do not assume UI, mobile, a framework, a branch type, or conventional commits.
-- Do not plan the entire dream product.
+- Do not implement.
+- Do not invent unresolved decisions.
+- Do not plan beyond the approved direction.
+- Do not add workflow metadata that the Feature template does not require.
+- Do not create tickets, tracker items, or extra planning files by default.
+- Do not scan unrelated repository areas.
+
+When implementation details are unclear, inspect only enough source code to
+write an accurate Feature.

package/skills/whereami/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: whereami
+description: Report a compact read-only snapshot of the current Pathfinder work session.
+---
+
+# Where Am I
+
+Answer one question: what is this session working on right now?
+
+Use it when a session resumes, after a long gap, or before deciding the next
+action. It reports state. It never changes it.
+
+## Process
+
+1. Role: report the role activated in this session via `/role`.
+   Roles are session state and are never written to disk, so if no role was
+   activated in this conversation, report `none`. Do not search `roles/`.
+2. Read `context/current-feature.md` if it exists.
+   Take Feature, Active chunk, and Next from it verbatim. The Feature number is
+   the `NN` recorded there, from its spec filename.
+   If the file is missing or still holds template placeholders, report `none`.
+3. Run `git status --short --branch` once.
+   Report the branch/ref, and `clean` or the count of changed paths.
+4. Compare the Git section of `context/current-feature.md` with step 3.
+   Report a drift line only if the recorded branch differs from the real one.
+5. Context telemetry: report it only if this harness exposes it.
+   Otherwise `unavailable`. Do not estimate.
+
+## Output
+
+Exactly this shape, one line each:
+
+```
+Role:    <role | none>
+Feature: <## — name | none>
+Chunk:   <number and name | none>
+Git:     <branch/ref> — <clean | N changed>
+Context: <telemetry | unavailable>
+Next:    <single next action | none>
+```
+
+Add at most one line after it, and only when step 4 found drift:
+
+```
+Drift:   current-feature.md records <branch>, working tree is on <branch>
+```
+
+Then stop.
+
+## Rules
+
+- Read only. No writes, no commits, no `git` command that mutates anything.
+- Read at most one file: `context/current-feature.md`.
+- Do not open the feature spec, history, roadmap, `.features/`, or source.
+- Report `none` or `unavailable` instead of inferring a missing value.
+- Do not offer to fix drift, update state, or start the next action.
+  The human decides what happens after the snapshot.
+
+## Example
+
+`/whereami` after resuming mid-feature:
+
+```
+Role:    developer
+Feature: 12 — export saved searches
+Chunk:   2 — CSV writer
+Git:     feature/12-export-saved-searches — 3 changed
+Context: unavailable
+Next:    Verify the CSV writer against the acceptance criteria
+```
+
+## Anti-example
+
+Do not do this:
+
+```
+Role:    developer (inferred from recent commits)
+Feature: 12 — export saved searches
+Chunk:   3 — probably the download endpoint
+Git:     feature/12-export-saved-searches — 3 changed
+Context: ~60% used
+Next:    I can update current-feature.md and start chunk 3 — want me to?
+```
+
+It guesses the role from history, invents a chunk the spec never named,
+estimates telemetry it cannot see, and turns a status report into a proposal
+to write state.

package/src/cli.mjs

@@ -205,7 +205,8 @@ export async function run(
   // as it goes.
   //
   // Planning adapters this early is safe, and specifically because of what the
-  // copy list contains: AGENTS.md, CLAUDE.md, context, skills, and templates.
+  // copy list contains: AGENTS.md, CLAUDE.md, context, roles, skills, and
+  // templates.
   // No entry writes into `.claude/` or `.agents/`, so the copy cannot change
   // the answer `planAdapters` gives about an adapter path, and the canonical
   // skills it reads come from the kit rather than from the destination. If a

package/src/detect.mjs

@@ -119,7 +119,7 @@ function detectTool(tool, { cwd, home, env, platform }) {
  * Decided by counting skill directories rather than by testing for `CLAUDE.md`,
  * which any agent-assisted project may have written for its own reasons.
  * A `skills/<name>/SKILL.md` is a far more specific signature, and the count is
- * worth having on its own — it is what makes "already installed (20 skills)"
+ * worth having on its own — it is what makes "already installed (N skills)"
  * checkable by the person reading it.
  */
 function detectPathfinder(cwd) {