Pathfinder

A reusable workflow kit for directing AI agents through software delivery, while keeping judgment and consequential decisions human.

Website · npm · Changelog · Releases · Contributing

by Lamadrid Labs

Field kit PF-047 · the unfolding atlascope · a Wonder Wagon tool

Pathfinder is a small, portable set of skills, roles, context files, and templates you copy into a software project.

It gives AI agents a repeatable way to discover, plan, build, test, complete, debug, learn from, and reflect on software work — without turning the agent into the authority.

You remain responsible for direction, approval, acceptance, merge, release, and other consequential decisions.

Pathfinder is intentionally stack-agnostic. It does not choose React, Python, mobile, a database, hosting platform, Git model, or any other implementation detail for you.

The kit owns the workflow. The project owns the stack.

What Pathfinder is

Pathfinder is a workflow kit for working with coding agents.

It provides:

• skills — reusable procedures for common software-development work
• roles — small responsibility boundaries for an AI session
• context — durable project truth and temporary workspace state
• templates — minimal shapes for project records created when needed

Pathfinder gives you one disciplined workflow with two ways to operate it: work one ticket at a time with direct human control in human-in-the-loop mode, or let orchestrator mode coordinate several dependency-safe workers while surfacing only the human gates that need you.

Agents can recommend and execute work, but they do not silently make decisions that belong to you. See Execution modes.

It is also not an autopilot. Recommendations are proposals, not silent decisions — see Human approval.

Pathfinder is not an application framework. Orchestration adds isolated workers, dependency-aware scheduling, and fewer unnecessary interruptions to the same delivery discipline. It has no daemon, broker, queue, database, or server; no automatic merging, no bypassing review, and no unlimited agents.

There is no required:

• application framework
• package manager
• database
• hosting provider
• programming language
• Git branching model
• agent swarm
• background runtime

See NOT_A_FRAMEWORK.md.

The human-in-the-loop delivery workflow needs no runtime. The optional render-artifact engine and orchestrator mode need Node; orchestration also uses Git and, with GitHub Issues, gh. None adds a runtime dependency to your application.

Quick start

Create or enter a Git repository:

mkdir my-project
cd my-project
git init

Then run:

npx create-pathfinder

Pathfinder copies the kit into the repository. It does not install a runtime dependency into your application.

If you configure Claude Code or Codex during setup, Pathfinder also generates native skill adapters for that tool. The installer also asks how Pathfinder should run the project. Choose human-in-the-loop or orchestrator, or set it explicitly with npx create-pathfinder --mode orchestrator.

Your coding tool is the only service Pathfinder needs. An orchestrator project may also enable the optional Evidence Judge, which asks Jev, TypeSafe's structured-decision model, whether recorded Tester evidence supports a ticket's verification items before you approve a merge. Jev is a separate service with its own account and API key: your Claude Code or Codex access does not include it, and Pathfinder works fully without it. It is off unless you choose it.

Then start with:

/kickstart-pathfinder

That begins a short discovery process to understand the project, record the important decisions, and prepare the project for delivery.

If your tool does not support native skill discovery, use:

Use skills/kickstart-pathfinder/SKILL.md to initialize this project.

Claude Code users have a second option: install Pathfinder as a plugin, which brings every command without copying anything into the repository first. See Install as a Claude Code plugin.

Install as a Claude Code plugin

Pathfinder supports two installation paths. They install different things, and most people eventually want both.

	npx create-pathfinder	Claude Code plugin
Installs	the project kit — context/, lib/, roles/, templates/, skills/, CLAUDE.md, AGENTS.md	the commands, nothing else
Lives in	your repository, reviewed and tracked in Git	your Claude Code installation
Command form	/kickstart-pathfinder, with a generated adapter	/pathfinder:kickstart-pathfinder, always
Works with	any agent that can read files	Claude Code
Updating	re-run the installer	claude plugin update pathfinder

Add the marketplace, then install:

/plugin marketplace add rikilamadrid/pathfinder
/plugin install pathfinder@lamadrid-labs

The same two steps from a terminal:

claude plugin marketplace add rikilamadrid/pathfinder
claude plugin install pathfinder@lamadrid-labs

rikilamadrid/pathfinder is the repository; lamadrid-labs is the marketplace it declares. The marketplace name appears when you install and never again — it is not part of any command.

Commands are namespaced

Claude Code namespaces every plugin skill, with no way to opt out. Through the plugin, each Pathfinder skill is /pathfinder:<skill>:

