plan2code/.agents-docs/AGENTS-architecture.md

Architecture

Part of 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.