mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-09-17 16:22:23 -07:00
jparkerweb
b78b3cd6a3
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
135 lines
10 KiB
Markdown
135 lines
10 KiB
Markdown
# Architecture
|
||
> Part of [AGENTS.md](../AGENTS.md) — project guidance for AI coding agents.
|
||
|
||
## Directory Structure
|
||
|
||
```
|
||
plan2code/
|
||
├── 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)
|
||
├── plan2code-metrics/ # Recursive self-improvement toolchain
|
||
│ ├── src/ # TypeScript source
|
||
│ │ └── prompts/ # Internal AI prompt templates (no char limit)
|
||
│ └── dist/ # Built output (tsup)
|
||
├── src/statusline-claude/ # Claude CLI status line (Node.js, zero deps, single file)
|
||
│ ├── statusline.js # Self-contained: config, git, formatters, render
|
||
│ └── statusline-config.json # Default config template
|
||
├── scripts/ # Development scripts
|
||
│ └── validate-char-count.js # Pre-commit character count validator
|
||
├── dist/ # Generated distribution files (auto-generated)
|
||
│ ├── global-commands/ # For global installation (~/.claude/, etc.)
|
||
│ └── local-commands/ # For per-project installation (.claude/, etc.)
|
||
├── .husky/ # Git hooks (husky)
|
||
│ └── pre-commit # Runs character count validation
|
||
├── .claude/ # Repo-local Claude Code config (NOT installed by install.js)
|
||
│ └── skills/ # Maintainer-only dev skills, e.g. plan2code-publish/
|
||
├── docs/ # Documentation and assets
|
||
├── specs/ # Feature specs (if any in-progress)
|
||
├── install.js # Interactive installer (Node.js)
|
||
├── package.json # Root package (husky only, private: true)
|
||
├── version.json # Version metadata
|
||
└── README.md # User documentation
|
||
```
|
||
|
||
## Key Files
|
||
|
||
| File | Purpose |
|
||
|------|---------|
|
||
| `install.js` | Main installer - generates and installs workflow files to AI tool directories |
|
||
| `src/plan2code-*.md` | Source workflow prompts (the "source of truth") |
|
||
| `scripts/validate-char-count.js` | Pre-commit validator ensuring all source prompts ≤ 11,000 chars |
|
||
| `version.json` | Version metadata (name, version, description) |
|
||
| `QUICK-REFERENCE.md` | User quick-reference card |
|
||
| `src/statusline-claude/` | Claude CLI status bar (included in `A` Install All + dev tools; also via Custom → S) |
|
||
|
||
## Workflow Prompts (in `src/`)
|
||
|
||
| File | Step | Purpose |
|
||
|------|------|---------|
|
||
| `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-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 (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
|
||
|
||
Workflow files follow a strict naming pattern:
|
||
- **Utilities:** `plan2code-<name>.md` (single dash)
|
||
- **Numbered steps:** `plan2code-<N>-<name>.md` (single dash, number, single dash)
|
||
|
||
Examples:
|
||
- `plan2code-init.md` (utility)
|
||
- `plan2code-1-plan.md` (step 1)
|
||
- `plan2code-1b-revise-plan.md` (step 1b)
|
||
|
||
## Reference Files
|
||
|
||
Some workflows use companion reference files for depth that exceeds the 11k char limit. The orchestrator (main workflow file) loads them via `Read` directives during execution.
|
||
|
||
**Pattern:** `src/<source-filename-without-extension>-references/` (e.g., `plan2code-review-references/`)
|
||
|
||
**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`).
|
||
|
||
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/`)
|
||
|
||
Maintainer-only Claude Code skills committed to the repo but **deliberately excluded** from `install.js` — they are dev tooling, not shipped product, so they never install to `~/.claude/skills/` and carry no version bump of their own (a product-version bump would wrongly imply a user-facing release); changelog mentions fold into the current version's entry.
|
||
|
||
- `plan2code-publish/` — cuts a GitHub Release from the top `CHANGELOG.md` entry once `CHANGELOG.md` / `version.json` / `package.json` agree and the version is ahead of the latest published release. Delegates tag creation to `gh release create --target main`.
|
||
|
||
**Warning:** anything named `plan2code-*` placed under `~/.claude/skills/` is deleted by the installer's uninstall (`uninstallFiles()` in `install.js`) and by every re-install's pre-copy cleanup in `install()` (both match `/^plan2code-/` for the Claude Code skills target). Keep these skills repo-local only.
|
||
|
||
## Status Line
|
||
|
||
Optional Claude Code status bar living in `src/statusline-claude/`. Three-line bar (icon + content per line) showing model, project, branch, uncommitted diff stats, session duration + cost, context window usage, and plan/quota usage.
|
||
|
||
**Design constraints:**
|
||
- **Zero runtime dependencies** — `statusline.js` is self-contained (config loader, git helpers, formatters, render). Copied verbatim to `~/.claude/plan2code-statusline.js` on install; no bundler step.
|
||
- **Stdin-driven** — all data comes from Claude Code's stdin JSON (`model`, `workspace`, `context_window`, `rate_limits`, `cost`). No API calls, no auth, no background processes.
|
||
- **Silent failure** — outer `try/catch` around `main()` plus `process.exit(0)` on missing stdin guarantees the script never crashes the CLI. All git ops are timeout-bounded (1.5s) and non-git workspaces short-circuit via `fs.existsSync('.git')`.
|
||
- **Atomic settings writes** — installer writes `~/.claude/settings.json` via temp file + rename so a crash never leaves the file truncated.
|
||
- **Custom-config respect** — installer detects non-plan2code `statusLine` entries, prompts before replacing, and backs up to `statusline-previous.json`. Uninstall only removes `settings.statusLine` if it points to the plan2code bundle.
|
||
|
||
**Layout:**
|
||
|
||
```
|
||
src/statusline-claude/
|
||
├── statusline.js # Self-contained: config, git, formatters, render
|
||
├── statusline-config.json # Default config template
|
||
└── README.md # User docs: install, config, debugging
|
||
```
|
||
|
||
**Adaptive plan-usage display:** the formatter auto-selects between `5h/7d` rate-limit percentages (Pro/Max/Teams — when `rate_limits` present in stdin) and `Nk in · Nk out` session-token counts (Bedrock/Vertex/PAYG — when `rate_limits` absent). Segment is hidden when neither shape is available.
|
||
|
||
**Installer integration** lives in `install.js` under the `STATUS LINE INSTALLATION` section (`installStatusLine`, `uninstallStatusLine`). Included in `A` (Install All + dev tools); also available individually via Custom → `S`.
|