mirror of https://github.com/jparkerweb/plan2code.git synced 2026-09-17 16:22:23 -07:00

Files

T

jparkerweb 1907281b40 Add a GitHub Issues backend to Pathfinder

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

2026-08-08 19:00:26 -07:00

5.5 KiB

Raw Blame History

Plan2Code Quick Reference

Commands

Step	Command	Input	Output
Init	/plan2code-init	None	AGENTS.md file
Update	/plan2code-init-update	AGENTS.md	Updated AGENTS.md
0	/plan2code-0-pathfinder	A foggy idea	pathfinder/map.md or GitHub Issues + PLAN-DRAFT-.md
quick	/plan2code-quick-task	Requirements	Conversational plan (standalone — not a pipeline step)
review	/plan2code-review	Scope guidance	Review findings + fixes
1	/plan2code-1-plan	Requirements	PLAN-CONVERSATION-.md + PLAN-DRAFT-.md
1b	/plan2code-1b-revise-plan	Specs + changes	Updated specs
2	/plan2code-2-document	PLAN-DRAFT.md	overview.md + Phase files
3	/plan2code-3-implement	overview.md	Implemented code
4	/plan2code-4-finalize	overview.md	Archived specs
handoff	/plan2code-handoff	Conversation	Self-contained handoff doc in handoffs/

File Structure

specs/
└── <feature-name>/
    ├── pathfinder/                   # From Step 0 (optional, if charted locally)
    │   ├── map.md                    #   the map: destination, decisions, fog
    │   └── questions/NN-<slug>.md    #   one decision question per file
    │                                 #   (GitHub Issues backend: map issue + sub-issues instead)
    ├── PLAN-DRAFT-<date>.md          # From Step 1 (verified plan)
    ├── PLAN-CONVERSATION-<date>.md   # From Step 1 (conversation log)
    ├── overview.md                   # From Step 2
    └── phase-X.md                    # From Step 2

specs--completed/                     # After Step 4
└── <feature-name>/                   # Archived specs

Note: <date> uses YYYYMMDD format (e.g., 20250204)

Key Rules

Start NEW conversation for each step (and each implementation phase)
ONE phase per conversation (but parallel phases can run in separate instances)
Reply "approved" to complete phases
90% confidence required before planning completes
Never look in specs--completed/ (it's archived specs)

Phase Status

Checkbox	Status	Meaning
`[ ]`	Pending	Not started
`[/]`	In Progress	Agent working (or paused)
`[x]`	Complete	Approved

Parallel Execution

When phases have no file conflicts or dependencies, they can run simultaneously:

Documentation Mode auto-detects parallel-eligible phases
Implementation Mode shows selection UI with status for each phase
Run multiple /plan2code-3-implement instances on different phases
[/] status shows which phases are actively being worked on

Quick Troubleshooting

Issue	Solution
Lost context mid-phase	Attach spec files, say "resume from Task X.Y"
Wrong phase started	Say "abort", start correct phase
Need to change plan	Use `/plan2code-1b-revise-plan`
Multiple spec folders	Specify which: "Continue with specs/user-auth/"
Need AGENTS.md file	Use `/plan2code-init` to generate one
Update AGENTS.md	Use `/plan2code-init-update` after sessions
Run phases in parallel	Check Parallel Execution Groups in overview.md

Workflow Decision

New to a project?
└── /plan2code-init → Generate AGENTS.md for project-specific guidance

Learned something during a session?
└── /plan2code-init-update → Add learnings to AGENTS.md

Too unclaer to plan? (big idea, don't yet know what the questions are)
└── /plan2code-0-pathfinder → chart it, clear one decision per session
    └── then → /plan2code-1-plan (resumes at Phase 4)

Is it a quick, small task?
├── Yes → /plan2code-quick-task (standalone)
└── No → /plan2code-1-plan (full workflow)
         ├── /plan2code-2-document
         ├── /plan2code-3-implement (repeat per phase)
         │   └── OR: plan2code-loop (autonomous alternative)
         └── /plan2code-4-finalize

Need to revise mid-implementation?
└── /plan2code-1b-revise-plan

Autonomous Loop (Alternative)

The plan2code-loop CLI is an alternative to Step 3, not a replacement.

Approach	Use When
`/plan2code-3-implement`	You want interactive control per phase
`plan2code-loop`	You want hands-off autonomous execution

plan2code-loop   # Fully interactive - auto-detects specs, prompts for options

Loop Modes

Mode	Description
One task per loop (default)	One task per agent invocation. Node handles git commits.
One phase per loop	All tasks in a phase per invocation. LLM handles git commits. Best for smart models with larger context.

Session state stored per-spec in specs/<feature>/.plan2code-loop/

5.5 KiB Raw Blame History