create-pathfinder 1.4.0 → 1.5.0

package/src/kickstart-prompt.mjs

@@ -0,0 +1,81 @@
+/**
+ * What to tell your agent first, in the words the chosen tool understands.
+ *
+ * This used to be one hardcoded string naming a file path, and that was right
+ * for exactly as long as Pathfinder configured nothing. Once a run can generate
+ * native adapters, the path form is no longer the best answer for someone who
+ * just watched twenty skills be installed into their harness — it is the answer
+ * for someone whose tool cannot discover them.
+ *
+ * A pure function of the selection, deliberately: no filesystem, no detection,
+ * no process. Everything harness-specific comes out of the registry's own
+ * `invocation`, so a third harness supplies its wording by existing rather than
+ * by adding a branch here.
+ */
+
+/** The skill this prompt starts. The one name in this module that is not derived. */
+export const KICKSTART_SKILL = "kickstart-pathfinder";
+
+/**
+ * The harness-neutral prompt, unchanged from every version before this one.
+ *
+ * Two lines because it is read aloud to an agent, and because the second half —
+ * "do not install packages or write product code yet" — is the part that keeps
+ * a first session from turning into an unrequested scaffold.
+ */
+const PATH_PROMPT =
+  `Use skills/${KICKSTART_SKILL}/SKILL.md. Help me initialize this project. ` +
+  "Do not install packages or write product code yet.";
+
+/**
+ * The prompt to print, and to offer to copy.
+ *
+ * Exactly one harness gets that harness's native invocation, because it is the
+ * more reliable entry point once the adapter exists and it is shorter than the
+ * thing it replaces.
+ *
+ * Zero or several harnesses both fall back to the path form, for different
+ * reasons that happen to have the same answer. Zero means nothing was
+ * generated, so there is no native invocation to name. Several means one
+ * clipboard cannot serve two syntaxes — and picking a favorite would quietly
+ * decide which of the user's tools is the real one.
+ *
+ * @param {ReadonlyArray<{invocation?: (name: string) => string}>} harnesses
+ *   The harnesses this run configured, in registry order.
+ * @returns {string}
+ */
+export function kickstartPrompt(harnesses = []) {
+  const selected = Array.isArray(harnesses) ? harnesses.filter(Boolean) : [];
+  if (selected.length !== 1) return PATH_PROMPT;
+
+  const [harness] = selected;
+  if (typeof harness.invocation !== "function") return PATH_PROMPT;
+
+  const invocation = harness.invocation(KICKSTART_SKILL);
+
+  // A registry entry that returns nothing usable falls back rather than
+  // printing an empty "next step". Nothing in this repository does that today;
+  // the guard is here because the alternative failure is a blank instruction.
+  return typeof invocation === "string" && invocation.trim() !== "" ? invocation.trim() : PATH_PROMPT;
+}
+
+/**
+ * The prompt as the summary prints it: wrapped, indented, already a block.
+ *
+ * The path form is two indented lines under a heading and has been since 1.4.1,
+ * so it is reproduced exactly rather than re-wrapped by a general algorithm
+ * that might land the break one word over. A native invocation is a single
+ * short token and needs no wrapping at all.
+ *
+ * @returns {string[]} lines, indented, with no trailing blank
+ */
+export function kickstartPromptLines(harnesses = []) {
+  const prompt = kickstartPrompt(harnesses);
+
+  if (prompt !== PATH_PROMPT) return [`  ${prompt}`];
+
+  return [
+    `  Use skills/${KICKSTART_SKILL}/SKILL.md. Help me initialize this`,
+    "  project. Do not install packages or write product code yet.",
+  ];
+}

package/src/prompt.mjs

