🧭 Pathfinder

Map the codebase  ·  Pick the path  ·  Forge the goal

Drop it on any unfamiliar repo — get back a bounded goal you can run,
or the reviewed pull requests themselves.

Pathfinder is a small agent skill for Claude Code and Codex. It reads a codebase from the source up, ranks the highest-value next moves, asks a few sharp questions, and forges a bounded, verifiable /goal you can run or hand to another agent — or, once it understands your intent deeply enough, runs the work itself and lands reviewable pull requests.

No micro-managing exploration. No guessing where to start.

🚀 Install

Claude Code

/plugin marketplace add chrisduvillard/pathfinder-skill
/plugin install pathfinder@pathfinder
/pathfinder

Codex

codex plugin marketplace add chrisduvillard/pathfinder-skill
codex plugin add pathfinder@pathfinder
# then run /skills, or type $pathfinder to invoke it

Note

Prefer no plugin system? Copy skills/pathfinder/ into ~/.claude/skills/ (Claude Code) or ~/.codex/skills/ (Codex). Full notes in README-INSTALL.md.

🧭 Three ways to use it

Bare /pathfinder opens a chooser so you can see every path before anything starts. All three build toward the same bounded, self-proving /goal.

	Reach for it when	Kick it off with
🗺️ Explore	you're new to the repo and want the best next move	Use the pathfinder skill on this repository.
🎯 Prompt‑to‑goal	you already know the task	Pathfinder, turn this into a /goal: <the work>
⚡ Autonomous (clarity-gated)	you want it done hands-off	Run Pathfinder autonomously on this repository.

🗺️ Explore reads the code itself — never the README, so a stale or missing doc can't mislead it — ranks the moves, adversarially verifies the top ones, captures your intent (charter, roadmap, doctrine + clarity gate), asks a few sharp questions, then forges the goal:

flowchart LR
    A["<b>1 · DISCOVER</b><br/><i>read code, not docs</i>"]
    B["<b>2 · SCOUT</b><br/><i>brief each domain</i>"]
    C["<b>3 · SYNTHESIZE</b><br/><i>rank the next moves</i>"]
    V["<b>4 · VERIFY</b><br/><i>adversarially re-check</i>"]
    G["<b>5 · DOCTRINE</b><br/><i>capture intent · clarity gate</i>"]
    D["<b>6 · ASK</b><br/><i>a few sharp questions</i>"]
    E["<b>7 · FORGE /goal</b><br/><i>bounded · proven · ready</i>"]

    A --> B --> C --> V --> G --> D --> E

    classDef step fill:#0F172A,stroke:#2DD4BF,stroke-width:2px,color:#E6EDF3;
    classDef gate fill:#0F172A,stroke:#A78BFA,stroke-width:2px,color:#DDD6FE;
    classDef forge fill:#0F172A,stroke:#F59E0B,stroke-width:2px,color:#FBBF24;
    class A,B,C,V step;
    class G gate;
    class E forge;

Loading

🎯 Prompt-to-goal skips the full sweep and researches only what your prompt touches, then forges the same bounded goal:

Pathfinder, turn this into a /goal: stop the dashboard empty-state from crashing when the API returns no rows

⚡ Autonomous is /pathfinder auto as Full Autonomous Mission Mode. It runs only after the clarity gate resolves: Pathfinder has built local doctrine (.pathfinder/doctrine.md, marker pathfinder:doctrine v1) plus the charter and roadmap, and each goal clears a model-depth proof gate. It creates an isolated mission worktree, then loops hands-off: branch → implement → verify → commit → push → open a PR → merge only if branch protection positively allows it. When roadmap work runs out, the Autonomous Opportunity Scout derives more doctrine-aligned candidates. Work needing review lands as an awaiting-review PR and the loop continues until the work is done, blocked, unsafe, capped, or out of budget. → Safety

✨ What a run looks like

You say:

Use the pathfinder skill on this repository. Start the full Pathfinder process.

Pathfinder maps the repo and hands back a route:

Best next move : fix the dashboard empty-state crash
Scope          : dashboard data loading and tests only
Proof          : regression test passes, typecheck passes, changed files listed
Goal           : /goal Fix the dashboard empty-state crash so users see a useful
                 empty state instead of a blank page; npm test exits 0; tsc clean;
                 no schema change; between loops note what changed and pick the next
                 fix; stop after 12 turns, then report the blocker and next input needed.

That /goal is bounded, measurable, and self-proving — paste it into Claude Code or Codex and it works toward the condition across turns until it holds.

📦 What you get

Every run leaves a clean, resumable trail inside the repo:

