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:
@@ -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.
|
||||
Reference in New Issue
Block a user