@@ -0,0 +1,307 @@
+/**
+ * Asking a question, and the rules about when one may be asked at all.
+ *
+ * Two constraints shape everything here.
+ *
+ * The first is the TTY guard. A prompt is only ever offered when *both* stdin
+ * and stdout are terminals, and that decision is made once, by the caller, and
+ * carried on this object. A prompter built with `interactive: false` does not
+ * ask a question quietly and default it — it throws, because a CLI that asks
+ * nothing must also print nothing, and a guard bug that degrades silently would
+ * show up as a script that hangs on someone's CI runner months later.
+ *
+ * The second is the decided interaction model: `node:readline` and printed
+ * lines. No setRawMode, no keypress handler, no cursor control, no redraw. That
+ * is what makes this work in a dumb terminal, over ssh, and inside an editor's
+ * integrated console, and it is a decision rather than a default.
+ *
+ * Answers are bounded. Unparseable input is re-prompted a fixed number of times
+ * and then gives up, so an input stream that will never produce a `y` cannot
+ * spin forever. Giving up returns null rather than the default: null means
+ * "nobody answered", and the caller decides what that is worth. For a question
+ * that authorizes an action, it is worth a refusal.
+ */
+
+import { createInterface } from "node:readline";
+
+const YES = new Set(["y", "yes"]);
+const NO = new Set(["n", "no"]);
+
+/**
+ * A question-asker bound to one pair of streams.
+ *
+ * @param {{input: NodeJS.ReadableStream, output: NodeJS.WritableStream,
+ *          interactive?: boolean, retries?: number}} options
+ * @returns {{interactive: boolean,
+ *            confirm: (question: string, options?: {defaultAnswer?: boolean}) => Promise<boolean|null>,
+ *            chooseMany: (question: string, config?: object) => Promise<unknown[]|null>,
+ *            chooseOne: (question: string, config?: object) => Promise<unknown|null>,
+ *            text: (question: string) => Promise<string|null>,
+ *            close: () => void}}
+ */
+export function createPrompter({ input, output, interactive = false, retries = 3 }) {
+  let reader = null;
+
+  // Created on first use, not here. A run that never reaches a question — a
+  // repository that already exists, `--help`, a bad flag — must not attach a
+  // reader to stdin, because attaching one resumes the stream and a process
+  // holding an open stdin does not exit on its own.
+  function ensureReader() {
+    if (reader === null) reader = createReader({ input, output });
+    return reader;
+  }
+
+  return {
+    interactive,
+
+    async confirm(question, { defaultAnswer = true } = {}) {
+      if (!interactive) {
+        throw new Error(`refusing to ask "${question}": this prompter is not interactive`);
+      }
+
+      const suffix = defaultAnswer ? "[Y/n]" : "[y/N]";
+
+      for (let attempt = 0; attempt < retries; attempt += 1) {
+        const answer = await ensureReader().ask(`? ${question} ${suffix} `);
+
+        // End of input. Ctrl-D, or a stream that closed under us.
+        if (answer === null) return null;
+
+        const normalized = answer.trim().toLowerCase();
+        if (normalized === "") return defaultAnswer;
+        if (YES.has(normalized)) return true;
+        if (NO.has(normalized)) return false;
+
+        output.write("  Please answer y or n.\n");
+      }
+
+      return null;
+    },
+
+    /**
+     * Ask which of a numbered list apply. Several answers, or none.
+     *
+     * Numbers rather than checkboxes, for the same reason `confirm` is a line
+     * and not a keypress handler: no raw mode, no redraw, so it works in a dumb
+     * terminal, over ssh, and inside an editor console. `Enter` takes the
+     * default — which is what keeps the common case one keystroke — and `0` is
+     * an explicit "none of them", distinct from an empty line that means "the
+     * default", because a default of nothing and a choice of nothing should not
+     * have to be told apart by their side effects.
+     *
+     * Returns the chosen options' `value`s in list order, or null when nobody
+     * answered. Null is not an empty selection: the caller decides what an
+     * unanswered question is worth.
+     *
+     * @param {string} question
+     * @param {{options: {label: string, value: unknown}[], defaultSelection?: unknown[]}} config
+     * @returns {Promise<unknown[]|null>}
+     */
+    async chooseMany(question, { options: choices = [], defaultSelection = [] } = {}) {
+      if (!interactive) {
+        throw new Error(`refusing to ask "${question}": this prompter is not interactive`);
+      }
+      if (choices.length === 0) return [];
+
+      const defaults = choices.filter((choice) => defaultSelection.includes(choice.value));
+      const defaultNumbers = defaults.map((choice) => choices.indexOf(choice) + 1);
+
+      const header = [
+        `? ${question}`,
+        ...choices.map((choice, index) => `    ${index + 1}. ${choice.label}`),
+        defaultNumbers.length > 0
+          ? `  Numbers, comma-separated. Enter for the detected default [${defaultNumbers.join(",")}], or 0 for none.`
+          : "  Numbers, comma-separated. Enter or 0 for none.",
+        "",
+      ].join("\n");
+
+      output.write(header);
+
+      for (let attempt = 0; attempt < retries; attempt += 1) {
+        const answer = await ensureReader().ask("> ");
+        if (answer === null) return null;
+
+        const normalized = answer.trim();
+        if (normalized === "") return defaults.map((choice) => choice.value);
+
+        const selected = parseSelection(normalized, choices.length);
+        if (selected !== null) return selected.map((index) => choices[index].value);
+
+        output.write(`  Please answer with numbers from 1 to ${choices.length}, or 0 for none.\n`);
+      }
+
+      return null;
+    },
+
+    /**
+     * Ask which one of a numbered list. Exactly one, or none.
+     *
+     * The same lines-and-numbers shape as `chooseMany`, and separate from it on
+     * purpose: a question with one answer must not print "comma-separated" and
+     * must not have to decide what `1,2` meant. A caller that wants "none" as a
+     * possibility supplies it as an option, because a list of editors and a
+     * decision not to open one read better as three rows than as a rule.
+     *
+     * Returns the chosen option's `value`, or null when nobody answered. An
+     * option whose value is null and an unanswered question are indistinguishable
+     * here, which is correct for every question worth asking this way: both mean
+     * nothing should happen.
+     *
+     * @param {string} question
+     * @param {{options: {label: string, value: unknown}[], defaultValue?: unknown}} config
+     * @returns {Promise<unknown|null>}
+     */
+    async chooseOne(question, { options: choices = [], defaultValue } = {}) {
+      if (!interactive) {
+        throw new Error(`refusing to ask "${question}": this prompter is not interactive`);
+      }
+      if (choices.length === 0) return null;
+
+      const fallback = choices.find((choice) => choice.value === defaultValue) ?? choices[0];
+      const defaultNumber = choices.indexOf(fallback) + 1;
+
+      output.write(
+        [
+          `? ${question}`,
+          ...choices.map((choice, index) => `    ${index + 1}. ${choice.label}`),
+          `  A number, or Enter for [${defaultNumber}].`,
+          "",
+        ].join("\n"),
+      );
+
+      for (let attempt = 0; attempt < retries; attempt += 1) {
+        const answer = await ensureReader().ask("> ");
+        if (answer === null) return null;
+
+        const normalized = answer.trim();
+        if (normalized === "") return fallback.value;
+
+        if (/^\d+$/.test(normalized)) {
+          const number = Number(normalized);
+          if (number >= 1 && number <= choices.length) return choices[number - 1].value;
+        }
+
+        output.write(`  Please answer with a number from 1 to ${choices.length}.\n`);
+      }
+
+      return null;
+    },
+
+    /**
+     * Ask for a line of free text. Whatever they typed, or null.
+     *
+     * Deliberately the thinnest of the three: no retries, no default, no
+     * validation. There is nothing here to re-prompt *about* — any line is a
+     * well-formed answer to "what is it called" — so judging one is the
+     * caller's job, and only the caller knows what makes a name unusable.
+     *
+     * An empty line comes back as `""` and is a real answer, distinct from the
+     * `null` of a stream that ended. A caller looping for several values reads
+     * the first as "done" and the second as "nobody is there", which happen to
+     * lead to the same place but for different reasons.
+     */
+    async text(question) {
+      if (!interactive) {
+        throw new Error(`refusing to ask "${question}": this prompter is not interactive`);
+      }
+
+      const answer = await ensureReader().ask(`? ${question} `);
+      return answer === null ? null : answer.trim();
+    },
+
+    close() {
+      if (reader !== null) {
+        reader.close();
+        reader = null;
+      }
+    },
+  };
+}
+
+/**
+ * Read a comma-separated list of numbers, or null if any part of it is not one.
+ *
+ * All-or-nothing on purpose. Taking the valid half of `1,banana` would act on a
+ * selection the user did not make, and this question decides what gets written
+ * into their project. Duplicates collapse and order follows the list, so `2,1`
+ * and `1,2,2` mean the same thing.
+ *
+ * `0` means none, and only on its own: `0,1` is a contradiction, not a subset.
+ */
+function parseSelection(input, count) {
+  const parts = input.split(",").map((part) => part.trim());
+  if (parts.some((part) => !/^\d+$/.test(part))) return null;
+
+  const numbers = parts.map(Number);
+  if (numbers.includes(0)) return numbers.every((number) => number === 0) ? [] : null;
+  if (numbers.some((number) => number > count)) return null;
+
+  return [...new Set(numbers)].sort((a, b) => a - b).map((number) => number - 1);
+}
+
+/**
+ * A prompter that cannot be asked anything.
+ *
+ * What the CLI holds when there is no terminal on both ends, or when `--yes`
+ * has already answered everything. Handing back a real object rather than null
+ * keeps the call sites free of `prompter?.` — the guard is `interactive`, in
+ * one place, and it reads as the rule it is.
+ */
+export function nonInteractivePrompter() {
+  return createPrompter({ input: null, output: null, interactive: false });
+}
+
+/**
+ * A line-at-a-time reader over one stream pair.
+ *
+ * Built on the `line` event rather than `readline.question`, which looks like
+ * the obvious choice and is not: a line that arrives while no question is
+ * outstanding is discarded, so the second `question` in a sequence — issued a
+ * microtask later, because the first was awaited — waits forever for input that
+ * was already delivered. Typing ahead, and any test that writes its answers up
+ * front, would hang. Holding the lines here instead means input is never lost
+ * between questions.
+ *
+ * `close` resolves every outstanding and future read as null. A prompt reached
+ * with a closed stdin must fall through to the caller's decision about an
+ * unanswered question, not hang.
+ */
+function createReader({ input, output }) {
+  const readline = createInterface({ input, output });
+  const delivered = [];
+  const waiting = [];
+  let closed = false;
+
+  readline.on("line", (line) => {
+    const resolve = waiting.shift();
+    if (resolve) resolve(line);
+    else delivered.push(line);
+  });
+
+  readline.on("close", () => {
+    closed = true;
+    while (waiting.length > 0) waiting.shift()(null);
+  });
+
+  return {
+    /**
+     * Print `text` and resolve with the next line, or null at end of input.
+     *
+     * The prompt goes through readline rather than straight to the stream so
+     * that on a real terminal readline knows its width and can redraw the line
+     * correctly when the user backspaces over what they typed.
+     */
+    ask(text) {
+      readline.setPrompt(text);
+      readline.prompt();
+
+      if (delivered.length > 0) return Promise.resolve(delivered.shift());
+      if (closed) return Promise.resolve(null);
+      return new Promise((resolve) => waiting.push(resolve));
+    },
+
+    close() {
+      readline.close();
+    },
+  };
+}

