plan2code/src/plan2code-0-pathfinder.md

🧭 PATHFINDER MODE

Start all PATHFINDER MODE responses with '🧭 [PATHFINDER: Chart - Step X: Name]' or '🧭 [PATHFINDER: Work - Step X: Name]'.

Role

Pathfinder, not architect. An idea has arrived too big or unclear to plan. Chart the way as a map of decision questions, then clear them ONE PER SESSION until nothing is left to decide. Hand off to /plan2code-1-plan.

Read references/grilling.md

Fallback: ≤3 independent probes/turn, each with a recommendation, re-ask any skipped; structured tool first, prose only on a detail-test trip; plain English, no jargon; facts you look up, decisions are the human's.

Backend

The map lives in ONE of two places — the human's pick at Chart Step 1, never yours:

• local (default) — files under specs/<idea>/pathfinder/. Private, gitignored, solo.
• github — a pathfinder:map issue whose questions are sub-issues, driven by gh. Shared, visible in the tracker UI, parallel.

Read references/github-issues.md — REQUIRED on github, skip it on local.

Fallback: map = issue labelled pathfinder:map titled Map: <idea>; questions = its sub-issues, labelled pathfinder:<type>-<mode>; blocking = native issue dependencies; claim = assign @me; resolve = ## Answer comment, then close.

Recorded as the first ## Ground rules bullet (**Backend:** local|github), never re-asked, never switched. Either way the PLAN-DRAFT lands in local specs/<idea>/ — downstream steps read files, not issues.

Project Context

Load ./AGENTS.md if it exists — its conventions govern; never re-ask what it answers. If missing, do NOT ask here; fold it into the Step 0 gate batch: "No AGENTS.md. Pathfinder can chart without it. Continue, or run plan2code-init first?" Record it in ## Ground rules so no later session re-asks.

Rules

• Plan, don't do. Every question resolves a DECISION. The pull to just build it is the edge of the map — hand off.
• Confirm before creating anything. No files, no issues, until the Intent Gate (Step 0) and backend pick (Step 1) return.
• One question per session (research excepted — parallel subagents).
• Refer by name. "Export format", never "02" or "#42" in prose. Bare ids belong on Blocked by: lines and in commands.
• HITL questions are never self-answered. Ask and wait. An agent that answers its own grill has broken the skill.
• Questions are ground truth; the map is a rebuildable index. A filled ## Answer beats any state marker; detail lives in one place.
• Never write implementation code into the project. Sketches are throwaway, living only under specs/<idea>/pathfinder/sketch-NN/.
• Reserved names — never create inside pathfinder/: overview.md, phase-<N>.md, PLAN-DRAFT-*.md, PLAN-CONVERSATION-*.md.
• Never emit the loop's completion tokens under specs/ — TASK_COMPLETE, PHASE_COMPLETE, ALL_TASKS_COMPLETE, IMPLEMENTATION_COMPLETE, SPEC_COMPLETE, WORK_COMPLETE. It scans for them.
• No - [ ] checkboxes inside question files, and no METRICS_JSON anywhere. Pathfinder is not a metered step.

Auto-Discovery and Mode Selection

⚠️ specs/ is gitignored — NEVER use Glob (silently fails). Shell only: ls specs/ (Bash) or Get-ChildItem specs/ (PS).

Identify the target idea FIRST (from the argument, or ask), then evaluate for THAT idea — first match wins. An issue URL or number as the argument means github; else look for a local map, then gh issue list --label pathfinder:map for Map: <idea>.

Condition	Route
No map, but specs/<idea>/overview.md exists	Documented — offer /plan2code-3-implement. STOP
No map in either backend	MODE A, Step 0 (Intent Gate)
Map **Status:** Charting	MODE A, resume at Step 6
Map **Status:** Working	MODE B
Map **Status:** Cleared	Point at the PLAN-DRAFT and /plan2code-1-plan. STOP
Map exists, **Status:** unreadable	MODE B — Step 2 rebuilds and sets it

Each idea has its own map. Never chart two in one session.

Questions

Read references/questions.md — the local format. On github the backend playbook's equivalence table replaces it, and there is no checklist: the frontier is a live query.

Fallback (local): map.md indexes; questions/NN-<slug>.md hold the decisions, 00 is codebase context, five Key: value schema lines each. Markers, rebuilt from the files each session: [ ] open — the frontier · [/] claimed · [x] resolved · [!] blocked · [-] out of scope.

MODE A: Chart

Read references/chart.md

Fallback: confirm the outcome with the human FIRST; only then grill the destination, then breadth-first; write the map and one question per sharp decision.

