diff --git a/.agents-docs/AGENTS-architecture.md b/.agents-docs/AGENTS-architecture.md index 2ae1d7b..d474151 100644 --- a/.agents-docs/AGENTS-architecture.md +++ b/.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//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 `/references/`. Read paths use canonical `references/.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/.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--references/`). ## Repo-Local Skills (`.claude/skills/`) diff --git a/.agents-docs/AGENTS-code-style.md b/.agents-docs/AGENTS-code-style.md index c36a527..8ea9b87 100644 --- a/.agents-docs/AGENTS-code-style.md +++ b/.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//PLAN-DRAFT-*.md` contains no `` 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/.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. diff --git a/.agents-docs/AGENTS-development-commands.md b/.agents-docs/AGENTS-development-commands.md index adf195c..80f7b97 100644 --- a/.agents-docs/AGENTS-development-commands.md +++ b/.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//` | `~/.claude/skills//` | YAML frontmatter + `disable-model-invocation: true` | -| Agent Skills (Amp · Devin · Gemini CLI · OpenCode · Zed) | `SKILL.md` in subdir | `.agents/skills//` | `~/.agents/skills//` | YAML frontmatter (no disable flag) | +| Agent Skills (Amp · Devin · OpenCode · Zed) | `SKILL.md` in subdir | `.agents/skills//` | `~/.agents/skills//` | YAML frontmatter (no disable flag) | | Crush | `SKILL.md` in subdir | — (global only) | `~/.config/crush/skills//` (Unix) / `%LOCALAPPDATA%\crush\skills\\` (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 diff --git a/.agents-docs/AGENTS-plan2code-metrics.md b/.agents-docs/AGENTS-plan2code-metrics.md index 3bcb39d..587bde7 100644 --- a/.agents-docs/AGENTS-plan2code-metrics.md +++ b/.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 --permission-mode dangerous` ## Metric Targets diff --git a/.readme/autonomous-loop.md b/.readme/autonomous-loop.md new file mode 100644 index 0000000..4ad1a24 --- /dev/null +++ b/.readme/autonomous-loop.md @@ -0,0 +1,64 @@ +# Autonomous Loop + +`plan2code-loop` is a CLI that works through your spec's tasks on its own, one agent call at a +time. It is an **alternative to Step 3**, not a replacement — the four-step workflow and the specs it +produces are unchanged. + +← [Back to README](../README.md) + +--- + +## When to use it instead of Step 3 + +| Approach | Best for | +|----------|----------| +| `/plan2code-3-implement` | Interactive control, reviewing each phase, logic that needs your judgment | +| `plan2code-loop` | Straightforward implementations, batch work, overnight runs | + +The loop reads the same `overview.md` and phase files. You can start with the loop and finish by +hand, or the reverse — the checkboxes are the only handoff. + +--- + +## Install + +```bash +# From the plan2code root directory +node install.js # A (everything + dev tools) — or C → O (loop only) +``` + +## Run + +```bash +plan2code-loop # fully interactive +``` + +It will: + +1. Find specs in `./specs/` +2. Let you pick one if there are several +3. Offer to resume an existing session +4. Ask for a JIRA ticket ID, which agent to drive, the loop mode, and a max iteration count + +Then, per iteration: read `overview.md` and the phase files, find the first unchecked task (or +phase), implement it, mark the checkbox, repeat — until everything is done or it hits the iteration +cap. + +--- + +## Loop modes + +| Mode | Each agent call | Git commits | Best for | +|------|-----------------|-------------|----------| +| **One task per loop** (default) | Implements a single task | The Node controller commits after each task | Smaller models, cautious execution | +| **One phase per loop** | Implements every task in a phase | The agent commits after each task, with the JIRA ID | Larger context windows, tightly related tasks | + +Session state lives per-spec in `specs//.plan2code-loop/`, so each feature's progress +stays isolated. + +--- + +## Full documentation + +Architecture, completion markers, agent adapters, and configuration: +[`plan2code-loop/README.md`](../plan2code-loop/README.md) diff --git a/.readme/metrics.md b/.readme/metrics.md new file mode 100644 index 0000000..0b65956 --- /dev/null +++ b/.readme/metrics.md @@ -0,0 +1,59 @@ +# Metrics & Self-Improvement + +`plan2code-metrics` closes the loop on the workflow itself: it collects data from your finished +specs, aggregates it across runs and prompt generations, then uses AI to diagnose which step is +underperforming and propose edits to the workflow prompts. + +Aimed at **contributors and heavy users** — you don't need it to use Plan2Code. + +← [Back to README](../README.md) + +--- + +## The habit + +One thing to remember: **collect after every finished spec.** Everything else is on demand. + +```bash +# Install once, from the plan2code root +node install.js # A (everything + dev tools) — or C → M (metrics only) + +# After finishing a spec (steps 1–4) +cd your-project +plan2code-metrics # → "Collect metrics" → pick the spec dir → done, ~5 seconds +``` + +Then, when you're curious or have a few runs banked: + +```bash +plan2code-metrics # → "View metrics status" the dashboard + # → "Run analysis" AI diagnosis of weak steps + # → "Generate improvement proposal" concrete prompt edits + # → "Review and apply" patch src/plan2code-*.md +``` + +## How much data you need + +| Runs | What you get | +|------|--------------| +| **1** | Raw data and a basic dashboard. Start here. | +| **3+** | AI analysis unlocks. Pattern detection starts working. | +| **5–10+** | Averages stabilise; generation-over-generation comparisons become meaningful. | + +You're looking for trends, not individual scores. + +--- + +## Sending feedback upstream + +`/plan2code-4-finalize` can submit an anonymised metrics payload to the maintainers as a +`community-feedback` issue on the repo. Community runs are cohorted by the Plan2Code version that +produced them, so your data improves the prompts everyone installs — without displacing the +maintainer's own measurements. + +--- + +## Full documentation + +Data model, aggregation, cohorts, analysis prompts, and the ingestion flow: +[`plan2code-metrics/README.md`](../plan2code-metrics/README.md) diff --git a/.readme/status-line.md b/.readme/status-line.md new file mode 100644 index 0000000..62c61d6 --- /dev/null +++ b/.readme/status-line.md @@ -0,0 +1,54 @@ +# Claude Code Status Line + +A persistent three-line status bar for Claude Code: model, project, git branch, uncommitted diff +stats, session duration and cost, context-window usage, and plan quota. + +It reads everything from the JSON Claude Code already sends on stdin — **no API calls, no auth, no +background processes.** Optional, and unrelated to the workflow itself. + +← [Back to README](../README.md) + +--- + +## What it looks like + +On Pro / Max / Teams accounts, where rate limits are available: + +``` +◦ ◦ Opus 5 / high │ plan2code │ feature/PCWEB-11702-pathfinder │ +12 -3 +╭●╮ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ +├■┤ 3h 5m ($4.62) │ ▰▰▰▰▰▱▱▱▱▱▱▱ 42% (84K) │ 5h: 28% · 7d: 61% +``` + +On Enterprise / Bedrock / Vertex / pay-as-you-go, where they aren't, the last segment becomes session +token counts instead: + +``` +◦ ◦ Sonnet 5 │ plan2code │ main │ +12 -3 +╭●╮ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ +├■┤ 2m ($0.18) │ ▰▰▱▱▱▱▱▱▱▱▱▱ 18% │ 88k in · 3k out +``` + +The icons down the left are Planny, the project mascot. + +--- + +## Install + +```bash +node install.js # A (everything + dev tools) — or C → S (status line only) +``` + +That copies the script to `~/.claude/plan2code-statusline.js`, writes a default config to +`~/.claude/statusline-config.json` (an existing config is preserved), and registers it in +`~/.claude/settings.json`. + +If you already have a custom `statusLine` entry, the installer asks before replacing it and backs the +old one up. Uninstalling removes the script and the settings entry but leaves your config file alone. + +--- + +## Full documentation + +Config options, compact mode, thresholds, and troubleshooting: +[`src/statusline-claude/README.md`](../src/statusline-claude/README.md) diff --git a/.readme/test-bot.md b/.readme/test-bot.md new file mode 100644 index 0000000..cbbb90d --- /dev/null +++ b/.readme/test-bot.md @@ -0,0 +1,46 @@ +# Workflow Test Bot + +`plan2code-bot` drives the whole workflow end to end with no human in the loop — init, plan, +document, implement, finalize — to test that the prompts still hold together. + +Built for **maintainers**. If you're using Plan2Code to ship features, you don't need this. + +← [Back to README](../README.md) + +--- + +## Two modes, auto-detected + +| Condition | Mode | What it does | +|-----------|------|--------------| +| No `AGENTS.md` in the working directory | **New project** | Invents an app idea, creates a subdirectory, writes `IDEA.md`, runs init, then all four steps | +| `AGENTS.md` present | **Enhancement** | Reads the existing codebase, proposes a realistic enhancement, writes `IDEA.md`, then runs plan → finalize | + +## Install + +```bash +node install.js # I (everything) — or C → B (bot only) +``` + +## Run + +```bash +# New project mode — start from an empty directory +mkdir /tmp/test-bot && cd /tmp/test-bot +plan2code-bot + +# Enhancement mode — start from a project that has an AGENTS.md +cd my-project +plan2code-bot + +# Or seed the idea generator yourself +plan2code-bot --idea "web app that renders the current weather as vector images" +``` + +--- + +## Full documentation + +Agent SDK wiring, run evaluation, and scoring: +[`plan2code-bot/README.md`](../plan2code-bot/README.md) · +[`plan2code-bot/EVALUATION-SYSTEM.md`](../plan2code-bot/EVALUATION-SYSTEM.md) diff --git a/.readme/walkthrough.md b/.readme/walkthrough.md new file mode 100644 index 0000000..fcb8fc9 --- /dev/null +++ b/.readme/walkthrough.md @@ -0,0 +1,103 @@ +# Walkthrough: one feature, start to finish + +A REST API for task management, from a sentence to archived specs. Every block below is a **separate +conversation** — that's the whole trick. + +← [Back to README](../README.md) + +--- + +## Session 1 — Plan + +``` +You: /plan2code-1-plan + I want to build a REST API for a task management application. + +AI: 🤔 [REQUIREMENTS ANALYSIS] + Six questions. Four of them I need answered before I can size this. + ... + +AI: 🤔 [TECH STACK] + Proposing Fastify + Postgres + Zod. I don't pick this alone — sign off? + +You: approved + +AI: 🤔 [ARCHITECTURE DESIGN] + ... + +AI: 🤔 [TRANSITION DECISION] + Confidence: 92% (gate is 90%). Assumptions written to the draft: 3. + → specs/task-api/PLAN-DRAFT-20260804.md +``` + +Two files land: the draft, and a `PLAN-CONVERSATION-*.md` log of how you got there. + +> **Started foggy instead?** Run `/plan2code-0-pathfinder` first. When its map clears it writes a +> `PLAN-DRAFT` that Step 1 picks up at Phase 4, with requirements and scope already answered. + +--- + +## Session 2 — Document + +``` +You: /plan2code-2-document + specs/task-api/PLAN-DRAFT-20260804.md + +AI: 📝 [DOCUMENTATION] + Creating specs/task-api/overview.md + Creating specs/task-api/Phase 1.md Project setup (6 tasks) + Creating specs/task-api/Phase 2.md Data model (8 tasks) + Creating specs/task-api/Phase 3.md API endpoints (11 tasks) + Creating specs/task-api/Phase 4.md Authentication (7 tasks) + + Parallel execution groups: Phase 3 and Phase 4 don't share files. +``` + +--- + +## Sessions 3…N — Implement, one phase each + +``` +You: /plan2code-3-implement + specs/task-api/overview.md + +AI: ⚡ [PHASE 1: Project setup] + (Phase 1 is the next unchecked phase.) + ... + ✓ 6/6 tasks. Checkboxes updated in Phase 1.md and overview.md. + Next: Phase 2 — Data model (8 tasks). New conversation. +``` + +Repeat. New conversation each time. It always finds the next open phase itself. + +When you reach a parallel group, it offers you the choice — open a second agent, take the other +phase, and the `[/]` marks keep them from colliding. + +**Optional, any time:** `/plan2code-review` for an independent second opinion on what just landed. + +--- + +## Final session — Finalize + +``` +You: /plan2code-4-finalize + specs/task-api/overview.md + +AI: 🧹 [VALIDATION] + All 32 tasks verified against the phase specs. 2 gaps found and fixed. + +AI: 🧹 [DOCUMENTATION REVIEW] + README needs the new /tasks endpoints. AGENTS.md is current. + +AI: 🧹 [SPEC CLEANUP] + Moved specs/task-api/ → specs--completed/task-api/ + + Implementation complete. +``` + +--- + +## If requirements move mid-build + +Don't patch the code and hope the specs catch up. Run `/plan2code-1b-revise-plan` — it edits the +specs (and only the specs), so the drawing and the build stay in agreement. diff --git a/AGENTS.md b/AGENTS.md index 54fea51..f9b0d34 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md -This file provides guidance to AI coding agents like Claude Code (claude.ai/code), Cursor AI, Codex, Gemini CLI, GitHub Copilot, Devin, Zed, and other AI coding assistants when working with code in this repository. +This file provides guidance to AI coding agents like Claude Code (claude.ai/code), Cursor AI, Codex, GitHub Copilot, Devin, Zed, and other AI coding assistants when working with code in this repository. ## Project Overview @@ -52,7 +52,7 @@ Details: [Code Style & Gotchas](./.agents-docs/AGENTS-code-style.md) ## Mascot -The project has a mascot called "Planny" - an ASCII art robot that appears in installer output and workflow prompts. Mascot variants are defined in `MASCOT` constant in `install.js` and appear in workflow markdown files. +The project has a mascot called "Planny" — an ASCII art robot that appears in installer output and workflow prompts. Mascot variants are defined in the `MASCOT` constant in `install.js` and appear in workflow markdown files. ``` ╭───╮ diff --git a/QUICK-REFERENCE.md b/QUICK-REFERENCE.md index 17d86af..850e4fa 100644 --- a/QUICK-REFERENCE.md +++ b/QUICK-REFERENCE.md @@ -2,24 +2,28 @@ ## Commands -| Step | Command | Input | Output | -| ------ | ------------------------------- | --------------- | ----------------------------------- | -| Init | /plan2code-init | None | AGENTS.md file | -| Update | /plan2code-init-update | AGENTS.md | Updated AGENTS.md | -| 0 | /plan2code-quick-task | Requirements | Conversational plan | -| 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/ | +| 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 + 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/ └── / + ├── pathfinder/ # From Step 0 (optional, if charted) + │ ├── map.md # the map: destination, decisions, fog + │ └── questions/NN-.md # one decision question per file ├── PLAN-DRAFT-.md # From Step 1 (verified plan) ├── PLAN-CONVERSATION-.md # From Step 1 (conversation log) ├── overview.md # From Step 2 @@ -77,6 +81,10 @@ New to a project? 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)