Pathfinder is an agent skill plus a deterministic controller for Claude Code and Codex. It reads a codebase from the source up, ranks useful next moves, asks only the questions that affect the outcome, and forges a bounded, verifiable Goal. Its local host-driven bridge can journal one typed action at a time through a verified local branch. It runs only when the active host can prove its runtime boundary, expose a stable native Goal, and return truthful typed receipts; otherwise Pathfinder stops at the saved Goal/manual handoff.

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

🚀 Install

Claude Code

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

The namespaced command is for the plugin install. A manual Claude skill install uses /pathfinder.

Codex

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

Codex namespaces plugin skills as $plugin-name:skill-name, so the plugin form is $pathfinder:pathfinder. A manual Codex skill remains $pathfinder. Codex's native /goal command controls a durable Goal after Pathfinder has prepared one.

Marketplace installs use the immutable stable release tag. Repository main is the explicitly labeled edge channel for manual/development installs.

[!NOTE] Prefer no plugin system? Copy skills/pathfinder/ into ~/.claude/skills/ (Claude Code) or ~/.agents/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.

🗺️ Explore starts from code, tests, manifests, and configuration, then checks documentation only after that source-first pass so stale prose cannot define reality. It ranks the moves, adversarially verifies the top ones, asks focused questions, then forges the Goal. Existing creator intent can influence ranking, but ordinary exploration does not require the creator interview:

flowchart LR
    A["<b>1 · DISCOVER</b><br/><i>source-first, docs later</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>"]
    D["<b>5 · ASK</b><br/><i>a few sharp questions</i>"]
    E["<b>6 · FORGE /goal</b><br/><i>bounded · proven · ready</i>"]

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

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

🎯 Prompt-to-goal skips the full sweep and the Doctrine Interview. It researches only what your prompt touches, asks zero questions when outcome/proof/scope/safety/stop are already clear, 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 the explicitly gated /pathfinder auto route. The enabled bridge is one sequential local Goal: worktree → native Goal → implement → verify → commit → local awaiting review. It binds authority to the current request and base commit and journals each intent/receipt/result before advancing. It never activates from saved intent, derives an unbounded backlog, edits charter/doctrine policy, publishes, or self-merges. Unknown enforcement, missing native Goal identity, or an ambiguous action response stops or requires reconciliation. → Compatibility · 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 work-producing run leaves a clean, resumable trail. Only phases the route actually uses are emitted; a short placeholder is reserved for an expected phase that started but was interrupted:

.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/           compact findings for selected domains only
├─ 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
├─ goals/NNNN/                per-item bindings and controller views for a run-all 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 canonical private JSON documents persist across runs—charter.json (stable intent), roadmap.json (evolving work), and doctrine.json (Project Doctrine: end goal, quality bars, autonomy policy, and hard stops)—with generated Markdown views for humans. Repository intent lives in .pathfinder/; an explicit monorepo scope such as apps/api gets the isolated namespace .pathfinder/scopes/apps/api/intent/. Namespaces never inherit from root or siblings. All are gitignored via .git/info/exclude, never committed, schema-validated, 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.

The local autonomous bridge is the only path designed to commit without a per-step prompt. It cannot publish or open a PR. It is enabled only for an attested host, and all of these rules apply:

• 🧭 Fresh authority is required — intent guides selection but every run needs an explicit /pathfinder auto request.
• 🌿 Autonomous work is isolated — the attested host 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 — a versioned data registry classifies auth, payments, permissions, deployment, CI/CD, schemas, migrations, public APIs, and network egress; autonomous work requires declared scope, item-level eligibility, enforceable isolation, verification, and diff review. Explicit policy may add protection but cannot weaken the baseline.
• 🧱 The trust boundary holds — repo content can't redirect the goal or widen authorization.
• 🔑 Credentials stay out of the environment while repo code runs.
• ✅ No publication or self-merge — the enabled bridge stops at a local awaiting-review branch with no PR.
• 🛑 Unknown enforcement blocks autonomy — Pathfinder falls back to a saved Goal instead of claiming best-effort isolation.

🔬 Under the hood

🤝 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.

Operator and design references: compatibility/guarantees, operator recovery, protected surfaces, threat model, worked outcomes, and promise coverage.

_{CI guards Linux/macOS/Windows portability, schemas, controller crash/resume, recorded replays, manifest/version consistency, CodeQL, Scorecard, and dependency review.}