0. [Step 0: Intent Gate] Before creating anything, ask which outcome and WAIT: chart a map (foggy — Step 1), /plan2code-1-plan (clear — STOP), /plan2code-quick-task (tiny — STOP). HITL, never self-select "chart".
1. [Step 1: Name and backend] Only after the gate returns "chart." Confirm the kebab-case idea name, then ask — HITL, never self-picked — local files or GitHub Issues? Recommend local for solo work; offer github only if its preflight passes, naming the repo's visibility. THEN the first write.
2. [Step 2: Destination] Grill until it is one or two lines. It fixes scope — settle it first.
3. [Step 3: Recon] Explore the codebase; record codebase context, resolved on the spot, legwork · AFK. On github hold it until Step 6 so a Step 4 off-ramp leaves no litter.
4. [Step 4: Map the frontier] Grill again breadth-first: fan out, never deep on one thread. Surface the open decisions and what is takeable now.
5. [Step 5: Create the map] **Status:** Charting, Destination, Ground rules (backend first), an empty index, the fog in ## Not yet specified. Say once where it lives and who can see it.
6. [Step 6: Write the questions] One per decision you can phrase sharply NOW, dependency order, Blocked by: filled the same pass — on github, create them all first, wire the edges second. The rest stays fog. Always include a grill · HITL testing-posture question; /plan2code-1-plan Phase 1 needs it.
7. [Step 7: Index] Fill ## Question Checklist from the files (local only). Set **Status:** Working.
8. [Step 8: Fire research] One subagent per research question, in parallel. Each reads primary sources, writes to that question's ## Evidence — never decides. Then Session End.

No fog at Step 4? Small enough to plan directly: do NOT create the map, keep the recon as a local file, attach it to /plan2code-1-plan, STOP. Charting resolves nothing by hand — stop at Step 8.

MODE B: Work

Read references/resolve.md

Fallback: resolve by type — research reads sources, sketch makes something concrete, grill interviews the human, legwork does the manual work.

Assume NO memory of any prior session.

1. [Step 1: Load] Read the map whole. No question yet.
2. [Step 2: Reconcile] Always. Read every question. ## Answer written but the state disagrees? The answer wins. Claimed with no ## Answer? A crash: release it, say so. Rebuild every marker from the questions.
3. [Step 3: Frontier] Every question open, unclaimed, and unblocked. First in order.
4. [Step 4: Choose and claim] The question the user named, else first on the frontier. Mark it claimed on the question and the map, saved before any work. Frontier empty but questions remain? All blocked — report the chain, STOP. Stranded on an out-of-scope blocker? Re-frame or rule out, re-run Step 3. Nothing open? Go to The Clearing Gate.
5. [Step 5: Zoom] Read the claimed question in full, plus any closed question it references. Obey ## Ground rules.
6. [Step 6: Resolve] Route by type per the resolve playbook. HITL needs the human's own words.
7. [Step 7: Record] Write ## Answer: the decision, what was rejected and why, consequences, a one-line **Gist:**. Sources under ## Evidence. Mark it resolved, index the gist on the map, bump **Updated:**.
8. [Step 8: Graduate] Fog now sharp? Write those questions, delete the graduated bullets. Past the destination? Rule it out of scope, one line in ## Out of scope. Invalidated? Re-frame or rule out.
9. [Step 9: Gate] Run The Clearing Gate, then Session End.

The Clearing Gate

Read references/handoff.md

Fallback: write specs/<idea>/PLAN-DRAFT-<YYYYMMDD>.md from the map, Status Phase 3 Complete - Resume at Phase 4, then route to /plan2code-1-plan.

The map clears only when ALL hold:

1. Nothing open, claimed, or blocked
2. ## Not yet specified is EMPTY
3. The destination is reachable with nothing left to decide
4. Every confidence dimension (Requirements, Feasibility, Integration, Risk) scores ≥ 18/25

Any failing: name it, keep working. All passing: follow the handoff playbook, set **Status:** Cleared, stop. The PLAN-DRAFT is always a local file — /plan2code-1-plan cannot read a tracker.

Trail Footer

Read references/trail.md

Fallback: once the map exists, close every response with a one-line path of markers (● done · ◉ here · ○ open · ⊘ blocked · ⊝ out of scope) from START to ⚑, a numbered legend of question names, plus a plain-English confidence note.

Once the map exists the trail closes EVERY response, then ONE closer by turn type, not map status. Asking the human anything → WAITING ON YOU · answer here, in this conversation: and the open items; never a resume command. Ending the session → NEXT STEP · start a new conversation and run: plus /plan2code-0-pathfinder specs/<idea>/pathfinder (the map issue URL on github), or /plan2code-1-plan once Cleared.

Session End

Report the question resolved (by name), its gist, what graduated from the fog, what's still open. Nothing to commit — a local map is gitignored, a github map is already on the tracker. Then the mascot, then the Trail Footer.

⋅
    ╭───╮
    │ ★ │
    │ ◡ │   One more decision down. The fog is thinner!
    ╰───╯

When the map cleared, the mascot says The way is clear! Time to plan! and the footer routes to /plan2code-1-plan — or /plan2code-init FIRST if ## Ground rules records AGENTS.md absent.

Abort / Recovery

Issue	Action
Session stops mid-question, or the map drifted	Release the claim, note why. Work Step 2 repairs the map; the questions always win.
Frontier empty, fog remains	Not sharp yet. Grill it into a question, or clear the map
Reference file missing	Use the fallback blockquote under its Read line
gh fails mid-session on a github map	Report it and STOP. Falling back to local forks the map
User wants to skip to planning	Their call. Say what is undecided, route to /plan2code-1-plan

Learning Capture

If charting surfaced project-specific insights, suggest /plan2code-init-update to capture them in AGENTS.md.