create-pathfinder 2.1.0 → 3.0.0

package/CLAUDE.md

@@ -79,11 +79,8 @@ An adapter carries the canonical skill's frontmatter and a pointer to it, and no
 - `reverse-engineer` — analyze an external reference and produce an evidence-based reconstruction blueprint
 - `prototype` — create and iterate the cheapest useful validation artifact
 - `to-specs` — generate context-sized feature specs
-- `load-feature` — prepare one feature for implementation
-- `start-feature` — implement scoped delivery chunks
+- `feature` — run one action of the Feature delivery loop: `load`, `start`, `review`, `complete`
 - `debug-issue` — diagnose an observed failure to its root cause, apply the smallest justified fix, and verify it
-- `review-feature` — review against requirements, regressions, and standards
-- `complete-feature` — verify and close a feature cleanly
 - `learn-feature` — create an interactive lesson for a completed feature
 - `learn-codebase` — create a modular learning portal for the repository
 - `teach-feature` — teach the verified current feature from its spec, diff, tests, and implementation

package/context/ai-interaction.md

@@ -38,10 +38,10 @@ Inspect current Git state before acting. If the workflow is unclear or
 
 Use the workflow skills instead of recreating their procedures in chat:
 
-1. `load-feature` — load the active work and relevant context.
-2. `start-feature` — implement the current delivery chunk.
-3. `review-feature` — verify the work and report findings.
-4. `complete-feature` — complete accepted work and durable records.
+1. `/feature load` — load the active work and relevant context.
+2. `/feature start` — implement the current delivery chunk.
+3. `/feature review` — verify the work and report findings.
+4. `/feature complete` — complete accepted work and durable records.
 5. `learn-feature` — optionally teach what was implemented.
 
 Roles are optional. The workflow must work without activating one.

package/package.json

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

package/roles/developer.md

@@ -17,8 +17,7 @@ Do not load unrelated history, roadmap, Features, or repository areas by default
 
 ## Use
 
-- `load-feature` to load the work.
-- `start-feature` to implement it.
+- `feature` — its load action to load the work, its start action to implement it.
 - Use the project's existing build, test, and verification commands as needed.
 
 ## Rules

package/roles/tester.md

@@ -20,7 +20,7 @@ Do not rely on the developer's summary as proof.
 
 ## Use
 
-- `review-feature` to verify implemented work.
+- `feature` — its review action, to verify implemented work.
 - Use the project's existing test commands and relevant testing tools.
 
 ## Rules

package/skills/debug-issue/SKILL.md

@@ -29,9 +29,9 @@ Use Debug Issue when there is a concrete unexpected behavior such as:
 
 Do not use it merely because implementation work is difficult.
 
-If the task is planned feature construction, use `start-feature`.
+If the task is planned feature construction, use `/feature start`.
 
-If the goal is reviewing completed implementation for possible defects, use `review-feature`.
+If the goal is reviewing completed implementation for possible defects, use `/feature review`.
 
 If the real question is broad understanding of the repository, use `learn-codebase`.
 
@@ -202,8 +202,8 @@ It does not:
 
 * implement unrelated feature scope
 * perform a general repository review
-* replace `review-feature`
-* replace `complete-feature`
+* replace `/feature review`
+* replace `/feature complete`
 * silently change architecture or dependencies
 * turn debugging into opportunistic refactoring
 * hide uncertainty behind a successful-looking workaround

package/skills/feature/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: feature
+description: Run one action of the Feature delivery loop — load, start, review, or complete.
+argument-hint: load|start|review|complete
+---
+
+# Feature
+
+The Feature delivery loop, as one skill. The human names the action:
+
+`/feature load`
+`/feature start`
+`/feature review`
+`/feature complete`
+
+## Process
+
+1. Take the action from the invocation.
+   If none was given, list the four actions below and stop.
+   If it is not one of the four, say so, list them, and stop.
+2. Read only `skills/feature/actions/<action>.md` and follow it exactly.
+
+## Actions
+
+- `load` — prepare one Feature for execution. Reads its spec and the minimum
+  context around it, checks for blockers, records the approval in the spec, and
+  writes the session's workspace state.
+- `start` — implement the active delivery chunk in small, stable increments,
+  restating the pre-implementation summary before editing anything.
+- `review` — verify implemented work against its Feature and report findings.
+  It changes no implementation and accepts nothing.
+- `complete` — complete work the human has accepted, through the project's
+  delivery workflow and its durable records.
+
+## Lifecycle
+
+The Feature spec's `## Status` holds the durable lifecycle state named in
+`context/ai-interaction.md`:
+
+`Proposed` → `Ready` → `In Progress` → `Complete`
+
+`Cancelled` and `Superseded` are terminal alternatives.
+
+- `load` writes `Proposed` → `Ready`.
+- `start` writes `Ready` → `In Progress`.
+- `complete` writes `Complete`.
+- `review` writes no status. Review is workflow activity, not lifecycle state.
+
+`context/current-feature.md` is transient workspace state and records no status.
+
+## Rules
+
+- Run the one action the human named. Do not continue into the next one.
+- Read only that action's file. The other three are not context for this work.
+- Human authority is unchanged: approval, acceptance, merge, and release are
+  the human's, whichever action is running.

