Pathfinder v3.0.0

Removed

• load-feature, start-feature, review-feature, and complete-feature are gone as standalone skills. This is a breaking change to the public surface: those four commands no longer exist, and there is no alias, deprecation stub, or second path to the same behavior. The behavior itself is unchanged — it moved, it was not redesigned.

Added

• One feature skill with four actions. /feature load, /feature start, /feature review, and /feature complete replace the four commands. Four skills was four discovery surfaces for one loop that is always run in one order; the names already carried the shared noun, but nothing in a skill list could show that they belonged together, so a reader meeting them had to infer the sequence. skills/feature/SKILL.md dispatches and nothing more — it names the four actions, states the lifecycle they move a Feature through, and sends the session to one file under skills/feature/actions/. Invoked with no action it lists the four and stops, the way role does with no role name. argument-hint: load|start|review|complete puts the actions in front of the human at the moment they type the command.
• create-pathfinder --version prints the package version on one line and exits, with no identity block, no detection findings, and no colour. It is recognized before any other argument is interpreted, so it answers from outside a Git repository and from behind a misspelled flag or an invalid --agents value — a wrapper that appends --version to arguments it was handed still gets a version number. -v is the same flag.

Changed

• start records Ready → In Progress in the Feature spec's ## Status, before the first file edit of the first chunk. A Feature already In Progress is left alone, because continuing across sessions and chunks is normal; any other status stops the session rather than being promoted. This completes what load began in 2.1.0 — the spec now states what is actually happening to it at every stage.
• complete treats its own invocation as acceptance. The old step 1, "Confirm the Feature is accepted", is removed: the human running the action is the answer, and asking again was a question with only one possible reply. Acceptance of the Feature is still not approval of the delivery steps — every gate the project's documented workflow names is asked for exactly as before, and an undocumented or TBD Git policy still stops the session rather than being invented.
• review writes no status, now stated in the action rather than left to inference. Review is workflow activity, not lifecycle state, and a reviewed Feature stays In Progress until it is completed.
• context/ai-interaction.md is the one place the lifecycle is defined. skills/feature/SKILL.md restates Proposed → Ready → In Progress → Complete as a summary so a human reading the command can see which action writes which transition, and points back to the source. No summary adds a state or a transition of its own.
• /role states its roles inline through argument-hint: planner|developer|tester. The body is unchanged and no role file, name, or count changes.

Notes

• A destination project upgrading from 2.1.0 or earlier must relearn four commands. Nothing in an existing project breaks on its own — Feature specs, context/, and history are untouched — but any habit, script, or note naming the old commands has to be updated, and running npx create-pathfinder does not delete the four old skill directories it previously installed. Remove skills/{load,start,review,complete}-feature/ and their generated adapters by hand.
• The website publishes one page per top-level skill, so /skills/feature/ documents the four actions and the four old URLs are gone. Each action's full procedure ships in the kit, under skills/feature/actions/, and is not published as its own page.

Pathfinder v2.1.0

Changed

• load-feature promotes the spec it loads. Invoking the skill on a Feature is the approval to prepare it for execution, and until now that approval was recorded nowhere: the spec kept claiming Proposed while the work was already underway. load-feature now writes the spec's own ## Status — Proposed becomes Ready, and that is the only value it ever writes. A spec already Ready or In Progress is left exactly as it is, because reloading mid-work is normal. A Complete, Cancelled, or Superseded spec blocks the load and stops; reopening terminal work stays the human's decision. The write happens after the readiness checks and before context/current-feature.md, so a blocked load never leaves a promoted spec behind.
• context/current-feature.md records no status line. It is transient workspace state belonging to one session on one machine, and the spec carries the durable lifecycle status — which context/coding-standards.md already required. The rule against rewriting a loaded spec is narrowed to what it always meant: Goal, Context, Requirements, Out of Scope, Delivery Chunks, and Acceptance Criteria are not touched, and ## Status is the one field this skill maintains.

