jparkerweb
1907281b40
Chart Step 1 now asks where the map should live: local files under gitignored specs/ (the default) or a pathfinder:map issue whose decision questions are its sub-issues, driven by gh. The pick is recorded as the first Ground rules bullet and never re-asked; Auto-Discovery resolves either backend, and an issue URL routes straight to github. On github the local model maps onto the tracker's own primitives rather than being simulated in issue bodies: sub-issues, native issue dependencies for blocking, the assignee as the claim, one pathfinder:<type>-<mode> label so type and mode cannot drift, and an Answer comment plus a close reason that distinguishes a decision from a question ruled out of scope. Both wiring calls key on the database id, not the number. The map body therefore carries no checklist at all. Sketches, secrets and the PLAN-DRAFT stay on local disk regardless -- plan2code-1-plan discovers its input with ls specs/ and has no notion of a tracker. github is only offered after a five-check preflight, and the offer names the repo's visibility, because a map on a public tracker publishes the destination and the codebase recon. The Step 3 recon is held until Step 6 so the no-fog off-ramp leaves no litter. Depth lives in a seventh reference file; the orchestrator was recompressed to absorb the new section within the 11,000 char limit by removing duplication with its references. Adapted from the GitHub tracker doc behind Matt Pocock's wayfinder skill (MIT). AI Assisted
2.6 KiB
Questions & Map Format
Part of plan2code-0-pathfinder — the on-disk format both modes share: directory layout,
NNnumbering, the question-file schema,Type:vocabulary, and the marker / blocking rules. The main file keeps only the marker legend and a layout gist; the authority is here.This file describes the
localbackend only. If## Ground rulessays**Backend:** github, the equivalence table ingithub-issues.mdreplaces every rule below — there are no files, noNN, no schema lines, and no checklist.
Layout
specs/<idea>/
├── pathfinder/
│ ├── map.md <- the index
│ ├── questions/NN-<slug>.md <- 00-codebase-context.md always exists
│ └── sketch-NN/ <- optional runnable sketch, throwaway
└── PLAN-DRAFT-<YYYYMMDD>.md <- written ONLY when the map clears
questions/ is ground truth; map.md is a rebuildable index that gists and links. A filled ## Answer beats any State: line. Detail lives in exactly one place — the question file.
Numbering
NN is zero-padded from 00, assigned in dependency order (blockers lower), never reused or renumbered — links and Blocked by: would rot silently. Next = max + 1. 00 is always 00-codebase-context.md, never anything else. Gaps in the sequence are normal and harmless.
The five schema lines
Each question file carries five contiguous Key: value lines after its H1 — NOT YAML frontmatter, no --- delimiters:
| Line | Values |
|---|---|
Type: |
grill · HITL | research · AFK | sketch · HITL | legwork · HITL | legwork · AFK — one token, so type and mode cannot drift |
State: |
open | claimed | resolved | out-of-scope |
Blocked by: |
none | 02, 04 |
Claimed: |
none | <YYYY-MM-DD HH:mm> |
Locked: |
yes only when hard to reverse AND surprising without context AND a real trade-off |
Type meanings. grill (default) — a decision only the human can make. research — a fact outside this directory gates it. sketch — the human needs something concrete to react to. legwork — manual work that must happen before a decision is possible.
Markers and blocking
Map markers, rebuilt from the files every session: [ ] open — these rows ARE the frontier · [/] claimed · [x] resolved · [!] open but blocked · [-] out of scope.
Unblocked ⟺ every NN in Blocked by: is resolved. Stranded: a blocker gone out-of-scope never resolves — the question is not merely blocked. Re-frame its ## Question to drop the dependency, or rule it out too. Never leave it sitting.