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

Architecture

Part of AGENTS.md — project guidance for AI coding agents.

Directory Structure

plan2code/
├── src/                        # Source workflow prompts (8 markdown files)
├── 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)
├── 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
├── 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

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---quick-task.md	0	Lightweight planning for small tasks
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-4--finalize.md	4	Validate, summarize, feedback, archive (7 steps)

Naming Convention

Workflow files follow a strict naming pattern:

• Utilities: plan2code---<name>.md (triple dash)
• Numbered steps: plan2code-<N>--<name>.md (single dash, number, double dash)

Examples:

• plan2code---init.md (utility)
• plan2code-1--plan.md (step 1)
• plan2code-1b--revise-plan.md (step 1b)