diff --git a/.gitignore b/.gitignore index 3eee8b0..54ff8fd 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ specs/ -video-promo/ \ No newline at end of file +dist/ +CLAUDE.md \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 5c01ca4..42ba35f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,230 @@ All notable changes to Plan2Code will be documented in this file. +## v1.3.1 - 2025-12-19 + +### โœจ Added + +- **Init-update mode** (`/plan2code---init-update`) - Interactive workflow to update existing AGENTS.md files + - Detects recent work context and suggests relevant additions + - Menu-driven update options: Commands, Architecture, Gotchas, Testing, Environment, General Rules + - Review and prune options for existing content + - Confirms changes before applying + - Prefix: None (utility command) +- **Session hints** in Steps 2, 3, 4 - Prompts to run `/plan2code---init-update` after discovering project insights +- **AGENTS.md pre-flight check** in Quick Task and Planning modes + - Checks for `./AGENTS.md` at session start + - Offers to run `/plan2code---init` before continuing if not found +- **VS Code Copilot global support** - New platform for VS Code's custom prompts feature + - Files installed to platform-specific VS Code config directory: + - Windows: `%APPDATA%\Code\User\prompts\` + - macOS: `~/Library/Application Support/Code/User/prompts/` + - Linux: `~/.config/Code/User/prompts/` + - Uses VS Code custom prompt format with `agent: agent` header + - File extension: `.prompt.md` + - Platform ID: `vscode-copilot` +- **Dynamic path resolution in install.js** - Added helper functions for targets with platform-specific paths + - `getVSCodeCopilotDir()` - Returns correct VS Code config path per platform + - `resolveTargetDir()` - Handles both static and dynamic directory configurations + - `getDisplayPath()` - Returns human-readable path for display + +### ๐Ÿ”ง Changed + +- **install.js interactive menu** - Now shows 6 platforms (added VS Code Copilot) +- **Help text updated** - Valid platform IDs now include `vscode-copilot` +- **Merged `sync-prompts.js` into `install.js`** - Distribution files are now generated on-the-fly + - No longer need to run a separate sync script before installation + - `dist/` folder is now gitignored (generated dynamically) + - Removed `src/sync-prompts.js` (functionality merged into `install.js`) +- **Added `--local` option** - Show instructions for project-level (local) installation + - Generates `dist/local-commands/` and displays copy/paste instructions + - Available via `node install.js --local` or interactive menu option `L` +- **Updated interactive menu** - Added "L. LOCAL" option for local installation instructions + +### ๐Ÿ—‘๏ธ Removed + +- **`src/sync-prompts.js`** - No longer needed; functionality merged into `install.js` +- **`dist/` from version control** - Now generated dynamically during installation + +## v1.3.0 - 2025-12-18 + +### โœจ Added + +- **AGENTS.md Integration** - All workflow prompts now check for and follow project-specific agent instructions + - Added rule: "If a `./AGENTS.md` file exists, follow the rules, guidelines and documentation in it" + - Applied to Steps 1, 2, 3, and 4 (plan, document, implement, finalize) + - Enables project-specific customization while maintaining consistent workflow methodology +- **Init mode** (`/plan2code---init`) - New command to generate AGENTS.md files for projects + - Analyzes codebase structure and common development commands + - Extracts important details from existing docs (README, PROJECT.md, etc.) + - Creates focused, actionable guidance for AI agents (under 500 lines) + - Prefix: None (utility command) + +### ๐Ÿ”ง Changed + +- **Moved source prompts to `src/` directory** - Cleaner project structure separating source files from distribution + - All `plan2code-*.md` files now live in `src/` + - `sync-prompts.js` moved to `src/sync-prompts.js` + - Run with `node src/sync-prompts.js` (was `node sync-prompts.js`) + - `install.js` remains in project root +- **Sync script now cleans dist folders before syncing** - Ensures no orphaned files from previous syncs + - Deletes `dist/local-commands/` and `dist/global-commands/` before regenerating + - Prevents old/renamed files from lingering in distribution +- **Added `version.json`** - Centralized project metadata file + - Contains name, version, description, author, license, etc. + - Version displayed in install.js TUI header +- **Renamed Quick Task command** - `plan2code-0--quick-task` โ†’ `plan2code---quick-task` + - Removed number prefix for better categorization (utility/standalone mode) + - Maintains same functionality (lightweight planning for small tasks) +- **Renamed Revision command** - `plan2code-1b--revise` โ†’ `plan2code-1b--revise-plan` + - Clearer name indicating it revises planning specs + - Maintains same functionality (modify specs mid-implementation) + +### ๐Ÿ“š Documentation + +- Commands table updated to reflect new naming convention +- README.md updated with new command references and `src/` paths +- QUICK-REFERENCE.md updated with new command names +- CLAUDE.md updated with new development commands and file locations +- **Landing page updated** (`docs/index.html`) + - Added terminal UI screenshot showing the interactive installer + - Added code block with full installation steps (clone, cd, run) + +## v1.2.1 - 2025-12-17 + +### ๐Ÿ”ง Changed + +- **Reorganized distribution files into `dist/` folder** - Cleaner project structure separating source from generated files + - `local-commands/` โ†’ `dist/local-commands/` + - `global-commands/` โ†’ `dist/global-commands/` +- **Updated `sync-prompts.js`** - Now outputs to `dist/local-commands/` and `dist/global-commands/` +- **Updated `install.js`** - Now reads from `dist/global-commands/` +- **Simplified implement/finalize workflow** - Now only requires `overview.md` path instead of both `overview.md` and `Phase X.md` + - Auto-detects next uncompleted phase from Phase Checklist in overview.md + - Automatically reads corresponding `Phase X.md` file + - Reduces user friction when continuing between phases +- **Updated Next Steps sections** across all prompts to show simplified workflow + - Step 2 (Document): Now instructs to provide only `overview.md` + - Step 1b (Revise): Now instructs to provide only `overview.md` + - Step 3 (Implement): Session end boxes updated with auto-detect messaging + - Step 4 (Finalize): Incomplete implementation box updated + +### ๐Ÿ“š Documentation + +- Updated CLAUDE.md with new `dist/` paths for all references +- Updated README.md installation commands (30+ path references updated for both Unix and Windows) +- Updated QUICK-REFERENCE.md commands table (Steps 3 & 4 now show `overview.md` as input) +- Updated README.md workflow examples to show new `[Provide: overview.md]` pattern +- Updated README.md "What to Attach" table with simplified requirements +- Updated README.md troubleshooting section + +## v1.2.0 - 2025-12-14 + +### โœจ Added + +- **Quick Task mode** (`/plan2code-0--quick-task`) - Lightweight planning for small tasks that don't need the full 4-step workflow + - Standalone mode (doesn't create spec files) + - Conversational output with implementation plan + - **Scope validation** with thresholds (โ‰ค3 components, โ‰ค2 integrations, โ‰ค15 tasks, โ‰ค8 files) + - **Escalation path** to full planning - creates PLAN-DRAFT and hands off to Step 1 + - Prefix: `๐Ÿš€` +- **Revision mode** (`/plan2code-1b--revise`) - Structured way to modify specs mid-implementation + - 5-step formal process: Change Analysis โ†’ Impact Assessment โ†’ Execute Revisions โ†’ Consistency Check โ†’ Summary + - Batch approval workflow + - Tracks revision history in overview.md + - Prefix: `๐Ÿ”„ [REVISION]` +- **Requirements Sign-Off gate** in Planning Phase 1 - User must explicitly approve requirements before Phase 2 +- **Escalated PLAN-DRAFT recognition** - Planning mode detects and resumes from Quick Task escalations +- **Good/bad examples** added to Steps 1, 3, and 4 for clearer AI guidance +- **Clarification loop protocol** in Step 1 with max 3 rounds per phase +- **Devil's Advocate check** in Planning Phase 5 (Architecture Design) +- **Error recovery tables** in all prompts' Abort Handling sections +- **Quick Reference card** (`QUICK-REFERENCE.md`) for at-a-glance command reference +- **Revision reminders** in Step 3 completion messages +- **Copilot CLI global support** - Now installs to `~/.copilot/agents/` for global access +- **`install.js`** - New interactive installation script for global setup + - Interactive menu when run without arguments + - Select individual platforms (1-5), multiple (comma-separated), or ALL (A) + - Uninstall option (U) to remove installed files + - Non-interactive flags: `--platform X`, `--dry-run`, `--uninstall` +- **`local-commands/`** directory - Pre-formatted files for project installation +- **`global-commands/`** directory - Pre-formatted files for home directory installation + +### ๐Ÿ”ง Changed + +- **Standardized section headers** across all prompts: + - Role โ†’ Rules โ†’ Examples โ†’ Process โ†’ Templates โ†’ Session End โ†’ Abort Handling โ†’ Recovery โ†’ Important Reminders +- **Condensed templates** for token efficiency (~30% reduction in template verbosity) +- **`sync-prompts.js` restructured** - Now only writes to `local-commands/` and `global-commands/` (removed project root platform directories) +- **Removed platform directories from project root** - No longer syncs to `.claude/`, `.cursor/`, etc. in project root; users copy from `local-commands/` or `global-commands/` instead +- Updated README.md with Quick Reference section and new commands table +- Updated CLAUDE.md with new commands and response prefixes + +### ๐Ÿ“š Documentation + +- Added QUICK-REFERENCE.md with commands table, mode prefixes, file structure, and troubleshooting +- Expanded README.md workflow table to include Steps 0, 1b +- Updated all installation instructions to use `local-commands/` and `global-commands/` +- Added interactive mode documentation for `install.js` +- Documented Copilot CLI global installation at `~/.copilot/agents/` + +## v1.1.1 - 2025-12-11 + +### ๐Ÿ”ง Changed + +- **Phase approval prompt now uses ASCII box** - The "Reply approved" request during implementation sign-off now matches the visual style of other important prompts +- **Cursor: Switched from Rules to Commands** - Now uses `.cursor/commands/` (slash commands) instead of `.cursor/rules/` (MDC rules) + - Commands support global installation at `~/.cursor/commands/` + - Better aligns with how other tools handle workflows/slash commands +- **Archived specs folder renamed** - Changed from `specs/completed/` to `specs--completed/` + - Simplifies folder structure by avoiding nested directories + - Eliminates need for exclusion rules when searching `specs/` + +### ๐Ÿ“š Documentation + +- **Corrected global installation support** - Verified which tools actually support global installation: + - โœ… **Claude Code**: `~/.claude/commands/` + - โœ… **Cursor**: `~/.cursor/commands/` (commands, not rules) + - โœ… **Continue**: `~/.continue/prompts/` + - โœ… **Windsurf**: `~/.codeium/windsurf/global_workflows/` + - โŒ **GitHub Copilot**: Project-only (`.github/agents/` and `.github/prompts/`) + - โŒ **Antigravity**: Project-only (`.agent/workflows/`) - global path not well documented +- Updated Quick Start commands to only include tools that support global installation +- Added Windows-specific installation commands (PowerShell and Command Prompt) +- Added troubleshooting entry for unrecognized slash commands/workflows + +## v1.1.0 - 2025-12-11 + +### โœจ Added + +- **Testing Strategy support** - Optional testing preferences during planning phase + - Test types selection (Unit, Integration, E2E, or None) + - Phase testing option (run tests at end of each phase) + - Coverage target selection (Critical paths, Moderate, Comprehensive) + - Testing tasks automatically added to phase specs when enabled +- **User sign-off requirement** for implementation phases + - Phases marked "Ready for Sign-Off" instead of auto-completing + - User must reply "approved" before phase is marked complete + - Test failure handling: user chooses to fix, document, or investigate +- **Enhanced overview.md structure** - Now includes: + - Architecture Pattern and Component Overview sections + - Risks and Mitigations table + - Success Criteria checklist +- **Improved "Next Steps" formatting** - ASCII box format for clearer guidance at workflow transitions + +### ๐Ÿ”ง Changed + +- Implementation mode no longer auto-marks phases complete; requires explicit user approval +- Self-review checklist now includes test execution verification +- Completion report format updated to show test results table when applicable +- Spec auto-detection now explicitly excludes `specs--completed/` folder + +### ๐Ÿ“š Documentation + +- Added Testing Strategy section (2.4) to PLAN-DRAFT template +- Added Phase Testing task block template for phase specs +- Expanded special cases documentation for testing task generation + ## v1.0.4 - 2025-12-07 ### ๐Ÿ“ฆ Updated diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 2430229..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,83 +0,0 @@ -# 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 - -```bash -# 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 - -1. **Plan** (`plan2code-1--plan.md`) - Requirements analysis and architecture design as a senior architect -2. **Document** (`plan2code-2--document.md`) - Transform planning output into structured implementation docs -3. **Implement** (`plan2code-3--implement.md`) - Execute implementation phase by phase -4. **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-.md # From Step 1 -โ”œโ”€โ”€ / -โ”‚ โ”œโ”€โ”€ 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 diff --git a/QUICK-REFERENCE.md b/QUICK-REFERENCE.md new file mode 100644 index 0000000..3b8cf62 --- /dev/null +++ b/QUICK-REFERENCE.md @@ -0,0 +1,66 @@ +# Plan2Code Quick Reference + +## Commands + +| Step | Command | Input | Output | +| ------ | ---------------------------| --------------- | ------------------------- | +| Init | /plan2code---init | None | AGENTS.md file | +| Update | /plan2code---init-update | AGENTS.md | Updated AGENTS.md | +| 0 | /plan2code---quick-task | Requirements | Conversational plan | +| 1 | /plan2code-1--plan | Requirements | PLAN-DRAFT.md | +| 1b | /plan2code-1b--revise-plan | Specs + changes | Updated specs | +| 2 | /plan2code-2--document | PLAN-DRAFT.md | overview.md + Phase files | +| 3 | /plan2code-3--implement | overview.md | Implemented code | +| 4 | /plan2code-4--finalize | overview.md | Archived specs | + +## File Structure + +``` +specs/ +โ”œโ”€โ”€ PLAN-DRAFT-.md # From Step 1 +โ””โ”€โ”€ / + โ”œโ”€โ”€ overview.md # From Step 2 + โ””โ”€โ”€ Phase X.md # From Step 2 + +specs--completed/ # After Step 4 +โ””โ”€โ”€ / # Archived specs +``` + +## Key Rules + +- Start NEW conversation for each step (and each implementation phase) +- ONE phase per conversation +- Reply "approved" to complete phases +- 90% confidence required before planning completes +- Never look in `specs--completed/` (it's archived specs) + +## Quick Troubleshooting + +| Issue | Solution | +| ---------------------- | ----------------------------------------------- | +| Lost context mid-phase | Attach spec files, say "resume from Task X.Y" | +| Wrong phase started | Say "abort", start correct phase | +| Need to change plan | Use `/plan2code-1b--revise-plan` | +| Multiple spec folders | Specify which: "Continue with specs/user-auth/" | +| Need AGENTS.md file | Use `/plan2code---init` to generate one | +| Update AGENTS.md | Use `/plan2code---init-update` after sessions | + +## Workflow Decision + +``` +New to a project? +โ””โ”€โ”€ /plan2code---init โ†’ Generate AGENTS.md for project-specific guidance + +Learned something during a session? +โ””โ”€โ”€ /plan2code---init-update โ†’ Add learnings to AGENTS.md + +Is it a quick, small task? +โ”œโ”€โ”€ Yes โ†’ /plan2code---quick-task (standalone) +โ””โ”€โ”€ No โ†’ /plan2code-1--plan (full workflow) + โ”œโ”€โ”€ /plan2code-2--document + โ”œโ”€โ”€ /plan2code-3--implement (repeat per phase) + โ””โ”€โ”€ /plan2code-4--finalize + +Need to revise mid-implementation? +โ””โ”€โ”€ /plan2code-1b--revise-plan +``` diff --git a/README.md b/README.md index 368c3f2..8267b23 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ A structured 4-step workflow for developing features and projects with AI assistance. This methodology emphasizes thorough planning before implementation, ensuring well-documented, maintainable code. -Plan2Code Workflow +Plan2Code Workflow ## Overview @@ -15,12 +15,39 @@ A structured 4-step workflow for developing features and projects with AI assist New Chat New Chat New Chat (per phase) New Chat ``` -| Step | File | Purpose | -| ---- | --------------------------- | ---------------------------------------------- | -| 1 | `plan2code-1--plan.md` | Requirements analysis and architecture design | -| 2 | `plan2code-2--document.md` | Create structured implementation documentation | -| 3 | `plan2code-3--implement.md` | Execute the implementation phase by phase | -| 4 | `plan2code-4--finalize.md` | Validate, summarize, and archive | +| Step | File | Purpose | +| ------ | -------------------------------------- | ---------------------------------------------- | +| Init | `src/plan2code---init.md` | Generate AGENTS.md file for project guidance | +| Update | `src/plan2code---init-update.md` | Update existing AGENTS.md with new learnings | +| 0 | `src/plan2code---quick-task.md` | Lightweight planning for small tasks | +| 1 | `src/plan2code-1--plan.md` | Requirements analysis and architecture design | +| 1b | `src/plan2code-1b--revise-plan.md` | Modify specs mid-implementation | +| 2 | `src/plan2code-2--document.md` | Create structured implementation documentation | +| 3 | `src/plan2code-3--implement.md` | Execute the implementation phase by phase | +| 4 | `src/plan2code-4--finalize.md` | Validate, summarize, and archive | + +--- + +## Quick Reference + +| Command | Use When | +|---------|----------| +| `/plan2code---init` | Generate AGENTS.md file for new/existing projects | +| `/plan2code---init-update` | Update AGENTS.md with new learnings from coding sessions | +| `/plan2code---quick-task` | Small, quick tasks that don't need full workflow | +| `/plan2code-1--plan` | Starting a new feature (full planning) | +| `/plan2code-1b--revise-plan` | Requirements change mid-implementation | +| `/plan2code-2--document` | After planning, create implementation specs | +| `/plan2code-3--implement` | Execute implementation (one phase per conversation) | +| `/plan2code-4--finalize` | All phases complete, ready to archive | + +**Key Rules:** +- Start NEW conversation for each step (and each implementation phase) +- ONE phase per conversation +- Reply "approved" to complete phases +- 90% confidence required before planning completes + +See [QUICK-REFERENCE.md](QUICK-REFERENCE.md) for full reference card. --- @@ -30,19 +57,120 @@ This repository includes pre-configured workflow files for all major AI coding a ### Supported Platforms -| Platform | Directory | Invocation | Status | -| ------------------------------------------ | ---------------------- | --------------------------------------------------------------------------------------------------- | ------ | +| Platform | Directory | Invocation | Status | +| ------------------------------------------ | ---------------------- | ----------------------------------------------------------------------------------------------------------- | ------ | | [Claude Code CLI](#claude-code-cli) | `.claude/commands/` | `/plan2code-1--plan`, `/plan2code-2--document`, `/plan2code-3--implement`, `/plan2code-4--finalize` | Ready | -| [GitHub Copilot CLI](#github-copilot-cli) | `.github/agents/` | `--agent=plan2code-1--plan` or `/agent plan2code-1--plan` | Ready | -| [VS Code Copilot](#vs-code-github-copilot) | `.github/prompts/` | Slash commands in chat | Ready | +| [GitHub Copilot CLI](#github-copilot-cli) | `.github/agents/` | `--agent=plan2code-1--plan` or `/agent plan2code-1--plan` | Ready | +| [VS Code Copilot](#vs-code-github-copilot) | `.github/prompts/` | Slash commands in chat | Ready | | [Windsurf IDE](#windsurf-ide) | `.windsurf/workflows/` | `/plan2code-1--plan`, `/plan2code-2--document`, `/plan2code-3--implement`, `/plan2code-4--finalize` | Ready | -| [Cursor AI](#cursor-ai) | `.cursor/rules/` | Command palette or auto-apply | Ready | +| [Cursor AI](#cursor-ai) | `.cursor/commands/` | `/plan2code-1--plan`, `/plan2code-2--document`, `/plan2code-3--implement`, `/plan2code-4--finalize` | Ready | | [Google Antigravity](#google-antigravity) | `.agent/workflows/` | `/plan2code-1--plan`, `/plan2code-2--document`, `/plan2code-3--implement`, `/plan2code-4--finalize` | Ready | | [Continue](#continue-vs-codejetbrains) | `.continue/prompts/` | `/plan2code-1--plan`, `/plan2code-2--document`, `/plan2code-3--implement`, `/plan2code-4--finalize` | Ready | +### Prerequisites + +The install script requires **Node.js** (v14 or later). If you don't have Node.js installed: + +1. Download from [nodejs.org](https://nodejs.org/) +2. Or use a package manager: + - **macOS:** `brew install node` + - **Windows:** `winget install OpenJS.NodeJS` or `choco install nodejs` + - **Linux:** `sudo apt install nodejs` (Debian/Ubuntu) or `sudo dnf install nodejs` (Fedora) + +> **Note:** If you prefer not to install Node.js, you can use **Method 2: Manual copy** below instead. + ### Quick Start -**Option A: Clone and copy to your project** +**Option A: Global Installation (Recommended for supported tools)** + +Some tools support global installation to your home directory. Use files from the `dist/global-commands/` directory: + +| Tool | Home Directory Location | +|------|------------------------| +| Claude Code | `~/.claude/commands/` | +| Copilot CLI | `~/.copilot/agents/` | +| Cursor | `~/.cursor/commands/` | +| Continue | `~/.continue/prompts/` | +| Windsurf | `~/.codeium/windsurf/global_workflows/` | +| VS Code Copilot | Windows: `%APPDATA%\Code\User\prompts\`
macOS: `~/Library/Application Support/Code/User/prompts/`
Linux: `~/.config/Code/User/prompts/` | + +Other tools (GitHub Copilot in `.github/`, Antigravity) require per-project installation. + +> **Home Directory Locations:** +> +> - **macOS/Linux:** `~/` (e.g., `/Users/yourname/` or `/home/yourname/`) +> - **Windows:** `%USERPROFILE%` (e.g., `C:\Users\yourname\`) + +**Method 1: Use the install script (easiest)** + +```bash +# Clone the repository +git clone https://github.com/your-username/plan2code.git +cd plan2code + +# Interactive mode - choose platforms from menu +node install.js +``` + +The interactive menu displays: +``` +Available platforms: + + 1. Claude Code (~/.claude/commands/) + 2. Copilot CLI (~/.copilot/agents/) + 3. Cursor (~/.cursor/commands/) + 4. Continue (~/.continue/prompts/) + 5. Windsurf (~/.codeium/windsurf/global_workflows/) + 6. VS Code Copilot (%APPDATA%\Code\User\prompts\) + + A. Install ALL platforms + U. Uninstall Plan2Code files + Q. Quit + +Enter choice (1-6, A, U, Q, or comma-separated like 1,3,5): +``` + + + +**Non-interactive options:** +```bash +node install.js --dry-run # Preview installation (all platforms) +node install.js --platform claude # Install specific platform only +node install.js --uninstall # Remove all installed files +``` + +**Method 2: Manual copy from `dist/global-commands/`** + +```bash +# Clone the repository +git clone https://github.com/your-username/plan2code.git + +# macOS/Linux - copy desired platform directories: +cp -r plan2code/dist/global-commands/.claude ~/ # Claude Code +cp -r plan2code/dist/global-commands/.copilot ~/ # Copilot CLI +cp -r plan2code/dist/global-commands/.cursor ~/ # Cursor +cp -r plan2code/dist/global-commands/.continue ~/ # Continue +mkdir -p ~/.codeium/windsurf && cp -r plan2code/dist/global-commands/.codeium/windsurf/global_workflows ~/.codeium/windsurf/ # Windsurf +# VS Code Copilot (macOS): +cp plan2code/dist/global-commands/vscode-copilot-prompts/*.prompt.md ~/Library/Application\ Support/Code/User/prompts/ +# VS Code Copilot (Linux): +mkdir -p ~/.config/Code/User/prompts && cp plan2code/dist/global-commands/vscode-copilot-prompts/*.prompt.md ~/.config/Code/User/prompts/ + +# Windows (PowerShell): +Copy-Item -Recurse plan2code\dist\global-commands\.claude $env:USERPROFILE\ +Copy-Item -Recurse plan2code\dist\global-commands\.copilot $env:USERPROFILE\ +Copy-Item -Recurse plan2code\dist\global-commands\.cursor $env:USERPROFILE\ +Copy-Item -Recurse plan2code\dist\global-commands\.continue $env:USERPROFILE\ +New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codeium\windsurf" +Copy-Item -Recurse plan2code\dist\global-commands\.codeium\windsurf\global_workflows $env:USERPROFILE\.codeium\windsurf\ +# VS Code Copilot (Windows): +New-Item -ItemType Directory -Force -Path "$env:APPDATA\Code\User\prompts" +Copy-Item plan2code\dist\global-commands\vscode-copilot-prompts\*.prompt.md $env:APPDATA\Code\User\prompts\ +``` + +**Option B: Per-Project Installation** + +If you prefer project-specific configuration, use files from the `dist/local-commands/` directory: ```bash # Clone the repository @@ -50,27 +178,45 @@ git clone https://github.com/your-username/plan2code.git # Copy the platform-specific directory to your project # Example for Claude Code: -cp -r plan2code/.claude your-project/ +cp -r plan2code/dist/local-commands/.claude your-project/ -# Example for Cursor: -cp -r plan2code/.cursor your-project/ +# Example for GitHub Copilot (VS Code): +cp -r plan2code/dist/local-commands/.github your-project/ + +# Example for Windsurf: +cp -r plan2code/dist/local-commands/.windsurf your-project/ ``` -**Option B: Copy individual platform directories** +> **Warning:** If your project's `.gitignore` includes patterns like `.windsurf/`, `.cursor/`, or similar, the AI tool may not recognize the workflows/commands. Use global installation instead. -Download only the directories you need for your AI coding tool. +**Option C: Download individual platform directories** + +Download only the directories you need from `dist/local-commands/` (for projects) or `dist/global-commands/` (for home directory). ---
Claude Code CLI -**Location:** `.claude/commands/` +**Location:** `.claude/commands/` (project) or `~/.claude/commands/` (global) **Setup:** -1. Copy the `.claude/commands/` directory to your project root -2. Restart Claude Code or start a new session +```bash +# Global installation (recommended) - interactive +node install.js # Select option 1 or A + +# Or non-interactive +node install.js --platform claude + +# Or manual copy +cp -r plan2code/dist/global-commands/.claude ~/ + +# Or per-project +cp -r plan2code/dist/local-commands/.claude your-project/ +``` + +Restart Claude Code or start a new session after installation. **Files:** @@ -100,12 +246,25 @@ Download only the directories you need for your AI coding tool.
GitHub Copilot CLI -**Location:** `.github/agents/` +**Location:** `.github/agents/` (project) or `~/.copilot/agents/` (global) **Setup:** -1. Copy the `.github/agents/` directory to your project root -2. Ensure GitHub Copilot CLI is installed: `npm install -g @github/copilot@latest` +```bash +# Global installation (recommended) - interactive +node install.js # Select option 2 or A + +# Or non-interactive +node install.js --platform copilot + +# Or manual copy +cp -r plan2code/dist/global-commands/.copilot ~/ + +# Or per-project +cp -r plan2code/dist/local-commands/.github your-project/ +``` + +Ensure GitHub Copilot CLI is installed: `npm install -g @github/copilot@latest` **Files:** @@ -137,13 +296,18 @@ copilot
VS Code GitHub Copilot -**Location:** `.github/prompts/` +**Location:** `.github/prompts/` (project only - no global support) **Setup:** -1. Copy the `.github/prompts/` directory to your project root -2. Open VS Code and ensure GitHub Copilot extension is installed -3. Prompts are automatically recognized +```bash +# Per-project installation only +cp -r plan2code/dist/local-commands/.github your-project/ +``` + +Open VS Code and ensure GitHub Copilot extension is installed. Prompts are automatically recognized. + +> **Note:** GitHub prompts must be installed per-project (no global support). **Files:** @@ -180,12 +344,28 @@ description: "Plan2Code Step 1: Planning Mode"
Windsurf IDE -**Location:** `.windsurf/workflows/` +**Location:** `.windsurf/workflows/` (project) or `~/.codeium/windsurf/global_workflows/` (global) **Setup:** -1. Copy the `.windsurf/workflows/` directory to your project root -2. Workflows appear automatically in Cascade +```bash +# Global installation (recommended) - interactive +node install.js # Select option 5 or A + +# Or non-interactive +node install.js --platform windsurf + +# Or manual copy (macOS/Linux) +mkdir -p ~/.codeium/windsurf +cp -r plan2code/dist/global-commands/.codeium/windsurf/global_workflows ~/.codeium/windsurf/ + +# Or per-project +cp -r plan2code/dist/local-commands/.windsurf your-project/ +``` + +> **Note:** Windsurf also searches parent directories up to git root for `.windsurf/workflows/`. + +> **Warning:** If `.windsurf/` is in your project's `.gitignore`, workflows may not be recognized. Use global installation instead. **Files:** @@ -212,41 +392,41 @@ description: "Plan2Code Step 1: Planning Mode"
Cursor AI -**Location:** `.cursor/rules/` +**Location:** `.cursor/commands/` (project) or `~/.cursor/commands/` (global) **Setup:** -1. Copy the `.cursor/rules/` directory to your project root -2. Rules are recognized automatically +```bash +# Global installation (recommended) - interactive +node install.js # Select option 3 or A + +# Or non-interactive +node install.js --platform cursor + +# Or manual copy +cp -r plan2code/dist/global-commands/.cursor ~/ + +# Or per-project +cp -r plan2code/dist/local-commands/.cursor your-project/ +``` **Files:** ``` -.cursor/rules/ -โ”œโ”€โ”€ plan2code-1--plan.mdc # Step 1: Planning -โ”œโ”€โ”€ plan2code-2--document.mdc # Step 2: Documentation -โ”œโ”€โ”€ plan2code-3--implement.mdc # Step 3: Implementation -โ””โ”€โ”€ plan2code-4--finalize.mdc # Step 4: Finalization -``` - -**File Format (MDC):** - -```yaml ---- -description: "Plan2Code Step 1: Planning Mode" -alwaysApply: false ---- -[prompt content] +.cursor/commands/ +โ”œโ”€โ”€ plan2code-1--plan.md # Step 1: Planning +โ”œโ”€โ”€ plan2code-2--document.md # Step 2: Documentation +โ”œโ”€โ”€ plan2code-3--implement.md # Step 3: Implementation +โ””โ”€โ”€ plan2code-4--finalize.md # Step 4: Finalization ``` **Usage:** -- Open Command Palette (Cmd+Shift+P) -- Type "New Cursor Rule" to create new rules -- Reference rules by mentioning them in chat -- Use `/Generate Cursor Rules` to create rules from conversation +- Type `/` in Cursor chat to see available commands +- Select `plan2code-1--plan` from the dropdown +- Commands from both project and global directories appear automatically -**Documentation:** [Cursor Rules for AI](https://docs.cursor.com/context/rules) +**Documentation:** [Cursor Commands](https://docs.cursor.com/agent/chat/commands)
@@ -255,12 +435,20 @@ alwaysApply: false
Google Antigravity -**Location:** `.agent/workflows/` +**Location:** `.agent/workflows/` (project only) + +> **Note:** Antigravity supports global workflows through the UI, but the exact filesystem path is not well documented. Project-level workflows in `.agent/workflows/` are the recommended approach. **Setup:** -1. Copy the `.agent/workflows/` directory to your project root -2. Workflows appear automatically in Antigravity +```bash +# Per-project installation only +cp -r plan2code/dist/local-commands/.agent your-project/ +``` + +Workflows appear automatically in Antigravity. + +> **Warning:** If `.agent/` is in your project's `.gitignore`, workflows may not be recognized. **Files:** @@ -294,13 +482,27 @@ description: "Plan2Code Step 1: Planning Mode"
Continue (VS Code/JetBrains) -**Location:** `.continue/prompts/` +**Location:** `.continue/prompts/` (project) or `~/.continue/prompts/` (global) **Setup:** -1. Copy the `.continue/prompts/` directory to your project root -2. Install the Continue extension for VS Code or JetBrains -3. Prompts are automatically recognized +```bash +# Global installation (recommended) - interactive +node install.js # Select option 4 or A + +# Or non-interactive +node install.js --platform continue + +# Or manual copy +cp -r plan2code/dist/global-commands/.continue ~/ + +# Or per-project +cp -r plan2code/dist/local-commands/.continue your-project/ +``` + +Install the Continue extension for VS Code or JetBrains. Prompts are automatically recognized. + +> **Warning:** If `.continue/` is in your project's `.gitignore`, prompts may not be recognized. Use global installation instead. **Files:** @@ -338,17 +540,17 @@ description: "Plan2Code Step 1: Planning Mode" If your AI tool isn't listed above, you can still use Plan2Code: -1. **Copy/Paste Method:** Copy the contents of the appropriate `plan2code-*.md` file and paste it at the start of your conversation. +1. **Copy/Paste Method:** Copy the contents of the appropriate `src/plan2code-*.md` file and paste it at the start of your conversation. -2. **File Reference Method:** Reference the file directly in your prompt or use the @plan2code-1--plan.md syntax: +2. **File Reference Method:** Reference the file directly in your prompt: ``` - Please follow the instructions in plan2code-1--plan.md + Please follow the instructions in src/plan2code-1--plan.md I want to build a user authentication system. ``` -3. **Custom Integration:** Adapt the prompts to your tool's custom instruction format. +3. **Custom Integration:** Use files from `dist/local-commands/` or `dist/global-commands/` as templates, then adapt to your tool's custom instruction format. --- @@ -425,10 +627,7 @@ specs/ **AI Role:** Senior software engineer -**Required Context:** Attach or reference the `specs//` directory contents: - -- `overview.md` (to identify which phase is next) -- The relevant `Phase X.md` file(s) +**Required Context:** Provide the path to `specs//overview.md`. The command will auto-detect the next uncompleted phase and read the corresponding `Phase X.md` file automatically. **Workflow:** @@ -460,7 +659,7 @@ specs/ 1. **Validation** - Verify all tasks implemented correctly, check for issues 2. **Summary** - Document what was built and list all modified/created files 3. **Documentation Review** - Identify any needed README/CHANGELOG updates -4. **Spec Cleanup** - Move completed specs to `specs/completed//` +4. **Spec Cleanup** - Move completed specs to `specs--completed//` 5. **Final Confirmation** - Confirm completion --- @@ -485,7 +684,7 @@ This repository includes pre-configured workflow files for all major AI coding a Reference the prompt files directly in your conversation: ``` -Please follow the instructions in plan2code-1--plan.md +Please follow the instructions in src/plan2code-1--plan.md I want to build a user authentication system with OAuth support. ``` @@ -530,10 +729,10 @@ AI: ๐Ÿ“ [DOCUMENTATION] ``` User: [Paste or invoke Step 3 prompt] - [Attach: specs/task-api/overview.md] - [Attach: specs/task-api/Phase 1.md] + [Provide: specs/task-api/overview.md] AI: โšก [PHASE 1: Project Setup] + (Auto-detected Phase 1 as next uncompleted phase) Implementing tasks... โœ“ Phase 1 complete. Updated checkboxes in Phase 1.md and overview.md. ``` @@ -542,10 +741,10 @@ AI: โšก [PHASE 1: Project Setup] ``` User: [Paste or invoke Step 3 prompt] - [Attach: specs/task-api/overview.md] - [Attach: specs/task-api/Phase 2.md] + [Provide: specs/task-api/overview.md] AI: โšก [PHASE 2: Database Models] + (Auto-detected Phase 2 as next uncompleted phase) Implementing tasks... โœ“ Phase 2 complete. Updated checkboxes in Phase 2.md and overview.md. ``` @@ -560,13 +759,13 @@ AI: โšก [PHASE 2: Database Models] ``` User: [Paste or invoke Step 4 prompt] - [Attach: specs/task-api/ directory contents] + [Provide: specs/task-api/overview.md] AI: ๐Ÿงน [VALIDATION] Verifying implementation... AI: ๐Ÿงน [SPEC CLEANUP] - Moving to specs/completed/task-api/ + Moving to specs--completed/task-api/ Implementation complete! ``` @@ -617,12 +816,12 @@ The checkbox system enables seamless progress tracking across multiple sessions: ## What to Attach at Each Step -| Step | Required Attachments | +| Step | Required Input | | ------------------ | ---------------------------------------------------- | | Step 1 (Plan) | None (describe your feature/project) | | Step 2 (Document) | `specs/PLAN DRAFT.md` or planning conversation | -| Step 3 (Implement) | `specs//overview.md` + current `Phase X.md` | -| Step 4 (Finalize) | All files in `specs//` directory | +| Step 3 (Implement) | `specs//overview.md` (auto-detects phase) | +| Step 4 (Finalize) | `specs//overview.md` | --- @@ -631,16 +830,15 @@ The checkbox system enables seamless progress tracking across multiple sessions: ``` your-project/ โ”œโ”€โ”€ specs/ -โ”‚ โ”œโ”€โ”€ completed/ -โ”‚ โ”‚ โ””โ”€โ”€ feature-name/ -โ”‚ โ”‚ โ”œโ”€โ”€ overview.md # Archived with completion summary -โ”‚ โ”‚ โ”œโ”€โ”€ Phase 1.md # All checkboxes marked [x] -โ”‚ โ”‚ โ”œโ”€โ”€ Phase 2.md -โ”‚ โ”‚ โ””โ”€โ”€ ... โ”‚ โ””โ”€โ”€ another-feature/ # In-progress feature โ”‚ โ”œโ”€โ”€ overview.md โ”‚ โ””โ”€โ”€ Phase 1.md -| +โ”œโ”€โ”€ specs--completed/ +โ”‚ โ””โ”€โ”€ feature-name/ +โ”‚ โ”œโ”€โ”€ overview.md # Archived with completion summary +โ”‚ โ”œโ”€โ”€ Phase 1.md # All checkboxes marked [x] +โ”‚ โ”œโ”€โ”€ Phase 2.md +โ”‚ โ””โ”€โ”€ ... โ”œโ”€โ”€ your project files... โ””โ”€โ”€ README.md ``` @@ -660,14 +858,20 @@ Feel free to modify these prompts to fit your workflow: ## Troubleshooting +**Slash commands/workflows not recognized:** + +- Check if your project's `.gitignore` includes patterns like `.windsurf/`, `.cursor/`, `.continue/`, or `.agent/` +- Many AI tools don't recognize workflows in gitignored directories +- Solution: Use global installation by copying the directories to your home directory (e.g., `cp -r .windsurf ~/`) + **AI jumps ahead to implementation during planning:** - The prompts explicitly forbid this, but if it happens, remind the AI: "Stay in planning mode. Do not write code yet." **AI doesn't know what to implement:** -- Make sure you attached the `overview.md` and relevant `Phase X.md` files -- The AI needs these files to understand the current state and tasks +- Make sure you provided the path to `overview.md` +- The AI will auto-detect the next phase and read the corresponding `Phase X.md` file **Lost progress between sessions:** diff --git a/docs/desk.jpg b/docs/desk.jpg new file mode 100644 index 0000000..7c1f33d Binary files /dev/null and b/docs/desk.jpg differ diff --git a/docs/favicon.png b/docs/favicon.png new file mode 100644 index 0000000..06c7a2d Binary files /dev/null and b/docs/favicon.png differ diff --git a/docs/index.html b/docs/index.html index c6b4e4f..16f943f 100644 --- a/docs/index.html +++ b/docs/index.html @@ -284,6 +284,28 @@ white-space: nowrap; } + .code-block { + font-family: 'Courier New', Courier, monospace; + background: var(--dark-gray); + color: var(--white); + padding: 1.5rem; + border-radius: 8px; + margin-top: 1rem; + overflow-x: auto; + font-size: 0.9rem; + line-height: 1.6; + font-weight: 400; + display: inline-block; + } + + .code-block .comment { + color: var(--gray); + } + + .code-block .command { + color: var(--accent); + } + .code-list { list-style: auto; margin-left: 40px; @@ -635,6 +657,21 @@ color: var(--gray); } + .install-screenshot { + margin-top: 2rem; + border-radius: 8px; + overflow: hidden; + box-shadow: 0 10px 40px rgba(0, 0, 0, 0.3); + border: 1px solid rgba(85, 96, 247, 0.3); + display: inline-block; + } + + .install-screenshot img { + display: block; + max-width: 100%; + height: auto; + } + /* CTA Section - INVERTED */ .cta { min-height: 100vh; @@ -870,7 +907,7 @@

The AI workflow that puts planning first

- View on GitHub + Get the Code
@@ -1025,8 +1062,19 @@
01

Install the workflow

-

Copy the Plan2Code prompts to your AI assistant. Works with Claude Code, Cursor, GitHub Copilot, Windsurf, and more.

- Get it on GitHub → +

Run the install script to copy the Plan2Code prompts to your AI assistant workflow directories. Works with Claude Code, Cursor, GitHub Copilot, Windsurf, and more.

+ 
# Clone the repository
+git clone https://github.com/jparkerweb/plan2code.git
+
+# Navigate to the directory
+cd plan2code
+
+# Run the interactive installer
+node install.js
+

Get the Code →

+
+ Plan2Code global installation terminal interface showing platform selection menu +
@@ -1057,8 +1105,8 @@

START
PLANNING
NOW

- GET IT ON GITHUB -

Free and open source — transform your AI development workflow today

+ GET THE CODE +

Transform your AI development workflow today