Research → Plan → Implement: The Claude Code Framework

Research → Plan → Implement → Validate

/1_research_codebase
> How does the authentication system handle session management and token refresh?

# Claude spawns parallel agents
agents = [
    CodebaseLocator(find="auth files, session management"),
    CodebaseAnalyzer(understand="token refresh implementation"),
    PatternFinder(discover="authentication patterns to follow")
]
 
# Agents work simultaneously
results = await parallel_execute(agents)
 
# Synthesize comprehensive findings
research_doc = compile_findings(results)

## Authentication System Analysis
 
### Token Management
- JWT tokens stored in httpOnly cookies (auth-utils.ts:45)
- Refresh tokens in secure Redis store (session-manager.ts:112)
- 15-minute access token, 7-day refresh token
 
### Session Handling Pattern
 
    // Current implementation at auth-middleware.ts:78
    async function refreshSession(refreshToken: string) {
      const session = await redis.get(`session:${refreshToken}`);
      if (!session || isExpired(session)) {
        throw new UnauthorizedError();
      }
 
      const newTokens = generateTokenPair(session.userId);
      await redis.setex(`session:${newTokens.refresh}`,
        7 * 24 * 60 * 60, session);
 
      return newTokens;
    }
 
 
### Security Considerations Found
- CSRF protection via double-submit cookies
- Rate limiting on refresh endpoint (5 requests/minute)
- Token rotation on every refresh

/2_create_plan
> Based on the research, add OAuth 2.0 support with Google and GitHub providers

# OAuth 2.0 Integration Plan
 
## Overview
Add OAuth 2.0 authentication with Google and GitHub providers while maintaining existing JWT session management.
 
## Implementation Approach
Extend current auth system rather than replace. Use Passport.js for OAuth strategies, integrate with existing JWT/Redis session management.
 
## Phase 1: Database & Models
 
### Changes Required:
 
#### 1. Database Schema
**File**: `prisma/schema.prisma`
**Changes**: Add OAuth provider tracking
 
    model User {
      id            String    @id @default(cuid())
      email         String    @unique
      providers     OAuthProvider[]
      // existing fields...
    }
 
    model OAuthProvider {
      id            String    @id @default(cuid())
      provider      String    // 'google' | 'github'
      providerId    String
      userId        String
      user          User      @relation(fields: [userId])
 
      @@unique([provider, providerId])
    }
 
### Success Criteria:
 
#### Automated Verification:
- [ ] Migration runs successfully: `npm run db:migrate`
- [ ] Schema validates: `npm run db:validate`
- [ ] Tests pass: `npm test -- auth.test.ts`
 
#### Manual Verification:
- [ ] Database accepts OAuth records
- [ ] Existing auth still works
 
---
 
## Phase 2: OAuth Strategy Implementation
 
### Changes Required:
 
#### 1. Passport Strategies
**File**: `src/auth/strategies/oauth.ts`
**Changes**: Implement OAuth strategies
 
    export const googleStrategy = new GoogleStrategy({
      clientID: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
      callbackURL: "/auth/google/callback"
    }, async (accessToken, refreshToken, profile, done) => {
      const user = await findOrCreateUser({
        provider: 'google',
        providerId: profile.id,
        email: profile.emails[0].value
      });
      done(null, user);
    });
 
 
### Success Criteria:
- [ ] Google OAuth flow completes
- [ ] GitHub OAuth flow completes
- [ ] Sessions created properly
- [ ] Rate limiting still works

/4_implement_plan
> @thoughts/shared/plans/001_oauth_integration.md

Starting Phase 1: Database & Models
 
✓ Updated prisma/schema.prisma
✓ Created migration
✓ Running migration... Success!
✓ Tests passing
 
Phase 1 Complete. Starting Phase 2...
 
✓ Installed passport dependencies
✓ Created OAuth strategies
⚠️ Issue: Google Client ID not in .env
 
Blocker Found:
Need GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET environment variables.
Please add these to your .env file:
 
GOOGLE_CLIENT_ID=your_client_id_here
GOOGLE_CLIENT_SECRET=your_client_secret_here
 
Once added, I'll continue with Phase 2.

/3_validate_plan
> Validate the OAuth implementation

## Validation Report: OAuth 2.0 Integration
 
### Implementation Status
✓ Phase 1: Database & Models - Fully implemented
✓ Phase 2: OAuth Strategies - Fully implemented
✓ Phase 3: UI Integration - Fully implemented
 
### Automated Verification Results
✓ Build passes
✓ All 47 tests pass
✓ Type checking clean
✓ No linting issues
 
### Code Review Findings
 
#### Matches Plan:
- Database schema correctly extended
- OAuth strategies properly configured
- Session management integrated seamlessly
 
#### Security Validation:
- CSRF protection maintained
- Rate limiting applies to OAuth endpoints
- Tokens properly secured
 
