🎯 Claude Code Dev Plan Builder

Turn your product idea into a production-ready development plan in minutes

Tell Claude Code to read this repo, and it will guide you through building a comprehensive, paint-by-numbers development plan with all the testing, git discipline, and best practices baked in.

🤖 For Claude Code

When a user asks you to help them create a development plan using this methodology, follow these exact steps:

Step 1: Interview the User

Ask these questions ONE AT A TIME, waiting for responses:

1. "What's your project name?"
2. "What type of project is this? (CLI tool, web app, API, or library)"
3. "In one sentence, what does it do?"
4. "Who will use it? (e.g., developers, end users, admins)"
5. "What are the 3-5 must-have features for MVP?"
6. "Any technologies you must use or cannot use?"
7. "What's your timeline?"
8. "Any constraints I should know about?"

Step 2: Create PROJECT_BRIEF.md

Write to PROJECT_BRIEF.md using this structure:

# Project Brief: {name}

## Overview

| Field | Value |
|-------|-------|
| **Project Name** | {name} |
| **Project Type** | {cli/web_app/api/library} |
| **Goal** | {one sentence} |
| **Timeline** | {timeline} |
| **Team Size** | 1 |

## Target Users

- {user type 1}
- {user type 2}

## Features

### Must-Have (MVP)

1. **{Feature Name}** - {description}
2. **{Feature Name}** - {description}
...

### Nice-to-Have (v2)

- {feature}
...

## Technical Requirements

### Tech Stack

| Component | Technology |
|-----------|------------|
| Language | {language} |
| Framework | {framework} |
| Testing | {test framework} |

### Constraints

- {constraint 1}
- {constraint 2}

## Success Criteria

1. {criterion 1}
2. {criterion 2}
...

## Out of Scope

- {thing 1}
- {thing 2}

Step 3: Create DEVELOPMENT_PLAN.md

Structure the plan with phases, tasks, and subtasks:

• Phases (0, 1, 2...): Major milestones
• Tasks (0.1, 1.2...): Features within a phase (one git branch each)
• Subtasks (0.1.1, 1.2.3...): Single-session work items (2-4 hours each)

Each subtask MUST include:

• Prerequisites (which subtasks must be done first)
• Deliverables (checkboxes for what to build)
• Files to Create/Modify
• Success Criteria (testable conditions)
• Completion Notes template

Critical: Write complete, copy-pasteable code blocks. Claude Haiku will execute this plan - it cannot infer missing details.

Git workflow: One branch per TASK (not subtask). Commit after each subtask. Squash merge when task completes.

Add "Task Complete" section after each task's subtasks:

### Task X.Y Complete - Squash Merge

- [ ] All subtasks complete
- [ ] All tests pass
- [ ] Squash merge: `git checkout main && git merge --squash feature/X-Y-name`
- [ ] Delete branch: `git branch -d feature/X-Y-name`

Step 4: Create CLAUDE.md

Write project rules with these sections:

1. Project Overview
2. Quick Reference (tech stack table)
3. Directory Structure
4. Commands (install, test, lint)
5. Coding Standards
6. Session Checklist (starting/ending)

Step 5: Create Executor Agent

Write to .claude/agents/{project}-executor.md:

---
name: {project}-executor
description: PROACTIVELY use this agent to execute {project} development subtasks.
tools: Read, Write, Edit, Bash, Glob, Grep
model: haiku
---

# {Project} Executor Agent

## Before Starting
1. Read CLAUDE.md completely
2. Read DEVELOPMENT_PLAN.md completely
3. Find the subtask you're assigned

## Execution Loop
For each deliverable checkbox:
1. Implement the requirement
2. Write/update tests
3. Run tests and fix failures
4. Mark checkbox complete

## After Completion
1. Update completion notes
2. Commit with semantic message
3. Report what was done

Step 6: Create Verifier Agent

Write to .claude/agents/{project}-verifier.md with model: sonnet - this agent validates the completed application against PROJECT_BRIEF.md and captures lessons learned.

Common Mistakes to Avoid

• Don't create branches for subtasks (only for tasks)
• Don't write vague deliverables ("implement feature") - be specific
• Don't skip success criteria - they're how we know it's done
• Don't forget the Task Complete section after each task
• Don't use placeholder code - write real, complete code blocks

