wayfinder

name

wayfinder

description

Govern long, uncertain engineering efforts with Codex as the sole lead and Claude Code as a manually isolated executor. Use only when the user explicitly invokes $wayfinder to chart decisions, fog, and frontier; select the next decision; generate a copy-paste Claude Code prompt; review a pasted Claude report against the real repository; checkpoint progress; or test whether the route is clear. Do not use for ordinary scoped tasks or automated cross-harness orchestration.

Wayfinder

Turn a foggy, multi-session effort into a controlled sequence of decisions and verified implementation tranches. Keep Codex and Claude Code in separate conversations. The user deliberately carries prompts and reports between them.

Preserve the control boundary

• Treat Codex as the map owner, prompt author, reviewer, governance-state writer, and acceptance authority. Humans may approve domain choices; Codex alone records their governance effect.
• Treat Claude Code as a bounded executor. It may report facts and recommend a next step, but it may not accept its own work or issue the next tranche.
• Treat manual copy and paste as an intentional air gap, not missing automation.
• Never call, configure, or modify Claude Code, its hooks, plugins, settings, task system, or conversation from this skill.
• Never create an MCP server, shared queue, background daemon, lease system, or cross-harness state synchronizer.
• Keep one active Claude tranche per map unless the user explicitly authorizes independent, non-overlapping tranches.

Separate navigation from execution

Maintain two planes:

1. Navigation plane — destination, decisions, open questions, frontier, fog, scope boundaries, evidence, and closure.
2. Execution plane — one bounded prompt, one Claude report, and one independent Codex verdict.

Do not turn every unknown into an implementation task. A precise unanswered question belongs on the frontier. An in-scope unknown that cannot yet be stated precisely remains fog. Execution starts only when accepted decisions make a bounded tranche possible.

Select the operation

Infer the operation from the explicit invocation:

• chart — establish or reconcile the map.
• next — select one frontier decision and explain why it dominates.
• resolve — investigate or decide one frontier question.
• prompt — produce one copy-paste Claude Code executor prompt.
• review — verify a pasted Claude report against the actual checkout.
• checkpoint — emit a compact, durable handoff for the next Codex session.
• close — evaluate WAY_CLEAR and implementation gates without conflating them.

If the user explicitly invokes $wayfinder without naming an operation:

• use review when a Claude report is present;
• use prompt when the map is ready for execution and the user asks what to send Claude;
• use chart for a loose initiative;
• otherwise use next.

Perform one state transition by default. Do not silently continue from an accepted review into a new Claude tranche unless the user requested both.

Start from repository authority

Before changing or interpreting a map:

1. Resolve the exact repository root, worktree, branch, base, and current HEAD.
2. Read the applicable AGENTS.md, CLAUDE.md, project instructions, active handoff, issue, PR, and verification docs.
3. Preserve dirty state and distinguish pre-existing changes from tranche work.
4. Reuse the project's existing authority surface.

Use a user-specified map or tracker when provided. Otherwise prefer, in order:

1. an existing canonical issue, WORKSTREAMS.md, HANDOFF.md, or equivalent;
2. a map returned in the conversation;
3. a new local file or tracker item only when persistence was explicitly requested.

Do not create .wayfinder/ or mutate an external tracker by default.

Operate the map

Read references/map-contract.md for chart, next, resolve, checkpoint, or close.

Apply these invariants:

• Name the destination before decomposing work.
• Record observable closure criteria, constraints, non-goals, and authority.
• Keep decisions append-only: supersede them; do not erase causal history.
• Derive frontier from accepted dependencies and current scope.
• Keep fog distinct from blocked questions and out-of-scope work.
• Require evidence and any necessary human domain approval before Codex records a decision as accepted.
• Let repository rules further restrict a tranche, but never use them to broaden the scope or permissions issued by Codex. Block on incompatible requirements.
• Reconcile the whole low-resolution map after every accepted decision or review.
• Stop using Wayfinder when the route is already small, clear, and executable in one ordinary task.

Select the default frontier item by balancing:

1. safety and architectural risk reduced;
2. information gained;
3. downstream decisions unblocked;
4. critical-path importance;
5. cost and reversibility.

State the selection rationale in one short paragraph.

Generate a Claude prompt

Read references/manual-bridge.md and use assets/claude-executor-prompt.md.

Generate exactly one self-contained fenced block headed CLAUDE_EXECUTOR_PROMPT_V1. The user must be able to copy it without reading the surrounding Codex conversation.

The prompt must include:

• exact repo identity and map revision;
• required reads and accepted decisions;
• one objective and an explicit authorized scope;
• non-goals and forbidden actions;
• observable acceptance criteria;
• verification commands or proof obligations;
• stop and escalation conditions;
• the exact EXECUTOR_REPORT_V1 schema;
• an instruction to stop after the report and not start another tranche.

Default to no commit, push, PR, deployment, destructive Git action, governance artifact edit, or scope expansion unless the user explicitly authorized it.

Set the bridge status to AWAITING_CLAUDE only after the complete prompt has been emitted. Do not claim the tranche has started or finished.

Review a Claude report

Read references/review-contract.md and use assets/claude-executor-report.md as the expected report shape.

Treat every claim in the report as EXECUTOR_REPORTED until verified. Then:

1. Re-resolve repo root, branch, HEAD, and dirty state.
2. Compare observed root, worktree, branch, base, starting HEAD, map ID, map revision, and tranche ID with the issued prompt.
3. Inspect the actual diff and classify every changed file.
4. Read the changed code and relevant authority surfaces.
5. Run the smallest tests that prove the acceptance criteria.
6. Run broader gates only when the repo contract or risk requires them.
7. Check for scope drift, hidden assumptions, destructive actions, and premature work on the next tranche.
8. Return ACCEPTED, REQUEST_CHANGES, or BLOCKED with evidence.
9. Reconcile decisions, fog, frontier, out-of-scope items, and gate status.

A green Claude self-report never closes the tranche. A green offline test never implies global, exact-HEAD, live, or production closure.

Close conservatively

Declare WAY_CLEAR only when:

• the destination and closure criteria remain valid;
• every necessary decision is accepted or explicitly disposed;
• no unresolved contradiction remains;
• residual fog is empty or recorded as an accepted risk with owner and reopen trigger;
• evidence freshness satisfies the map policy;
• an independent Codex closure pass finds no missing decision.

Report implementation and environment gates separately. Use only gates that exist in the repository; do not invent ceremony.

Output discipline

Lead with the result:

• current operation and map revision;
• decision, prompt, review verdict, or closure verdict;
• evidence status;
• one next action.

Use names in human-facing prose. IDs may support traceability but must not replace readable names. Keep the map low-resolution and load detail on demand.