From 035cc680a7bfa9b9783df69706c7a1a61b443789 Mon Sep 17 00:00:00 2001 From: Justin Parker Date: Tue, 3 Feb 2026 20:32:18 -0800 Subject: [PATCH] spacing --- AGENTS.md | 3 +++ CHANGELOG.md | 9 +++++++++ QUICK-REFERENCE.md | 10 ++++++++++ README.md | 17 +++++++++++++++++ install.js | 23 +++++++++++++++++++++++ src/plan2code---quick-task.md | 2 ++ src/plan2code-2--document.md | 15 +++++++++++++++ 7 files changed, 79 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index f1d8ce1..1b2ecb0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -169,8 +169,11 @@ When modifying workflow prompts in `src/`: ## Gotchas/Pitfalls - **Version sync:** When adding a new version to `CHANGELOG.md`, also update `version.json` to match. The installer displays the version from `version.json` in its header. + ## Mascot + The project has a mascot - 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. + ``` ╭───╮ │ ● │ diff --git a/CHANGELOG.md b/CHANGELOG.md index fea161d..e1f16a4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,8 +13,11 @@ All notable changes to Plan2Code will be documented in this file. - Correct relative paths for each file location (./AGENTS.md, ../AGENTS.md, ../../AGENTS.md) - **Knowledge Transfer** - Init mode now uses existing CLAUDE.md content as context when creating new AGENTS.md - Preserves project knowledge during migration to AGENTS.md + ## v1.5.1 + ### ✨ Added + - **Prerequisite verification workflow** - Agents now verify/complete prerequisites before starting phase tasks - Implementation mode processes prerequisites in order: verify, complete, or mark assumed - Loop prompt treats prerequisites as "Task 0.X" - one per iteration before tasks @@ -30,6 +33,7 @@ All notable changes to Plan2Code will be documented in this file. - Consistency check now verifies phase completion status matches task completion ### 🔧 Changed + - **Installer UI refresh** - Cleaner, narrower layout for better terminal compatibility - Narrower menu boxes (65 characters instead of 76) - Smaller mascot display at end of installation @@ -47,6 +51,7 @@ All notable changes to Plan2Code will be documented in this file. ## v1.5.0 - 2026-01-22 ### ✨ Added + - **Plan2Code Loop** - New autonomous CLI tool for hands-off spec implementation - Separate Node.js/TypeScript tool in `plan2code-loop/` directory - LLM-driven task discovery - AI reads spec files and finds unchecked tasks @@ -60,6 +65,7 @@ All notable changes to Plan2Code will be documented in this file. - Option `U` uninstalls prompts AND unlinks the loop CLI ### 📝 Documentation + - Updated README.md with "Autonomous Loop" section explaining when to use loop vs manual Step 3 - Updated QUICK-REFERENCE.md with loop commands and decision tree - Updated AGENTS.md with loop architecture, commands, and completion markers @@ -67,6 +73,7 @@ All notable changes to Plan2Code will be documented in this file. ## v1.4.0 - 2026-01-09 ### ✨ Added + - **Parallel Phase Execution** - Run multiple implementation phases simultaneously in separate agent instances - Documentation Mode auto-detects parallel-eligible phases based on file conflicts and dependencies - Implementation Mode presents phase selection UI when parallel options are available @@ -82,6 +89,7 @@ All notable changes to Plan2Code will be documented in this file. - Supports multiple agent sessions on parallel phases with clear visibility of what's active ### 🔧 Changed + - **Documentation Mode process** - Added step 6 "Analyze phases for parallel execution eligibility" - **Implementation Mode detection** - Now checks for parallel siblings before starting phase - **Implementation Mode phase selection** - 4-case decision logic for parallel, resume, auto-start scenarios @@ -108,6 +116,7 @@ All notable changes to Plan2Code will be documented in this file. ## v1.3.2 - 2025-12-25 + ### 🔧 Changed - **Phase file naming convention** - Changed from `Phase X.md` to `phase-X.md` (lowercase, hyphen instead of space) diff --git a/QUICK-REFERENCE.md b/QUICK-REFERENCE.md index 49fb5bf..7c905e7 100644 --- a/QUICK-REFERENCE.md +++ b/QUICK-REFERENCE.md @@ -35,17 +35,22 @@ specs--completed/ # After Step 4 - Never look in `specs--completed/` (it's archived specs) ## Phase Status + | Checkbox | Status | Meaning | |----------|--------|---------| | `[ ]` | Pending | Not started | | `[/]` | In Progress | Agent working (or paused) | | `[x]` | Complete | Approved | + ## Parallel Execution + When phases have no file conflicts or dependencies, they can run simultaneously: + 1. Documentation Mode auto-detects parallel-eligible phases 2. Implementation Mode shows selection UI with status for each phase 3. Run multiple `/plan2code-3--implement` instances on different phases 4. `[/]` status shows which phases are actively being worked on + ## Quick Troubleshooting | Issue | Solution | @@ -78,13 +83,18 @@ Is it a quick, small task? Need to revise mid-implementation? └── /plan2code-1b--revise-plan ``` + ## Autonomous Loop (Alternative) + The `plan2code-loop` CLI is an **alternative** to Step 3, not a replacement. + | Approach | Use When | |----------|----------| | `/plan2code-3--implement` | You want interactive control per phase | | `plan2code-loop` | You want hands-off autonomous execution | + ```bash plan2code-loop # Fully interactive - auto-detects specs, prompts for options ``` + Session state stored per-spec in `specs//.plan2code-loop/` diff --git a/README.md b/README.md index afb1e6e..fc94e52 100644 --- a/README.md +++ b/README.md @@ -39,10 +39,13 @@ See [QUICK-REFERENCE.md](QUICK-REFERENCE.md) for full reference card. ## Installation Plan2Code includes an interactive installer that generates and installs workflow files for all major AI coding assistants. + + ### 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` @@ -50,6 +53,7 @@ The install script requires **Node.js** (v14 or later). If you don't have Node.j - **Linux:** `sudo apt install nodejs` (Debian/Ubuntu) or `sudo dnf install nodejs` (Fedora) ### Supported Platforms + | Platform | Global Directory | Invocation | | ---------------- | -------------------------------------- | ---------------------------- | | Claude Code | `~/.claude/commands/` | `/plan2code-1--plan`, etc. | @@ -59,16 +63,19 @@ The install script requires **Node.js** (v14 or later). If you don't have Node.j | Windsurf | `~/.codeium/windsurf/global_workflows/`| `/plan2code-1--plan`, etc. | | Codeium (IJ) | `~/.codeium/global_workflows/` | `/plan2code-1--plan`, etc. | | VS Code Copilot | Platform-specific (see below) | Slash commands in chat | + **VS Code Copilot paths:** - Windows: `%APPDATA%\Code\User\prompts\` - macOS: `~/Library/Application Support/Code/User/prompts/` - Linux: `~/.config/Code/User/prompts/` + ### Quick Start ```bash # Clone the repository git clone https://github.com/plan/plan2code.git cd plan2code + # Run the interactive installer node install.js ``` @@ -85,6 +92,7 @@ Available platforms: 5. Windsurf (~/.codeium/windsurf/global_workflows/) 6. Codeium (IJ) (~/.codeium/global_workflows/) 7. VS Code Copilot (%APPDATA%\Code\User\prompts\) + A. Install ALL platforms + loop CLI O. Build/link plan2code-loop CLI only L. Show local (project) install instructions @@ -112,22 +120,28 @@ Enter choice (1-7, A, O, L, U, Q, or comma-separated like 1,3,5): ```bash # Install to Claude Code only node install.js --platform claude + # Install to multiple specific platforms node install.js # Then enter "1,3,5" for Claude, Cursor, Windsurf # Preview installation without making changes node install.js --dry-run + # Remove all installed files node install.js --uninstall ``` ### Per-Project Installation + If you prefer project-specific configuration instead of global installation: + ```bash # Run the installer with --local flag node install.js --local ``` + This will generate the distribution files and display instructions for copying them to your project. The generated files will be in `dist/local-commands/` organized by platform: + ``` dist/local-commands/ ├── .claude/commands/ # Claude Code @@ -138,10 +152,13 @@ dist/local-commands/ ├── .windsurf/workflows/ # Windsurf └── .agent/workflows/ # Google Antigravity ``` + > **Note:** Some AI tools (Windsurf, Cursor, Continue) may not recognize workflows in gitignored directories. If your project's `.gitignore` includes patterns like `.windsurf/`, consider using global installation instead. + --- ## Platform-Specific Notes +
Claude Code CLI diff --git a/install.js b/install.js index f7111a3..9085451 100644 --- a/install.js +++ b/install.js @@ -1317,11 +1317,13 @@ function runInteractive() { rl.close(); const uninstallResult = uninstallFiles(targets); + // If uninstalling from ALL platforms, also unlink plan2code-loop if (uninstallInput === 'A') { console.log(''); uninstallPlan2CodeLoop(); } + process.exit(uninstallResult); } @@ -1358,16 +1360,20 @@ function runInteractive() { } rl.close(); + // If installing ALL platforms, install plan2code-loop first let loopResult = 0; if (input === 'A') { loopResult = installPlan2CodeLoop(); console.log(''); } + const installResult = install(targets); + if (input === 'A') { process.exit(installResult === 0 && loopResult === 0 ? 0 : 1); } + process.exit(installResult); } @@ -1381,25 +1387,32 @@ function runInteractive() { // ============================================================================ // PLAN2CODE-LOOP INSTALLATION // ============================================================================ + const { execSync, spawn } = require('child_process'); + /** * Build plan2code-loop package */ function buildPlan2CodeLoop() { const loopDir = path.join(__dirname, 'plan2code-loop'); + // Check if directory exists if (!fs.existsSync(loopDir)) { console.log(`${COLORS.YELLOW}${SYMBOLS.WARNING}${COLORS.RESET} plan2code-loop directory not found`); return false; } + console.log(`${COLORS.CYAN}${SYMBOLS.ACTIVE} Building plan2code-loop...${COLORS.RESET}`); + try { // Install dependencies console.log(` ${COLORS.DIM}Installing dependencies...${COLORS.RESET}`); execSync('npm install', { cwd: loopDir, stdio: 'pipe' }); + // Build console.log(` ${COLORS.DIM}Running build...${COLORS.RESET}`); execSync('npm run build', { cwd: loopDir, stdio: 'pipe' }); + console.log(` ${COLORS.GREEN}${SYMBOLS.SUCCESS}${COLORS.RESET} Build complete`); return true; } catch (error) { @@ -1606,14 +1619,17 @@ function removeGlobalSymlink() { */ function installPlan2CodeLoop() { displaySectionHeader('PLAN2CODE-LOOP', '[ BUILD & INSTALL ]'); + const buildSuccess = buildPlan2CodeLoop(); if (!buildSuccess) { return 1; } + const symlinkSuccess = createGlobalSymlink(); if (!symlinkSuccess) { return 1; } + console.log(''); console.log(`${COLORS.GREEN}${SYMBOLS.SUCCESS} plan2code-loop installed successfully!${COLORS.RESET}`); console.log(''); @@ -1623,19 +1639,25 @@ function installPlan2CodeLoop() { console.log(` ${COLORS.BRIGHT}plan2code-loop -v${COLORS.RESET} Verbose mode`); console.log(` ${COLORS.BRIGHT}plan2code-loop --help${COLORS.RESET} Show all options`); console.log(''); + return 0; } + /** * Uninstall plan2code-loop */ function uninstallPlan2CodeLoop() { displaySectionHeader('PLAN2CODE-LOOP', '[ UNINSTALL ]'); + removeGlobalSymlink(); + console.log(''); console.log(`${COLORS.GREEN}${SYMBOLS.SUCCESS} plan2code-loop uninstalled${COLORS.RESET}`); console.log(''); + return 0; } + // ============================================================================ // MAIN // ============================================================================ @@ -1643,6 +1665,7 @@ function uninstallPlan2CodeLoop() { // Additional CLI arguments for plan2code-loop const installLoop = args.includes('--loop'); const uninstallLoop = args.includes('--uninstall-loop'); + // Run the appropriate function if (installLoop) { process.exit(installPlan2CodeLoop()); diff --git a/src/plan2code---quick-task.md b/src/plan2code---quick-task.md index 33f8278..3320168 100644 --- a/src/plan2code---quick-task.md +++ b/src/plan2code---quick-task.md @@ -41,6 +41,7 @@ You are a senior software architect and engineer. Your purpose is to thoroughly - Keep plans concise and actionable - Focus on the immediate implementation, not future enhancements - This is a standalone workflow - does NOT create spec files or feed into steps 2-4 + ``` ⋅ ╭───╮ @@ -150,4 +151,5 @@ If scope is within thresholds (or user chose to continue), present the implement │ ◡ │ Plan ready! What do you think? ╰───╯ ``` + Ready to implement? (yes / modify plan / escalate to full planning / abort) diff --git a/src/plan2code-2--document.md b/src/plan2code-2--document.md index e039a76..816b3a5 100644 --- a/src/plan2code-2--document.md +++ b/src/plan2code-2--document.md @@ -93,21 +93,29 @@ Each task should be: 6. **Analyze** phases for parallel execution eligibility (see Parallel Eligibility Analysis below) 7. **Verify** all requirements from planning document are covered 8. **Present** summary to user and ask about the planning document + ### Parallel Eligibility Analysis + After creating all phase files, analyze which phases can be executed in parallel. This enables users to run multiple agent instances simultaneously for faster implementation. + **Analysis Process:** + 1. For each pair of adjacent phases (Phase N and Phase N+1), check for conflicts: + | Conflict Type | How to Detect | Result if Found | |---------------|---------------|-----------------| | **File Overlap** | Any task in Phase N modifies a file also modified in Phase N+1 | NOT parallel-eligible | | **Prerequisite Dependency** | Phase N+1's Prerequisites section references Phase N | NOT parallel-eligible | | **Data/Output Dependency** | Phase N+1 tasks require artifacts, exports, or state created by Phase N | NOT parallel-eligible | | **Shared State** | Both phases modify the same database tables, config, or global state | NOT parallel-eligible | + 2. Group consecutive phases with NO conflicts into Parallel Execution Groups: - If Phases 2 and 3 have no conflicts → Group A: 2, 3 - If Phase 4 depends on Phase 3 → Phase 4 starts a new sequence - If Phases 5 and 6 have no conflicts → Group B: 5, 6 + 3. Populate the "Parallel Execution Groups" table in `overview.md`: + **Example with parallel groups:** ```markdown | Group | Phases | Reason | @@ -115,13 +123,16 @@ After creating all phase files, analyze which phases can be executed in parallel | A | 2, 3 | Phase 2 (data models) and Phase 3 (API routes) touch separate files | | B | 5, 6 | Phase 5 (frontend) and Phase 6 (tests) have no shared dependencies | ``` + **Example with no parallel phases:** ```markdown | Group | Phases | Reason | |-------|--------|--------| | None | - | All phases must run sequentially due to dependencies | ``` + 4. Inform the user about parallel eligibility in the completion summary: + > **Parallel Execution:** Phases [X, Y] can be run simultaneously in separate agent instances. Phases [Z] must be run sequentially due to dependencies. ### Output Structure @@ -200,12 +211,15 @@ Check the Testing Strategy from the PLAN-DRAFT (section 2.4): ## Phase Checklist - [ ] Phase 1: [Name] - [Description] ... + ## Parallel Execution Groups + | Group | Phases | Reason | |-------|--------|--------| | [A/B/etc or "None"] | [phase numbers] | [Why these can run in parallel] | + _If no phases can run in parallel, this table will show "None - all phases must run sequentially"_ ## Quick Reference @@ -295,6 +309,7 @@ Total phases: X Total tasks: Y Requirements coverage: [Confirm all planning requirements are addressed] + Parallel Execution Groups: - Group A: Phases X, Y (can run simultaneously) - [Or: "None - all phases must run sequentially"]