Notes

• A Feature loaded before upgrading needs nothing done to it. A spec left at Proposed is promoted the next time it is loaded, and one already past Proposed is never rewritten, so no existing spec has to be corrected by hand.
• Skill frontmatter is unchanged, so no harness adapter needs regenerating.

Pathfinder v2.0.0

A simplification release. Pathfinder had been accumulating structure faster than it was earning it — role files that restated procedure, templates carrying sections nobody filled in, and a context/ shipped full of blank stencils a reader had to recognise as empty before ignoring. This release removes that surface. The kit is smaller, and what remains is what a project actually uses.

The shape of the change: a fresh install is now 36 files instead of 43. context/ ships two files instead of six. Templates go from six to five, roles from four to three, and the feature spec from sixteen sections to eight.

Removed

• roles/qa.md and roles/human.md. qa is now tester, which does the same job under the name most projects already use. human is gone on purpose: human authority is not one contract among several that an agent might also read, and shipping a file describing it invited the exact misreading it was meant to prevent — that a session could name it and act with a human's authority. Approval and acceptance live in context/ai-interaction.md and nowhere else.
• templates/tracker.template.md — 370 lines of backend-neutral work-item model, item kinds, blocked-by edges, tag-mapping tables, chunk projections, and a marker specification. It asked every project to adopt a project-management taxonomy in order to use a feature most projects never turn on, and the great majority of it described trackers nobody had configured. setup-tracker now composes a config that fits the tracker you actually named.
• templates/progress-entry.template.md, and the blank context/ stencils: project-overview.md, history.md, current-feature.md, features/example-feature-spec.md, and the three context/learning/ placeholders.

Changed

• Files are created when a workflow first needs them, not scaffolded at install. context/ ships ai-interaction.md and coding-standards.md. Everything else — project-overview.md, features/, history.md, current-feature.md, handoff.md, tracker.md — is written by the skill that first needs it. Skills that read these files now treat absence as normal rather than as an error, and the skills that write them create what is missing.
• Roles carry responsibility; skills carry procedure. The three shipped roles state what a worker is responsible for, what it may read, and what ends its turn — and stop there. A role that starts explaining first do X, then do Y has become a skill, and CI now holds a 40-line ceiling to catch it.
• The feature spec template is eight sections: Status, Goal, Context, Requirements, Out of Scope, Delivery Chunks, Acceptance Criteria, Notes / Decisions. Context Boundary is now a three-line ## Context. Dropped: Overview, Problem, Dependencies, Tags, Experience Notes, Technical Notes, Verification, Learning Targets, and Suggested Delivery Metadata.
• Feature status is durable lifecycle state only: Proposed → Ready → In Progress → Complete, with Cancelled and Superseded terminal. Review and testing are optional workflow activity, not a status — a Feature stays In Progress until it is complete.
• context/project-overview.md records TBD and None. The parallel proposed / accepted / superseded record-status vocabulary is gone: two vocabularies meant every row invited two questions, and the second was almost always answerable from the first.
• A Feature spec is named NN-feature-name.md, and that number is the Feature's identity. to-specs numbers each new spec with the next unused number in the spec source, and 27-export-saved-searches.md is Feature 27 wherever the file sits. Numbers are never reused and never renumbered. The number lives in the filename and nowhere else — the eight-section template carries no number field, so there is no second place to keep in agreement. This is also what a published tracker item is matched on: with the 370-line tracker template gone, the key sync-tracker publishes under is read from the basename alone, never from the directory above it, the title inside it, or the order specs happen to be read. Moving or reorganising specs therefore orphans nothing, and a spec whose filename carries no number is skipped and reported by name rather than being assigned one.
• Work tracking stays optional and got smaller with it. sync-tracker no longer decomposes a Feature into assignable tickets, and infers no labels, tags, or status. The repository stays canonical, sync stays one-way, and a second run with no changes still writes nothing.

