Document Pathfinder and community feedback across the contributor docs

Moves the README's deep material into .readme/ (walkthrough, autonomous
loop, status line, metrics, test bot) and brings AGENTS.md, the .agents-docs
set and QUICK-REFERENCE.md in line with Step 0 and the metrics ingestion
flow.

AI Assisted

.agents-docs/AGENTS-architecture.md

@@ -5,11 +5,23 @@
 
 ```
 plan2code/
-├── src/                        # Source workflow prompts (9 markdown files)
-│   └── plan2code-review-references/     # Reference files for review skill
-│       ├── verification-protocol.md        # Deep verification + confidence calibration
-│       ├── dimensions.md                   # 11 dimensions with detailed checklists
-│       └── false-positives.md              # Known false-positive patterns
+├── src/                        # Source workflow prompts (11 markdown files)
+│   ├── plan2code-0-pathfinder-references/ # Reference files for pathfinder skill
+│   │   ├── chart.md                        # MODE A: destination + frontier grills, templates
+│   │   ├── grilling.md                     # Folded-in grilling + domain-modeling
+│   │   ├── questions.md                    # On-disk question-file format + markers
+│   │   ├── resolve.md                      # Per-type resolution + graduating the fog
+│   │   ├── handoff.md                      # Clearing gate + PLAN-DRAFT handoff
+│   │   └── trail.md                        # Every-response map visual + pathed resume command
+│   ├── plan2code-review-references/     # Reference files for review skill
+│   │   ├── verification-protocol.md        # Deep verification + confidence calibration
+│   │   ├── dimensions.md                   # 11 dimensions with detailed checklists
+│   │   ├── false-positives.md              # Known false-positive patterns
+│   │   └── session-end.md                  # Next-step routing at review session end
+│   ├── plan2code-init-update-references/ # Reference files for init-update skill
+│   │   └── ai-agent-file-sync.md           # Step 7: replace AI configs with AGENTS.md refs
+│   └── plan2code-4-finalize-references/ # Reference files for finalize skill
+│       └── community-feedback-submission.md # STEP 6.5 payload schema + submission tiers
 ├── plan2code-loop/           # Autonomous loop CLI tool (Node.js/TypeScript)
 │   ├── src/                    # TypeScript source
 │   └── dist/                   # Built output (tsup)
@@ -54,14 +66,15 @@ plan2code/
 |------|------|---------|
 | `plan2code-init.md` | Init | Generate AGENTS.md as index + `.agents-docs/` section files (progressive discovery) |
 | `plan2code-init-update.md` | Update | Update AGENTS.md with learnings; detects and routes edits to `.agents-docs/` files |
-| `plan2code-quick-task.md` | 0 | Lightweight planning for small tasks |
+| `plan2code-0-pathfinder.md` | 0 | Chart a foggy idea as a local map of decision questions under `specs/<idea>/pathfinder/`, resolve one per session, hand a seeded PLAN-DRAFT to Step 1 |
+| `plan2code-quick-task.md` | quick | Lightweight planning for small tasks (standalone — not a pipeline step) |
 | `plan2code-1-plan.md` | 1 | Requirements analysis & architecture |
 | `plan2code-1b-revise-plan.md` | 1b | Mid-implementation revisions |
 | `plan2code-2-document.md` | 2 | Create implementation specs |
 | `plan2code-3-implement.md` | 3 | Execute implementation (phase by phase) |
 | `plan2code-review.md` | review | Post-implementation comprehensive review |
-| `plan2code-4-finalize.md` | 4 | Validate, summarize, feedback, archive (7 steps) |
-| `plan2code-handoff.md` | handoff | Compact the conversation into a self-contained handoff document |
+| `plan2code-4-finalize.md` | 4 | Validate, summarize, feedback, archive (steps 1–7, +optional 6.5) |
+| `plan2code-handoff.md` | handoff | Compact the conversation into a self-contained handoff document for a fresh session |
 
 ## Naming Convention
 
@@ -83,9 +96,10 @@ Some workflows use companion reference files for depth that exceeds the 11k char
 **How the installer handles them:**
 - **Skill-directory platforms** (Claude Code, Agents, Crush, Devin): reference files are nested as `<skill-name>/references/`. Read paths use canonical `references/<file>.md`.
 - **Flat-file platforms** (Windsurf, Cursor, Copilot, Continue): reference files are placed as a sibling directory. The installer rewrites Read paths to the sibling directory name (e.g., `plan2code-review-references/<file>.md`).
-- **TOML platforms** (Gemini CLI): reference files are skipped — TOML embeds content inline, so Read directives won't resolve. The orchestrator's inline fallback text covers this.
 
-Reference files are NOT subject to the 11,000 character limit. Currently only the review workflow uses this pattern — it serves as the POC for potential adoption by other workflows.
+Reference files are NOT subject to the 11,000 character limit. The review workflow pioneered this pattern (`verification-protocol`, `dimensions`, `false-positives`, `session-end`); the init-update workflow also uses it (`ai-agent-file-sync` for its Step 7), `plan2code-4-finalize.md` uses it for STEP 6.5 (`community-feedback-submission`), and `plan2code-0-pathfinder.md` leans on it hardest (`chart`, `grilling`, `questions`, `resolve`, `handoff`, `trail` — the orchestrator is a dispatcher, the depth lives in the references). Other workflows can adopt it when a source file's detail exceeds the 11k limit.
+
+**`Read` directives must sit at column 0.** `install.js` matches `/^(Read\s+)references\//gm` for the flat-file path rewrite — anchored, with no leading-whitespace tolerance. An indented or bulleted `Read` line is silently skipped, so flat-file platforms ship a `references/` path that does not exist there (they receive the reference dir as a *sibling*, named `plan2code-<name>-references/`).
 
 ## Repo-Local Skills (`.claude/skills/`)
 