package/skills/feature/actions/complete.md

@@ -0,0 +1,22 @@
+# Feature: Complete
+
+Invoking this action is the human's acceptance of the Feature. Do not ask for
+acceptance again.
+
+Acceptance of the Feature is not approval of the delivery steps below. Each one
+that the project's documented workflow gates is still asked for.
+
+1. Run the project's required final checks.
+2. Follow the documented Git, merge, version, release, and deployment workflow.
+   Ask for approval where it requires it. If that workflow is undocumented or
+   `TBD`, stop and ask rather than choosing one.
+3. Mark the Feature `Complete` in its spec's `## Status`.
+4. Add a compact entry to `context/history.md`.
+   Create it from `templates/history.template.md` if it does not exist.
+5. Clear or update `context/current-feature.md`. Do nothing if it does not exist.
+6. If work tracking is configured, sync the completed state.
+7. Report the completed outcome and any remaining follow-up.
+
+Do not re-review accepted work unless final verification exposes a new problem.
+
+Do not claim completion if required checks or delivery steps failed.

package/skills/{load-feature/SKILL.md → feature/actions/load.md}

@@ -1,9 +1,6 @@
----
-name: load-feature
-description: Load one approved Feature and the minimum context needed to work on it.
----
+# Feature: Load
 
-# Load Feature
+Prepare one Feature for execution.
 
 1. Select the Feature the human named. Being invoked on it is the approval to
    prepare it for execution, so its spec does not already have to say `Ready`.
@@ -15,7 +12,7 @@ description: Load one approved Feature and the minimum context needed to work on
 5. Stop if a required human decision or explicit dependency blocks the work.
 6. Record the approval in the Feature spec's `## Status`, which holds the
    durable lifecycle state:
-   - `Proposed` becomes `Ready`. That is the only value this skill writes.
+   - `Proposed` becomes `Ready`. That is the only value this action writes.
    - `Ready` or `In Progress` is left exactly as it is. Reloading a Feature
      mid-work is normal and must not rewrite its state.
    - `Complete`, `Cancelled`, or `Superseded` blocks the load. Report it and
@@ -38,11 +35,11 @@ description: Load one approved Feature and the minimum context needed to work on
    its key is that Feature number. Do nothing here if it does not.
 9. Present a short readiness summary.
 
-Do not implement the Feature.
+Do not implement the Feature. That is `/feature start`.
 
 Do not scan unrelated repository areas, load history or roadmap by default, or
 silently resolve `TBD` decisions.
 
 Do not rewrite the Feature's substance — its Goal, Context, Requirements, Out of
 Scope, Delivery Chunks, or Acceptance Criteria. `## Status` is the one field this
-skill maintains.
+action maintains.

package/skills/{review-feature/SKILL.md → feature/actions/review.md}

@@ -1,9 +1,4 @@
----
-name: review-feature
-description: Verify implemented work against its Feature and report findings.
----
-
-# Review Feature
+# Feature: Review
 
 Review the actual diff and behavior, not only the developer's summary.
 
@@ -31,3 +26,7 @@ Report:
 Do not modify the implementation unless the human explicitly asks.
 
 Do not invent findings or treat passing tests as automatic acceptance.
+
+Do not write the Feature's `## Status`. Review is workflow activity, not
+lifecycle state, and a reviewed Feature stays `In Progress` until it is
+completed.

package/skills/feature/actions/start.md

@@ -0,0 +1,33 @@
+# Feature: Start
+
+Implement the active delivery chunk.
+
+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. Record the Feature spec's `## Status` as `In Progress`, before the first file
+   edit of the first chunk:
+   - `Ready` becomes `In Progress`. That is the only value this action writes.
+   - `In Progress` is left exactly as it is. Continuing a Feature across
+     sessions and chunks is normal and must not rewrite its state.
+   - Any other status stops the session. Report it. A Feature that was never
+     loaded is not approved for execution, and terminal work is the human's to
+     reopen.
+4. Follow the Feature and existing project conventions.
+5. Make the smallest complete change.
+6. Verify the behavior you changed.
+7. Keep the repository stable.
+8. Create or update `context/current-feature.md` with the current state and next
+   action. Do not record the lifecycle status there; the spec carries it.
+
+## Rules
+
+- 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/reverse-engineer/SKILL.md

@@ -173,7 +173,7 @@ Use one of these:
 * `debate-me` — when major product or technical decisions remain
 * `prototype` — when the experience or technical assumption needs validation
 * `to-specs` — when the direction is approved and ready to become feature files
