create-pathfinder 1.8.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,18 +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.
-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.
+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

@@ -1,74 +1,42 @@
 ---
 name: setup-tracker
-description: Configure an optional external work tracker by interviewing the human and writing context/tracker.md from the shipped template.
+description: Configure optional work tracking for the project.
 ---
 
 # 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`.
+Configure a work tracker only when the human asks.
 
-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.
+Pathfinder works normally without one.
 
 ## 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.
+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
 
-   **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.
+- 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.
 
-## Stop Condition
+Publishing belongs to `sync-tracker`.
 
-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.
+Stop after configuration.

package/skills/start-feature/SKILL.md

@@ -1,26 +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.
-- 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.
+- 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

@@ -1,120 +1,81 @@
 ---
 name: sync-tracker
-description: Publish approved feature specs to the configured work tracker, one-way and idempotently, writing nothing when nothing has changed.
+description: Project Feature specs onto the configured work tracker.
 ---
 
 # Sync Tracker
 
-Use this skill to project the project's approved feature specs onto the tracker
-described in `context/tracker.md`.
+Sync project Features to the tracker configured 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.
+The repository is canonical.
+Tracker state never changes Pathfinder state.
 
 ## 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.
+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 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.
+- 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.
-
-## 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/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: