Recursive self-improvement toolchain for plan2code contributors. Collects metrics from completed project specs, aggregates them across runs and prompt generations, then uses AI to diagnose weak steps and propose targeted edits to the workflow prompts.
plan2code-metrics # → "Collect metrics" → pick your spec dir → done (5 sec)
# When you're curious or have 3+ runs:
plan2code-metrics # → "View metrics status" to see the dashboard
# → "Run analysis" for AI diagnosis of weak spots
# → "Generate improvement proposal" for prompt edits
# → "Review and apply" to patch src/plan2code-*.md
```
**One habit:** collect after every finished spec. Everything else is on-demand.
### How Many Runs Do I Need?
| Runs | What You Get |
|------|-------------|
| **1** | Raw data and basic dashboard. Start here. |
| **3+** | AI analysis unlocks (warns below 3 that results may be unreliable). Pattern detection starts working. |
| **5-10+** | Averages stabilize. Generation-over-generation comparisons become meaningful. |
More is always better — each run adds a data point. You're looking for trends, not individual scores.
### The Feedback Loop
```
Use plan2code on a project (steps 1-4)
|
v
Collect metrics from the finished spec <-- do this every time
|
v
Aggregate across runs (automatic)
|
v
Analyze weak spots (AI-powered, 3+ runs)
|
v
Generate prompt improvements
|
v
Apply edits to src/plan2code-*.md
|
v
Prompts have new SHA hashes = new "generation"
|
v
Use improved prompts on next project
|
v
Collect again, compare generations <-- the loop closes
```
After applying edits, the prompt file SHA hashes change. The next collected run falls into a **new cohort** (generation). The dashboard then shows generation-over-generation deltas — "Did confidence go up? Did blockers decrease?" — so you can measure whether your edits actually helped.
Choose **A** (Advanced) then **E** (Everything) to install prompts, bot, metrics, and status line together. Or choose **A** then **M** (Metrics) to install just the metrics CLI.
The installer handles `npm install`, `npm run build`, and global linking automatically. After install, `plan2code-metrics` is available from any directory.
### Manual install
If you prefer to install manually or are developing on the metrics package:
```bash
cd plan2code-metrics
npm install
npm run build
npm link
```
To run without linking:
```bash
npm start
# or
node dist/bin/plan2code-metrics.js
```
## Usage
Run `plan2code-metrics` from inside (or near) a plan2code repository. The CLI is fully interactive — no flags, all inputs collected via prompts.
```
plan2code-metrics
```
### Main Menu
| Option | Description |
|--------|-------------|
| **Collect metrics** | Parse a completed project spec and extract step-by-step metrics into a run JSON |
| **Import run data** | Copy a run JSON from another project into the local metrics store |
| **View metrics status** | Show aggregated metrics with health indicators and generation deltas |
| **Fetch community submissions** | List open community-feedback GitHub issues, parse + validate their METRICS_JSON payload, import into the local run store, and close them |
After completing Step 4 (finalize) on any project:
```bash
cd your-project
plan2code-metrics
```
Pick **"Collect metrics"** and point it at your spec directory (`specs/<feature>/` or `specs--completed/<feature>/`). It reads your artifacts, extracts ~30 metrics, and writes a run JSON. Takes about 5 seconds.
The data stays local to that project in `.plan2code/metrics/runs/`. To aggregate across multiple projects, use **"Import"** to copy run files into one central location.
- **Tasks completed / total** — task counts read from the METRICS_JSON block in `overview.md`, else the Completion Summary, else checkbox counts across the phase files
Reads completed project artifacts from `specs/` or `specs--completed/` and extracts metrics for each workflow step. Output: `.plan2code/metrics/runs/run-<timestamp>.json`
Merges all run files into `aggregated.json`, grouped by **prompt generation** — a SHA fingerprint of the 8 workflow prompt files. Two runs that used identical prompt files belong to the same cohort.
### 3. Analyze
Sends aggregated metrics to an AI model with an analyst prompt. The AI produces a diagnosis identifying the weakest workflow steps and root causes. No edits are proposed at this stage.
Interactive diff review for each proposed edit. Accept, reject, or skip individual changes. Applied edits are patched directly into `src/plan2code-*.md`.