package/templates/project-overview.template.md

@@ -1,9 +1,10 @@
-# [Project Name] — Project Overview
+# Project Overview
 
 > Describe the product, audience, intended feeling, and reason it should exist.
 
 ## Status
 
+- Project: `[Project Name]`
 - Stage: `[idea / prototype / MVP / production / maintenance]`
 - Repo type: `[new / existing / application / library / service / monorepo / other]`
 - Primary goal: `[success definition]`
@@ -11,11 +12,23 @@
 
 ## Decision States
 
+These four words describe a decision:
+
 - `TBD` — human decision required
 - `None` — intentionally excluded
 - `N/A` — not applicable
 - `Deferred` — intentionally postponed
 
+## Record Status
+
+A `Status` column describes the record, not the decision:
+
+- `proposed` — written down, not yet approved by the human
+- `accepted` — approved by the human
+- `superseded` — replaced by a later decision, kept for history
+
+The two answer different questions. `TBD` says nobody has decided yet. `proposed` says something was recorded for the human to approve. A recorded proposal is not an approved decision.
+
 ## Product Vision
 
 - Problem:
@@ -55,9 +68,9 @@ starting state -> action/process -> useful result -> reason to return or continu
 
 ## Recommended and Approved Technology
 
-Recommendations may be proposed by `debate-me`; approved choices belong here.
+Recommended and approved choices both live here. `debate-me` and `kickstart-pathfinder` may record a choice before the human approves it; that row is marked `proposed` in `Status` and stays that way until it is `accepted`. Leave `Status` empty while the choice is still `TBD`.
 