Added

• Roles: three declarative contracts that scope a session to one responsibility. roles/ ships planner, developer, and tester, each stating what a worker is responsible for, what it reads, what ends its turn, and what it must not do. They hold the constraints a skill cannot, because a skill cannot see what preceded it: tester forbids continuing into start-feature in the same session to repair what it just found. Naming a role is the only thing that activates one, so a project that never names one behaves exactly as it did in 1.8.0. They are plain Markdown carrying no model, tools, or isolation, which is why they need no adapter and work unchanged in any tool that can read a file. The copy list moves from five entries to six, its first addition since it was created.
• role — activate one named role for the current session, in one line.
• whereami — a read-only snapshot of the current session: role, Feature, chunk, Git state, and next action. It reads one file, reports none rather than inferring, and never offers to fix what it finds.
• templates/history.template.md — the compact completed-work record complete-feature appends to.
• A version-control policy for context/. Durable project truth is tracked (project-overview.md, features/, history.md, tracker.md); transient session state is ignored (current-feature.md, handoff.md). Two lines in .gitignore are the whole mechanism, and the documentation is explicit that ignoring context/ wholesale is the mistake to avoid — it quietly untracks the file documenting your stack.
• Work tracking can find your specs wherever you keep them. context/tracker.md names the project's spec source, and setup-tracker asks for it only when it is not context/features/. A config that names none behaves exactly as it did in 1.8.0.

Fixed

• context/tracker.md can no longer be shipped by accident. 1.8.0 said the file does not ship, and that was true only because none had ever existed in the kit repository — context is a directory entry in the copy list, so a config placed beneath it would have been copied into every new project, handing them a tracker they do not own with work tracking's off switch already defeated on first install. No released version ever shipped one; this closes the gap before it could open.
• context/current-feature.md and context/handoff.md are covered by the same guard. Having stopped shipping blank stencils, the risk inverts: a maintainer's filled-in copy reaching a new project, so somebody's first session opens on a note about whichever feature was loaded on release day. A .gitignore entry does not prevent this — the publish-staging script copies from the working tree and never consults Git — so the installer and the staging script both refuse to carry these files, and tests cover both paths.

Upgrading

Nothing is deleted from a project that already has Pathfinder; re-running the installer adds what is missing and leaves your edits alone. Adopt at your own pace:

• If you named the qa role, name tester instead. If you relied on roles/human.md, the policy it pointed at is in context/ai-interaction.md.
• Feature specs written against the old template still read fine. New specs get the eight-section shape.
• If a spec sits in In Review or Accepted, move it to In Progress or Complete.
• Add the two transient context/ files to .gitignore.
• If you configured work tracking, your context/tracker.md keeps working. The template it was written from no longer ships.
• Rename existing specs to NN-feature-name.md before your next sync-tracker run. Preserve the numbers already published — give each spec the number its tracker item carries today, rather than renumbering from one. A spec that reaches sync without a number in its filename is skipped and reported; a spec that reaches it under a different number publishes a second item beside the first. If you have never configured a tracker, rename at your leisure: nothing outside the repository depends on the numbers yet.

Pathfinder v1.8.0

Added

