Codex Wayfinder

Codex Wayfinder is a governance skill for a deliberate two-conversation workflow:

  • Codex charts the route, writes the prompt, and verifies the result.
  • You copy the prompt into a separate Claude Code conversation.
  • Claude Code implements one bounded tranche and returns a structured report.
  • You paste the report back into Codex for independent review.

There is no agent-to-agent transport, MCP server, hook, shared queue, or hidden automation. The manual handoff is the control boundary.

Version française

Why this exists

Matt Pocock's Wayfinder has a strong core idea: for large, foggy work, map decisions instead of pretending the entire implementation path is already known.

This project adapts that idea to a different operating model. It separates:

  • a navigation plane for destination, decisions, frontier, fog, and scope;
  • an execution plane for one Claude prompt, one report, and one Codex verdict.

Codex is the single writer for governance state. Claude Code is a bounded executor, not a second planner or acceptance authority.

sequenceDiagram
    participant U as User
    participant C as Codex lead
    participant A as Claude Code executor

    C->>C: Chart destination, decisions, frontier, fog
    C-->>U: CLAUDE_EXECUTOR_PROMPT_V1
    U->>A: Manual copy/paste
    A->>A: Implement one bounded tranche
    A-->>U: EXECUTOR_REPORT_V1
    U->>C: Manual copy/paste
    C->>C: Inspect real diff and rerun proof
    C-->>U: ACCEPTED / REQUEST_CHANGES / BLOCKED

Design boundaries

  • Explicit invocation only: $wayfinder
  • Codex-only installation
  • Nothing to install in Claude Code
  • No change to either harness
  • No automatic commits, pushes, PRs, deployments, or tracker mutations
  • No acceptance based on executor self-report
  • No conflation of route clarity, offline tests, global gates, exact PR head, or live production status

Install

Use the repository installer from PowerShell:

.\scripts\install.ps1

On macOS or Linux:

./scripts/install.sh

Both installers stage a complete copy before activation. On reinstall, they move the previous wayfinder directory to a timestamped sibling backup instead of copying into it. The output prints the backup path. To roll back, move the active wayfinder directory aside, then rename the backup to wayfinder.

The destination is ${CODEX_HOME}/skills/wayfinder, or $HOME/.codex/skills/wayfinder when CODEX_HOME is unset. For isolated testing, pass -CodexHome <path> on PowerShell or --codex-home <path> on macOS/Linux.

Start a new Codex task after installation. The skill does not trigger implicitly.

Use

$wayfinder chart
I need to redesign this subsystem, but the architecture and migration path are
still unclear.

$wayfinder prompt
Generate the next bounded Claude Code prompt from this map.

$wayfinder review
Here is Claude's EXECUTOR_REPORT_V1. Verify it against the checkout.

$wayfinder checkpoint
Produce a durable checkpoint for the next Codex task.

The other operations are next, resolve, and close.

Integration with an existing repository

Wayfinder reads the repository's existing authority first: AGENTS.md, CLAUDE.md, active handoffs, issues, PRs, and verification docs. It reuses an existing map or tracker when one is provided. It does not create a .wayfinder/ directory or mutate GitHub by default.

The skill package lives in skills/wayfinder. Reusable prompt and report templates live under skills/wayfinder/assets.

Validate and package

No dependencies are required beyond Node.js 20+ and Python 3.10+:

node scripts/validate.mjs
node --test tests/contracts.test.mjs
python scripts/package_skill.py

The package is written to dist/wayfinder.skill.

The .skill file is a ZIP-compatible distribution archive containing the skill plus first- and third-party license notices. Installation from the source folder remains the least surprising option because it is directly inspectable.

evals/evals.json is a forward-test specification. CI validates its structure but does not call an AI model. Behavioral results must come from an explicit evaluation run and should not be represented as a deterministic CI gate.

Status

This is an initial public release. The governance contract is intentionally conservative: manual transport and independent verification are features. Feedback and adversarial examples are welcome.

Attribution

The destination/frontier/fog model is inspired by Matt Pocock's MIT-licensed Wayfinder skill. This repository is an independent implementation for a Codex-led, manually bridged Claude Code workflow. See NOTICE.md.

License

MIT