.agent-work/pathfinder/<date>-<task>/
├─ 00-session.md              repo root, branch, tooling, objective
├─ 01-blind-discovery.md      what the repo actually is
├─ 02-scout-briefs/           located, evidence-graded findings per domain
├─ 03-synthesis.md            ranked next moves + risks
├─ 03b-verification.md        adversarial check of the Top 5 (grades, rejects, re-rank)
├─ 04-question-funnel.md      the choices put to you
├─ 05-user-answers.md         what you picked
├─ 06-goal-command.md         a ready-to-copy /goal or grouped goal pack
├─ 07-run-log.md              progress if the goal is run
├─ 07b-cross-model-review.md  optional second-model review packet
├─ 08-final-summary.md        what was explored, found, and decided
├─ 03-candidates.json         machine-readable candidate/search record
├─ 03b-verification.json      machine-readable verifier decisions
├─ 06-goal-binding.json       machine-readable goal/adaptor binding
├─ 07-run-log.json            machine-readable execution ledger
└─ 08-final-summary.json      machine-readable final ledger

Markdown is the human view; JSON sidecars are the eval/replay/search view. That keeps the skill readable while giving stronger future models stable contracts to optimize against.

Three private files persist across runs — .pathfinder/charter.md (stable intent), .pathfinder/roadmap.md (evolving work), and .pathfinder/doctrine.md (Project Doctrine: end goal, quality bars, autonomy policy, and hard stops). All are gitignored via .git/info/exclude, never committed, and sanitized on every read.

🔒 Safety

Every repo file is treated as untrusted data. Pathfinder won't run scripts, install packages, read secrets, or push changes without your say-so, and it redacts tokens and private paths from its artifacts.

Autonomous mode is the one path that commits and merges without a per-step prompt. Even then:

• 🧭 Doctrine is required — missing, stale, incomplete, tracked, or contradicted doctrine triggers the interview before autonomy can run.
• 🌿 Autonomous work is isolated — /pathfinder auto creates a mission worktree before edits, using <repo-parent>/.pathfinder-worktrees/<repo-name>-<timestamp>-auto> when possible.
• 🔐 Irreversible/external hard stops stay blocked — secrets/credentials, destructive data operations, releases, repo visibility/remotes/default-branch changes, force-pushes, branch/tag deletion, and real-world external side effects.
• 🧪 Protected areas need proof — auth, payments, CI/CD, schemas, migrations, public APIs, and network-related code can be improved autonomously only with doctrine alignment, scoped proof, verification, diff review, and branch-protected merge gates.
• 🧱 The trust boundary holds — repo content can't redirect the goal or widen authorization.
• 🔑 Credentials stay out of the environment while repo code runs.
• ✅ Self-merge is default-deny — only on a positive branch-protection signal; anything that needs review lands as an awaiting-review PR.
• 🛑 Doubt blocks autonomy — no escalation on a fresh repo or while any blocking question is open.

🔬 Under the hood

How it ranks, verifies, and proves work

• Reads the source, not the docs. The current default uses five domain scouts (architecture, frontend/product, backend/data, testing/reliability, DX/security) and a ranked Top 5, but those are adaptive strategies: future stronger models can search shorter or deeper routes while satisfying the same evidence and sidecar contracts.
• Adversarial verification. The default blind three-verifier panel re-checks top candidates, downgrades or rejects the weak ones, and surfaces a Verified: grade. Low-risk work can take cheaper paths; protected, autonomous, or contested work uses deeper verification.
• Pick the work your way. Choose from ranked candidate cards, drill down intent → domain → surface → target → boundaries, or select several moves as a numbered goal pack.
• Proof bound to the goal. Each goal records a Goal Binding plus capability profile; run logs and summaries record the Runtime Boundary and Binding Status, so "done" is checked against the original objective instead of drifting into looks-done prose.
• Optional cross-model review. After a run, Pathfinder can hand the goal, diff, and checks to the best available reviewer capability profile for goal-bounded fixes — recorded in 07b-cross-model-review.md, or a manual handoff packet if no safe launcher is available.

How it learns your intent (charter, roadmap, doctrine)

On first use, Pathfinder runs the Doctrine Interview: up to 8–12 compact, value-of-information questions about purpose, users, success, constraints, non-goals, finished state, future capabilities, product philosophy, quality bars, improvement heuristics, autonomy policy, and hard stops. It keeps asking until no blocking doubt remains (the clarity gate) and skips questions whose answers would not change the goal, proof, safety, or autonomy decision. It saves stable intent to .pathfinder/charter.md, evolving work to .pathfinder/roadmap.md, and the deep end-state model to .pathfinder/doctrine.md. Later runs reuse all three, show their influence, reconcile them against the current code, and let you refresh or override with /pathfinder charter.

Checking state without starting work

Run /pathfinder status (or "Show Pathfinder status.") for a read-only look at safe local state — repo/branch, whether the charter, roadmap, and doctrine exist and are complete, the latest run, and the available paths — without creating artifacts or triggering the interview.

🤝 Contributing & support

Contributions are welcome when they keep Pathfinder safe, bounded, and easy to run on unfamiliar repos. Start with CONTRIBUTING.md; get usage help in SUPPORT.md; report vulnerabilities privately via SECURITY.md, not public issues. Version and changelog live in VERSION.md.

_{CI guards manifest/version consistency, artifact evals, CodeQL scanning, OpenSSF Scorecard, and dependency review.}

Map the codebase  ·  Pick the path  ·  Forge the goal

_{MIT licensed · built for Claude Code and Codex}