Claude Code Research-Plan-Implement Framework Playbook

Table of Contents

1. Overview
2. Quick Start
3. Framework Architecture
4. Workflow Phases
5. Command Reference
6. Session Management
7. Agent Reference
8. Best Practices
9. Customization Guide
10. Troubleshooting

Overview

The Research-Plan-Implement Framework is a structured approach to AI-assisted software development that emphasizes:

• Thorough research before coding
• Detailed planning with clear phases
• Systematic implementation with verification
• Persistent context through markdown documentation

Core Benefits

• 🔍 Deep Understanding: Research phase ensures complete context
• 📋 Clear Planning: Detailed plans prevent scope creep
• ✅ Quality Assurance: Built-in validation at each step
• 📚 Knowledge Building: Documentation accumulates over time
• ⚡ Parallel Processing: Multiple AI agents work simultaneously
• 🧪 Test-Driven Development: Design test cases following existing patterns before implementation

Quick Start

Installation

1. Copy framework files to your repository:

# From the .claude-framework-adoption directory
cp -r .claude your-repo/
# Create docs directory structure
mkdir -p your-repo/docs/tickets
mkdir -p your-repo/docs/notes

2. Customize for your project:

• Edit .claude/commands/*.md to match your tooling
• Update agent descriptions if needed
• Add project-specific CLAUDE.md

3. Test the workflow:

Standard Approach:

/1_research_codebase
> How does user authentication work in this codebase?

/2_create_plan
> I need to add two-factor authentication

/3_implement_plan
> docs/tickets/TICKET-NAME/plan.md

Test-Driven Approach:

/8_define_test_cases
> Two-factor authentication for user login

# Design tests, then implement feature
/3_implement_plan
> Implement 2FA to make tests pass

Framework Architecture

your-repo/
├── .claude/                      # AI Assistant Configuration
│   ├── agents/                   # Specialized AI agents
│   │   ├── codebase-locator.md   # Finds relevant files
│   │   ├── codebase-analyzer.md  # Analyzes implementation
│   │   ├── codebase-pattern-finder.md # Finds patterns to follow
│   │   ├── codebase-research-locator.md # Finds docs/ files
│   │   ├── codebase-research-analyzer.md # Extracts insights from docs
│   │   └── codebase-online-researcher.md # Web research
│   └── commands/                 # Numbered workflow commands
│       ├── 1_research_codebase.md
│       ├── 2_create_plan.md
│       ├── 3_define_test_cases.md   # Generate executable tests
│       ├── 4_implement_plan.md
│       ├── 5_validate_implementation.md
│       ├── 6_iterate_implementation.md
│       ├── 7_save_progress.md   # Save work session
│       ├── 8_resume_work.md     # Resume saved work
│       └── 9_research_cloud.md  # Cloud infrastructure analysis
├── docs/                         # Persistent Context Storage
│   ├── tickets/                  # Ticket-associated documentation
│   │   └── TICKET-NAME/         # Feature/ticket folders
│   │       ├── plan.md
│   │       ├── research.md
│   │       ├── test-cases.md     # Lightweight test index
│   │       ├── notes-YYYY-MM-DD.md # Implementation notes
│   │       └── sessions/        # Work session summaries
│   │           └── NNN_feature.md
│   └── notes/                    # General notes and meetings
│       └── YYYY-MM-DD-meeting.md
├── test/                         # Test files
│   └── [feature]/
│       └── [feature].test.ts    # Actual runnable tests
└── CLAUDE.md                    # Project-specific instructions

Workflow Phases

Phase 1: Research (/1_research_codebase)

Purpose: Comprehensive exploration and understanding

Process:

1. Invoke command with research question
2. Optimize question using prompt-engineer skill
3. Read mentioned files FULLY before spawning sub-tasks
4. AI spawns parallel agents to investigate
5. Findings compiled into structured document
6. Saved to docs/tickets/TICKET-NAME/{research-topic}.md or docs/{research-topic}.md (creates folder if needed)

Example:

/1_research_codebase
> How does the payment processing system work?

Output: Detailed research document with:

• Code references (file:line)
• Architecture insights
• Patterns and conventions
• Related components
• Historical context from docs/

Phase 2: Planning (/2_create_plan)

Purpose: Create detailed, phased implementation plan

Process:

1. Read requirements and research FULLY
2. Interactive planning with user
3. Generate phased approach
4. Save to docs/tickets/TICKET-NAME/plan.md (creates folder if needed)

Example:

/2_create_plan
> Add Stripe payment integration based on the research

Plan Structure:

# Feature Implementation Plan

## Phase 1: Database Setup
### Changes Required:
- Add payment tables
- Migration scripts

### Success Criteria:
#### Automated:
- [ ] Migration runs successfully
- [ ] Tests pass

#### Manual:
- [ ] Data integrity verified

## Phase 2: API Integration
[...]

Phase 3: Define Test Cases (/3_define_test_cases)

Purpose: Design executable test cases using BDD principles

Process:

1. Invoke command with feature description
2. AI researches existing test patterns in codebase
3. Generates actual runnable test code file
4. Creates lightweight index in docs/tickets/TICKET-NAME/test-cases.md

Example:

/3_define_test_cases
> Partner enrollment workflow when ordering kit products

Output:

1. PRIMARY: Test Code File - test/[feature]/[feature].test.ts

   • Actual runnable tests with Given-When-Then structure
   • Minimal helpers (only when duplication > 2x)
   • Tests ARE the specification

2. SECONDARY: Lightweight Index - docs/tickets/TICKET-NAME/test-cases.md

   • Quick reference with line numbers
   • Commands to run tests
   • Coverage summary

Test Structure:

describe("Feature Name", () => {
  test("behavior description", async () => {
    // Given: [preconditions]
    const state = { files: {}, todos: [] };

    // When: [action]
    const result = await executeFeature(state);

    // Then: [expected outcome]
    expect(result.success).toBe(true);
  });
});

Coverage Areas:

• Happy paths
• Edge cases
• Error scenarios
• Boundary conditions
• Authorization/permission checks

Phase 4: Implementation (/4_implement_plan)

Purpose: Execute plan systematically

Process:

1. Read plan and test files (if exist) FULLY
2. Read all note files in ticket folder
3. Implement phase by phase
4. If test file exists: Make tests pass (test-driven approach)
5. Run verification after each phase
6. Update plan checkboxes

Example:

/4_implement_plan
> docs/tickets/TICKET-NAME/plan.md

Progress Tracking:

• Uses checkboxes in plan
• TodoWrite for task management
• Creates note files for new requirements
• Communicates blockers clearly

Phase 5: Validation (/5_validate_implementation)

Purpose: Verify implementation matches plan

Process:

1. Read all ticket documentation (plan, test-cases, notes, research, sessions)
2. Review git changes
3. Run all automated checks
4. If test file exists: Run tests and verify 100% pass
5. Generate validation report
6. Identify deviations
7. Recommend iteration if issues found

Example:

/5_validate_implementation
> Validate the Stripe integration implementation

Report Includes:

• Implementation status
• Test results (if applicable)
• Code review findings
• Requirements from notes
• Manual testing requirements
• Next steps (often: run step 6)

Phase 6: Iteration (/6_iterate_implementation)

Purpose: Fix bugs, address deviations, refine features

Process:

1. Read validation report, plan, notes
2. Categorize issues (bugs, deviations, missing requirements)
3. Prioritize and fix systematically
4. Fix production code to make tests pass (not modify tests)
5. Update documentation (plan checkboxes, note files)
6. Verify fixes with automated checks

Example:

/6_iterate_implementation
> docs/tickets/TICKET-NAME/plan.md

Iteration Cycle:

Step 5 (Validate) → Step 6 (Iterate) → Step 5 (Validate) → ...

Continue until all validation criteria pass.

Command Reference

Core Workflow Commands

/1_research_codebase

• Purpose: Deep dive into codebase
• Input: Research question
• Output: Research document
• Agents Used: All locator/analyzer agents (codebase-locator, codebase-analyzer, codebase-pattern-finder, codebase-research-locator, codebase-research-analyzer, codebase-online-researcher)

/2_create_plan

• Purpose: Create implementation plan
• Input: Requirements/ticket
• Output: Phased plan document
• Interactive: Yes

/3_define_test_cases

• Purpose: Generate executable test code using BDD principles
• Input: Feature/functionality to test
• Output: Test file (test/[feature]/[feature].test.ts) + lightweight index (docs/tickets/TICKET-NAME/test-cases.md)
• Approach: Tests ARE the specification - executable documentation
• Agent Used: codebase-pattern-finder (automatic)

/4_implement_plan

• Purpose: Execute implementation
• Input: Plan path
• Output: Completed implementation
• Note: If tests exist, uses test-driven approach

/5_validate_implementation

• Purpose: Verify implementation
• Input: Plan path (optional)
• Output: Validation report
• Note: Works in cycle with step 6

/6_iterate_implementation

• Purpose: Fix bugs and address deviations found in validation
• Input: Plan path
• Output: Fixed implementation
• Note: Works in cycle with step 5

Session Management

The framework supports saving and resuming work through persistent documentation:

/7_save_progress

• Purpose: Save work progress and context
• Input: Current work state
• Output: Session summary and checkpoint
• Creates: docs/tickets/TICKET-NAME/sessions/NNN_feature.md document (NNN is sequential)

/8_resume_work

• Purpose: Resume previously saved work
• Input: Session summary path or auto-discover
• Output: Restored context and continuation
• Reads: Session, plan, research, and note files

/9_research_cloud

• Purpose: Analyze cloud infrastructure (READ-ONLY)
• Input: Cloud platform and focus area
• Output: Infrastructure analysis document
• Creates: docs/tickets/TICKET-NAME/cloud-platform-environment.md or docs/cloud-platform-environment.md documents
• Safety: Only executes READ-ONLY operations

Agent Reference

codebase-locator

• Role: Find relevant files
• Tools: Grep, Glob, LS
• Returns: Categorized file listings

codebase-analyzer

• Role: Understand implementation
• Tools: Read, Grep, Glob, LS
• Returns: Detailed code analysis

codebase-pattern-finder

• Role: Find examples to follow
• Tools: Grep, Glob, Read, LS
• Returns: Code patterns and examples

codebase-research-locator

• Role: Find existing documents in docs/ directory
• Tools: Read, Grep, Glob, LS
• Returns: Categorized document listings

codebase-research-analyzer

• Role: Extract insights from research documents
• Tools: Read, Grep, Glob, LS
• Returns: Key decisions, constraints, and actionable insights

codebase-online-researcher

• Role: Research external documentation and web resources
• Tools: DeepWiki, Playwright browser tools
• Returns: External documentation findings with links

Best Practices

1. Research First

• Always start with research for complex features
• Don't skip research even if you think you know the codebase
• Research documents become valuable references

2. Plan Thoroughly

• Break work into testable phases
• Include specific success criteria
• Document what's NOT in scope
• Resolve all questions before finalizing
• Consider how work will be committed

3. Implement Systematically

• Complete one phase before starting next
• Run tests after each phase
• Update plan checkboxes as you go
• Communicate blockers immediately

4. Document Everything

• Research findings persist in docs/tickets/TICKET-NAME/ or docs/
• Plans serve as technical specs
• Session summaries maintain continuity

5. Use Parallel Agents

• Spawn multiple agents for research
• Let them work simultaneously
• Combine findings for comprehensive view

6. Design Tests Early

• Define test cases before implementing features
• Use /3_define_test_cases to generate actual runnable test code
• Tests become the living specification
• Ensure tests cover happy paths, edge cases, and errors
• Let tests guide implementation (test-driven approach)

Customization Guide

Adapting Commands

1. Remove framework-specific references:

# Before (cli project specific)
Run `cli thoughts sync`

# After (Generic)
Save to docs/tickets/TICKET-NAME/research.md or docs/{research-topic}.md

2. Adjust tool commands:

# Match your project's tooling
- Tests: `npm test` → `yarn test`
- Lint: `npm run lint` → `make lint`
- Build: `npm run build` → `cargo build`

3. Customize success criteria:

# Add project-specific checks
- [ ] Security scan passes: `npm audit`
- [ ] Performance benchmarks met
- [ ] Documentation generated

Adding Custom Agents

Create new agents for specific needs:

---
name: security-analyzer
description: Analyzes security implications
tools: Read, Grep
---

You are a security specialist...

Project-Specific CLAUDE.md

Add instructions for your project:

# Project Conventions

## Testing
- Always write tests first (TDD)
- Minimum 80% coverage required
- Use Jest for unit tests

## Code Style
- Use Prettier formatting
- Follow ESLint rules
- Prefer functional programming

## Git Workflow
- Feature branches from develop
- Squash commits on merge
- Conventional commit messages

Troubleshooting

Common Issues

Q: Research phase taking too long?

• A: Limit scope of research question
• Focus on specific component/feature
• Use more targeted queries

Q: Plan too vague?

• A: Request more specific details
• Ask for code examples
• Ensure success criteria are measurable

Q: Implementation doesn't match plan?

• A: Stop and communicate mismatch
• Update plan if needed
• Validate assumptions with research

Q: How to commit changes?

• A: Use git commands directly after validation
• Group related changes logically
• Write clear commit messages following project conventions

Tips for Success

1. Start Small: Test with simple feature first
2. Iterate: Customize based on what works
3. Build Library: Accumulate research/plans over time
4. Team Alignment: Share framework with team
5. Regular Reviews: Update commands based on learnings

Advanced Usage

Chaining Commands

For complex features, chain commands:

# Step 1: Research
/1_research_codebase
> Research current auth system

# Step 2: Plan
/2_create_plan
> Based on research, plan OAuth integration

# Step 3: Define tests
/3_define_test_cases
> OAuth authentication flows

# Step 4: Implement
/4_implement_plan
> docs/tickets/TICKET-NAME/plan.md

# Step 5: Validate
/5_validate_implementation
> docs/tickets/TICKET-NAME/plan.md

# Step 6: Iterate if needed
/6_iterate_implementation
> docs/tickets/TICKET-NAME/plan.md

# Then manually commit using git

Parallel Research

Research multiple aspects simultaneously:

/1_research_codebase
> How do authentication, authorization, and user management work together?

This spawns agents to research each aspect in parallel.

Cloud Infrastructure Analysis

Analyze cloud deployments without making changes:

/9_research_cloud
> Azure
> all

# Analyzes:
- Resource inventory and costs
- Security and compliance
- Architecture patterns
- Optimization opportunities

Test-Driven Development Workflow

Design tests before implementation:

# Step 1: Define test cases
/3_define_test_cases
> Partner enrollment when customer orders a kit product

# Output includes:
# - Actual test code: test/partners/enrollment.test.ts
# - Lightweight index: docs/tickets/TICKET-NAME/test-cases.md
# - Tests cover happy path, edge cases, errors, boundaries, auth

# Step 2: Create plan for feature implementation
/2_create_plan
> Implement partner enrollment logic to make tests pass

# Step 3: Implement the feature
/4_implement_plan
> docs/tickets/TICKET-NAME/plan.md
# Tests drive implementation - make them pass!

# Step 4: Validate
/5_validate_implementation
> docs/tickets/TICKET-NAME/plan.md

# Step 5: Iterate if tests don't pass
/6_iterate_implementation
> docs/tickets/TICKET-NAME/plan.md

Key Benefit: Tests are the living specification - executable documentation that defines correct behavior.

Conclusion

This framework provides structure without rigidity. It scales from simple features to complex architectural changes. The key is consistent use - the more you use it, the more valuable your docs/tickets/ directory becomes as organizational knowledge.

Remember: The framework is a tool to enhance development, not replace thinking. Use it to augment your capabilities, not as a rigid process.