/pathfinder:ticket load
/pathfinder:role planner
/pathfinder:whereami

The bare /ticket form comes from a generated adapter in your repository, which is the installer's job (npx create-pathfinder --agents claude-code). A repository with both installed has both forms. They run the same canonical skill body, so neither overrides the other and it does not matter which you type.

What the plugin does not install

The plugin distributes commands. It does not distribute project state. context/ is written per project and belongs to that project, so a repository reached only through /plugin install has every Pathfinder command and none of the files those commands read.

/pathfinder:kickstart-pathfinder closes that gap: in a project missing the kit, it offers to install it from the plugin's own copy, names every file before writing, overwrites nothing without asking, and deletes nothing. npx create-pathfinder remains fully supported and is the only path that also generates adapters.

A local or custom marketplace

Any clone can serve as its own marketplace — the repository is the plugin:

/plugin marketplace add ./
/plugin install pathfinder@lamadrid-labs

To try a working copy without installing anything, start Claude Code with claude --plugin-dir /path/to/pathfinder.

Updating, versions, and uninstalling

The plugin's version is the kit's version: one number in CHANGELOG.md, packages/create-pathfinder/package.json, and .claude-plugin/plugin.json, which CI keeps in agreement. claude plugin update pathfinder hands you a new version when a release changes that number, and never between releases.

claude plugin uninstall pathfinder removes the commands. Kit files in your repository are yours and survive it — deleting them is a Git operation you perform deliberately, not something an uninstall does behind you.

The workflow

The core Pathfinder flow is deliberately small:

idea
  ↓
kickstart / debate / prototype
  ↓
to-specs
  ↓
to-tickets
  ↓
choose the coordinator
  ├─ human-in-the-loop: you drive one ticket session
  └─ orchestrator: /orchestrate start coordinates isolated workers
  ↓
each claim: /ticket load → /ticket start → adversary (optional in human-in-the-loop) → independent review → human acceptance
  ↓
integration safety + human merge authority
  ↓
/ticket complete → next eligible work

Orchestrated delivery uses separate Developer, Adversary and Tester sessions on one claim. Adversary produces bounded reproducible experiments with potential impact and uncertainty; Tester alone confirms PASS or findings. Human-in-the-loop /ticket adversary is optional. Reports live transiently in the claimed context/current-ticket.md, tied to the exact PR head. Recovery resumes the recorded stage; confirmed repairs rerun Adversary then Tester. Integration-only refresh of unchanged behavior needs fresh Tester/CI without rerunning Adversary. Acceptance and final merge still require the human. An optional Evidence Judge can check the recorded evidence before that merge gate; it classifies, Pathfinder decides, and its absence or failure is never approval. Separately, optional routing assessment can recommend Tester, Adversary or Human for one unresolved concern. It is off by default, requires its own invocation-scoped consent, and leaves follow-up and dispatch under separate human/coordinator control.

A prototype is optional. Use one when an important assumption is cheaper to prove than to debate.

Features are small, focused, and independently verifiable.

When something is observably broken, the loop pauses and debug-issue runs instead of the agent guessing its way forward. It reproduces before repairing and tests hypotheses rather than editing at random. See When something breaks.

Supporting skills handle learning, reference analysis, handoff, reflection, and ticket-store selection when those are useful.

See the workflow guide for the complete model.

Automatic roles and explicit overrides

The normal lifecycle assumes its responsibility boundary automatically:

Invocation	Assumed role
kickstart-pathfinder, to-specs, to-tickets	planner
/ticket load, /ticket start, /ticket complete	developer
/ticket adversary (optional)	adversary
/ticket review	tester
/orchestrate status, start, resume	orchestrator
/orchestrate integrate	integrator

Pathfinder ships six:

Role	Responsibility
planner	Discovers project direction and produces Features and tickets
orchestrator	Coordinates dependency-safe workers without implementing their tickets
developer	Implements approved work without accepting its own work
adversary	Challenges implementation through experiments for Tester, without a verdict
tester	Independently verifies delivered work and reports findings
integrator	Checks whether reviewed work can land, under human merge authority

Use /role only when you want to override that default explicitly or debug a workflow under a particular boundary:

/role developer

They do not grant authority. The human always owns approval, acceptance, merge, release, and other decisions requiring judgment.

Know where you are

During a working session:

/whereami