### Manual Testing Checklist:
- [ ] Google sign-in flow works
- [ ] GitHub sign-in flow works
- [ ] Session persistence correct
- [ ] Logout clears all sessions
- [ ] Account linking works

/7_research_cloud
> Azure
> all

## Cloud Infrastructure Analysis: Production Azure
 
### Resource Inventory
| Type | Count | Monthly Cost | Region |
|------|-------|--------------|--------|
| VMs | 12 | $2,400 | East US |
| Storage | 8 | $450 | East US |
| SQL DBs | 3 | $1,200 | East US |
 
### Security Findings
✅ All storage encrypted at rest
⚠️ 2 VMs missing network security groups
❌ Public RDP exposed on jumpbox-01
 
### Cost Optimization
- $800/month: Resize overprovisioned VMs
- $300/month: Delete unattached disks
- $150/month: Use reserved instances
 
### Recommendations
1. Immediate: Close public RDP port
2. Short-term: Implement NSGs on all VMs
3. Long-term: Migrate to AKS for containers

/5_save_progress
> Need to switch to urgent bug fix, save OAuth work

## Session Summary: OAuth Integration
 
### Completed:
- Phase 1: Database setup ✓
- Phase 2: Strategy implementation ✓
- Partial Phase 3: UI (50% complete)
 
### Current State:
- Working on OAuth button components
- Google flow tested and working
- GitHub flow needs callback URL fix
 
### To Resume:
1. Fix GitHub callback URL in .env
2. Complete button styling
3. Add loading states
4. Test account linking
 
### Commands to Resume:
/6_resume_work @thoughts/shared/sessions/2025-09-23_oauth.md

/6_resume_work
> @thoughts/shared/sessions/2025-09-23_oauth.md
 
Restored context:
- Plan: OAuth 2.0 Integration
- Progress: Phase 3 (50% complete)
- Next: Fix GitHub callback URL
 
Continuing from where we left off...

your-project/
├── .claude/                      # Framework configuration
│   ├── agents/                   # Specialized AI agents
│   │   ├── codebase-locator.md
│   │   ├── codebase-analyzer.md
│   │   └── codebase-pattern-finder.md
│   └── commands/                 # Workflow commands
│       ├── 1_research_codebase.md
│       ├── 2_create_plan.md
│       ├── 3_validate_plan.md
│       ├── 4_implement_plan.md
│       ├── 5_save_progress.md
│       ├── 6_resume_work.md
│       └── 7_research_cloud.md  # Cloud infrastructure analysis
├── thoughts/                     # Persistent knowledge base
│   └── shared/
│       ├── research/            # Research findings
│       │   ├── 001_auth_system.md
│       │   └── 002_payment_flow.md
│       ├── plans/               # Implementation plans
│       │   ├── 001_oauth_integration.md
│       │   └── 002_stripe_upgrade.md
│       ├── sessions/            # Work sessions
│       │   └── 2025-09-23_oauth.md
│       └── cloud/               # Cloud infrastructure analyses
│           └── azure_production.md
└── CLAUDE.md                    # Project-specific instructions

# Clone the framework
git clone https://github.com/brilliantconsultingdev/claude-research-plan-implement.git
cd claude-research-plan-implement
 
# Run the setup script with your project directory
./setup.sh /path/to/your-project

# Research a feature
/1_research_codebase
> How does the current search implementation work?
 
# Create a plan
/2_create_plan
> Add Elasticsearch to improve search performance
 
# Implement the plan
/4_implement_plan
> @thoughts/shared/plans/elasticsearch_integration.md
 
# Validate
/3_validate_plan
 
# Commit changes manually
git add .
git commit -m "feat: Add Elasticsearch integration"

/1_research_codebase
> Current error handling patterns in API routes

# Day 1: Research and plan
/1_research_codebase
/2_create_plan
/5_save_progress
 
# Day 2: Implement core
/6_resume_work
/4_implement_plan (Phase 1-2)
/5_save_progress
 
# Day 3: Finish and ship
/6_resume_work
/4_implement_plan (Phase 3)
/3_validate_plan
git commit -m "feat: Complete feature implementation"

/1_research_codebase
> How do authentication, authorization, and rate limiting work together?
 
# Spawns 3 parallel agents to research each aspect
# 3x faster than sequential research

/1_research_codebase → /2_create_plan → /4_implement_plan → /3_validate_plan

/1_research_codebase (understand the bug) → /4_implement_plan (fix) → /3_validate_plan

/1_research_codebase (current state) → /2_create_plan (refactor strategy) → /4_implement_plan (incremental changes)

/1_research_codebase (bottlenecks) → /2_create_plan (optimization strategy) → /4_implement_plan → /3_validate_plan (benchmark)

/7_research_cloud (analyze current) → /2_create_plan (optimization plan) → /4_implement_plan (apply changes)

/7_research_cloud (security focus) → /1_research_codebase (app security) → /2_create_plan (remediation)