• Optional work tracking, configured in prose rather than code. A new setup-tracker skill interviews you for which tracker you use, where it lives, how an agent reaches it, and which tags your project actually uses — then writes context/tracker.md from templates/tracker.template.md once you approve it. Two projections ship, both proven against real backends: GitHub Issues via the gh CLI, and local Markdown files under .work/. Any other tracker is supported by describing it in prose, which is the mechanism rather than a gap — it is why this adds no runtime, no dependency, and no credential handling to the kit.
• templates/tracker.template.md — one file carrying the backend-neutral work-item model once and both projections beneath it. The model is byte-identical whichever backend you pick, and the template marks its own boundaries so that claim is checkable in one place rather than asserted twice.
• sync-tracker publishes your approved feature specs, and a second run writes nothing. It reads context/tracker.md, publishes in dependency order with blockers first, and reports what it created, edited, and left alone. Re-running when nothing has changed issues zero writes — not writes that happen to be no-ops. Comparison is normalized rather than byte-for-byte, tag sets are compared as sets, and item bodies are composed as a pure function of the spec, because each of those is a way for sync to look like it works while rewriting every item forever.
• Work tracking happens during normal work, not as a stage to remember. to-specs offers to publish once specs are written, load-feature names the tracked item, and complete-feature reconciles it after the merge. start-feature deliberately publishes nothing: a delivery chunk is internal, and finishing one is not an event the outside world needs. Each is one conditional line that does nothing at all without a config.
• An approval boundary for writes that leave your repository, in context/ai-interaction.md alongside commits and releases. Publishing to a shared tracker asks first; writing local files under .work/ does not, because it reaches nothing outside your repository.
• An optional ## Tags section in templates/feature-spec.template.md, which is the only place a published item's tags come from. Tags are never inferred from a title or a path, a spec without the section publishes untagged, and that is the expected case — the section is meaningful only once a tracker is configured, and nothing else in Pathfinder reads it.

Notes

• Work tracking is off unless you ask for it, and the off switch is the absence of a file. No context/tracker.md ships, nothing prompts you for one, and no existing skill behaves differently without it. A project that never runs /setup-tracker sees no change of any kind from this release.
• Configuring a tracker publishes nothing. setup-tracker writes a config and stops; it never contacts a tracker. Publishing is sync-tracker, and it asks before the first write that leaves your repository.
• Sync is one-way, and the repository stays canonical. Nothing reads tracker state back into a spec, context/current-feature.md, or context/history.md. A ticked checkbox on a published item means nothing to Pathfinder, and items are matched by key rather than title, so renaming one on the tracker breaks nothing.
• Nothing here is something an existing project has to adopt. Upgrading does not require configuring a tracker, and it does not require adding ## Tags to any feature spec — existing specs stay valid exactly as written, and specs written after the upgrade only get a tags section if a tracker config defines namespaces to fill it. The whole of work tracking is opt-in, and staying opted out is a supported way to use Pathfinder rather than a deferral.

Pathfinder v1.7.0

Added

• Every question the installer asks is answerable with the arrow keys. ↑/↓ (or k/j) move, Space toggles a checkbox, Enter confirms, and Escape cancels. The harness question becomes a checkbox list that names the directory each tool writes to, and a Yes/No question becomes two rows rather than a letter to type — y and n still work and are deliberately not advertised.
• PATHFINDER_PROMPT=classic asks the old way, on purpose. The numbered/y n prompts are a supported path rather than a fallback, and are byte-identical to 1.6.0. They are the first-class answer for a screen reader, for which a repainting block re-announces itself on every keypress and a highlight carried by position conveys nothing. Documented in --help, not only here.
• theme.line.up(n) — one new escape primitive, cursor-up, joining the two the theme already exposed. There is still no cursor hiding anywhere in the package, which is why an interrupted run cannot leave a terminal with an invisible cursor.

Changed

• Keyboard selection is offered only where it can be drawn correctly. It needs a terminal on both ends, TERM that is not dumb, an input that can be put into raw mode, and at least 49 columns — the measured width below which the interaction hint or the path context would be cut mid-word. Anything narrower asks the classic way. The capability is deliberately independent of colour and Unicode: NO_COLOR is a statement about decoration, not about repainting.
• (detected) is shown only when the whole row fits, and omitted rather than truncated when it does not. The ENVIRONMENT block has already reported detection, so the suffix duplicates information rather than carrying it — which is why it does not get to raise the width floor. Deciding that needs a real width: the installer now measures what a terminal will draw rather than what .length counts, so a decorated string is no longer measured as longer than it looks and a wide glyph no longer as narrower. A repainting list depends on it — a line believed to be one row that wraps to two puts every cursor-up afterwards off by one.
• The harness question's alignment moved out of cli.mjs. The call site now supplies a label, the path it writes to, and whether it was detected, and the renderer decides where each goes. It previously measured its labels with .length and padded them by hand, which is wrong about a terminal by the length of any escape sequence and produced a layout only one of the two prompt styles could use.

