plan2code/skills/plan2code-0-pathfinder/SKILL.md

name, description, disable-model-invocation

name	description	disable-model-invocation
plan2code-0-pathfinder	Plan2Code Step 0: Pathfinder Mode - user-initiated workflow step. Do not invoke autonomously.	true

🧭 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 at a time 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; AskUserQuestion for every question, prose only if unavailable; plain English; 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, parallel.

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

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

Recorded as the first ## Ground rules bullet (**Backend:** local|github), never re-asked or 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, 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.

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 at a time (research excepted — parallel); fork-menu between decisions, fresh session after ~3.
• 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 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.

Auto-Discovery and Mode Selection

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

Brief/recap/minutes asked? → read references/brief.md: reconcile, write plain-English briefs/brief-<YYYYMMDD>.md (decisions in range, still open, next step), STOP. Never resolves.

Identify the idea FIRST (from the argument, or ask), then evaluate for THAT idea — first match wins. An issue URL or number 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

One idea per session, each with its own map.

Questions

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

Fallback (local): map.md indexes; questions/NN-<slug>.md hold the decisions, 00 is codebase context, six Key: value lines each, Resolved: dating it. 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, use AskUserQuestion for the 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 says "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 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 sees 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 all first, wire edges second. The rest stays fog. 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 its ## Evidence — never decides. Then Session End.

No fog at Step 4? Small enough to plan directly: create no 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; backfill a missing Resolved: date from the claim.
3. [Step 3: Frontier] Every question open, unclaimed, and unblocked. First in order.
4. [Step 4: Choose and claim] The one 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? 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, dated today, index the gist + date 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: Menu] Run The Clearing Gate. Not cleared: fork-menu (Form C) — pick → Step 4, stop → 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. All four confidence dimensions score ≥ 18/25

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

Trail Footer

Read references/trail.md

Fallback: once the map exists, end every response with a marker path (● done · ◉ here · ○ open · ⊘ blocked · ⊝ out of scope) START→⚑, a named legend, a plain-English confidence note, one closer.

Once the map exists the trail closes EVERY response, then ONE closer by turn type. Asking anything → Form B: WAITING ON YOU · answer here, in this conversation: + open items, no command. Menu after a decision → Form C: NEXT UP picks + OR START FRESH. Session end → Form A: NEXT STEP · start a new conversation and run: + /plan2code-0-pathfinder specs/<idea>/pathfinder (map issue URL on github), or /plan2code-1-plan once Cleared.

Session End

Report each question resolved (name + gist), what graduated, what's still open; offer a brief for today. Nothing to commit — local is gitignored, github 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 map drift	Release the claim, note why. Work Step 2 repairs both; questions 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 and STOP. Falling back to local forks the map
User skips to planning	Their call. Name 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.