gives you a compact orientation view such as the active role, current Feature, execution mode, Git state, and next action. In orchestrator mode, /orchestrate status shows all workers, worktrees, gates, and blockers.

When you need to stop and continue later:

/handoff

records only the minimum factual state another session needs to resume safely.

Start a new project

Running:

npx create-pathfinder

copies these kit entries:

Path	Purpose
AGENTS.md	Agent entry point for tools that use it
CLAUDE.md	Claude Code project guidance
context/	Project standards and interaction rules
lib/	Shared code more than one skill's engine needs
roles/	Planner, orchestrator, developer, adversary, tester, and integrator responsibility contracts
skills/	Reusable workflow procedures
templates/	Minimal starting shapes created when needed

lib/ is the entry you never open. It is code the skills' engines import, rather than guidance to read or a shape to copy — today the evidence-reference grammar that blog-post-redactor cites its evidence in — so that a skill needing the same rule imports it from here rather than from another skill's engine.

The installer never silently overwrites. Files you already have are left alone and listed by name in the summary.

Use:

npx create-pathfinder --dry-run

to preview changes, or:

npx create-pathfinder --force

when you want files that already exist overwritten — any file in the list above, whoever created or edited it — and a file you wrote at a path an adapter would occupy replaced.

Pathfinder installs only into a Git repository. If the current directory is not one, the installer explains why Git is required and can offer to initialize it for you. Declining leaves the project untouched.

Pathfinder's own CHANGELOG.md is not copied into destination projects. Projects that want a changelog can use:

templates/CHANGELOG.template.md

Add Pathfinder to an existing repo

Run:

npx create-pathfinder

inside the existing Git repository.

Pathfinder preserves existing files and project conventions. Nothing is overwritten unless you explicitly use --force.

Then run:

/kickstart-pathfinder

Kickstart inspects only what it needs to understand the existing project and separates repository facts from decisions that still require human input.

For deeper onboarding or architectural understanding, use:

/learn-codebase

Do not use reverse-engineer to analyze the repository Pathfinder is currently operating inside. That responsibility belongs to kickstart-pathfinder, learn-codebase, or the active ticket's lifecycle action.

Native to your tools

Claude Code and Codex can receive native Pathfinder skill adapters during installation.

The canonical behavior remains in:

skills/<name>/SKILL.md

Generated adapters simply make those skills available through the tool's own skill interface.

In a terminal you are asked which tools to configure, with the detected ones as the default. Without one, name them explicitly:

npx create-pathfinder --agents claude-code,codex

Nothing is configured unless you choose it, and choosing one tool never touches the other's directory.

Adapters are generated artifacts, not copy-list entries. The seven paths in the table above are the kit; adapters are derived from skills/ at install time and never added to copy-list.json.

The Claude Code plugin is a third way to reach the same canonical skills, and it generates nothing: it exposes skills/ directly, under the /pathfinder: prefix. Installing it adds no file to your repository, adapters included. See Install as a Claude Code plugin.

Re-running the installer refreshes Pathfinder-owned adapters while preserving your own configuration and unrelated skills.

The ownership rule is one sentence: 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, and nothing is ever deleted.

Without native skill support, invoke any Pathfinder skill directly:

Use skills/<name>/SKILL.md and follow it exactly.

For example:

Use skills/reverse-engineer/SKILL.md to analyze this reference.

Useful skills

Some common entry points:

Skill	Use it when
kickstart-pathfinder	Starting or adopting a project
debate-me	Pressure-testing a direction before committing to it
prototype	Proving an important assumption cheaply
to-specs	Turning approved direction into Features
to-tickets	Slicing one approved Feature into executable tickets
ticket	The delivery loop: load, start, adversary, review, complete
orchestrate	Coordinating isolated workers and controlled integration in orchestrator mode
debug-issue	Something is observably broken
handoff	Leaving factual state for another session
whereami	Getting quick session orientation
learn-feature	Learning from completed work
reflect	Improving the workflow from actual experience, kept in the improvement ledger
blog-post-redactor	Writing up shipped work from repository evidence
setup-tracker	Choosing where tickets live

The complete list lives in skills/ and on the Pathfinder website.

Ticket stores

Every project has a ticket store. With no configuration it is local Markdown files under context/tickets/, which needs no credentials and no dependency.

If your tickets belong somewhere else — GitHub Issues, Jira, Linear, Azure DevOps, something internal — run:

/setup-tracker

