mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-09-17 16:22:23 -07:00
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
This commit is contained in:
@@ -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/`)
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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/<feature>/.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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
```
|
||||
╭───╮
|
||||
|
||||
+20
-12
@@ -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-<date>.md + PLAN-DRAFT-<date>.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-<date>.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-<date>.md + PLAN-DRAFT-<date>.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)
|
||||
│ ├── map.md # the map: destination, decisions, fog
|
||||
│ └── questions/NN-<slug>.md # one decision question per file
|
||||
├── PLAN-DRAFT-<date>.md # From Step 1 (verified plan)
|
||||
├── PLAN-CONVERSATION-<date>.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)
|
||||
|
||||
Reference in New Issue
Block a user