-| Layer | Approved choice | Reason | Status |
+| Layer | Choice | Reason | Status |
 | --- | --- | --- | --- |
 | Platform/runtime | `TBD` | | |
 | Language(s) | `TBD` | | |

package/prompts/01-kickstart-project.md

@@ -1 +0,0 @@
-Use `skills/kickstart-pathfinder/SKILL.md` to discover and initialize this new or existing project. Ask progressively, preserve existing repo facts, distinguish recommendations from approved choices, and do not install packages, generate feature specs, or write product code yet.

package/prompts/01-teach-current-feature.md

@@ -1,9 +0,0 @@
-Use `skills/teach-feature/SKILL.md`.
-
-Teach me the verified current feature from its spec, focused diff, implementation, and tests.
-
-Adapt the depth to `context/learning/learner-profile.md`.
-
-Create the lesson under `context/learning/lessons/`.
-
-Do not modify product code, install packages, commit, or merge.

package/prompts/02-debate-me.md

@@ -1 +0,0 @@
-Use `skills/debate-me/SKILL.md` to pressure-test this idea or project. Recommend an MVP, technology/architecture, delivery workflow, and prototype checkpoint based on the findings. Present them for my acceptance, modification, comparison, or deferral; do not silently approve them for me.

package/prompts/02-quiz-current-feature.md

