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

Architecture

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

Directory Structure

plan2code/
├── src/                        # Source workflow prompts (9 markdown files)
│   └── plan2code-3b-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
├── 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-3b-review.md	3b	Post-implementation comprehensive review
plan2code-4-finalize.md	4	Validate, summarize, feedback, archive (7 steps)

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-3b-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-3b-review-references/<file>.md).
• TOML platforms (Gemini CLI): reference files are skipped — TOML embeds content inline, so Read directives won't resolve. The orchestrator's inline fallback text covers this.

Reference files are NOT subject to the 11,000 character limit. Currently only the review workflow (Step 3b) uses this pattern — it serves as the POC for potential adoption by other workflows.