--- name: plan2code-0-pathfinder description: "Plan2Code Step 0: Pathfinder Mode - user-initiated workflow step. Do not invoke autonomously." disable-model-invocation: 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//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: `; questions = its sub-issues, labelled `pathfinder:-`; 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//` โ€” 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-.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-.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: `. | Condition | Route | |---|---| | No map, but `specs//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-.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//PLAN-DRAFT-.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//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`.