Execution Prompt

Tell the user to execute subtasks with:

Use the {project}-executor agent to execute subtask [X.Y.Z]

Reference Examples

For complete examples of each file type, see examples/hello-cli/:

• PROJECT_BRIEF.md
• CLAUDE.md
• DEVELOPMENT_PLAN.md
• hello-cli-executor.md
• hello-cli-verifier.md

Also read examples/GLOBAL_LESSONS.md for patterns to incorporate based on project type.

🚀 Quick Start (For Users)

Got a product idea? Here's all you need to do:

Step 1: Start a Conversation with Claude Code

In your new project repository, paste this prompt:

Go read the README at https://github.com/mmorris35/ClaudeCode-DevPlanBuilder and help me develop my idea into a complete development plan.

Step 2: Answer Claude's Questions

Claude Code will guide you through creating a PROJECT_BRIEF.md by asking about:

• What you're building (the goal)
• Who it's for (target users)
• What it needs to do (key features)
• Your tech stack (if decided)
• Timeline and constraints

Step 3: Get Your Development Plan

Claude Code will generate:

• ✅ CLAUDE.md - Rules for how Claude Code should work on your project
• ✅ PROJECT_BRIEF.md - Your requirements captured in a structured format
• ✅ DEVELOPMENT_PLAN.md - Paint-by-numbers roadmap with numbered subtasks
• ✅ .claude/agents/{project}-executor.md - Specialized agent to execute your plan (haiku)
• ✅ .claude/agents/{project}-verifier.md - QA agent to validate the completed app (sonnet)

Step 4: Build Your Product

Use this simple prompt for every work session (replace {project} with your project name):

Use the {project}-executor agent to execute subtask [X.Y.Z]

Replace [X.Y.Z] with the next subtask number (like 0.1.1, 1.2.3, etc.)

That's it! Claude Code will:

• Complete each subtask fully (2-4 hours of work)
• Write comprehensive tests (>80% coverage)
• Run linting and type checking
• Commit to the task's feature branch (NOT create a new branch per subtask)
• Update progress in DEVELOPMENT_PLAN.md

Step 5: Verify Your Product

After all subtasks are complete, validate the application:

Use the {project}-verifier agent to validate the application against PROJECT_BRIEF.md

The verifier agent (sonnet) will:

• Smoke test the application
• Verify each feature against requirements
• Test edge cases the plan may have missed
• Check error handling and security basics
• Produce a verification report with pass/fail status

Step 6: Post-Release Maintenance

After your project ships, use devplan to manage bug fixes and enhancements from GitHub issues:

1. Fetch the issue:

   hljs language-bash

   Copy

   gh issue view 123 --json number,title,body,labels,comments,url
   

2. Generate a remediation task: Use devplan_issue_to_task with the issue JSON

3. Choose your mode:

   • Append mode: Add remediation phases (R.1, R.2, etc.) to your existing DEVELOPMENT_PLAN.md
   • Standalone mode: Create a new REMEDIATION_PLAN.md for isolated fixes

4. Execute subtasks using the executor agent as usual

See docs/REMEDIATION_WORKFLOW.md for the complete post-release workflow guide.

🎨 What Makes This "Paint by Numbers"?

Your development plan will have:

1. Numbered subtasks (0.1.1, 0.1.2, etc.) - Always know what's next
2. 3-7 specific deliverables per subtask - Clear checkboxes for completion
3. Single-session sizing - Each subtask takes 2-4 hours max
4. Explicit prerequisites - No guessing about order
5. Success criteria - Objective verification of completion
6. Git workflow at TASK level - One feature branch per task (NOT per subtask!)
7. Commits per subtask - Each subtask commits to the task's branch, squash merge when task complete
8. Testing throughout - Not an afterthought, >80% coverage required
9. Quality gates - Linting, type checking, validation at every step
10. Completion notes - Knowledge capture for every subtask
11. One simple prompt - Same format for every session

⚠️ Git Workflow: TASK-Level Branching

IMPORTANT: Branches are created at the TASK level, NOT the subtask level!

gitGraph
   commit id: "main"
   branch feature/1.2-user-auth
   checkout feature/1.2-user-auth
   commit id: "1.2.1: models"
   commit id: "1.2.2: routes"
   commit id: "1.2.3: tests"
   checkout main
   merge feature/1.2-user-auth id: "squash merge" type: HIGHLIGHT