Fixed

• prompt.mjs no longer claims "No setRawMode". node:readline enables raw mode itself the moment its input is a terminal. What is true, and is what the interrupt guarantee actually rests on, is that readline owns raw mode and Pathfinder never touches it — the selector borrows readline's keypress and resize listeners and gives both back.

Pathfinder v1.6.0

Added

• create-pathfinder looks and sounds like Pathfinder. In a terminal, a run now opens with the Pathfinder mark drawn from assets/logo.svg — four strokes tapering upward, in blaze orange #E0611F — beside a letterspaced wordmark, the version, and a tagline. The run is then divided into named phases with a gutter down the left of each: ENVIRONMENT, INSTALLING, and SUMMARY. It ends on a completion state that repeats the mark as a bookend and signs off, replacing an ending that used to be a subordinate clause about whichever editor had just launched.
• A determinate progress bar during the install. The denominator is the number of units in the file-copy and adapter plans, both of which are computed in full before a single byte is written; the numerator is units that actually completed. Nothing is estimated, no percentage is synthesised, and there is no timer anywhere in the package — the bar advances on completion events alone, so an install that finishes in one tick shows a full bar in one tick and moves on. A failed write leaves the bar visibly short rather than rounding up to a clean 100%.
• The brand colour renders at whatever depth the terminal advertises. A terminal claiming truecolor (COLORTERM, or a -direct TERM) gets #E0611F exactly; one claiming 256 colours gets index 166, the nearest cell of the colour cube; anything else gets the one warm accent the eight ANSI values offer. With colour off, the mark's shape carries the identity on its own. Colour depth affects that one colour and nothing else — every severity stays on the eight ANSI values, and no depth can change what a run prints.
• Warnings are told apart from successes at a glance. Skipped files, adapter conflicts, and orphan adapters each render at the warn level with their own glyph and a leading category word — Skipped, Conflict, Orphan — so the hierarchy survives with colour disabled, in ASCII, and for a colour-blind reader. Adapters already up to date and --force overwrites are reported without being raised to warnings.

Changed

• Diagnostic paths are printed plain and stay pasteable. The file lists under a skipped, conflict, or orphan warning carry no glyph, no colour, no gutter, no truncation, and no wrapping, so selecting them and pasting them into an issue yields paths a maintainer can act on unedited.
• The installer's terminal output is now a presentation, and its non-interactive output is not. Piped, redirected, and NO_COLOR runs are byte-identical to what 1.5.1 produced for every pre-existing scenario, verified by running this build beside the published create-pathfinder@1.5.1 and comparing captured bytes. The decorated rendering and the byte-compatible one live side by side in the source for that reason. A terminal that reports no Unicode still gets the full structure in ASCII.
• --help is unchanged. It stays plain reference output with no identity block, because it is read mid-task and piped to a pager.
• AGENTS.md no longer names a "launcher". The fallback invocation line is unchanged; it just stops referring to a file a fresh install has never had. prompts/ was retired in v1.5.0.
• create-pathfinder's homepage is the documentation site rather than the GitHub README anchor, and its README is scoped to CLI and package usage. Both reach npmjs.com on the next publish.

Fixed

• create-pathfinder now writes ASCII punctuation on terminals that asked for ASCII. Seven strings printed an em dash or an ellipsis regardless of what the terminal could render, bypassing the fallback that already governed the tick and cross marks. A UTF-8 terminal sees exactly what it saw in 1.5.1; a terminal with a non-UTF-8 locale — LANG=C, and a Windows console that is neither Windows Terminal nor VS Code — now reads Next step - give your agent this prompt:, Something else..., Not copied - …, Not opened - …, X is supported - …, and Re-run with --force to replace it/them - … instead of mojibake. The tool-selection list's arrows shift two columns in ASCII mode to follow the widened Something else... row.

