plan2code/AGENTS.md

AGENTS.md

This file provides guidance to AI coding agents like Claude Code (claude.ai/code), Cursor AI, Codex, Gemini CLI, GitHub Copilot, and other AI coding assistants when working with code in this repository.

Project Overview

Plan2Code is a structured 4-step workflow methodology for AI-assisted software development. It provides prompt templates that can be installed globally or per-project for various AI coding tools (Claude Code, Cursor, Copilot, Continue, Windsurf, Codeium).

Version: Check version.json for current version Author: Justin Parker License: MIT

Architecture

plan2code/
├── src/                    # Source workflow prompts (8 markdown files)
├── plan2code-loop/         # Autonomous loop CLI tool (Node.js/TypeScript)
│   ├── src/                # TypeScript source
│   └── 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 for projects
plan2code---init-update.md	Update	Update AGENTS.md with learnings
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, archive

Plan2Code Loop (plan2code-loop/)

A separate Node.js CLI tool that autonomously implements specs by looping through tasks.

Loop Architecture

The loop uses an LLM-driven discovery approach:

• Node app just orchestrates iterations and parses completion markers
• The LLM reads spec files (overview.md, phase-X.md) to discover tasks
• The LLM finds unchecked checkboxes, implements ONE task per iteration, marks it complete
• No regex parsing of markdown in Node - the AI handles all task discovery

Loop Commands

# Build the loop CLI
cd plan2code-loop && npm run build

# Run the loop (after linking) - fully interactive
plan2code-loop

The CLI auto-detects specs in ./specs/, prompts for selection if multiple found, and handles session continuation interactively. Session state is stored per-spec in specs/<feature>/.plan2code-loop/.

Loop Modes

The CLI asks users to choose a loop mode:

• One task per loop (default) - Each agent invocation implements exactly one task. The Node controller handles git commits.
• One phase per loop - Each agent invocation implements all remaining tasks in the current phase. The LLM handles git commits (with JIRA ticket ID if provided). The controller parses multiple completion markers from a single iteration.

Completion Markers

The LLM must output one of these formats:

• TASK_COMPLETE: 1.1 - Task description - Task done successfully
• TASK_BLOCKED: 1.1 - Reason - Cannot complete task
• PHASE_COMPLETE - Current phase finished (phase mode only)
• LOOP_COMPLETE - All phases finished

Development Commands

# Install dev dependencies (sets up husky pre-commit hooks)
npm install

# Run the interactive installer (always interactive — any CLI args are silently ignored)
node install.js

# Plan2Code Loop
cd plan2code-loop && npm install   # First time setup
cd plan2code-loop && npm run build # Build the CLI

Installer Menu Options

Main menu:

Option	Action
I	Install Plan2Code for all platforms + loop CLI
U	Uninstall Plan2Code files + loop CLI (confirmation required)
C	Open CUSTOM sub-menu
Q	Quit

CUSTOM sub-menu (C):

Option	Action
L	Show local (per-project) install instructions
O	Install plan2code-loop CLI only
Q	Return to main menu

How the Installer Works

1. Reads source prompts from src/plan2code-*.md
2. Generates platform-specific files with appropriate headers (YAML frontmatter for some platforms)
3. Writes to dist/ subdirectories organized by destination type
4. Copies to target directories (global: ~/.claude/commands/, etc.)

Platform-Specific File Formats

Platform	Extension / File	Local Dir	Global Dir	Header
Claude Code	.md	—	—	None
Cursor	.md	—	—	None
Copilot CLI	.md	—	—	YAML frontmatter
Continue	.prompt.md	—	—	YAML frontmatter
Windsurf	.md	—	—	YAML frontmatter
VS Code Copilot	.prompt.md	—	—	YAML frontmatter
Codeium	.md	—	—	YAML frontmatter
Claude Code (Skills)	SKILL.md in subdir	.claude/skills/<skill-name>/	~/.claude/skills/<skill-name>/	YAML frontmatter + disable-model-invocation: true
Agent Skills (Amp · Gemini CLI · OpenCode)	SKILL.md in subdir	.agents/skills/<skill-name>/	~/.agents/skills/<skill-name>/	YAML frontmatter (no disable flag)
Crush	SKILL.md in subdir	— (global only)	~/.config/crush/skills/<skill-name>/ (Unix) / %LOCALAPPDATA%\crush\skills\<skill-name>\ (Windows)	YAML frontmatter
Gemini CLI (TOML)	.toml	.gemini/commands/	~/.gemini/commands/	None (TOML fields: description, prompt)

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)

Editing Workflow Prompts

When modifying workflow prompts in src/:

1. Edit the source file in src/
2. Run node install.js to regenerate distribution files
3. Test the workflow in your AI tool of choice
4. The dist/ folder is regenerated automatically - don't edit files there directly

Code Style

• JavaScript: CommonJS modules (Node.js built-ins only - no external dependencies)
• Console output: Uses ANSI color codes via the COLORS constant
• User interaction: Readline-based interactive prompts
• File operations: Synchronous fs operations for simplicity

Gotchas/Pitfalls

• Version sync: When adding a new version to CHANGELOG.md, also update version.json and package.json to match. The installer displays the version from version.json in its header.
• Loop .gitignore setup: ensureGitignore() runs at startup in Controller.run() as a pre-flight step, not just inside createTaskCommit(). This is critical for phase mode where the Node controller doesn't handle commits — without it, git add -A would stage spec files.
• Workflow file character limit: All src/plan2code-*.md files must be ≤ 11,000 characters. A husky pre-commit hook enforces this. The 11,000 limit leaves buffer for platform-specific YAML headers (106-142 chars) to stay under Windsurf's 12,000 char limit.

Git Commit Messages

• AI Assisted footer: All git commit messages must include AI Assisted as the final line, separated from the message body by a blank line
• Commit paths: This is enforced across all commit surfaces:
  • Loop task mode: createTaskCommit() in plan2code-loop/src/utils/git.ts appends the footer automatically
  • Loop phase mode: Prompt template instructs the LLM to add -m "AI Assisted" as the final flag
  • Implement mode: User-facing commit suggestions in src/plan2code-3--implement.md include the footer
• Init workflow: src/plan2code---init.md generates AGENTS.md files with a Git Commit Messages section that includes this convention by default

Mascot

The project has a mascot called "Planny" - an ASCII art robot that appears in installer output and workflow prompts. Mascot variants are defined in MASCOT constant in install.js and appear in workflow markdown files.

  o     o
   ╲   ╱
   ╭───╮
   │ ● │
   │ ◡ │
   ├───┤
   │ · │
   ╰───╯