create-pathfinder 2.1.0 → 3.1.0

package/CLAUDE.md

@@ -70,6 +70,8 @@ Ask before actions identified in `context/ai-interaction.md`, especially depende
 
 Canonical Pathfinder skills are tool-neutral and live under `skills/`. Harness-specific representations — `.claude/skills/`, `.agents/skills/` — are generated integration artifacts and must not become independent behavior contracts. Edit the canonical file; regenerate the adapter.
 
+The Claude Code plugin declared by `.claude-plugin/plugin.json` is a third discovery surface, and the only one that generates nothing: it exposes the canonical `skills/` tree itself, namespaced `/pathfinder:<skill>`. There is no plugin copy of any skill and there must never be one. If a discovery surface and its canonical skill disagree, the canonical skill is correct.
+
 An adapter carries the canonical skill's frontmatter and a pointer to it, and nothing else. If an adapter and its canonical skill disagree, the canonical skill is correct.
 
 ## Available skills
@@ -79,11 +81,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/README.md

@@ -261,6 +261,23 @@ Pathfinder also never writes to personal/global skill directories such as:
 ~/.agents/skills/
 ```
 
+### The Claude Code plugin is a separate path
+
+Pathfinder is also distributed as a Claude Code plugin, installed with
+`/plugin marketplace add rikilamadrid/pathfinder` followed by
+`/plugin install pathfinder@lamadrid-labs`. It does not replace this installer
+and does not change anything it does.
+
+The two install different things. The plugin installs commands, always
+namespaced `/pathfinder:<skill>`, into your Claude Code installation and writes
+nothing into your repository — no kit, no adapters. This installer copies the
+kit your repository keeps under version control, and generates the adapters that
+expose the bare `/<skill>` names.
+
+A repository can have both, and then carries both command forms running the same
+canonical skill body. If you arrived through the plugin with no kit yet,
+`/pathfinder:kickstart-pathfinder` offers to install one for you.
+
 ### Interactive selection
 
 In an interactive terminal, the installer asks which supported tools to

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.1.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/kickstart-pathfinder/SKILL.md

@@ -36,18 +36,57 @@ When the user is unsure, provide a small recommendation with reasoning and alter
 
 ## Process
 
-1. Read the kit context and inspect relevant repository facts.
-2. Ask the minimum unresolved questions in small groups.
-3. Summarize requirements, preferences, constraints, open decisions, and contradictions.
-4. Route uncertain product/technical choices to `debate-me` when useful.
-5. Present the proposed context and request human corrections or approval.
-6. Update `context/project-overview.md`, `context/coding-standards.md`, `context/ai-interaction.md`, `CLAUDE.md`, and `AGENTS.md` only after the choices are sufficiently clear.
+1. If the project is missing kit files, and this session loaded this skill from
+   the Pathfinder plugin, offer to install the kit before going further. See
+   `Kit Bootstrap` below. Otherwise start at the next step.
+2. Read the kit context and inspect relevant repository facts.
+3. Ask the minimum unresolved questions in small groups.
+4. Summarize requirements, preferences, constraints, open decisions, and contradictions.
+5. Route uncertain product/technical choices to `debate-me` when useful.
+6. Present the proposed context and request human corrections or approval.
+7. Update `context/project-overview.md`, `context/coding-standards.md`, `context/ai-interaction.md`, `CLAUDE.md`, and `AGENTS.md` only after the choices are sufficiently clear.
    `context/project-overview.md` does not ship; create it from `templates/project-overview.template.md` at this step.
    Project facts go there; approval rules and tool actions requiring a human go
    in `context/ai-interaction.md`. Fill the sections the project has and mark
    the rest `TBD` or `None`. Do not add sections the template does not carry,
    and do not leave a field blank.
-7. Recommend `debate-me`, `prototype`, or `to-specs` as the next action.
+8. Recommend `debate-me`, `prototype`, or `to-specs` as the next action.
+
+## Kit Bootstrap
+
+The Pathfinder plugin distributes commands. It does not distribute project
+state. A repository reached through `/plugin install` therefore has every
+Pathfinder command and none of the files those commands read.
+
+This step applies only when both are true: the project is missing kit files,
+and this skill was loaded from the plugin, which is what makes
+`${CLAUDE_PLUGIN_ROOT}` — the plugin's install directory — a real path. When
+the kit installed this skill into the repository instead, there is no plugin
+root, the condition is false, and this whole section is skipped without being
+raised or quoted.
+
+When it does apply:
+
+- Copy from the plugin root into the project root, and copy only the kit. That
+  list is not restated here: `packages/create-pathfinder/copy-list.json`, inside
+  the plugin root, is the one statement of it. Read that file and copy the
+  entries it names.
+- Exclude exactly what the installer excludes, and read that from the installer
+  too: `NEVER_SHIPS` in `packages/create-pathfinder/src/kit.mjs`, also inside
+  the plugin root, is the one statement of it. Skip every kit-relative path it
+  holds. Those files are one repository's own working state and would be wrong
+  in any other project. Restating them here would be a second list to keep in
+  step, and the first time it drifted this step would hand a project what
+  `npx create-pathfinder` refuses to.
+- Name every file before writing it, and wait for approval.
+- Overwrite nothing without asking about that file by name. Delete nothing.
+- Report exactly what was written, what was skipped, and what was left alone.
+- Generate no harness adapters. Plugin commands stay namespaced
+  `/<plugin-name>:<skill>`, and that is the intended plugin form.
+  `npx create-pathfinder --agents claude-code` is what generates adapters and
+  the bare command names, for a human who wants both.
+
+When the project already has the kit, change nothing and say so.
 
 ## Stop Condition
 

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.