-* `load-feature` — when the analysis applies to one already-planned feature
+* `/feature load` — when the analysis applies to one already-planned feature
 * `learn-codebase` — when the user wants to understand their own repository instead
 * no handoff — when the user only requested analysis
 

package/skills/role/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: role
 description: Activate one named Pathfinder role for the current session.
+argument-hint: planner|developer|tester
 ---
 
 # Role

package/src/cli.mjs

@@ -49,6 +49,8 @@ Options:
                   It does not authorize \`git init\` or configure any tool;
                   pass --git-init and --agents for those.
   -h, --help      Show this message.
+  -v, --version   Print the version and exit, whatever else you passed.
+                  Nothing else is printed.
 
 Adapters are generated files Pathfinder owns and regenerates without --force.
 A file it did not generate is never replaced, at any path, without --force.
@@ -83,6 +85,22 @@ export async function run(
 ) {
   const options = parseArguments(argv);
 
+  // Answered before the error branch, and before every other flag: `--version`
+  // is a question about this package, not about this run. It holds outside a Git
+  // repository, alongside a misspelled flag, and when stdout is redirected to a
+  // file or a pipe, because the one thing a caller asking for a version number
+  // can never use is a paragraph explaining why the version could not be
+  // printed. A reader that closes the pipe before this write lands still raises
+  // EPIPE, as it does for every other write here; that is not something this
+  // early return changes.
+  //
+  // One line, `VERSION` alone. No `v` prefix, no identity block, no findings:
+  // this output is read by scripts, and the plain form is the whole contract.
+  if (options.version) {
+    out(`${VERSION}\n`);
+    return 0;
+  }
+
   if (options.error) {
     err(`create-pathfinder: ${options.error}\n\n${USAGE}`);
     return 2;
@@ -570,21 +588,43 @@ function countWritten(result, plan, options) {
   return result.written + result.overwritten;
 }
 
+/**
+ * Every option at its unasked-for default. `parseArguments` starts from a copy
+ * of this and `--version` returns one, so the two agree by construction.
+ */
+const NO_OPTIONS = {
+  dryRun: false,
+  force: false,
+  help: false,
+  version: false,
+  gitInit: false,
+  noGitInit: false,
+  noClipboard: false,
+  noOpen: false,
+  yes: false,
+  // null means "not said", which is not the same as "none". Only the first
+  // suppresses the question.
+  agents: null,
+  error: null,
+};
+
+/**
+ * Which options this run asks for.
+ *
+ * `-v` and `--version` are recognized here, before any other token in `argv`
+ * is interpreted, because they ask what this package is rather than what this
+ * run should do. A misspelled flag or an invalid `--agents` value must not
+ * swallow the answer, and the answer must not depend on position: a wrapper
+ * that appends `--version` to arguments it was handed still gets a version
+ * number. That is why this is a scan and not another `case` below — the
+ * refusals in the loop return early, and one of them would otherwise win.
+ */
 function parseArguments(argv) {
-  const options = {
-    dryRun: false,
-    force: false,
-    help: false,
-    gitInit: false,
-    noGitInit: false,
-    noClipboard: false,
-    noOpen: false,
-    yes: false,
-    // null means "not said", which is not the same as "none". Only the first
-    // suppresses the question.
-    agents: null,
-    error: null,
-  };
+  if (argv.some((argument) => argument === "-v" || argument === "--version")) {
+    return { ...NO_OPTIONS, version: true };
+  }
+
+  const options = { ...NO_OPTIONS };
 
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index];

package/src/kit.mjs

@@ -68,7 +68,7 @@ export function isExcluded(basename) {
  *
  * `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`
+ * stopped shipping a blank `current-feature.md` stencil, because `/feature load`
  * 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

package/skills/complete-feature/SKILL.md

@@ -1,23 +0,0 @@
----
-name: complete-feature
-description: Complete accepted work through the project's delivery workflow and durable records.
----
-
-# Complete Feature
-
-Complete only work the human has accepted.
-
-1. Confirm the Feature is accepted.
-2. Run the project's required final checks.
-3. Follow the documented Git, merge, version, release, and deployment workflow.
-   Ask for approval where required.
-4. Mark the Feature complete.
-5. Add a compact entry to `context/history.md`.
-   Create it from `templates/history.template.md` if it does not exist.
-6. Clear or update `context/current-feature.md`. Do nothing if it does not exist.
-7. If work tracking is configured, sync the completed state.
-8. Report the completed outcome and any remaining follow-up.
-
-Do not re-review accepted work unless final verification exposes a new problem.
-
-Do not claim completion if required checks or delivery steps failed.

package/skills/start-feature/SKILL.md

@@ -1,29 +0,0 @@
----
-name: start-feature
-description: Implement the active Feature in small, stable increments.
----
-
-# Start Feature
-
-Implement the active delivery chunk.
-
-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
-
-- 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.