The store you choose is canonical. There is one ticket artifact and no copy of it in the repository, so there is nothing to sync and no way for a mirror to go stale. Feature specs are not tickets: they stay in the repository whatever store you pick.

Changing store later is a deliberate migration, not a background job.

Context stays small

A fresh Pathfinder install ships only the context needed immediately:

context/
├── ai-interaction.md
└── coding-standards.md

Other project context is created only when a workflow actually needs it.

For example:

context/project-overview.md
context/features/
context/tickets/          # only when local Markdown is the ticket store
context/history.md
context/tracker.md        # only when the store is not local Markdown
context/current-ticket.md
context/handoff.md

This avoids filling a new project with blank scaffolding.

What belongs in Git

The rule is simple:

Durable project truth is tracked.

Examples:

context/project-overview.md
context/features/
context/tickets/          # when local Markdown is the ticket store
context/history.md
context/tracker.md        # when it is not
context/execution-mode.md # when explicitly selected

Temporary session state is normally ignored.

Two paths belong to one session on one machine, and are two lines in .gitignore:

context/current-ticket.md
context/handoff.md

In orchestrator mode, also ignore /.pathfinder/, which holds local worker worktrees. Each worker has its own ignored context/current-ticket.md.

Do not ignore context/ wholesale. That would also hide the durable project truth future sessions need.

Teams that intentionally want to share workspace state can choose to track the transient files instead.

A project installed before v1.5.0 also has a prompts/ directory, which the installer leaves untouched and which keeps working, since those launchers point at skills/.

What's in the kit

.
├── AGENTS.md
├── CLAUDE.md
├── CHANGELOG.md                  # Pathfinder's own history
├── NOT_A_FRAMEWORK.md
├── context/
│   ├── ai-interaction.md
│   └── coding-standards.md
├── lib/
│   └── evidence-references.mjs
├── roles/
│   ├── integrator.md
│   ├── orchestrator.md
│   ├── developer.md
│   ├── planner.md
│   └── tester.md
├── skills/
│   ├── blog-post-redactor/
│   ├── challenge-me/
│   ├── debate-me/
│   ├── debug-issue/
│   ├── handoff/
│   ├── hooksmith/
│   ├── kickstart-pathfinder/
│   ├── learn-codebase/
│   ├── learn-feature/
│   ├── learning-review/
│   ├── map-system/
│   ├── orchestrate/
│   ├── prototype/
│   ├── quiz-me/
│   ├── reflect/
│   ├── render-artifact/
│   ├── reverse-engineer/
│   ├── role/
│   ├── setup-tracker/
│   ├── skillsmith/
│   ├── teach-architecture/
│   ├── teach-feature/
│   ├── ticket/
│   ├── to-specs/
│   ├── to-tickets/
│   └── whereami/
└── templates/
    ├── CHANGELOG.template.md
    ├── feature-spec.template.md
    ├── history.template.md
    ├── lesson.template.md
    ├── project-overview.template.md
    └── ticket.template.md

Generated harness files may also appear under:

.claude/skills/
.agents/skills/
.claude/hooks/pathfinder-session-orientation.mjs

The two skills directories hold adapters, derived from the canonical files under skills/.

The third is a session orientation handler, generated only for Claude Code. It is inert: Pathfinder writes no settings file, so nothing references it and nothing runs it. Add one SessionStart fragment to .claude/settings.local.json and a starting session receives your work state automatically; leave it alone and there is no automatic orientation and no other difference — whereami gives the same picture on demand. The fragment, the two activation surfaces, and the two-step removal are in Session orientation.

Learn more

The website contains the deeper guides that do not need to live in this README:

• Workflow
• Human approval
• Context boundaries
• Ticket stores
• Session orientation

The Wonder Wagon family

Pathfinder is PF-047 in the Wonder Wagon family of tools, beside Lorekeeper and Forge. It is the family's deepest consumer: the website's semantic colour layer uses Wonder Wagon tokens, and the installer's terminal identity is generated by wonder-wagon-ui/cli and checked for drift. The trail mark, the atlascope, and the workflow itself stay Pathfinder's own. See the Wonder Wagon Catalog.

Contributing

See CONTRIBUTING.md for development, pull request, versioning, release, and skill-contribution guidance.

Conduct expectations are in CODE_OF_CONDUCT.md.

Report security concerns privately according to SECURITY.md.

License

MIT — see LICENSE.

Copy Pathfinder into your own projects freely. The kit is licensed; what you build with it is yours.