• One branch per task (e.g., feature/1.2-user-auth)
• Multiple commits per task (one for each subtask)
• Squash merge when task complete (not after each subtask)

✅ Task Complete Checkpoints

Every task in your DEVELOPMENT_PLAN.md ends with an explicit merge checkpoint:

### ✅ Task X.Y Complete - Squash Merge to Main

**When all subtasks (X.Y.1, X.Y.2, ...) are complete:**

git push -u origin feature/X-Y-description
gh pr create --title "type: description" --body "Task X.Y complete"
gh pr merge --squash --delete-branch

**Checklist:**
- [ ] All subtasks complete
- [ ] All tests pass
- [ ] PR created and squash merged to main
- [ ] Feature branch deleted

This ensures you never forget the merge step - it's explicit in the plan, not something you need to remember.

🤖 The Executor Agent

Each project gets a specialized agent file at .claude/agents/{project-name}-executor.md. This agent:

• Knows your project - Has context about tech stack, architecture, and phases
• References your docs - Reads CLAUDE.md, PROJECT_BRIEF.md, and DEVELOPMENT_PLAN.md
• Expects executable plans - Plans must have complete, copy-pasteable code (not vague descriptions)
• Follows git discipline - One branch per task, commits per subtask, verification before commits

To use the agent, invoke it with a subtask:

@taskflow-executor execute subtask 1.2.3

The agent will read your planning documents, verify prerequisites, implement the deliverables, run verification, and commit the changes.

⚠️ Common Mistakes with Executor Agents

Claude sometimes makes errors when creating executor agent files. Watch for these:

❌ Wrong - YAML list for tools:

tools:
  - Read
  - Write
  - Edit

✅ Correct - Comma-separated string:

tools: Read, Write, Edit, Bash, Glob, Grep

❌ Wrong - Using sonnet model:

model: sonnet

✅ Correct - Using haiku model:

model: haiku

Using sonnet defeats the purpose of having an executor agent. The agent should be lightweight (haiku) since the development plans are designed to be "Haiku-executable" - containing complete, copy-pasteable code that doesn't require inference.

❌ Wrong - Missing frontmatter delimiters:

name: my-executor
tools: Read, Write

✅ Correct - With delimiters:

---
name: my-executor
description: PROACTIVELY use this agent to execute...
tools: Read, Write, Edit, Bash, Glob, Grep
model: haiku
---

Always double-check your agent files match this format before use.

📚 What's In This Repo?

This repository contains:

For Users (You!)

• PROMPT_SEQUENCE.md - Detailed guide with all the prompts you'll need
• This README - Everything you need to get started