Pathfinder v1.5.1

What's Changed

• Describe the released 1.5.0 installer on the site (Feature 14, chunk 4) by @rikilamadrid in #22
• docs: check npm auth before the release tag is pushed by @rikilamadrid in #23
• Deploy the documentation site from site/ on Vercel (Feature 08) by @rikilamadrid in #24
• Sharpen verification evidence and feature completion (Feature 19) by @rikilamadrid in #25
• Release v1.5.1 by @rikilamadrid in #26

Full Changelog: v1.5.0...v1.5.1

Pathfinder v1.5.0

Pathfinder now configures itself for the coding tool you actually use.

Frictionless start

npx create-pathfinder no longer refuses to run outside a Git repository. It explains why version control is required and offers to run git init — only git init, only in the current directory, never in a parent. Decline and nothing is written.

Before it writes anything it reports what it found: whether this is a repository, whether git is on your PATH, whether Pathfinder is already installed, and which supported tools are available. Findings set defaults and nothing else.

Native skill discovery

Pathfinder's skills now appear in your tool's own skill list instead of being a path you paste.

• Claude Code — adapters generated at .claude/skills/<name>/SKILL.md, invoked as /reflect
• Codex — adapters generated at .agents/skills/<name>/SKILL.md, invoked as $reflect

Pick one, both, or neither. In a terminal you are asked, with detected tools as the default; a scripted run configures nothing unless --agents claude-code,codex says so. Choosing one harness never generates, removes, or claims anything under the other's directory, and a personal skills directory such as $HOME/.agents/skills is never touched.

The question's last entry is Something else…, and it generates nothing. Name a tool Pathfinder cannot configure and it says so plainly, then names the two things that do work — AGENTS.md at the repository root, and the line the adapters delegate to anyway.

One behavior contract, in one place

Canonical skills live under skills/ and are the only behavior contract. Everything under .claude/skills/ or .agents/skills/ is a generated pointer to one, rendered from the canonical skill's frontmatter alone — so editing a skill body produces byte-identical adapters. Edit the canonical file; regenerate the adapter.

prompts/ is retired

A fresh install copies five entries instead of six. Every launcher in prompts/ was a wrapper that delegated by path to skills/<name>/SKILL.md, and its stated purpose — a fallback for tools that cannot discover local skills — was never what it did: a tool too weak to find a local skill is not helped by a second local file telling it to open the first one.

An existing project keeps its prompts/ directory. The installer only ever writes, so re-running over a 1.4.x project leaves those files byte-for-byte intact, and they keep working because they point at skills/, which still ships. No migration command, no cleanup step, no deprecation shim.

Onboarding

Every install ends by printing the one prompt that starts a session, matched to the tool you configured — /kickstart-pathfinder, $kickstart-pathfinder, or the neutral form for both or neither. In a terminal you are then asked whether to copy it, with the question saying that it replaces what is on your clipboard now. Nothing is copied without an explicit yes, no clipboard is ever read, and the prompt is printed either way.

The last question offers to open the project — only in an editor already on your PATH (code, cursor), never one you do not have. Both the copy and the launch are conveniences: if either fails, the installer says so in one line and still exits 0.

Safe, non-destructive upgrades

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.

The installer owns a file at an adapter path only if the name is a Pathfinder skill and the file carries the pathfinder:adapter marker it wrote. Your settings.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. Nothing is ever deleted.

That is how a project installed before v1.5.0 gains adapters — one ordinary run.

New flags

--agents <ids>, --git-init, --no-git-init, --yes (alias --no-input), --no-clipboard, --no-open.

Questions are asked only when stdin and stdout are both terminals. Piped, redirected, or in CI, nothing is asked and nothing is prompted for.