.agents-docs/AGENTS-code-style.md

@@ -17,4 +17,6 @@
 - **Workflow file character limit:** All `src/plan2code-*.md` files must be ≤ 11,000 characters. A husky pre-commit hook enforces this. The 11,000 limit leaves buffer for platform-specific YAML headers (106-142 chars) to stay under Windsurf's 12,000 char limit.
 - **Metrics internal prompts have no char limit:** Files in `plan2code-metrics/src/prompts/` are NOT subject to the 11,000 char limit — only `src/plan2code-*.md` consumer-facing prompts are.
 - **User Feedback table format:** The `## User Feedback` markdown table in `overview.md` has a strict format the collector regex depends on. Field names must be exactly `Rating`, `Reason`, `Went Well`, `Went Poorly`. Pipe characters in values must be escaped as `\|`.
+- **PLAN-DRAFT confidence numbers are scraped by regex:** when a `specs/<feature>/PLAN-DRAFT-*.md` contains no `<!-- METRICS_JSON ... -->` comment, `collector.ts` falls back to prose scraping (`collector.ts:186-241`). The overall-confidence pattern requires a literal `%`, but the four *breakdown* patterns (`collector.ts:201-204`) do **not** — `/[Rr]equirements?[:\s|]+(\d{1,2})/` and its siblings match a bare dimension word followed by whitespace, a colon, or a pipe and then digits. So a PLAN-DRAFT written by anything other than `/plan2code-1-plan` Phase 7 must keep both the `%` sign **and** bare `Requirements` / `Feasibility` / `Integration` / `Risk` followed by a number off the page — including innocent table rows like `| Requirements | 11 |`. Otherwise the metrics pipeline records a planning-step confidence that no planning step produced. `/plan2code-0-pathfinder` works around this by hyphenating the labels (`Requirements-clarity 22/25`), which breaks the character class.
 - **Reference file sizing guideline:** Files in `src/plan2code-*-references/` directories target ~100-200 lines each (soft guideline; evaluate splitting above 300). They are NOT subject to the 11,000 character limit. The pre-commit hook (`validate-char-count.js`) only checks `src/plan2code-*.md` flat files — subdirectory contents are automatically excluded.
+- **The splitting guideline has a hard ceiling — reference files cannot always be split:** two constraints bound it. (1) Each new reference costs the orchestrator a column-0 `Read references/<file>.md` line plus its fallback blockquote (~150-200 chars), and orchestrators near the 11,000 limit have no room to spend. (2) **The path rewrite is not recursive** — `syncPrompts()` rewrites `Read references/…` paths on the *orchestrator's* content only, so a `Read references/…` directive placed *inside* a reference file is never rewritten for flat-file targets; it ships as a dangling instruction pointing at a path that does not exist there. When a reference legitimately exceeds 300 lines (e.g. `plan2code-0-pathfinder-references/chart.md`), that is an accepted trade-off, not an oversight.