Example Artifacts (What You'll Get)

The examples/ directory contains complete, minimal examples for different project types:

Each example includes:

• PROJECT_BRIEF.md - Requirements in structured format
• CLAUDE.md - Coding standards and session checklist
• DEVELOPMENT_PLAN.md - Haiku-executable plan with complete code blocks
• {project}-executor.md - Executor agent (haiku) for building
• {project}-verifier.md - Verifier agent (sonnet) for QA

These examples demonstrate the key principle: every subtask contains copy-pasteable code, not vague descriptions. Claude Haiku can execute these plans mechanically, then Claude Sonnet can verify the result.

💡 How Claude Code Will Help You

When you ask Claude Code to help you develop your idea, it will:

flowchart LR
    A[Your Idea] --> B[Interview]
    B --> C[PROJECT_BRIEF.md]
    C --> D[CLAUDE.md]
    D --> E[DEVELOPMENT_PLAN.md]
    E --> F[Executor Agent]
    F --> G[Execute Subtasks]
    G --> H[Working Product]

    style A fill:#f9f,stroke:#333
    style H fill:#9f9,stroke:#333

1. Interview You About Your Project

Claude will ask clarifying questions like:

• "What problem does this solve?"
• "Who are your target users?"
• "What are the must-have features for MVP?"
• "What's your tech stack? (Or would you like recommendations?)"
• "What's your timeline?"

2. Create Your PROJECT_BRIEF.md

A comprehensive document covering:

• Basic information (name, type, goal, users, timeline)
• Functional requirements (input, output, key features)
• Technical constraints (must-use tech, cannot-use, deployment)
• Quality requirements (performance, security, scalability)
• Success criteria

3. Generate CLAUDE.md

Project-specific rules defining:

• How Claude Code should work on YOUR project
• Testing requirements (coverage, frameworks)
• Code quality standards (linting, type checking, style guides)
• Git workflow and commit standards
• Build verification steps
• Project-specific best practices

4. Build DEVELOPMENT_PLAN.md

A complete roadmap with:

• Phase 0: Foundation - Repo setup, dependencies, CI/CD
• Phase 1-N: Development - Your features broken into digestible pieces
• Final Phase: Testing & Distribution - Polish and release

Each task includes:

• Git Strategy - Branch name, commit prefix, merge strategy (one branch per task, all subtasks commit to it)

Each subtask includes:

• Exact deliverables (what to build)
• Files to create/modify (where to build it)
• Success criteria (how to verify it works)
• Completion notes template (knowledge capture)

5. Create an Executor Agent

A specialized agent file at .claude/agents/{project-name}-executor.md that:

• Has your project context baked in (tech stack, phases, directory structure)
• References CLAUDE.md, PROJECT_BRIEF.md, and DEVELOPMENT_PLAN.md
• Expects "Haiku-executable" plans with complete, copy-pasteable code
• Follows strict git discipline (verify → implement → test → commit)

6. Guide You Through Execution

flowchart TD
    A[Start Subtask] --> B[Read CLAUDE.md + DEVELOPMENT_PLAN.md]
    B --> C[Verify Prerequisites]
    C --> D{Prerequisites Met?}
    D -->|No| E[Stop & Report]
    D -->|Yes| F[Implement Deliverables]
    F --> G[Write Tests]
    G --> H[Run Verification]
    H --> I{All Pass?}
    I -->|No| J[Fix Issues]
    J --> H
    I -->|Yes| K[Update DEVELOPMENT_PLAN.md]
    K --> L[Git Commit]
    L --> M{Last Subtask in Task?}
    M -->|No| N[Next Subtask]
    M -->|Yes| O[Squash Merge to Main]

    style A fill:#f9f,stroke:#333
    style O fill:#9f9,stroke:#333

For every subtask, Claude Code will:

• Read the full context (CLAUDE.md + DEVELOPMENT_PLAN.md)
• Implement all deliverables
• Write comprehensive tests
• Run quality checks (linting, type checking)
• Update completion notes
• Create semantic git commit

🎯 Who Is This For?

Perfect For:

• ✅ Solo developers building side projects or startups
• ✅ Small teams wanting consistent development practices
• ✅ Experienced developers who want to move fast with quality
• ✅ Anyone using Claude Code for software development

Works Great For These Project Types:

• 🖥️ CLI Tools - Command-line applications and utilities
• 🌐 Web Apps - Full-stack web applications
• 🔌 APIs - RESTful services and microservices
• 📦 Libraries - Reusable packages and frameworks
• 🤖 Automation Tools - Scripts and workflow automation

📖 Documentation & Resources

📁 Templates (Use These as Your Source)

Claude: Use the examples folder as templates when generating artifacts. Choose based on project type:

Each example contains:

• PROJECT_BRIEF.md - Template for requirements
• CLAUDE.md - Template for coding standards
• DEVELOPMENT_PLAN.md - Template for Haiku-executable plans
• {project}-executor.md - Template for executor agents (haiku)
• {project}-verifier.md - Template for verifier agents (sonnet)

📚 Reference Guides (For Understanding)

• PROMPT_SEQUENCE.md - Step-by-step prompts for manual plan creation
• docs/EXECUTOR_AGENT.md - Explains executor agent concepts and common mistakes
• docs/VERIFIER_AGENT.md - Explains verifier agent for post-build QA
• docs/HAIKU_EXECUTABLE_PLANS.md - Explains what makes plans "Haiku-executable"
• docs/AUTONOMOUS_EXECUTION.md - Guide to hands-free execution
• docs/BEST_PRACTICES.md - Anti-patterns and best practices for development plans
• docs/ERROR_RECOVERY.md - What to do when things go wrong
• docs/LESSONS_LEARNED.md - How the feedback loop works

Community Learning

• examples/GLOBAL_LESSONS.md - Patterns from verification failures (read by plan generator)
• Submit a lesson - Share patterns to help future plans

Advanced

• MULTI_AGENT_INFRASTRUCTURE.md - Multi-agent setups (only if needed)

Quick Reference

Standard session prompt (use this every time, replacing {project} with your project name):

Use the {project}-executor agent to execute subtask [X.Y.Z]

When a subtask is too large:

Use the {project}-executor agent to break down subtask [X.Y.Z] into 2-3 smaller subtasks that each take 2-4 hours, have 3-7 deliverables, and can be completed independently.

Progress validation:

Use the {project}-executor agent to review Phase [X] completion: verify all completion notes, run tests, and provide a Phase [X] completion report before moving to Phase [Y].

🏗️ What This Repository Actually Is

This is both:

1. A methodology for building development plans with Claude Code ✅ READY TO USE - The prompt sequences and examples are battle-tested

2. A working CLI tool that automates plan generation ✅ USABLE - Core features complete, validation/distribution in progress

The tool was built using its own generated development plan - eating our own dog food! 🎉

Development Roadmap

The CLI Tool Progress:

gantt
    title DevPlan Builder Progress
    dateFormat X
    axisFormat %s

    section Core
    Foundation       :done, 0, 1
    Data Models      :done, 1, 2
    Parser           :done, 2, 3
    Templates        :done, 3, 4
    Generators       :done, 4, 5
    CLI Commands     :done, 5, 6

    section Polish
    Validation       :active, 6, 7
    Git Integration  :7, 8
    Testing & Docs   :8, 9
    Distribution     :9, 10

What Works Right Now

✅ The Methodology - Use PROMPT_SEQUENCE.md to build dev plans for ANY project ✅ CLI Tool - claude-planner generate, validate, list-templates ✅ MCP Server - DevPlan tools for Claude Code integration ✅ Executor Agents - Haiku-powered agents that execute your plans ✅ Autonomous Mode - Build entire projects hands-free

What's Coming

🚧 Enhanced Validation - Deeper quality checks and error reporting 🚧 Git Integration - Automatic repository initialization 🚧 PyPI Distribution - pip install claude-planner

How to Use It Today

Option 1: Use the Methodology (Recommended)

• Follow PROMPT_SEQUENCE.md
• Let Claude Code guide you through building your development plan
• Works for any project, any tech stack

Option 2: Use the CLI Tool

# Install (from source for now)
pip install -e .

# Generate a development plan (provide your own PROJECT_BRIEF.md)
claude-planner generate my-project --brief your-PROJECT_BRIEF.md

# List available templates
claude-planner list-templates

Option 3: Use the MCP Server

Install:

claude mcp add devplan --transport sse https://devplan-mcp-server.mike-c63.workers.dev/sse

Key tools:

• devplan_generate_plan - Generate DEVELOPMENT_PLAN.md from PROJECT_BRIEF.md
• devplan_generate_executor - Generate Haiku executor agent
• devplan_generate_verifier - Generate Sonnet verifier agent
• devplan_add_lesson - Capture lessons from verification failures

Lessons captured via devplan_add_lesson are automatically incorporated into future plan generation.

See devplan-mcp-server for the full tool list.

🎓 Example Workflow

Here's what a typical project looks like:

Session 1: Planning (30-60 minutes)

You: Go read the README at https://github.com/mmorris35/ClaudeCode-DevPlanBuilder
     and help me develop my idea

Claude: [Asks questions about your project]
You: [Answers questions]
Claude: [Creates PROJECT_BRIEF.md]
You: [Reviews and approves]

Claude: [Creates claude.md]
You: [Reviews and approves]

Claude: [Creates DEVELOPMENT_PLAN.md with all phases/tasks/subtasks]
You: [Reviews and approves]

Claude: [Validates the plan]
You: [Git commit - your plan is ready!]

Session 2: Foundation (2-4 hours)

You: Use the taskflow-executor agent to execute subtask 0.1.1

Claude: [Completes subtask 0.1.1]
        [Runs tests, linting, type checking]
        [Updates DEVELOPMENT_PLAN.md]
        [Creates git commit]

You: [Reviews] Looks good!

You: Use the taskflow-executor agent to execute subtask 0.1.2

Claude: [Completes subtask 0.1.2]
...

Sessions 3-N: Development (2-4 hours each)

You: Use the taskflow-executor agent to execute subtask [next ID]

Claude: [Completes subtask]
You: [Reviews, commits, moves to next]

Just keep going until all subtasks are complete!

🚀 Autonomous Execution (Hands-Free Mode)

Want Claude to build your entire project without asking for approval at every step? You can run in autonomous mode using --dangerously-skip-permissions.

When Is This Safe?

Safe for:

• ✅ Brand new projects in isolated directories
• ✅ Directories containing only DevPlan-generated planning files
• ✅ Development machines (not production servers)

Not safe for:

• ❌ Existing production code
• ❌ Directories with sensitive data or credentials
• ❌ System directories or your home folder

The flag is called "dangerously" for a reason - it bypasses safety prompts. For greenfield projects in isolated folders, this is fine. For anything touching production, don't use this flag.

Quick Example

# Execute a single subtask autonomously (replace {project} with your project name)
claude --dangerously-skip-permissions \
  "Use the {project}-executor agent to execute subtask 1.2.3"

# Execute an entire phase
claude --dangerously-skip-permissions \
  "Use the {project}-executor agent to execute all tasks in Phase 1. For each task: create feature branch, complete all subtasks with commits, merge when done."

# Build the entire project
claude --dangerously-skip-permissions \
  "Use the {project}-executor agent to execute the entire development plan from current progress. Follow git discipline throughout."

Recommended Workflow

1. Plan interactively - Answer interview questions, review generated files
2. Execute Phase 0 interactively - Set up foundation with your oversight
3. Switch to autonomous for development phases - Let Claude build while you grab coffee
4. Review between phases - Check git history, run tests, verify progress
5. Run verification - Use the verifier agent to validate against requirements

# After autonomous build completes, verify the result
claude "Use the {project}-verifier agent to validate against PROJECT_BRIEF.md"

See docs/AUTONOMOUS_EXECUTION.md for the complete guide including safety checklists, troubleshooting, and monitoring tips.

💪 Why This Works

Traditional Approach:

• ❌ Vague requirements
• ❌ No clear next step
• ❌ Testing as an afterthought
• ❌ Inconsistent code quality
• ❌ No progress tracking
• ❌ Git history is a mess

With Dev Plan Builder:

• ✅ Crystal clear requirements (PROJECT_BRIEF.md)
• ✅ Always know what's next (numbered subtasks)
• ✅ Tests written alongside code (every subtask)
• ✅ Quality enforced (linting, type checking, pre-commit hooks)
• ✅ Progress visible (checkboxes, completion notes)
• ✅ Clean git history (semantic commits, one per subtask)

🤝 Contributing

Want to improve the methodology or the tool? Contributions welcome!

This project follows strict development guidelines (see examples/hello-cli/CLAUDE.md for the pattern). Each subtask must:

• Be completed in a single session
• Include comprehensive tests (>80% coverage)
• Pass all linting and type checking
• End with a semantic git commit

📜 License

MIT License - see LICENSE file for details

Use this for anything - personal projects, commercial products, open source, whatever!

🙏 Acknowledgments

Built with Claude Code - An AI pair programmer that executes development plans with precision.

This methodology emerged from real-world usage of Claude Code on production projects. It codifies best practices for:

• Project planning and task breakdown
• Testing and quality assurance
• Git workflow and discipline
• Progress tracking and knowledge capture

🚀 Ready to Start?

Just paste this in Claude Code:

Go read the README at https://github.com/mmorris35/ClaudeCode-DevPlanBuilder and help me develop my idea into a complete development plan.

Then answer Claude's questions about your project, and you're off to the races! 🎉

❓ Questions?

• 📖 Read: PROMPT_SEQUENCE.md for detailed guidance
• 👀 See: examples/ for complete Haiku-executable examples (CLI, API, Web App, Library)
• 🔍 Learn: docs/HAIKU_EXECUTABLE_PLANS.md for writing better plans
• ⚠️ Avoid: docs/BEST_PRACTICES.md for common anti-patterns
• 💬 Ask: Open an issue at https://github.com/mmorris35/ClaudeCode-DevPlanBuilder/issues

Built with Claude Code • Powered by Anthropic • CC-BY-4.0 License