- Updated tooling references in `plan2code-loop/`, `plan2code-bot/`, and `plan2code-metrics/`
- Fixed pre-existing broken test assertion in `plan2code-bot` step-instructions test
- Repaired Windows-1252 / U+FFFD encoding artifacts (em-dashes) in `plan2code-loop` and `plan2code-bot` source files
### 🎁 Added
- **Devin platform support** — Added Devin to supported platforms list across `README.md`, `AGENTS.md`, `install.js` Agent Skills targets, `.agents-docs/AGENTS-development-commands.md`, and the `/plan2code-init` prompt
- **CLAUDE.md MANDATORY FIRST STEP template** — `/plan2code-init` and `/plan2code-init-update` now generate a CLAUDE.md template containing a `CRITICAL — MANDATORY FIRST STEP` directive that forces Claude Code to read AGENTS.md before responding to any user message
## v1.12.0
### 🔧 Changed
- **Resilient code references in workflow prompts** — Workflow prompts now explicitly guide AI agents to use semantic anchors (function names, class names, code patterns) instead of line numbers, which become stale as tasks modify files during implementation
- **Document mode** (`plan2code-2-document.md`) — New "Code references" block in Task Writing section lists four preferred anchor types with examples; line numbers allowed only as supplemental context
- **Revise-plan mode** (`plan2code-1b-revise-plan.md`) — Matching code reference rule added to Step 3 (Execute Revisions) so revised and new tasks follow the same convention
- **Implement mode** (`plan2code-3-implement.md`) — New "Verify locations" row in Code Consistency Rules table instructs agents to treat line numbers as approximate and locate by function/symbol name
- **plan2code-bot** — New autonomous workflow test runner (`plan2code-bot/`) that uses the Claude Agent SDK to simulate a human running the entire plan2code workflow end-to-end
- Two auto-detected modes: **new-project** (generates an app idea, creates a subdirectory, runs init through finalize) and **enhancement** (scans existing codebase, proposes a realistic enhancement)
-`--idea` flag to seed the idea generator with a specific concept
-`--resume` flag to continue incomplete runs from saved state — skips previously succeeded steps and restores idea, config, and implement pass counter
- State file (`.plan2code-bot-state.json`) saved after each step; automatically deleted on full success, preserved on failure for later resume
- Resume auto-detects state files in current directory (enhancement mode) or immediate subdirectories (new-project mode)
- Artifact validation after each step (aborts on missing expected outputs)
- **LLM-as-judge evaluation system** — Always-on quality assessment that transforms bot from "yes-man" to authentic QA agent
- **Intelligent decision making**: Uses LLM to answer `AskUserQuestion` prompts based on current observations (tools used, files created, errors) instead of hardcoded keyword matching
- **Post-step evaluation**: Comprehensive quality assessment after each step using step-specific criteria (score 0-100, strengths, weaknesses, suggestions, critical issues)
- **Observation tracking**: Full execution history captured (tools, files, messages, errors, questions with LLM reasoning)
- **Quality gate**: Blocks finalization if average score < 60, ensuring minimum quality standards
- **Evaluation artifacts**: Creates `BOT-EVALUATION.md` (quality assessments) and `BOT-NOTES.md` (execution observations) for metrics analysis
- **Color-coded output**: Green (≥85), yellow (70-84), red (<70) score display in console
- **Honest scoring**: Evaluation criteria emphasize realistic assessment (most work scores 70-85, not inflated)
- **Metrics-ready data**: Structured `EvaluationResult` and `ExecutionObservation` in state file for `plan2code-metrics` analysis
- **Retry logic with escalating timeouts in loop controller** — Timed-out iterations now retry automatically instead of silently continuing
- Default base timeout reduced from 30 minutes to 3 minutes per attempt
- Up to 5 retry attempts per iteration (configurable via `maxRetries`)
- Each retry escalates timeout by +30 seconds (attempt 0 = base, attempt 1 = base + 30s, etc.)
- New `executeWithRetry()` method wraps `executeIteration()` with retry loop
- Fatal timeout (all attempts exhausted) stops the loop cleanly with a logged error
- Spinner displays elapsed seconds during each attempt; retries show attempt count
-`maxRetries` field added to `SessionConfig` and `DEFAULT_CONFIG`
### 🔧 Changed
- **Append-only scratchpad enforcement in loop prompt templates** — Both task-mode and phase-mode templates now explicitly prohibit editing or reorganizing existing scratchpad content
- Instruction changed from "append to scratchpad.md" to "add a new entry at the **bottom**"
- Added rule: "Never edit, reorganize, or insert into existing content — only append new entries to the end of the file"
- **AGENTS.md restructured into progressive discovery format** — AGENTS.md converted to a lightweight index with summaries and markdown links; full detail moved to `.agents-docs/` section files
-`.agents-docs/AGENTS-architecture.md` — Architecture overview and key design decisions
-`init-update` prompt updated with `.agents-docs/` detection in pre-flight check
- **Agents mode emoji updated** — Loop controller agents-mode indicator changed from wheel to hammer
## v1.9.1
### ✨ Added
- **Pi (pi.dev) platform support** — New target for the Pi terminal-based coding agent
- Local prompt templates installed to `.pi/prompts/` (flat `.md` with YAML `description` frontmatter)
- Global prompt templates installed to `~/.pi/agent/prompts/`
- Pi users already get skill support via existing `.agents/skills/` target; this adds native slash command access
- No new helper functions needed — Pi uses the same flat-file-with-YAML pattern as Windsurf, Copilot CLI, and Codeium
### 📚 Documentation
-`AGENTS.md` Platform-Specific File Formats table updated with Pi row
-`README.md` Supported Platforms list updated with Pi (pi.dev)
## v1.9.0
### ✨ Added
- **Progressive discovery for AGENTS.md** — Init and init-update prompts now generate AGENTS.md as a lightweight index with summaries and markdown links, plus `.agents-docs/` section files containing full detail
- **Init prompt** — New `## Progressive Discovery` section defines index format, always-inline sections (Project Overview, Git Commit Messages, How to Use This File), `.agents-docs/` directory setup, grouping heuristics, and opt-in restructure offer for existing single-file AGENTS.md
- **Reference templates** updated in both prompts to include `.agents-docs/` in the bullet list
- **"How to Use This File"** added as a required content section in generated AGENTS.md files
## v1.8.2
### 🐛 Fixed
- **Inflated metrics task counts** — Metrics collector regex now matches only `**Task X.N:**` checkbox items instead of all checkboxes, fixing ~100-200% count inflation from prerequisite and acceptance criteria checkboxes
- **Document workflow** — Checkbox format `- [ ]` now restricted to Task items only; Prerequisites, Acceptance Criteria, and Success Criteria use plain bullet lists (no checkboxes)
- **Implement workflow** — Prerequisite verification changed from checkbox-based (`[x]`/`[?]`/`[!]`) to inline annotation approach (`VERIFIED`/`ASSUMED: [reason]`/`BLOCKED: [reason]`); added clarifying note that checkbox states apply to Task items and Phase Checklist only
- **Finalize workflow** — Task completion audit now specifies counting only `**Task X.N:**` checkbox items
- **Loop prompt templates** — Both task-mode and phase-mode templates updated: prerequisites use plain bullets with inline annotations instead of checkboxes; Checkbox States section scoped to "Task items only"
- **Pipe-safe feedback parsing** — User text containing `|` characters is escaped on write and correctly unescaped on parse using negative lookbehind regex
### 🐛 Fixed
- **Duplicate run files** — Interactive feedback no longer creates a second run JSON; the original is deleted before re-collecting
- **Finalize step ordering** — Feedback collection moved to Step 5 (before archival at Step 6), ensuring `overview.md` is written while still in the active spec directory
- **Review and apply** proposals with interactive diff review
- Cohort-based aggregation groups runs by prompt generation (SHA fingerprint of prompt files)
- Supports both Claude Code and GitHub Copilot CLI as AI backends
- Standalone TypeScript package with tsup build (ESM), installed via `npm link`
### 🔧 Changed
- **plan2code-4--finalize.md** — Added "Metrics Capture (Contributors)" note in Step 6 directing contributors to run `plan2code-metrics` after finalization
- **plan2code-loop index.ts** — Added dim hint "run plan2code-metrics" after session summary
- **AI Assisted commit attribution** - All git commit messages now include an `AI Assisted` footer for transparency
- **Init mode** - Generated AGENTS.md files include a Git Commit Messages section instructing agents to always append `AI Assisted`
- **Init-update mode** - New "Git Commit Messages" menu option (option 7) for adding or modifying commit message conventions
- **Loop task mode** - `createTaskCommit()` automatically appends `AI Assisted` footer to every commit
- **Loop phase mode** - Prompt template instructs LLM to include `-m "AI Assisted"` as final flag on every commit
- **Implement mode** - User-facing git commit suggestions after phase approval include `-m "AI Assisted"`
### 🔧 Changed
- **README loop install instructions** - Replaced inline text with formatted code block showing both install options
## v1.5.3
### ✨ Added
- **Loop mode selection** - Plan2Code Loop now asks users to choose between two loop modes:
- **One task per loop** (default) - Each agent invocation implements exactly one task. Node controller handles git commits after each task. Same behavior as before.
- **One phase per loop** - Each agent invocation implements all remaining tasks in the current phase. The LLM handles git commits after each task (with JIRA ticket ID). Ideal for related tasks and smart models with higher context windows.
- **Phase-mode prompt template** - New `LOOP_PROMPT_TEMPLATE_PHASE` instructs the LLM to complete all tasks in the current phase, create git commits per task, and output `TASK_COMPLETE` markers for each
- **Multi-marker completion detection** - New `checkForAllCompletions()` function parses all `TASK_COMPLETE`, `TASK_BLOCKED`, and `PREREQ_COMPLETE` markers from a single agent output
- **`PHASE_COMPLETE` marker** - New completion marker for phase mode indicating current phase is done (distinct from `LOOP_COMPLETE` which means all phases done)
- **`loopMode` config field** - New `SessionConfig.loopMode` field (`'task' | 'phase'`) persisted in session state for resume support
- **Documentation auto-discovery** - Documentation workflow now auto-discovers features to document
- If only one feature exists, uses it without prompting
- If multiple features exist, presents list and asks user to choose
- Automatically reads `PLAN-CONVERSATION-*.md` if present (optional, for context)
- **Documentation Verification Pass** - Documentation workflow now cross-references against PLAN-DRAFT before finalizing
- New Process Step 7 with sub-steps: 7A (re-read PLAN-DRAFT), 7B (cross-reference sections), 7C (fix gaps), 7D (output summary)
- New "Documentation Verification Pass" section with mapping table showing which PLAN-DRAFT sections to verify against which spec files
- Gap handling: Missing items added with `<!-- VERIFICATION: Added - FR-X from PLAN-DRAFT -->` markers
- Session end output now includes verification summary table showing Items in PLAN-DRAFT / Covered / Added per section
- Added reminders: "Always run verification pass before finalizing" and "PLAN-DRAFT is the source of truth"
- **Conversation Logging** - Planning workflow now saves the full planning conversation before creating PLAN-DRAFT
- New file: `specs/<feature-name>/PLAN-CONVERSATION-<YYYYMMDD>.md` created in Phase 7
- Contains full conversation transcript organized by phase with speaker attribution (`[AGENT]` vs `[USER RESPONSE]`)
- Decision summary tables with user quotes, confirmed requirements, approved technologies, and assumptions
- Serves as source of truth for plan verification
- **PLAN-DRAFT Verification Pass** - New STEP 7C verifies PLAN-DRAFT against conversation log
- Cross-references all requirements, tech decisions, risks, and assumptions
- Missing items added with `<!-- VERIFICATION: Added from Phase X -->` markers
- Outputs verification summary showing what was captured vs added
- **Conversation Log field in PLAN-DRAFT** - New header field links to the conversation log file
### 🔧 Changed
- **Installer default option** - Pressing Enter without selecting an option now defaults to `A` (Install to ALL platforms + loop CLI) instead of quitting
- **Planning output location changed** - PLAN-DRAFT and conversation log now created in feature subdirectory
- New location: `specs/<feature-name>/PLAN-DRAFT-<date>.md` and `specs/<feature-name>/PLAN-CONVERSATION-<date>.md`
- Date format: YYYYMMDD (e.g., `20250204`) instead of full timestamp
- Uppercase `PLAN-CONVERSATION` for consistency with `PLAN-DRAFT`
- Feature directory created during planning (Step 1) instead of documentation (Step 2)
- Documentation step no longer archives PLAN-DRAFT (already in correct location)
- **Planning Phase 7 restructured** - Now has three sub-steps:
- STEP 7A: Save Conversation Log (new)
- STEP 7B: Create PLAN-DRAFT (existing behavior, uses same timestamp)
- STEP 7C: Verification Pass (new)
- **Session End example updated** - Now shows both conversation log and PLAN-DRAFT files
- **Important Reminders expanded** - Added reminders about conversation log and verification pass
### 🐛 Fixed
- **`.gitignore` missing `specs/` entries in phase mode** - `ensureGitignore()` only ran inside `createTaskCommit()`, which is never called in phase mode. Moved `ensureGitRepo()` and `ensureGitignore()` to run once at startup in `Controller.run()` as a pre-flight step, ensuring `.gitignore` entries are set before the first iteration regardless of loop mode
- **`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)
- Added explicit transition check to `Planning Phase 6` - when confidence >= 90%, the model now asks the user for confirmation before proceeding to create the PLAN-DRAFT document
- Improved spec file referencing in Documentation and Implementation modes - users can now reference either a `specs/<feature-name>/` folder or individual files
- Implementation mode now auto-detects single spec folders before prompting the user for file references
- Added Initial Context Check to `Planning Phase 1` - Model now asks about additional files, reference materials, and external integrations before
analyzing requirements
- Added user verification checklist and git checkpoint to `Implementation Phase 3` - Phase completion reports now guide users through verification and git checkpointing before starting the next phase
