CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Repository Is

Plan2Code is a structured 4-step workflow methodology for AI-assisted software development. It contains prompt templates, not executable code. The workflow emphasizes thorough planning before implementation.

Development Commands

# Sync source prompts to all platform-specific directories
node sync-prompts.js

# Preview changes without writing
node sync-prompts.js --dry-run

Repository Architecture

Source prompts (root directory) are the canonical versions:

plan2code-1--plan.md - Planning mode prompt
plan2code-2--document.md - Documentation mode prompt
plan2code-3--implement.md - Implementation mode prompt
plan2code-4--finalize.md - Finalization mode prompt

sync-prompts.js copies these to platform-specific directories with appropriate YAML headers:

.claude/commands/ - Claude Code CLI (no headers)
.cursor/rules/ - Cursor AI (.mdc extension, alwaysApply: false)
.github/prompts/ - VS Code Copilot (mode: agent)
.github/agents/ - GitHub Copilot CLI
.continue/prompts/ - Continue extension
.windsurf/workflows/ - Windsurf IDE
.agent/workflows/ - Google Antigravity

Always edit source prompts in root, then run node sync-prompts.js to propagate changes.

Workflow Steps

Plan (plan2code-1--plan.md) - Requirements analysis and architecture design as a senior architect
Document (plan2code-2--document.md) - Transform planning output into structured implementation docs
Implement (plan2code-3--implement.md) - Execute implementation phase by phase
Finalize (plan2code-4--finalize.md) - Validate, summarize, and archive

Key Behavioral Rules

Start a new conversation before each step (and for each implementation phase)
Complete only one planning/implementation phase at a time, then stop
Must reach 90% confidence before finalizing plans
Tech stack decisions require explicit user approval
Keep checkboxes updated in spec files for progress tracking
Follow specifications exactly as documented
Do NOT run tests unless explicitly included in phase tasks

Response Prefixes

Each mode has a required prefix:

Planning: 🤔 [CURRENT PLANNING PHASE]
Documentation: 📝 [CURRENT DOCUMENTATION PHASE]
Implementation: ⚡ [CURRENT IMPLEMENTATION PHASE]
Finalization: 🧹 [FINALIZATION STEP]

Output Structure

Specs are stored in specs/ folder:

specs/
├── PLAN-DRAFT-<timestamp>.md    # From Step 1
├── <feature-name>/
│   ├── overview.md              # Phase checklist
│   └── Phase X.md               # Detailed tasks per phase
└── completed/                   # Archived after finalization

Using as Slash Commands

In Claude Code, invoke with:

/plan2code-1--plan - Start planning
/plan2code-2--document - Create implementation docs
/plan2code-3--implement - Execute implementation
/plan2code-4--finalize - Validate and archive

3.1 KiB Raw Blame History