.agents-docs/AGENTS-development-commands.md

@@ -61,9 +61,8 @@ cd plan2code-metrics && npm run build # Build the CLI
 | VS Code Copilot | `.prompt.md` | — | — | YAML frontmatter |
 | Codeium | `.md` | — | — | YAML frontmatter |
 | Claude Code (Skills) | `SKILL.md` in subdir | `.claude/skills/<skill-name>/` | `~/.claude/skills/<skill-name>/` | YAML frontmatter + `disable-model-invocation: true` |
-| Agent Skills (Amp · Devin · Gemini CLI · OpenCode · Zed) | `SKILL.md` in subdir | `.agents/skills/<skill-name>/` | `~/.agents/skills/<skill-name>/` | YAML frontmatter (no disable flag) |
+| Agent Skills (Amp · Devin · OpenCode · Zed) | `SKILL.md` in subdir | `.agents/skills/<skill-name>/` | `~/.agents/skills/<skill-name>/` | YAML frontmatter (no disable flag) |
 | Crush | `SKILL.md` in subdir | — (global only) | `~/.config/crush/skills/<skill-name>/` (Unix) / `%LOCALAPPDATA%\crush\skills\<skill-name>\` (Windows) | YAML frontmatter |
-| Gemini CLI (TOML) | `.toml` | `.gemini/commands/` | `~/.gemini/commands/` | None (TOML fields: `description`, `prompt`) |
 | Pi (pi.dev) | `.md` | `.pi/prompts/` | `~/.pi/agent/prompts/` | YAML frontmatter (`description`) |
 
 ## Editing Workflow Prompts

.agents-docs/AGENTS-plan2code-metrics.md

@@ -32,6 +32,9 @@ plan2code-metrics                      # Run (fully interactive, no flags)
 | Analyze | AI diagnosis of weak metrics |
 | Propose | AI improvement proposals with validation |
 | Apply | Interactive diff review + file patching |
+| Fetch community submissions | List/parse/import open community-feedback GitHub issues from jparkerweb/plan2code, close on success |
+
+Community submissions arrive as GitHub issues labeled `community-feedback` on `jparkerweb/plan2code`, created by the finalize prompt's post-Step-6 submission flow; the "Fetch community submissions" option requires an authenticated `gh` CLI to list/close them.
 
 ## Key Source Files
 
@@ -40,11 +43,12 @@ plan2code-metrics                      # Run (fully interactive, no flags)
 | `types.ts` | All interfaces (`RunMetrics`, `UserFeedback`, `CohortMetrics`, etc.) + `METRIC_TARGETS` |
 | `collector.ts` | Reads project artifacts → run JSON (parses plan drafts, overview.md, loop logs) |
 | `aggregator.ts` | Merges runs by prompt generation (SHA cohort) → `aggregated.json` |
+| `community.ts` | Lists/parses/closes `community-feedback`-labeled GitHub issues via `gh` CLI |
 | `analyzer.ts` | AI diagnosis via `prompts/analyze.md` template |
 | `improver.ts` | AI proposals via `prompts/improve.md` + validation (char count, old_text match) |
 | `applier.ts` | Interactive diff review + file patching |
 | `cli.ts` | Menu-driven interactive CLI (100% prompts, no flags) |
-| `invoke-llm.ts` | Unified LLM interface (Claude Code or Copilot CLI) |
+| `invoke-llm.ts` | Unified LLM interface (Claude Code, GitHub Copilot CLI, or Devin CLI) |
 
 ## User Feedback
 
@@ -66,6 +70,7 @@ Feedback is collected during finalize (Step 5) or retroactively via the CLI. Pip
 
 - **Claude Code** (recommended): `claude` CLI with `--inputFile` for prompt delivery
 - **GitHub Copilot CLI**: `copilot` CLI with stdin prompt delivery
+- **Devin CLI**: `devin` CLI with `--print --prompt-file <file> --permission-mode dangerous`
 
 ## Metric Targets