mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-07-21 18:33:22 -07:00
jparkerweb
5e48e98293
- Add /plan2code-3b-review: 5-step post-implementation review with adaptive scope, 11 dimensions, reference-file architecture, and Plan/Apply/Verify fixes - Unify workflow/skill file naming to single-dash (drop -- and --- conventions) - Add Devin platform support and CLAUDE.md MANDATORY FIRST STEP template - Guide agents to use semantic anchors over line numbers in workflow prompts - Bump version to 1.14.0
82 lines
4.6 KiB
Markdown
82 lines
4.6 KiB
Markdown
# Architecture
|
|
> Part of [AGENTS.md](../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.
|