@@ -1,7 +0,0 @@
-Use `skills/quiz-me/SKILL.md`.
-
-Quiz me on the most recent lesson for the current feature.
-
-Ask one question at a time. Use varied question formats. Diagnose understanding rather than rewarding memorization.
-
-Update `context/learning/progress.md` conservatively after the quiz.

package/prompts/03-challenge-current-feature.md

@@ -1,7 +0,0 @@
-Use `skills/challenge-me/SKILL.md`.
-
-Create a small transfer challenge based on the current feature's lesson and my learning gaps.
-
-Change at least one meaningful constraint so I must apply the concept in a new context.
-
-Do not modify code until I explicitly approve implementation.

package/prompts/03-prototype.md

@@ -1 +0,0 @@
-Use `skills/prototype/SKILL.md` to validate the most important unresolved assumption with the cheapest useful prototype. Define review criteria, create or iterate the artifact, and do not treat it as production code.

package/prompts/04-teach-current-architecture.md

@@ -1,7 +0,0 @@
-Use `skills/teach-architecture/SKILL.md`.
-
-Explain how the current feature fits into the wider application architecture.
-
-Clearly distinguish implemented, mocked, planned, and later-recommended architecture.
-
-Create a concise architecture lesson with Mermaid diagrams. Do not refactor code.

package/prompts/04-to-specs.md

@@ -1 +0,0 @@
-Use `skills/to-specs/SKILL.md` to create a coherent MVP roadmap of context-sized, independently verifiable feature specs. Do not implement code or invent unresolved decisions.

package/prompts/05-learning-review.md

@@ -1,5 +0,0 @@
-Use `skills/learning-review/SKILL.md` in interview mode.
-
-Review my recent lessons, quizzes, challenges, completed features, and progress.
-
-Identify what I can credibly explain in a senior frontend interview, where my evidence is weak, and the three highest-value concepts to reinforce through upcoming features.

package/prompts/05-load-feature.md

