create-pathfinder 1.4.0 → 1.5.0

package/AGENTS.md

@@ -5,3 +5,7 @@ Read `CLAUDE.md` first.
 Project truth lives in `context/`. Follow the technology and delivery choices documented in `context/project-overview.md`; do not assume a framework, package manager, branch model, or release process.
 
 Use the smallest relevant context for the active task. Keep each delivery chunk stable, reviewable, and verifiable.
+
+Canonical skills live under `skills/` and are the only behavior contract; anything under `.claude/skills/` or `.agents/skills/` is a generated pointer to one, so edit the canonical file and regenerate the adapter.
+
+If this tool has no native skill discovery, invoke a skill by reading its canonical file directly: `Use skills/<name>/SKILL.md and follow it exactly.` That is the whole fallback — there is no launcher file, and no second copy of a skill to find.

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # Project Agent Guide
 
-This repository uses an AI-assisted, human-in-the-loop workflow. Project truth lives in `context/`, reusable behaviors live in `skills/`, and manual launchers live in `prompts/`.
+This repository uses an AI-assisted, human-in-the-loop workflow. Project truth lives in `context/`, and reusable behaviors live in `skills/`.
 
 ## Read only what is needed
 
@@ -48,6 +48,12 @@ Ask before actions identified in `context/ai-interaction.md`, especially depende
 - Prefer concrete verification over confident narration.
 - Report conflicts between specs, repository reality, and durable context.
 
+## Canonical skills and harness adapters
+
+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.
+
+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
 
 - `kickstart-pathfinder` — discover and initialize project context

package/README.md

@@ -2,7 +2,7 @@
 
 **An AI-assisted, human-in-the-loop workflow for building software — without giving up the decisions.**
 
