plan2code/plan2code-bot

plan2code-bot

Autonomous workflow test runner for plan2code. Uses the Claude Agent SDK to simulate a human running through the entire plan2code workflow (init, plan, document, implement, finalize) end-to-end.

Two Modes (Auto-Detected)

1. New Project Mode — No AGENTS.md in cwd: generates an app idea, creates a subdirectory, writes IDEA.md, runs init, then all 4 steps.
2. Enhancement Mode — AGENTS.md exists in cwd: scans the existing codebase and proposes a realistic enhancement, writes IDEA.md, then runs plan through finalize.

Installation

From the plan2code root:

node install.js
# Select C > B to install bot only, or I to install everything

Or manually:

cd plan2code-bot
npm install
npm run build
npm link

Usage

# New project mode (run from an empty directory)
mkdir /tmp/test-bot && cd /tmp/test-bot
plan2code-bot

# Enhancement mode (run from an existing project with AGENTS.md)
cd my-project
plan2code-bot

# Seed the idea generator with a specific concept
plan2code-bot --idea "web app that displays the current weather as vector images"

# Resume a previous incomplete run
plan2code-bot --resume

--idea

Pass a quoted string after --idea to seed the idea generator with a specific concept. The AI will use it as inspiration rather than generating a completely random idea. Wrap the value in double quotes so the shell treats it as a single argument.

# Specific app concept
plan2code-bot --idea "web app that displays the current weather as vector images"

# Short keyword to nudge the category
plan2code-bot --idea "markdown editor"

# Detailed constraint
plan2code-bot --idea "CLI tool that converts CSV files to SQLite databases with type inference"

# Works in enhancement mode too — guides what kind of enhancement to propose
cd my-existing-project
plan2code-bot --idea "add dark mode support"

Without --idea, the bot picks a random category (CLI tool or web app) and invents something on its own.

--resume

Resume a previous incomplete run. The bot searches for a .plan2code-bot-state.json file in the current directory (enhancement mode) or in immediate subdirectories (new-project mode). If found, it restores the idea, config, and progress — skipping steps that already succeeded and continuing from where it left off.

# A run failed at the implement step — resume it
plan2code-bot --resume

# Can combine with --idea (idea is ignored when resuming since it's restored from state)
plan2code-bot --resume --idea "ignored when state exists"

If no state file is found, the bot starts a fresh run.

How It Works

1. Detects mode based on presence of AGENTS.md
2. Generates an idea (new app or enhancement) via Claude, optionally guided by --idea seed
3. Writes IDEA.md to the project directory
4. Installs bot-friendly copies of plan2code skills (strips disable-model-invocation so sessions can invoke them)
5. Runs each workflow step as a separate Claude Agent SDK session:
   • init — generates AGENTS.md (new-project mode only)
   • plan — creates plan draft in specs/<feature>/
   • document — produces overview.md and phase-*.md files
   • implement — loops until all phases are complete (max 10 passes)
   • finalize — validates and archives to specs--completed/
6. Validates expected artifacts after each step (aborts on missing artifacts)
7. Moves IDEA.md into specs/<feature>/ after the plan step so it stays with its feature
8. Auto-responds to AskUserQuestion prompts (approvals, testing gates, name questions)
9. Saves state to .plan2code-bot-state.json after each step

State File

After each step, the bot saves its state to .plan2code-bot-state.json in the project directory. This includes the config, all step results, and progress tracking.

• On full success — the state file is automatically deleted (clean finish)
• On failure/incomplete — the state file is preserved so you can --resume later

Development

npm run build    # Build with tsup
npm run dev      # Watch mode
npm test         # Run tests (vitest)