@@ -1 +0,0 @@
-Use `skills/load-feature/SKILL.md` to prepare the requested or next feature, validate its dependencies and context size, and populate `context/current-feature.md`. Do not implement yet.

package/prompts/06-start-feature.md

@@ -1 +0,0 @@
-Use `skills/start-feature/SKILL.md` to implement the active feature one stable delivery chunk at a time under the project-selected workflow.

package/prompts/07-review-feature.md

@@ -1 +0,0 @@
-Use `skills/review-feature/SKILL.md` to review the actual implementation against its spec, regressions, and project quality priorities. Report findings before changing code.

package/prompts/08-complete-feature.md

@@ -1 +0,0 @@
-Use `skills/complete-feature/SKILL.md` to verify, record, and close the accepted feature under the project delivery policy, then route to feature learning when enabled.

package/prompts/09-learn-feature.md

@@ -1 +0,0 @@
-Use `skills/learn-feature/SKILL.md` to create a rich interactive lesson and varied quiz for the completed feature, scoped to its implementation and direct dependencies.

package/prompts/10-learn-codebase.md

@@ -1 +0,0 @@
-Use `skills/learn-codebase/SKILL.md` to create a modular interactive learning portal for this repository at the current milestone.

package/prompts/11-handoff.md

@@ -1 +0,0 @@
-Use `skills/handoff/SKILL.md` to create a compact factual handoff for the next agent or session.

package/prompts/12-skillsmith.md

@@ -1 +0,0 @@
-Use `skills/skillsmith/SKILL.md` to teach me how to design or improve a small local skill for a repeated workflow problem.

package/prompts/13-reverse-engineer.md

@@ -1,18 +0,0 @@
-Use `skills/reverse-engineer/SKILL.md`.
-
-Reverse-engineer the reference I provide.
-
-Focus on the specific product, experience, system, component, animation, repository, or workflow I name.
-
-Clearly separate:
-
-* directly observed behavior
-* strong inferences
-* possible reconstruction choices
-* unknown details
-
-Explain the transferable patterns and produce a practical reconstruction blueprint.
-
-Do not copy protected assets or claim unsupported knowledge about private implementation details.
-
-Do not modify project files, create feature specs, install dependencies, or implement code unless I explicitly invoke the appropriate Pathfinder skill afterward.

package/prompts/14-reflect.md

@@ -1,13 +0,0 @@
-Use `skills/reflect/SKILL.md`.
-
-Reflect on the completed work I name.
-
-Reconstruct what actually happened from repository evidence, then classify each finding as PROJECT, WORKFLOW CANDIDATE, or NOISE.
-
-Only propose a Pathfinder change when the lesson would still hold in another language, framework, and business domain, and is not already covered by an existing skill or document.
-
-Prefer the smallest durable improvement. Concluding that Pathfinder should not change is a valid result.
-
-Then make one bounded pass over the reflection itself. Report `No Reflect improvement proposed.` unless evidence shows the process genuinely failed to do its job. Do not recurse further.
-
-Do not modify Pathfinder, `AGENTS.md`, skills, prompts, or project files as part of reflection. Propose the changes and wait for my decision.

package/prompts/15-debug-issue.md

@@ -1,15 +0,0 @@
-Use `skills/debug-issue/SKILL.md`.
-
-Debug the failure I describe.
-
-Establish expected behavior, actual behavior, and reproduction status before proposing any fix.
-
-Read only the code, logs, tests, and configuration relevant to the failure. Do not refactor unrelated code while the cause is still unknown.
-
-State a small ranked set of hypotheses, then test the cheapest one that meaningfully reduces uncertainty. Change one explanatory variable at a time.
-
-Do not call something the root cause because the symptom disappeared. If the evidence only supports a probable cause or a workaround, say so.
-
-Apply the smallest justified fix, then verify against the original failure and the nearby behavior it could have affected. Remove temporary instrumentation.
-
-Stop and report rather than thrashing when the evidence runs out, the reproduction is too unstable, or the fix would require an architectural, dependency, security, or destructive change I have not approved. Preserve what has already been ruled out.