mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-09-17 16:22:23 -07:00
jparkerweb
e57dad052c
Align release notes, version metadata, installation guidance, and maintainer documentation with the canonical skills workflow. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
134 lines
9.7 KiB
Markdown
134 lines
9.7 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
|
||
├── skills/ # Committed build artifact — one Agent Skill per src/ prompt
|
||
│ └── plan2code-<name>/ # SKILL.md plus references/ where present
|
||
│ # Generated by npm run build:skills; consumed by skills add
|
||
├── .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` | Interactive installer — builds `skills/` from `src/`, then delegates installation to the skills CLI |
|
||
| `src/plan2code-*.md` | Source workflow prompts (the "source of truth") |
|
||
| `skills/` | Generated Agent Skills committed for installation and drift verification |
|
||
| `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:** the directory is copied verbatim to `skills/<skill-name>/references/`, so `Read references/<file>.md` resolves consistently for every agent. There is one output format, with no flat-file sibling directory or path rewrite.
|
||
|
||
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`, `github-issues` — 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.
|
||
|
||
## Repo-Local Skills (`.claude/skills/`)
|
||
|
||
Maintainer-only skills committed to the repo but deliberately excluded from the generated `skills/` product artifact:
|
||
|
||
- `plan2code-publish/` — publishes a GitHub Release after version files agree.
|
||
- `plan2code-changelog/` — validates release classification and keeps version files synchronized.
|
||
- `sync-repo/` — decrypts the protected upstream-sync workflow in memory.
|
||
|
||
Do not run `skills add` against the repository root: recursive discovery also finds these maintainer skills. `install.js` targets `skills/` and passes explicit workflow names instead. Global install/uninstall cleanup removes `plan2code-*` workflow skills from user skill directories; it never operates on this repository's `.claude/skills/` directory, and `sync-repo` intentionally has no `plan2code-` prefix.
|
||
|
||
## 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`.
|