-This package installs [Pathfinder](https://github.com/rikilamadrid/pathfinder) into a Git repository you already have.
+This package installs [Pathfinder](https://github.com/rikilamadrid/pathfinder) into a Git repository — one you already have, or one it offers to create for you.
 
 ```bash
 npx create-pathfinder
@@ -17,16 +17,21 @@ Do not install packages or write product code yet.
 
 ## What it installs
 
-Pathfinder is a kit of context files and skills — not a framework. There is no runtime, no dependency, and nothing to build. The installer copies six things into your repository and nothing else:
+Pathfinder is a kit of context files and skills — not a framework. There is no runtime, no dependency, and nothing to build. The installer copies five things into your repository and nothing else:
 
 | Path | What it is |
 | --- | --- |
 | `AGENTS.md`, `CLAUDE.md` | Entry files that tell an agent how to work in the project |
 | `context/` | Project truth — overview, standards, interaction rules, current feature |
 | `skills/` | Twenty skills covering discovery, specs, delivery, debugging, review, and learning |
-| `prompts/` | Manual launchers for tools that do not discover local skills |
 | `templates/` | Starting points the project copies when it needs them |
 
+On request it also writes one thing it does not copy:
+
+| Path | What it is |
+| --- | --- |
+| `.claude/skills/`, `.agents/skills/` | **Generated** — a small adapter per skill, derived from `skills/` at install time, so your coding tool discovers them natively. Not part of the five above; see [Native skills for your coding tool](#native-skills-for-your-coding-tool) |
+
 It never copies Pathfinder's own `README.md`, `CHANGELOG.md`, CI configuration, or brand assets. Your repository gets the workflow, not the project that maintains it.
 
 ## What it will not do to your repository
@@ -34,22 +39,105 @@ It never copies Pathfinder's own `README.md`, `CHANGELOG.md`, CI configuration,
 This runs once, in real code, so it is deliberately timid:
 
 - **It never overwrites.** Files that already exist are left exactly as they are and listed by name in the summary. Pass `--force` if you actually want them replaced.
-- **It refuses to run outside a Git repository**, so whatever it writes is reviewable and undoable.
-- **`--dry-run` reports the same plan the real install would carry out**, without writing anything.
+- **It will not install outside a Git repository**, so whatever it writes is reviewable and undoable. In an empty directory it offers to run `git init` for you — and that is the only Git command it will ever run. No `add`, no `commit`, no config, no branch. If you say no, nothing is written.
+- **It never touches an existing history.** A directory that is already a repository, or inside one, is never asked about and never initialized.
+- **`--dry-run` reports the same plan the real install would carry out**, including any `git init`, without writing anything.
+- **It owns a generated adapter, and nothing else in your tool's directory.** A file at `.claude/skills/<name>/SKILL.md` or `.agents/skills/<name>/SKILL.md` belongs to the installer only if that name is a Pathfinder skill *and* the file carries the `pathfinder:adapter` marker it wrote. Your `settings.json`, `settings.local.json`, agents, commands, hooks, and any skill of your own are never read and never written, a file you wrote at an adapter path is left alone and named in the summary, and nothing is ever deleted.
+
+**Re-running `npx create-pathfinder` in a project that already has Pathfinder is safe, requires no flags, and is idempotent.** Canonical files you have edited are skipped and listed; files new in this version are written; adapters are regenerated, byte-identical if nothing changed; anything you own is untouched. That is how a project installed before v1.5.0 gains adapters — one ordinary run, no migration command.
+
+## Native skills for your coding tool
+
+Pathfinder's skills are tool-neutral files at `skills/<name>/SKILL.md`. Some coding tools discover skills natively from their own directory, and the installer can generate small adapters there so you get `/reflect` instead of pasting a path.
+
+```bash
+npx create-pathfinder --agents claude-code,codex
+```
+
+| Id | Writes to | Invoked as |
+| --- | --- | --- |
+| `claude-code` | `.claude/skills/<name>/SKILL.md` | `/reflect` |
+| `codex` | `.agents/skills/<name>/SKILL.md` | `/skills`, or `$reflect` |
+
+Each adapter is a few lines long: it carries the skill's name and description, and tells the tool to read the canonical file. Both harnesses get the same bytes at a different path — the behavior lives in one place, and the adapter never restates it.
+
+Pick one, both, or neither. Choosing one never generates, removes, or claims anything under the other's directory, and Pathfinder never writes to a personal skills directory such as `$HOME/.agents/skills`.
+
+In a terminal you are asked instead of passing the flag — a numbered list, comma-separated, `Enter` for the tools found on your machine, `0` for none. Each option shows the directory it writes to before you choose it.
+
+The list has a third entry, **Something else…**, and it generates nothing. Name your tool and the summary says so plainly, because a `.mdc` file Cursor half-reads or a `SKILL.md` in a directory nothing scans would be a file your tool ignores under a summary claiming success. Two things do work for any tool: the kit installs `AGENTS.md` at the repository root, which Codex, Cursor, and several others read, and any agent can be given the line the adapters delegate to anyway — `Use skills/<name>/SKILL.md and follow it exactly.`
+
+Nothing is configured unless you choose it. Detection only sets the default, a piped or scripted run configures nothing at all unless `--agents` says so, and `--agents` accepts only the ids in the table above — an unknown one exits 2 rather than quietly installing nothing.
+
+**What the installer owns, and what it will not touch:**
+
+- **It owns a file at `<tool>/skills/<name>/SKILL.md` only if that name is a Pathfinder skill *and* the file carries the `pathfinder:adapter` marker it wrote.** Those it regenerates freely, with no flag — that is how an older install gains adapters by re-running.
+- **A file you wrote at one of those paths is left alone** and listed by name in the summary. `--force` replaces it; nothing else does.
+- **Everything else under that directory is never read and never written** — your `settings.json`, `settings.local.json`, agents, commands, hooks, and any skill of your own.
+- **Nothing is ever deleted.** An adapter for a skill a newer version no longer ships is reported and left in place.
+
+Re-running is idempotent: the second run writes the same bytes and reports the adapters as already up to date.
 
-Re-running it is safe, and fills in only what is missing.
+## The Kickstart prompt, and your clipboard
+
+Every install ends by printing the one prompt that starts a session, and the prompt follows the tool you chose:
+
+| Configured | Prompt |
+| --- | --- |
+| `claude-code` | `/kickstart-pathfinder` |
+| `codex` | `$kickstart-pathfinder` |
+| both, or neither | `Use skills/kickstart-pathfinder/SKILL.md. Help me initialize this project. Do not install packages or write product code yet.` |
+
+Two harnesses fall back to the neutral form because one clipboard cannot hold two syntaxes, and picking a favorite would quietly decide which of your tools is the real one.
+
+In a terminal you are then asked whether to copy it. The question says what it replaces, because your clipboard is yours:
+
+```text
+? Copy that prompt to your clipboard? This replaces what is on it now. [Y/n]
+```
+
+- **Nothing is copied without an explicit yes.** Declining, an unanswered question, `--no-clipboard`, `--yes`, `--dry-run`, and any run without a terminal on both ends all leave your clipboard exactly as it was.
+- **The prompt is printed either way.** Copying is a convenience, never the only way to get it, which is what lets every failure be a non-event.
+- **No dependency, and no clipboard is ever read.** The copy uses whatever your system already has — `pbcopy`, `clip.exe` including under WSL, or `wl-copy`, `xclip`, or `xsel` — chosen by what is actually installed rather than by your platform's name. If none of them is there, or one of them fails, the installer says so in one line and still exits 0.
+
+## Opening the project
+
+The last question is whether to open the project, and it is only ever about an editor you already have. The installer looks for `code` (VS Code) and `cursor` (Cursor) on your `PATH`:
+
+- **One found** — a yes/no naming it: `? Open this project in VS Code? [Y/n]`
+- **Several found** — a numbered list, alphabetical, ending in `Don't open`
+- **None found** — no question at all
+
+Neither editor is a Pathfinder requirement, and the alphabetical order is not a recommendation. Nothing else can be launched: there is no way to name an editor or pass a path, because an editor the installer did not find is one it cannot honestly offer.
+
+The launch is detached — the installer hands over the project directory and exits immediately, so it never waits for your editor and never prints your editor's output as its own.
+
+- **Nothing is launched without an explicit yes.** Declining, an unanswered question, `Don't open`, `--no-open`, `--yes`, `--dry-run`, and any run without a terminal on both ends all leave your screen alone.
+- **A failed launch is not a failed install.** If the binary is there but cannot be run, the installer says so in one line, tells you the directory to open yourself, and still exits 0. The install already succeeded; opening it was a convenience.
 
 ## Options
 
 | Option | Effect |
 | --- | --- |
-| `--dry-run` | Report what would be written; change nothing |
-| `--force` | Overwrite files that already exist |
+| `--agents <ids>` | Generate skill adapters for these tools, comma-separated. Valid ids: `claude-code`, `codex`. Alias: `--agent` |
+| `--dry-run` | Report what would be written, and any `git init` that would run first; change nothing |
+| `--force` | Overwrite files that already exist, and replace a file you wrote at a path an adapter would occupy |
+| `--git-init` | Run `git init` here if this is not a repository yet |
+| `--no-git-init` | Never run `git init`; refuse instead |
+| `--no-clipboard` | Never offer to copy the Kickstart prompt. The prompt is printed either way |
+| `--no-open` | Never offer to open the project in an editor |
+| `--yes`, `--no-input` | Take the defaults and ask nothing. It does not authorize `git init`, configure any tool, touch your clipboard, or open an editor — pass `--git-init` and `--agents` for the first two |
 | `-h`, `--help` | Show usage |
 
+Questions are asked only when stdin and stdout are both terminals. Piped, redirected, or in CI, nothing is asked and nothing is prompted for — so a directory that is not a repository needs `--git-init`, or the install is refused, no tool is configured without `--agents`, the clipboard is never touched at all, and no editor is ever launched.
+
 ## Requirements
 
-Node 18 or newer, and a Git repository. No dependencies — this package installs nothing into your project's `node_modules`, and has none of its own.
+Node 18 or newer, and a Git repository — though the installer will offer to create one for you.
+
+The `git` binary is only needed to *create* that repository. Inside one that already exists, the installer finds it by walking the filesystem for `.git` and never runs Git at all, so it works on a machine where `git` is not on your `PATH`.
+
+No dependencies — this package installs nothing into your project's `node_modules`, and has none of its own.
 
 ## Links
 

package/bin/create-pathfinder.mjs

@@ -1,8 +1,36 @@
 #!/usr/bin/env node
 import { run } from "../src/cli.mjs";
+import { createPrompter } from "../src/prompt.mjs";
 
-process.exitCode = run(process.argv.slice(2), {
-  cwd: process.cwd(),
-  out: (text) => process.stdout.write(text),
-  err: (text) => process.stderr.write(text),
+// Everything the CLI learns about the outside world arrives through this call.
+// `run` reads no globals of its own, so a test can hand it a synthesized
+// environment — a Windows PATH, an absent $HOME, a terminal that is not one —
+// without touching the process it runs in.
+//
+// The TTY guard is decided here, once, and both ends must be terminals: a
+// question needs somewhere to be printed *and* someone able to answer it.
+// `create-pathfinder < /dev/null` in a terminal is not interactive, and neither
+// is a run whose stdout is a pipe.
+const interactive = Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+
+const prompter = createPrompter({
+  input: process.stdin,
+  output: process.stdout,
+  interactive,
 });
+
+try {
+  process.exitCode = await run(process.argv.slice(2), {
+    cwd: process.cwd(),
+    out: (text) => process.stdout.write(text),
+    err: (text) => process.stderr.write(text),
+    env: process.env,
+    platform: process.platform,
+    stdoutIsTTY: Boolean(process.stdout.isTTY),
+    prompter,
+  });
+} finally {
+  // An open reader holds stdin open, and a process with an open stdin does not
+  // exit. Closed on every path, including the ones that refused.
+  prompter.close();
+}

package/context/features/example-feature-spec.md

@@ -1,4 +1,8 @@
-# [Feature Name]
+# Example Feature Spec
+
+> A worked example of the shape `to-specs` writes into this folder. Real
+> specs are new files here, titled with the feature's own name; copy
+> `templates/feature-spec.template.md` to start one.
 
 ## Status
 

package/context/project-overview.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/copy-list.json

@@ -4,7 +4,6 @@
     "AGENTS.md",
     "CLAUDE.md",
     "context",
-    "prompts",
     "skills",
     "templates"
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pathfinder",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Install the Pathfinder AI-assisted, human-in-the-loop workflow kit into a Git repository.",
   "keywords": [
     "pathfinder",
@@ -34,11 +34,11 @@
     "AGENTS.md",
     "CLAUDE.md",
     "context",
-    "prompts",
     "skills",
     "templates"
   ],
   "scripts": {
+    "test": "node --test",
     "stage": "node scripts/stage-kit.mjs",
     "unstage": "node scripts/stage-kit.mjs --clean",
     "prepack": "node scripts/stage-kit.mjs",

package/skills/reflect/SKILL.md

@@ -50,9 +50,9 @@ And:
 
 ---
 
-# Part 1 — Reflect on the work
+## Part 1 — Reflect on the work
 
-## 1. Reconstruct what happened
+### 1. Reconstruct what happened
 
 Review the relevant work and available evidence.
 
@@ -73,7 +73,7 @@ Do not rely on vague recollection when repository evidence is available.
 
 Distinguish what actually happened from what was intended to happen.
 
-## 2. Identify learning signals
+### 2. Identify learning signals
 
 Look specifically for:
 
@@ -96,11 +96,11 @@ Success alone is not evidence that the workflow was good.
 
 Failure alone is not evidence that the workflow must change.
 
-## 3. Separate local knowledge from reusable learning
+### 3. Separate local knowledge from reusable learning
 
 Classify each finding as one of:
 
-### PROJECT
+#### PROJECT
 
 Specific to this repository, stack, business domain, architecture, environment, or team.
 
@@ -113,7 +113,7 @@ Examples:
 * this service must start before another service
 * a framework-specific workaround is required
 
-### WORKFLOW CANDIDATE
+#### WORKFLOW CANDIDATE
 
 Potentially useful across unrelated projects.
 
@@ -125,7 +125,7 @@ Examples:
 * an undocumented dependency should have been discovered during system analysis
 * the agent repeatedly needed human correction for something the workflow could have surfaced earlier
 
-### NOISE
+#### NOISE
 
 Interesting but not useful enough to preserve.
 
@@ -133,7 +133,7 @@ Discard it.
 
 Not every observation deserves memory.
 
-## 4. Test generality
+### 4. Test generality
 
 For every WORKFLOW CANDIDATE ask:
 
@@ -149,7 +149,7 @@ If the lesson fails these tests, keep it project-specific.
 
 Generalize behavior, not technology.
 
-## 5. Check for existing coverage
+### 5. Check for existing coverage
 
 Before proposing anything new, inspect the existing Pathfinder workflow and skills.
 
@@ -169,41 +169,41 @@ Avoid duplicate skills.
 
 Do not respond to every failure by adding another instruction.
 
-## 6. Require evidence
+### 6. Require evidence
 
 Every proposed Pathfinder improvement must include:
 
-### Observation
+#### Observation
 
 What happened?
 
-### Evidence
+#### Evidence
 
 What concrete part of the execution demonstrates it?
 
-### Generalization
+#### Generalization
 
 Why could this recur outside this project?
 
-### Current gap
+#### Current gap
 
 Why does Pathfinder not already handle it?
 
-### Proposed change
+#### Proposed change
 
 What is the smallest change that would address it?
 
-### Risk
+#### Risk
 
 How could this rule become harmful, redundant, overly restrictive, or too specific?
 
-### Validation
+#### Validation
 
 How could future work demonstrate that the improvement actually helped?
 
 Do not promote intuition into workflow policy without evidence.
 
-## 7. Prefer the smallest durable improvement
+### 7. Prefer the smallest durable improvement
 
 Possible outcomes include:
 
@@ -222,7 +222,7 @@ An improvement should remove more uncertainty than complexity it introduces.
 
 ---
 
-# Part 2 — Reflect on Reflect
+## Part 2 — Reflect on Reflect
 
 Reflect is subject to the same evidence standard it applies to Pathfinder.
 
@@ -234,7 +234,7 @@ Its purpose is not to endlessly rewrite Reflect.
 
 Its purpose is to discover whether Reflect systematically failed to do its own job.
 
-## 8. Evaluate reflection quality
+### 8. Evaluate reflection quality
 
 Ask:
 
@@ -255,11 +255,11 @@ Do not search for a self-improvement merely because this section exists.
 
 "No improvement needed" is a valid and desirable result.
 
-## 9. Identify Reflect improvement candidates
+### 9. Identify Reflect improvement candidates
 
 If the reflection process itself demonstrated a meaningful weakness, classify it as:
 
-### REFLECT IMPROVEMENT CANDIDATE
+#### REFLECT IMPROVEMENT CANDIDATE
 
 This classification is reserved for improvements to `reflect/SKILL.md` itself.
 
@@ -267,23 +267,23 @@ Do not use it for general Pathfinder improvements.
 
 For each candidate provide:
 
-### Observed weakness
+#### Observed weakness
 
 What was inadequate about Reflect's behavior or reasoning?
 
-### Evidence
+#### Evidence
 
 What concrete output, omission, human correction, or repeated failure demonstrates the weakness?
 
-### Root cause
+#### Root cause
 
 What part of the current Reflect process allowed the weakness?
 
-### Proposed change
+#### Proposed change
 
 What is the smallest change to `reflect/SKILL.md` that could improve future reflections?
 
-### Regression risk
+#### Regression risk
 
 Could the change make Reflect:
 
@@ -295,7 +295,7 @@ Could the change make Reflect:
 * excessively conservative
 * more expensive in context or execution time
 
-### Validation
+#### Validation
 
 What future behavior would demonstrate that the modification actually improved Reflect?
 
@@ -303,11 +303,11 @@ Do not recursively optimize stylistic preferences, wording preferences, or isola
 
 Self-improvements must materially improve reflection quality.
 
-## 10. Evidence levels for self-improvement
+### 10. Evidence levels for self-improvement
 
 Treat evidence for changes to Reflect according to three levels:
 
-### Level 1 — Incident
+#### Level 1 — Incident
 
 One reflection exposed a plausible weakness.
 
@@ -315,13 +315,13 @@ This may justify an improvement candidate.
 
 It does not establish a general pattern.
 
-### Level 2 — Pattern
+#### Level 2 — Pattern
 
 The same weakness has appeared across multiple reflections or required repeated human correction.
 
 This provides stronger justification for changing Reflect.
 
-### Level 3 — Validation
+#### Level 3 — Validation
 
 A proposed change addresses the weakness and subsequent reflections demonstrate better behavior without obvious regression.
 
@@ -331,7 +331,7 @@ When history is available, prefer patterns over isolated incidents.
 
 Do not fabricate historical evidence.
 
-## 11. Bound the recursion
+### 11. Bound the recursion
 
 Reflect may perform only one self-evaluation pass per invocation.
 
@@ -355,9 +355,9 @@ Recursive improvement should accumulate evidence across executions, not consume
 
 ---
 
-# Promotion rules
+## Promotion rules
 
-## Pathfinder improvements
+### Pathfinder improvements
 
 Reflect proposes.
 
@@ -365,7 +365,7 @@ Humans promote.
 
 Do not silently modify Pathfinder's workflow, AGENTS.md, skills, templates, principles, or other durable guidance unless explicitly asked to implement an accepted recommendation.
 
-## Reflect self-improvements
+### Reflect self-improvements
 
 The same rule applies to Reflect itself.
 
@@ -379,21 +379,21 @@ It raises it.
 
 ---
 
-# Output
+## Output
 
 Return only sections that contain meaningful information.
 
 Do not inflate the output to satisfy the template.
 
-## What happened
+### What happened
 
 A concise reconstruction of the relevant execution.
 
-## What we learned
+### What we learned
 
 The important findings and supporting evidence.
 
-## Classification
+### Classification
 
 For each meaningful finding:
 
@@ -403,13 +403,13 @@ For each meaningful finding:
 
 Omit trivial noise when it adds no value.
 
-## Pathfinder gaps
+### Pathfinder gaps
 
 Only genuine gaps not already covered.
 
 If none exist, say so.
 
-## Recommended changes
+### Recommended changes
 
 Rank recommendations from highest to lowest value.
 
@@ -423,11 +423,11 @@ For each recommendation provide:
 * validation approach
 * confidence
 
-## No-change findings
+### No-change findings
 
 Mention important observations that should not modify Pathfinder and explain why.
 
-## Reflect self-evaluation
+### Reflect self-evaluation
 
 Briefly assess whether this reflection process itself performed adequately.
 
@@ -437,7 +437,7 @@ If no material weakness was discovered, state:
 
 Do not invent one.
 
-## Reflect improvement candidates
+### Reflect improvement candidates
 
 Include this section only when evidence supports changing `reflect/SKILL.md`.
 
@@ -454,7 +454,7 @@ For each candidate provide:
 
 ---
 
-# Principles
+## Principles
 
 > Execution is evidence.
 

package/skills/reverse-engineer/SKILL.md

@@ -183,6 +183,7 @@ Do not silently run or imitate the responsibilities of those skills.
 
 Use only the sections that add value:
 
+```markdown
 # Reverse-Engineering Report
 
 ## Objective
@@ -220,6 +221,7 @@ Complexity, accessibility, performance, maintenance, legal, or fidelity concerns
 ## Recommended Pathfinder Handoff
 
 The appropriate next skill, if any, and why.
+```
 
 ## Rules
 

package/skills/to-specs/SKILL.md

@@ -32,7 +32,7 @@ Split a feature when it mixes several systems, requires a repo-wide mental model
 
 ## Output
 
-Create only the coherent MVP roadmap in `context/features/`, using the example template and project-selected naming/delivery policies.
+Create only the coherent MVP roadmap in `context/features/`, using `templates/feature-spec.template.md` and project-selected naming/delivery policies.
 
 Each spec must include Context Boundary, Delivery Chunks, and Learning Targets.