---

Full detail in CHANGELOG.md.

Pathfinder v1.4.1

A PATCH: four content corrections to files a destination project consumes. No skill gains or loses a responsibility, and the install path is unchanged.

Fixed

• skills/reverse-engineer/SKILL.md fences its report template. The # Reverse-Engineering Report block was live markdown, so the file read as though it contained a report rather than describing the one to produce. Wording unchanged.
• skills/reflect/SKILL.md uses one H1. The Part 1, Part 2, Promotion rules, Output, and Principles dividers were H1s with H2s beneath. Every heading from the Part 1 divider drops one level; prose is byte-identical.
• context/project-overview.md and templates/project-overview.template.md are titled Project Overview, with the project's name captured as a Project: field instead of standing in for the document's own title.
• context/features/example-feature-spec.md says it is an example and names templates/feature-spec.template.md as the stencil to copy. skills/to-specs/SKILL.md points at that template by path.

Existing projects are unaffected — the installer never overwrites, so these arrive only on a fresh install or an explicit --force.

npx create-pathfinder@1.4.1

Pathfinder v1.4.0

Pathfinder has a skill for diagnosing a failure, instead of leaving it to the skill built for planned construction.

npx create-pathfinder@1.4.0

debug-issue

The delivery loop ran specs → load → start → review → complete. A failing test, a runtime error, or a regression fell to start-feature, which is built for planned construction and has no rule against editing until the symptom goes away. debug-issue is the twentieth skill and it owns that case.

It establishes expected behavior, actual behavior, and reproduction status before proposing a fix. It states a small ranked set of hypotheses and tests the cheapest one that meaningfully reduces uncertainty, changing one explanatory variable at a time. Then it applies the smallest justified fix and verifies against the original failure and the nearby behavior that fix could have affected.

Reproduce before repairing.

A symptom disappearing does not count as a root cause. When the evidence only supports a probable cause or a workaround, the skill is required to say so.

It stops instead of thrashing

The failure mode this exists to prevent is an agent making twenty edits and reporting success. debug-issue has explicit stop conditions: when the evidence runs out, when the reproduction is too unstable to learn from, or when the fix would require an architectural, dependency, security, or destructive change the human has not approved. It reports what has been ruled out rather than continuing.

Where it sits

Debugging interrupts the delivery loop rather than living inside it, and the boundary against its neighbours is documented in the README:

debug-issue     = an observed failure needs an explanation
start-feature   = planned construction is difficult
review-feature  = completed implementation needs inspection for defects
learn-codebase  = the real question is understanding the repository

It is for a concrete unexpected behavior — a failing test, runtime error, regression, incorrect output, integration failure, environment-specific or intermittent failure. Not for work that is merely hard.

What a destination project receives

Three files, 241 insertions:

• skills/debug-issue/SKILL.md
• prompts/15-debug-issue.md — the manual launcher, for tools that do not discover local skills
• CLAUDE.md — one line adding the skill to the list an agent reads

Upgrading an existing project

Run npx create-pathfinder@1.4.0 in it. The installer never overwrites, which matters here:

  2 files written
  54 files left untouched because they already exist

You get the skill and its launcher. You do not get the CLAUDE.md change, because your CLAUDE.md already exists and the installer will not touch it. If you want your agent to discover the skill from that list, add the line yourself:

- `debug-issue` — diagnose an observed failure to its root cause, apply the smallest justified fix, and verify it

Invoking the skill directly works either way:

Use skills/debug-issue/SKILL.md. Debug the failure I describe.

Also included in the repository at this tag, but outside the versioned kit scope

The Astro Starlight documentation site, which reads skills/ and context/ in place. site/ is not copied by create-pathfinder, so under Pathfinder's documented version-scope policy it does not independently require an npm/version bump.

Full changelog: https://github.com/rikilamadrid/pathfinder/blob/v1.4.0/CHANGELOG.md