create-pathfinder 1.8.0 → 2.0.0

package/skills/to-specs/SKILL.md

@@ -1,49 +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
 
-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.
+Prefer fewer Features and fewer artifacts.
 
-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.
+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/install.mjs

@@ -16,7 +16,7 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";
 
-import { COPY_LIST, isExcluded } from "./kit.mjs";
+import { COPY_LIST, isExcluded, neverShips } from "./kit.mjs";
 import {
   ADAPTER_STATE,
   adapterPath,
@@ -43,6 +43,10 @@ export function planInstall(kitRoot, targetRoot, { force = false } = {}) {
   for (const entry of COPY_LIST) {
     for (const source of walkFiles(join(kitRoot, entry))) {
       const relativePath = relative(kitRoot, source).split(sep).join("/");
+      // Filtered here rather than in walkFiles, which sees basenames only and
+      // would have to guess whether a `tracker.md` is *the* one.
+      if (neverShips(relativePath)) continue;
+
       const destination = join(targetRoot, relativePath);
       const exists = existsSync(destination);
 

package/src/kit.mjs

@@ -8,7 +8,7 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -49,6 +49,75 @@ export function isExcluded(basename) {
   return EXCLUDED.has(basename) || basename.startsWith("._");
 }
 
+/**
+ * Kit files that are deliberately not part of the kit, by kit-relative path.
+ *
+ * A different idea from EXCLUDED above, and kept separate for that reason.
+ * Those are OS and editor droppings that were never anybody's file. These are
+ * real, hand-written files that live inside a copy-list directory and must
+ * still never reach a destination project.
+ *
+ * All three are this repository's own working state, and every one of them
+ * would be actively wrong in somebody else's project.
+ *
+ * `context/tracker.md` is the original case. Work Tracking's off switch is the
+ * *absence* of that file in a destination project, so shipping this
+ * repository's own copy would hand every new project a configuration naming a
+ * tracker it does not own, pointing at a spec directory it does not have, with
+ * the off switch already defeated on first install.
+ *
+ * `context/current-feature.md` and `context/handoff.md` are transient session
+ * state, and they are here for the same reason one step further on: the kit
+ * stopped shipping a blank `current-feature.md` stencil, because `load-feature`
+ * writes the real one on first use and a placeholder is just a file a reader
+ * has to recognise as empty. Having stopped shipping the blank one, the thing
+ * to guard against is shipping a *filled-in* one — a destination project
+ * opening its first session to a note about whichever feature a Pathfinder
+ * maintainer had loaded on the day of the release.
+ *
+ * `context` is a *directory* entry in the copy list, so anything placed beneath
+ * it ships by default. Making the invariant enforced rather than intended is
+ * the same move `check_no_junk_tracked` made: an ignore rule is advisory, one
+ * `git add -f` defeats it, and `stage-kit.mjs` copies from the working tree
+ * without consulting it at all.
+ *
+ * Matched on the kit-relative path, never the basename — a project's own
+ * `tracker.md` somewhere else is not this file and must not be caught by it.
+ */
+const NEVER_SHIPS = new Set([
+  "context/tracker.md",
+  "context/current-feature.md",
+  "context/handoff.md",
+]);
+
+/**
+ * Is this kit-relative path one the kit must never hand over?
+ *
+ * @param {string} relativePath forward-slashed, relative to the kit root
+ */
+export function neverShips(relativePath) {
+  return NEVER_SHIPS.has(relativePath);
+}
+
+/**
+ * A `cpSync` filter that drops never-ships files from a recursive copy.
+ *
+ * Lives here rather than inline in `stage-kit.mjs` so the staging path and its
+ * test run the same code. A test that rebuilds the predicate proves only that
+ * `cpSync` honours `filter`; it cannot catch the path arithmetic below going
+ * wrong, which is the part with anything to get wrong in it.
+ *
+ * `cpSync` hands the filter absolute paths and calls it for the copy root
+ * itself, so the root resolves to `""` and is kept — filtering a directory out
+ * would take its whole subtree with it.
+ *
+ * @param {string} rootDir absolute path the kit-relative paths are relative to
+ * @returns {(source: string) => boolean} true to copy, false to skip
+ */
+export function neverShipsFilter(rootDir) {
+  return (source) => !neverShips(relative(rootDir, source).split(sep).join("/"));
+}
+
 const PACKAGE_ROOT = resolve(HERE, "..");
 
 /**

package/templates/CHANGELOG.template.md

@@ -1,6 +1,7 @@
 # Changelog
 
-Use this file only when the destination project adopts a changelog.
+Use only when the project adopts a changelog.
+Record user-facing changes, not implementation history.
 
 ## [Unreleased]
 

package/templates/feature-spec.template.md

@@ -2,104 +2,42 @@
 
 ## Status
 
-Not Started
-
-## Overview
-
-Describe the smallest coherent outcome, where it fits, and why it matters.
-
-## Problem
-
-- What is missing, risky, confusing, inaccessible, unreliable, or inefficient?
-- Who or what is affected?
-- Why does this matter now?
+Proposed
 
 ## Goal
 
-State one user-visible or system-verifiable outcome.
-
-## Dependencies
+[One clear user-visible or system-verifiable outcome.]
 
-- Earlier feature, system, decision, prototype, or `None`.
+## Context
 
-## Tags
+Include only what materially helps someone implement this Feature.
 
-- Optional. `namespace:value`, e.g. `area:cli`, `type:infra`, `agent:suitable`.
-- Omit this section entirely, or write `None`, when the project does not use tags. Most do not.
-- Only meaningful when the project has configured work tracking; nothing else reads them.
+- Read: `[specific files, sections, or systems]`
+- Relevant area: `[path or component]`
+- Avoid: `[unrelated area, if useful]`
 
 ## Requirements
 
-- Requirement 1
-- Requirement 2
-- Requirement 3
-- Include relevant failure, permission, loading, empty, retry, responsive, accessibility, operational, or compatibility states only when applicable.
+- `[required behavior]`
+- `[important constraint]`
+- `[relevant edge or failure behavior, when applicable]`
 
 ## Out of Scope
 
-- Explicit exclusion
-- Later feature, if known
-- Unrelated refactors, dependencies, or polish
-
-## Experience or Operational Notes — When Applicable
-
-- User interaction, system behavior, responsive behavior, accessibility, observability, performance, security, or operational expectations.
-
-## Technical Notes
-
-Likely areas:
-
-- `[specific path or bounded area]`
-
-Implementation constraints:
-
-- Follow project context and approved prototype direction.
-- Do not silently resolve open architecture decisions.
-- Keep prototype and production code boundaries explicit.
-
-## Context Boundary
-
-Read:
-
-- `[specific context and code]`
-
-Avoid loading:
-
-- `[unrelated systems, old specs, generated output]`
-
-Split this feature further if its required context is not focused enough for reliable implementation and verification.
+- `[explicit exclusion]`
 
 ## Delivery Chunks
 
-1. `[stable, verifiable increment]`
-2. `[stable, verifiable increment]`
-3. `[optional stable increment]`
+1. `[small, stable, verifiable increment]`
+2. `[next increment, if needed]`
 
-Each chunk should leave the project stable.
+Use one chunk when the Feature is already small.
 
 ## Acceptance Criteria
 
-- The defined outcome works end to end within scope.
-- Relevant failure and edge behavior is handled.
-- Applicable quality requirements are met.
-- Required automated/manual checks pass.
-- The work can be reviewed independently.
-
-## Verification
-
-- Manual or operational checks:
-- Automated checks:
-- Edge cases:
-- Quality checks:
-
-## Learning Targets
-
-- Concepts worth explaining after completion:
-- Diagram or demonstration opportunity:
-- Quiz ideas:
+- `[observable result proving the Feature works]`
+- `[important verification result]`
 
-## Suggested Delivery Metadata
+## Notes / Decisions
 
-- Git action: `[follow project workflow]`
-- Suggested branch, when applicable: `[project naming convention]`
-- Suggested commit, when applicable: `[project convention]`
+- `[Feature-specific dependency, approved decision, constraint, or None]`

package/templates/history.template.md

@@ -0,0 +1,12 @@
+# Project History
+
+Compact record of completed work.
+
+## Completed
+
+### [YYYY-MM-DD] — [Feature or milestone]
+
+- Outcome: `[what changed for the project/user]`
+- Verification: `[brief result or evidence pointer]`
+- Commit/PR: `[sha, PR, or release reference]`
+- Follow-up: `[only if something remains, otherwise none]`

package/templates/lesson.template.md

@@ -1,71 +1,42 @@
 # Lesson — [Feature Name]
 
 - Date:
-- Branch:
-- Feature spec:
-- Commit or diff range:
-- Difficulty:
-- Estimated review time:
+- Feature:
+- Commit/diff:
 
-## 1. Feature in One Minute
+## What Changed
 
-What changed, why it exists, and the user or system value it creates.
+Explain what was implemented and why it matters.
 
-## 2. Mental Model
+## Mental Model
 
-Explain the feature through one clear model. Include a small Mermaid diagram when useful.
+Explain the simplest useful way to understand the Feature.
 
-## 3. Execution and Data Flow
+Include a small diagram only when it helps.
 
-Trace one representative interaction from input to visible result.
+## How It Works
 
-## 4. Important Files
+Trace one representative flow through the implementation.
 
-| File | Responsibility | Why it matters |
-| --- | --- | --- |
+## Important Files
 
-## 5. Key Decisions and Tradeoffs
+| File | Responsibility |
+| --- | --- |
 
-For each meaningful decision:
+Include only files that materially help understanding.
 
-- Decision
-- Evidence in the repository
-- Benefit
-- Cost
-- Credible alternative
-- When the alternative would be better
+## Key Decisions
 
-## 6. Concepts Worth Retaining
+- `[important decision and why it was made]`
 
-Limit this to the most transferable concepts.
+Include only decisions worth remembering.
 
-## 7. Quality Lens
+## Concepts to Retain
 
-### Testing
+- `[transferable concept]`
 
-### Accessibility
+## Check Your Understanding
 
-### Performance
-
-### Maintainability
-
-### Error and edge states
-
-## 8. Production-Scale Gap
-
-What would need to change for higher traffic, larger datasets, multiple teams, stricter security, or real-time collaboration?
-
-## 9. Interview Preparation
-
-- Likely question:
-- Strong answer outline:
-- Follow-up question:
-- Vocabulary to use carefully:
-
-## 10. Check Your Understanding
-
-Three short retrieval questions. Do not include answers here.
-
-## 11. Suggested Next Action
-
-Choose one: quiz, challenge, architecture lesson, spaced review, or no further work.
+1. `[question]`
+2. `[question]`
+3. `[question]`