docs: add dual-instance planning pattern (Jon Williams)
Add vertical separation pattern (planner/implementer) as complement to horizontal scaling (Boris pattern). ## Changes **Main guide (ultimate-guide.md)**: - New Section 9.17.1: "Alternative Pattern: Dual-Instance Planning" (~350 lines) - When to use (solo devs, spec-heavy, $100-200/month) - Setup instructions (2 Claude instances, Plans/ directory) - Complete workflow (5 phases: planning, review, implementation, verification, archive) - Comparison table (Boris horizontal vs Jon vertical scaling) - Cost analysis (2 instances vs correction loops) - Agent-ready plan best practices - Limitations and tips **Workflow file (workflows/dual-instance-planning.md)**: - Full workflow guide (~750 lines) - Complete example (JWT auth implementation) - Plan template (ready to copy-paste) - Cost breakdown and decision matrix - Troubleshooting and bash aliases **References updated**: - machine-readable/reference.yaml: 15 new entries - dual_instance_planning, dual_instance_workflow, etc. - Line numbers, source attribution, metadata - guide/workflows/plan-driven.md: Link in See Also section - README.md: Update evaluation count (46 → 47) **Evaluation documented**: - docs/resource-evaluations/jon-williams-dual-instance-pattern.md - Full methodology (fetch, analyze, challenge, fact-check) - Score progression (2-3/5 → 4/5 after technical-writer challenge) - Gap analysis, comparison, integration rationale ## Source LinkedIn post by Jon Williams (Product Designer, UK) Date: 2026-02-03 URL: https://www.linkedin.com/posts/thatjonwilliams_ive-been-using-cursor-for-six-months-now-activity-7424481861802033153-k8bu Context: Transition from Cursor (6 months) to Claude Code with Opus 4.5 Pattern: Vertical separation (Claude Zero: planning/review, Claude One: implementation) Distinction: Orthogonal to Boris pattern (vertical vs horizontal scaling) ## Stats - Lines added: ~1,400 - Files modified: 4 - Files created: 2 (workflow + evaluation) - References added: 15 (reference.yaml) - Evaluation score: 4/5 (High Value) - Integration time: ~2.5 hours Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
bc6b32ed3a
commit
9c5d030b11
6 changed files with 1402 additions and 4 deletions
|
|
@ -12881,6 +12881,343 @@ The broader team extends Boris's individual workflow with institutional patterns
|
|||
|
||||
---
|
||||
|
||||
### Alternative Pattern: Dual-Instance Planning (Vertical Separation)
|
||||
|
||||
While Boris's workflow demonstrates **horizontal scaling** (5-15 instances in parallel), an alternative pattern focuses on **vertical separation**: using two Claude instances with distinct roles for quality-focused workflows.
|
||||
|
||||
**Pattern source**: Jon Williams (Product Designer, UK), transition from Cursor to Claude Code after 6 months. [LinkedIn post, Feb 3, 2026](https://www.linkedin.com/posts/thatjonwilliams_ive-been-using-cursor-for-six-months-now-activity-7424481861802033153-k8bu)
|
||||
|
||||
#### When to Use Dual-Instance Pattern
|
||||
|
||||
This pattern is **orthogonal** to Boris's approach: instead of scaling breadth (more features in parallel), it scales depth (separation of planning and execution phases).
|
||||
|
||||
| Your Context | Use Dual-Instance? | Monthly Cost |
|
||||
|--------------|-------------------|--------------|
|
||||
| **Solo dev, spec-heavy work** | ✅ Yes | $100-200 |
|
||||
| **Small team, complex requirements** | ✅ Yes | $150-300 |
|
||||
| **Product designers coding** | ✅ Yes | $100-200 |
|
||||
| **High-volume parallel features** | ❌ No, use Boris pattern | $500-1K+ |
|
||||
|
||||
**Use when**:
|
||||
- You need plan verification before execution
|
||||
- Specs are complex or ambiguous (interview-based clarification helps)
|
||||
- Lower budget than Boris pattern ($100-200/month vs $500-1K+)
|
||||
- Quality > speed (willing to sacrifice parallelism for better plans)
|
||||
|
||||
**Don't use when**:
|
||||
- You need to ship 10+ features simultaneously (use Boris pattern)
|
||||
- Plans are straightforward (single instance with `/plan` is enough)
|
||||
- Budget is very limited (<$100/month)
|
||||
|
||||
#### Setup: Two Instances, Two Roles
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ DUAL-INSTANCE ARCHITECTURE │
|
||||
├─────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────────────┐ │
|
||||
│ │ Claude Zero │ Planning & Review │
|
||||
│ │ (Planner) │ - Explores codebase │
|
||||
│ └────────┬─────────┘ - Writes plans │
|
||||
│ │ - Reviews implementations │
|
||||
│ │ - NEVER touches code │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ │
|
||||
│ │ Plans/Review/ │ Human review checkpoint │
|
||||
│ │ Plans/Active/ │ │
|
||||
│ └────────┬────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────┐ │
|
||||
│ │ Claude One │ Implementation │
|
||||
│ │ (Implementer) │ - Reads approved plans │
|
||||
│ └──────────────────┘ - Writes code │
|
||||
│ - Commits changes │
|
||||
│ - Reports completion │
|
||||
│ │
|
||||
│ Key: Separation of concerns = fewer mistakes │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Setup steps**:
|
||||
|
||||
1. **Create directory structure**:
|
||||
```bash
|
||||
mkdir -p .claude/plans/{Review,Active,Completed}
|
||||
```
|
||||
|
||||
2. **Launch Claude Zero** (Terminal 1):
|
||||
```bash
|
||||
cd ~/projects/your-project
|
||||
claude
|
||||
# Set role in first message:
|
||||
# "You are Claude Zero. Your role: explore codebase, write plans,
|
||||
# review implementations. NEVER edit code. Save all plans to
|
||||
# .claude/plans/Review/"
|
||||
```
|
||||
|
||||
3. **Launch Claude One** (Terminal 2):
|
||||
```bash
|
||||
cd ~/projects/your-project
|
||||
claude
|
||||
# Set role in first message:
|
||||
# "You are Claude One. Your role: read plans from .claude/plans/Active/,
|
||||
# implement them, commit changes, report back."
|
||||
```
|
||||
|
||||
#### Workflow: 5 Steps
|
||||
|
||||
**Step 1: Planning (Claude Zero)**
|
||||
|
||||
```
|
||||
You (to Claude Zero): /plan
|
||||
|
||||
Implement JWT authentication for the API.
|
||||
- Support access tokens (15min expiry)
|
||||
- Support refresh tokens (7 day expiry)
|
||||
- Middleware to validate tokens on protected routes
|
||||
```
|
||||
|
||||
Claude Zero explores codebase, interviews you about requirements:
|
||||
- "Should we support multiple sessions per user?"
|
||||
- "Do you want token revocation (logout) capability?"
|
||||
- "Which routes should be protected vs public?"
|
||||
|
||||
Claude Zero writes plan to `.claude/plans/Review/auth-jwt.md`:
|
||||
|
||||
```markdown
|
||||
# Plan: JWT Authentication
|
||||
|
||||
## Summary
|
||||
Add JWT-based authentication with access/refresh tokens.
|
||||
Support token revocation for logout.
|
||||
|
||||
## Files to Create
|
||||
- src/auth/jwt.ts (line 1-120)
|
||||
- generateAccessToken(userId)
|
||||
- generateRefreshToken(userId)
|
||||
- verifyToken(token)
|
||||
|
||||
- src/middleware/auth.ts (line 1-45)
|
||||
- requireAuth middleware
|
||||
- Token validation logic
|
||||
|
||||
## Files to Modify
|
||||
- src/routes/api.ts (line 23)
|
||||
- Add auth middleware to protected routes
|
||||
|
||||
- src/config/env.ts (line 15)
|
||||
- Add JWT_SECRET, JWT_REFRESH_SECRET env vars
|
||||
|
||||
## Implementation Steps
|
||||
1. Install jsonwebtoken library
|
||||
2. Create JWT utility functions
|
||||
3. Create auth middleware
|
||||
4. Add JWT secrets to .env
|
||||
5. Protect existing routes
|
||||
6. Write tests for auth flow
|
||||
|
||||
## Success Criteria
|
||||
- POST /auth/login returns access + refresh token
|
||||
- Protected routes reject without valid token
|
||||
- POST /auth/refresh exchanges refresh token for new access token
|
||||
- POST /auth/logout revokes refresh token
|
||||
|
||||
## Risks
|
||||
- Token secrets must be in .env (never committed)
|
||||
- Refresh token storage needs database table
|
||||
```
|
||||
|
||||
**Step 2: Human Review**
|
||||
|
||||
You review `.claude/plans/Review/auth-jwt.md`:
|
||||
- Is the approach correct?
|
||||
- Are all requirements covered?
|
||||
- Any security issues?
|
||||
|
||||
If approved, move to Active:
|
||||
```bash
|
||||
mv .claude/plans/Review/auth-jwt.md .claude/plans/Active/
|
||||
```
|
||||
|
||||
**Step 3: Implementation (Claude One)**
|
||||
|
||||
```
|
||||
You (to Claude One): Implement .claude/plans/Active/auth-jwt.md
|
||||
```
|
||||
|
||||
Claude One reads the plan file, implements all steps, commits.
|
||||
|
||||
**Step 4: Verification (Claude Zero)**
|
||||
|
||||
```
|
||||
You (to Claude Zero): Review the JWT implementation Claude One just completed.
|
||||
```
|
||||
|
||||
Claude Zero reviews:
|
||||
- Code matches plan?
|
||||
- Security best practices followed?
|
||||
- Tests cover success criteria?
|
||||
|
||||
**Step 5: Archive**
|
||||
|
||||
If approved:
|
||||
```bash
|
||||
mv .claude/plans/Active/auth-jwt.md .claude/plans/Completed/
|
||||
```
|
||||
|
||||
#### Comparison: Boris (Horizontal) vs Jon (Vertical)
|
||||
|
||||
| Dimension | Boris Pattern | Jon Pattern (Dual-Instance) |
|
||||
|-----------|---------------|----------------------------|
|
||||
| **Scaling axis** | Horizontal (5-15 instances, parallel features) | Vertical (2 instances, separated phases) |
|
||||
| **Primary goal** | Speed via parallelism | Quality via separation of concerns |
|
||||
| **Monthly cost** | $500-1,000 (Opus × 5-15) | $100-200 (Opus × 2 sequential) |
|
||||
| **Entry barrier** | High (worktrees, CLAUDE.md 2.5K, orchestration) | Low (2 terminals, Plans/ directory) |
|
||||
| **Audience** | Teams, high-volume, 10+ devs | Solo devs, product designers, spec-heavy |
|
||||
| **Context pollution** | Isolated by worktrees (git branches) | Isolated by role separation (planner vs implementer) |
|
||||
| **Accountability** | Git history (commits per instance) | Human-in-the-loop (review plans before execution) |
|
||||
| **Tooling required** | Worktrees, teleport, `/commit-push-pr` | Plans/ directory structure |
|
||||
| **Coordination** | Self-orchestrated (Boris steers 10 sessions) | Human gatekeeper (approve plans) |
|
||||
| **Best for** | Shipping 10+ features/day, experienced teams | Complex specs, quality-critical, budget-conscious |
|
||||
|
||||
**Key insight**: These patterns are **not mutually exclusive**. You can use dual-instance for complex features (planning rigor) and Boris pattern for high-volume simple features (speed).
|
||||
|
||||
#### Cost Analysis: 2 Instances vs Correction Loops
|
||||
|
||||
**Question**: Is it cheaper to use 2 instances (planner + implementer) or 1 instance with correction loops?
|
||||
|
||||
| Scenario | 1 Instance (Corrections) | 2 Instances (Dual) | Winner |
|
||||
|----------|-------------------------|-------------------|--------|
|
||||
| **Simple feature** (login form) | 1 session × $5 = $5 | 2 sessions × $3 each = $6 | 1 instance |
|
||||
| **Complex spec** (auth system) | 1 session × $15 + 2 correction loops × $10 = $35 | 2 sessions × $12 each = $24 | 2 instances |
|
||||
| **Ambiguous requirements** | 1 session × $20 + 3 correction loops × $15 = $65 | 2 sessions × $18 each = $36 | 2 instances |
|
||||
|
||||
**Breakeven point**: For features requiring ≥2 correction loops, dual-instance is cheaper and faster.
|
||||
|
||||
**Hidden cost savings**:
|
||||
- **Context pollution**: Planner doesn't see implementation details → cleaner reasoning
|
||||
- **Fewer hallucinations**: Plans have file paths + line numbers → implementer is grounded
|
||||
- **Learning**: Review step catches mistakes before they compound
|
||||
|
||||
#### Agent-Ready Plans: Best Practices
|
||||
|
||||
The key to dual-instance efficiency is **plan structure**. Jon Williams emphasizes "agent-ready plans with specific file references and line numbers."
|
||||
|
||||
**Bad plan** (vague):
|
||||
```markdown
|
||||
## Implementation
|
||||
Add authentication to the API.
|
||||
Update the routes.
|
||||
Create middleware.
|
||||
```
|
||||
|
||||
**Good plan** (agent-ready):
|
||||
```markdown
|
||||
## Implementation
|
||||
|
||||
### Step 1: Create JWT utilities
|
||||
**File**: src/auth/jwt.ts (new file, ~120 lines)
|
||||
**Functions**:
|
||||
- Line 10-30: generateAccessToken(userId: string): string
|
||||
- Line 35-55: generateRefreshToken(userId: string): string
|
||||
- Line 60-85: verifyToken(token: string): { userId: string } | null
|
||||
|
||||
**Dependencies**: jsonwebtoken (npm install)
|
||||
|
||||
### Step 2: Create auth middleware
|
||||
**File**: src/middleware/auth.ts (new file, ~45 lines)
|
||||
**Export**:
|
||||
- Line 15-40: requireAuth middleware (checks Authorization header)
|
||||
|
||||
**Imports**: jwt.ts (Step 1)
|
||||
|
||||
### Step 3: Protect routes
|
||||
**File**: src/routes/api.ts
|
||||
**Location**: Line 23 (after imports, before route definitions)
|
||||
**Change**: Import requireAuth, apply to /api/protected routes
|
||||
|
||||
**Example**:
|
||||
router.get('/profile', requireAuth, profileController)
|
||||
```
|
||||
|
||||
**Why agent-ready plans work**:
|
||||
- File paths → Claude One knows exactly where to work
|
||||
- Line numbers → Reduces guessing, fewer file reads
|
||||
- Dependencies explicit → No surprises during implementation
|
||||
- Examples included → Claude One understands expected structure
|
||||
|
||||
**Template**: See [guide/workflows/dual-instance-planning.md](workflows/dual-instance-planning.md) for full plan template.
|
||||
|
||||
#### Tips for Success
|
||||
|
||||
**1. Role enforcement**:
|
||||
Set roles in **first message** of each session:
|
||||
- Claude Zero: "NEVER edit code, only write plans to .claude/plans/Review/"
|
||||
- Claude One: "ONLY implement plans from .claude/plans/Active/, never plan"
|
||||
|
||||
**2. Plans directory in .gitignore**:
|
||||
```bash
|
||||
# .gitignore
|
||||
.claude/plans/Review/ # Work in progress
|
||||
.claude/plans/Active/ # Under implementation
|
||||
# Don't ignore Completed/ (optional: archive for team learning)
|
||||
```
|
||||
|
||||
**3. Use /plan mode**:
|
||||
Claude Zero should start with `/plan` for safe exploration:
|
||||
```
|
||||
/plan
|
||||
|
||||
[Your feature request]
|
||||
```
|
||||
|
||||
**4. Interview prompts**:
|
||||
Encourage Claude Zero to ask clarifying questions:
|
||||
```
|
||||
"Interview me about requirements before drafting the plan.
|
||||
Ask about edge cases, success criteria, and constraints."
|
||||
```
|
||||
|
||||
**5. Review checklist**:
|
||||
When Claude Zero reviews Claude One's implementation:
|
||||
- [ ] Code matches plan structure?
|
||||
- [ ] All files from plan created/modified?
|
||||
- [ ] Tests cover success criteria?
|
||||
- [ ] Security best practices followed?
|
||||
- [ ] No TODO comments for core functionality?
|
||||
|
||||
#### Limitations
|
||||
|
||||
**When dual-instance doesn't help**:
|
||||
- **Trivial changes**: Typo fixes, simple refactors → 1 instance faster
|
||||
- **Exploratory coding**: Unknown problem space → planning overhead not justified
|
||||
- **Tight deadlines**: Speed > quality → use 1 instance, accept corrections
|
||||
- **Very limited budget**: <$100/month → use Sonnet, 1 instance
|
||||
|
||||
**Overhead**:
|
||||
- **Manual coordination**: You move plans between directories (no automation)
|
||||
- **Context switching**: Managing 2 terminal sessions
|
||||
- **Slower iteration**: Plan → approve → implement (vs immediate execution)
|
||||
|
||||
**Partial adoption**: You can use this pattern selectively:
|
||||
- Dual-instance for complex features
|
||||
- Single instance for simple tasks
|
||||
- No need to commit to one pattern exclusively
|
||||
|
||||
#### See Also
|
||||
|
||||
- **Workflow guide**: [dual-instance-planning.md](workflows/dual-instance-planning.md) — Full workflow with templates
|
||||
- **Plan Mode**: Section 9.1 "The Trinity" — Foundation for planning
|
||||
- **Multi-Instance (Boris)**: Section 9.17 — Horizontal scaling alternative
|
||||
- **Cost optimization**: Section 8.10 — Budget management strategies
|
||||
|
||||
**External resource**: [Jon Williams LinkedIn post](https://www.linkedin.com/posts/thatjonwilliams_ive-been-using-cursor-for-six-months-now-activity-7424481861802033153-k8bu) (Feb 3, 2026)
|
||||
|
||||
---
|
||||
|
||||
### Foundation: Git Worktrees (Non-Negotiable)
|
||||
|
||||
Multi-instance workflows **REQUIRE** git worktrees to avoid conflicts. Without worktrees, parallel instances create merge hell.
|
||||
|
|
|
|||
746
guide/workflows/dual-instance-planning.md
Normal file
746
guide/workflows/dual-instance-planning.md
Normal file
|
|
@ -0,0 +1,746 @@
|
|||
# Dual-Instance Planning Workflow
|
||||
|
||||
> **Confidence**: Tier 2 — Based on practitioner experience (Jon Williams, Feb 2026). Pattern validated through personal transition Cursor → Claude Code over 6 months.
|
||||
|
||||
Use two Claude instances with distinct roles: one for planning and review (Claude Zero), one for implementation (Claude One). Separation of concerns improves plan quality and reduces implementation errors.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [TL;DR](#tldr)
|
||||
2. [When to Use This Pattern](#when-to-use-this-pattern)
|
||||
3. [Setup](#setup)
|
||||
4. [Complete Workflow](#complete-workflow)
|
||||
5. [Plan Template](#plan-template)
|
||||
6. [Cost Analysis](#cost-analysis)
|
||||
7. [Tips and Troubleshooting](#tips-and-troubleshooting)
|
||||
8. [See Also](#see-also)
|
||||
|
||||
---
|
||||
|
||||
## TL;DR
|
||||
|
||||
```
|
||||
1. Launch Claude Zero (planner): explores, writes plans, reviews
|
||||
2. Launch Claude One (implementer): reads plans, codes, commits
|
||||
3. Human gatekeeper: approve plans before implementation
|
||||
4. Plans directory: Review/ → Active/ → Completed/
|
||||
5. Cost: ~$100-200/month (vs $500-1K for Boris horizontal pattern)
|
||||
```
|
||||
|
||||
**Best for**: Solo devs, spec-heavy work, quality > speed, budget <$300/month
|
||||
|
||||
---
|
||||
|
||||
## When to Use This Pattern
|
||||
|
||||
### ✅ Use When
|
||||
|
||||
- **Complex specifications**: Requirements need clarification through interview-style questions
|
||||
- **Quality-critical features**: Security, payments, data migrations
|
||||
- **Learning phase**: New codebase, unfamiliar patterns
|
||||
- **Product designers coding**: Non-dev background, need planning rigor
|
||||
- **Budget constraints**: $100-200/month (vs $500-1K for parallel multi-instance)
|
||||
- **Spec-heavy workflows**: Detailed requirements, many edge cases
|
||||
|
||||
### ❌ Don't Use When
|
||||
|
||||
- **Simple changes**: Typo fixes, trivial refactors (use single instance)
|
||||
- **Exploratory coding**: Problem space unknown (planning overhead not justified)
|
||||
- **Tight deadlines**: Speed > quality (accept correction loops)
|
||||
- **High-volume parallel features**: Use Boris pattern (Section 9.17) instead
|
||||
- **Very limited budget**: <$100/month (use Sonnet, single instance)
|
||||
|
||||
### Comparison to Other Patterns
|
||||
|
||||
| Pattern | Scaling Axis | Cost/Month | Best For |
|
||||
|---------|--------------|------------|----------|
|
||||
| **Single instance** | None | $50-100 | Most developers, general use |
|
||||
| **Dual-instance (Jon)** | Vertical (plan ↔ implement) | $100-200 | Spec-heavy, quality focus |
|
||||
| **Multi-instance (Boris)** | Horizontal (5-15 parallel) | $500-1,000 | Teams, high-volume shipping |
|
||||
|
||||
---
|
||||
|
||||
## Setup
|
||||
|
||||
### Step 1: Create Directory Structure
|
||||
|
||||
```bash
|
||||
cd ~/projects/your-project
|
||||
mkdir -p .claude/plans/{Review,Active,Completed}
|
||||
```
|
||||
|
||||
**Directory roles**:
|
||||
- `Review/` — Plans awaiting human approval
|
||||
- `Active/` — Approved plans under implementation
|
||||
- `Completed/` — Archived plans (learning resource)
|
||||
|
||||
**Add to .gitignore**:
|
||||
```bash
|
||||
# .gitignore
|
||||
.claude/plans/Review/
|
||||
.claude/plans/Active/
|
||||
# Optional: commit Completed/ for team learning
|
||||
```
|
||||
|
||||
### Step 2: Launch Claude Zero (Planner)
|
||||
|
||||
**Terminal 1**:
|
||||
```bash
|
||||
cd ~/projects/your-project
|
||||
claude
|
||||
```
|
||||
|
||||
**First message** (role enforcement):
|
||||
```
|
||||
You are Claude Zero (Planner).
|
||||
|
||||
Your role:
|
||||
- Explore codebase using /plan mode
|
||||
- Interview user about requirements
|
||||
- Write detailed plans to .claude/plans/Review/
|
||||
- Review implementations after Claude One completes them
|
||||
- NEVER edit code directly
|
||||
- NEVER commit changes
|
||||
|
||||
Start by acknowledging this role.
|
||||
```
|
||||
|
||||
Claude Zero confirms: "Understood. I am Claude Zero (Planner). I will explore, plan, and review, but never touch code."
|
||||
|
||||
### Step 3: Launch Claude One (Implementer)
|
||||
|
||||
**Terminal 2** (new session):
|
||||
```bash
|
||||
cd ~/projects/your-project
|
||||
claude
|
||||
```
|
||||
|
||||
**First message** (role enforcement):
|
||||
```
|
||||
You are Claude One (Implementer).
|
||||
|
||||
Your role:
|
||||
- Read approved plans from .claude/plans/Active/
|
||||
- Implement exactly as specified
|
||||
- Commit changes after each logical step
|
||||
- Report completion back to user
|
||||
- NEVER create plans
|
||||
- NEVER skip approval steps
|
||||
|
||||
Start by acknowledging this role.
|
||||
```
|
||||
|
||||
Claude One confirms: "Understood. I am Claude One (Implementer). I execute approved plans only."
|
||||
|
||||
---
|
||||
|
||||
## Complete Workflow
|
||||
|
||||
### Phase 1: Planning (Claude Zero)
|
||||
|
||||
#### Step 1.1: Initiate Planning
|
||||
|
||||
**You** (to Claude Zero):
|
||||
```
|
||||
/plan
|
||||
|
||||
Implement JWT authentication for the API:
|
||||
- Access tokens (15min expiry)
|
||||
- Refresh tokens (7 day expiry)
|
||||
- Middleware to protect routes
|
||||
- Logout capability (revoke refresh tokens)
|
||||
```
|
||||
|
||||
#### Step 1.2: Claude Zero Explores
|
||||
|
||||
Claude Zero (in `/plan` mode):
|
||||
- Reads existing auth code
|
||||
- Searches for auth patterns in codebase
|
||||
- Identifies dependencies (libraries, env vars)
|
||||
|
||||
#### Step 1.3: Claude Zero Interviews You
|
||||
|
||||
Claude Zero asks clarifying questions:
|
||||
```
|
||||
Before I draft the plan, I need to clarify:
|
||||
|
||||
1. Should we support multiple concurrent sessions per user?
|
||||
(e.g., user logged in on phone + laptop simultaneously)
|
||||
|
||||
2. Where should refresh tokens be stored?
|
||||
- Database table
|
||||
- Redis
|
||||
- Other
|
||||
|
||||
3. Which routes should be protected?
|
||||
- All /api/* routes?
|
||||
- Specific routes only?
|
||||
|
||||
4. Do you want rate limiting on login attempts?
|
||||
|
||||
5. Success criteria for "done"?
|
||||
- Tests passing?
|
||||
- Postman collection?
|
||||
- Documentation updated?
|
||||
```
|
||||
|
||||
**You answer**, Claude Zero refines understanding.
|
||||
|
||||
#### Step 1.4: Claude Zero Writes Plan
|
||||
|
||||
Claude Zero creates `.claude/plans/Review/auth-jwt.md`:
|
||||
|
||||
```markdown
|
||||
# Plan: JWT Authentication
|
||||
|
||||
**Created**: 2026-02-04
|
||||
**Author**: Claude Zero
|
||||
**Estimated effort**: 3-4 hours
|
||||
**Risk level**: Medium (security-critical)
|
||||
|
||||
## Summary
|
||||
Implement JWT-based authentication with access/refresh token pattern.
|
||||
Support multiple concurrent sessions per user.
|
||||
Refresh tokens stored in database with revocation capability.
|
||||
|
||||
## Requirements Clarified
|
||||
- Multiple sessions per user: YES
|
||||
- Refresh token storage: Database (new table)
|
||||
- Protected routes: All /api/* except /api/auth/*
|
||||
- Rate limiting: YES (5 attempts per 15min)
|
||||
- Success criteria: Tests pass + Postman collection
|
||||
|
||||
## Files to Create
|
||||
|
||||
### 1. src/auth/jwt.ts (~120 lines)
|
||||
**Purpose**: JWT utility functions
|
||||
|
||||
**Exports**:
|
||||
- `generateAccessToken(userId: string): string`
|
||||
- Payload: { userId, type: 'access' }
|
||||
- Expiry: 15 minutes
|
||||
- Sign with JWT_SECRET
|
||||
|
||||
- `generateRefreshToken(userId: string): string`
|
||||
- Payload: { userId, type: 'refresh', jti: uuid() }
|
||||
- Expiry: 7 days
|
||||
- Sign with JWT_REFRESH_SECRET
|
||||
- jti = unique token ID for revocation
|
||||
|
||||
- `verifyAccessToken(token: string): { userId: string } | null`
|
||||
- Verify signature
|
||||
- Check expiry
|
||||
- Return payload or null
|
||||
|
||||
- `verifyRefreshToken(token: string): { userId: string, jti: string } | null`
|
||||
- Verify signature
|
||||
- Check expiry
|
||||
- Check not revoked (database lookup)
|
||||
- Return payload or null
|
||||
|
||||
**Dependencies**: jsonwebtoken, uuid
|
||||
|
||||
### 2. src/middleware/auth.ts (~60 lines)
|
||||
**Purpose**: Authentication middleware
|
||||
|
||||
**Exports**:
|
||||
- `requireAuth(req, res, next)`
|
||||
- Extract token from Authorization header (Bearer format)
|
||||
- Verify using verifyAccessToken()
|
||||
- Attach userId to req.userId
|
||||
- 401 if invalid/missing
|
||||
|
||||
**Dependencies**: jwt.ts
|
||||
|
||||
### 3. src/db/migrations/YYYYMMDD_create_refresh_tokens.ts (~40 lines)
|
||||
**Purpose**: Database table for refresh tokens
|
||||
|
||||
**Schema**:
|
||||
```sql
|
||||
CREATE TABLE refresh_tokens (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||
jti UUID NOT NULL UNIQUE,
|
||||
created_at TIMESTAMP DEFAULT NOW(),
|
||||
expires_at TIMESTAMP NOT NULL,
|
||||
revoked_at TIMESTAMP
|
||||
);
|
||||
CREATE INDEX idx_refresh_tokens_user_id ON refresh_tokens(user_id);
|
||||
CREATE INDEX idx_refresh_tokens_jti ON refresh_tokens(jti);
|
||||
```
|
||||
|
||||
## Files to Modify
|
||||
|
||||
### 1. src/routes/api.ts
|
||||
**Location**: Line 23 (after imports)
|
||||
**Change**: Add requireAuth middleware to all routes except /auth/*
|
||||
|
||||
**Before**:
|
||||
```typescript
|
||||
router.get('/profile', profileController);
|
||||
router.post('/posts', createPostController);
|
||||
```
|
||||
|
||||
**After**:
|
||||
```typescript
|
||||
import { requireAuth } from '../middleware/auth';
|
||||
router.get('/profile', requireAuth, profileController);
|
||||
router.post('/posts', requireAuth, createPostController);
|
||||
```
|
||||
|
||||
### 2. src/routes/auth.ts
|
||||
**Location**: Create new file OR add to existing auth routes
|
||||
**Changes**:
|
||||
- POST /auth/login → return { accessToken, refreshToken }
|
||||
- POST /auth/refresh → exchange refresh token for new access token
|
||||
- POST /auth/logout → revoke refresh token
|
||||
|
||||
### 3. src/config/env.ts
|
||||
**Location**: Line 15 (after existing secrets)
|
||||
**Add**:
|
||||
```typescript
|
||||
JWT_SECRET: process.env.JWT_SECRET || '',
|
||||
JWT_REFRESH_SECRET: process.env.JWT_REFRESH_SECRET || '',
|
||||
```
|
||||
|
||||
### 4. .env.example
|
||||
**Add**:
|
||||
```
|
||||
JWT_SECRET=your-secret-here-min-32-chars
|
||||
JWT_REFRESH_SECRET=your-refresh-secret-here-min-32-chars
|
||||
```
|
||||
|
||||
## Implementation Steps (Sequential)
|
||||
|
||||
1. **Install dependencies**
|
||||
```bash
|
||||
npm install jsonwebtoken uuid
|
||||
npm install --save-dev @types/jsonwebtoken @types/uuid
|
||||
```
|
||||
|
||||
2. **Create JWT utilities** (jwt.ts)
|
||||
- Implement all 4 functions
|
||||
- Add error handling (try/catch on verify)
|
||||
|
||||
3. **Run database migration** (refresh_tokens table)
|
||||
- Test migration up/down
|
||||
|
||||
4. **Create auth middleware** (auth.ts)
|
||||
- Implement requireAuth
|
||||
- Test with mock token
|
||||
|
||||
5. **Create/update auth routes** (auth.ts routes)
|
||||
- POST /auth/login
|
||||
- POST /auth/refresh
|
||||
- POST /auth/logout
|
||||
|
||||
6. **Protect existing routes** (api.ts)
|
||||
- Apply requireAuth to all /api/* routes
|
||||
|
||||
7. **Add JWT secrets to .env**
|
||||
- Generate secure random strings (64 chars)
|
||||
|
||||
8. **Write tests**
|
||||
- Unit tests for jwt.ts functions
|
||||
- Integration tests for auth flow
|
||||
- Test token expiry
|
||||
- Test revocation
|
||||
|
||||
9. **Create Postman collection**
|
||||
- Login → get tokens
|
||||
- Access protected route with access token
|
||||
- Refresh access token
|
||||
- Logout → revoke refresh token
|
||||
- Verify revoked token rejected
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] POST /auth/login returns accessToken + refreshToken
|
||||
- [ ] Protected routes return 401 without valid access token
|
||||
- [ ] Protected routes return 200 with valid access token
|
||||
- [ ] POST /auth/refresh exchanges refresh token for new access token
|
||||
- [ ] POST /auth/logout revokes refresh token
|
||||
- [ ] Revoked refresh tokens are rejected on /auth/refresh
|
||||
- [ ] Expired access tokens are rejected
|
||||
- [ ] Multiple sessions per user work (different refresh tokens)
|
||||
- [ ] All tests pass (npm test)
|
||||
- [ ] Postman collection works end-to-end
|
||||
|
||||
## Security Checklist
|
||||
|
||||
- [ ] JWT secrets are in .env (never committed)
|
||||
- [ ] JWT secrets are ≥32 characters
|
||||
- [ ] Refresh tokens stored in database (not just JWT)
|
||||
- [ ] Refresh tokens have unique jti for revocation
|
||||
- [ ] Access tokens have short expiry (15min)
|
||||
- [ ] Authorization header validated (Bearer format)
|
||||
- [ ] Token verification errors are caught (no crashes)
|
||||
|
||||
## Risks & Mitigation
|
||||
|
||||
| Risk | Impact | Mitigation |
|
||||
|------|--------|------------|
|
||||
| JWT secrets leaked | High | .env in .gitignore, never log secrets |
|
||||
| Token expiry too long | Medium | 15min access, 7 day refresh (short enough) |
|
||||
| No rate limiting on login | Medium | Add rate limiting (5 attempts/15min) |
|
||||
| Refresh token table grows indefinitely | Low | Add cleanup job (delete expired tokens) |
|
||||
|
||||
## Questions for Implementer (Claude One)
|
||||
|
||||
If you encounter these scenarios during implementation:
|
||||
|
||||
1. **Existing user login flow**: Integrate with existing login logic, don't replace entire auth system
|
||||
2. **Database ORM**: Use existing ORM (Prisma/TypeORM/Knex) for refresh_tokens table
|
||||
3. **Error messages**: Return generic "Invalid token" (don't leak whether token is expired vs invalid signature)
|
||||
|
||||
## Estimated Effort Breakdown
|
||||
|
||||
- JWT utilities: 45 min
|
||||
- Database migration: 15 min
|
||||
- Middleware: 30 min
|
||||
- Auth routes: 60 min
|
||||
- Protect existing routes: 15 min
|
||||
- Tests: 90 min
|
||||
- Postman collection: 15 min
|
||||
|
||||
**Total**: ~4 hours
|
||||
|
||||
---
|
||||
|
||||
**Plan approved?** → Move to `.claude/plans/Active/auth-jwt.md`
|
||||
```
|
||||
|
||||
### Phase 2: Human Review
|
||||
|
||||
**You review** `.claude/plans/Review/auth-jwt.md`:
|
||||
|
||||
**Checklist**:
|
||||
- [ ] All requirements covered?
|
||||
- [ ] Approach makes sense for this codebase?
|
||||
- [ ] Security considerations addressed?
|
||||
- [ ] Estimated effort realistic?
|
||||
- [ ] Success criteria clear and testable?
|
||||
- [ ] Files to create/modify are correct paths?
|
||||
|
||||
**If approved**:
|
||||
```bash
|
||||
mv .claude/plans/Review/auth-jwt.md .claude/plans/Active/
|
||||
```
|
||||
|
||||
**If changes needed**, ask Claude Zero to revise:
|
||||
```
|
||||
(to Claude Zero): Update the plan:
|
||||
- Change refresh token expiry to 30 days instead of 7
|
||||
- Add password reset flow to scope
|
||||
```
|
||||
|
||||
### Phase 3: Implementation (Claude One)
|
||||
|
||||
**You** (to Claude One):
|
||||
```
|
||||
Implement .claude/plans/Active/auth-jwt.md
|
||||
|
||||
Follow the plan exactly. Commit after each logical step.
|
||||
Report back when complete.
|
||||
```
|
||||
|
||||
Claude One:
|
||||
1. Reads plan file
|
||||
2. Installs dependencies
|
||||
3. Creates jwt.ts
|
||||
4. Creates database migration
|
||||
5. Runs migration
|
||||
6. Creates auth middleware
|
||||
7. Updates routes
|
||||
8. Adds env vars
|
||||
9. Writes tests
|
||||
10. Creates Postman collection
|
||||
|
||||
**Claude One commits** after each step:
|
||||
```
|
||||
feat: add JWT utility functions
|
||||
feat: create refresh_tokens table migration
|
||||
feat: add auth middleware
|
||||
feat: protect API routes with JWT auth
|
||||
test: add JWT auth flow tests
|
||||
```
|
||||
|
||||
### Phase 4: Verification (Claude Zero)
|
||||
|
||||
**You** (to Claude Zero):
|
||||
```
|
||||
Review the JWT implementation Claude One just completed.
|
||||
Check against the plan in .claude/plans/Active/auth-jwt.md.
|
||||
```
|
||||
|
||||
Claude Zero reviews:
|
||||
- Code structure matches plan?
|
||||
- All success criteria met?
|
||||
- Security checklist completed?
|
||||
- Tests passing?
|
||||
- Any code smells or issues?
|
||||
|
||||
**Claude Zero report**:
|
||||
```
|
||||
✅ Review complete: auth-jwt.md
|
||||
|
||||
Code Quality: 9/10
|
||||
- All files created as planned
|
||||
- Success criteria met (9/9)
|
||||
- Security checklist complete
|
||||
- Tests pass (15/15)
|
||||
|
||||
Minor suggestions:
|
||||
1. Consider adding refresh token rotation (security best practice)
|
||||
2. Add JSDoc comments to jwt.ts functions
|
||||
3. Consider extracting magic numbers (15min, 7 days) to config
|
||||
|
||||
Critical issues: None
|
||||
|
||||
Ready to archive plan to Completed/.
|
||||
```
|
||||
|
||||
### Phase 5: Archive
|
||||
|
||||
**If approved**:
|
||||
```bash
|
||||
mv .claude/plans/Active/auth-jwt.md .claude/plans/Completed/
|
||||
```
|
||||
|
||||
**Plan is now archived** for future reference and team learning.
|
||||
|
||||
---
|
||||
|
||||
## Plan Template
|
||||
|
||||
Save this template to `.claude/plan-template.md` for consistent plan structure:
|
||||
|
||||
```markdown
|
||||
# Plan: [Feature Name]
|
||||
|
||||
**Created**: [Date]
|
||||
**Author**: Claude Zero
|
||||
**Estimated effort**: [Hours]
|
||||
**Risk level**: Low | Medium | High
|
||||
|
||||
## Summary
|
||||
[2-3 sentence overview of what this plan accomplishes]
|
||||
|
||||
## Requirements Clarified
|
||||
[List of requirements confirmed through interview]
|
||||
- Requirement 1: [Answer]
|
||||
- Requirement 2: [Answer]
|
||||
|
||||
## Files to Create
|
||||
|
||||
### 1. [File path] (~[Lines] lines)
|
||||
**Purpose**: [What this file does]
|
||||
|
||||
**Exports**:
|
||||
- `functionName(params): returnType`
|
||||
- [What it does]
|
||||
- [Key implementation details]
|
||||
|
||||
**Dependencies**: [Libraries, other files]
|
||||
|
||||
## Files to Modify
|
||||
|
||||
### 1. [File path]
|
||||
**Location**: Line [N] ([Context: after what, before what])
|
||||
**Change**: [What to change]
|
||||
|
||||
**Before**:
|
||||
```[language]
|
||||
[Existing code snippet]
|
||||
```
|
||||
|
||||
**After**:
|
||||
```[language]
|
||||
[Modified code snippet]
|
||||
```
|
||||
|
||||
## Implementation Steps (Sequential)
|
||||
|
||||
1. **[Step name]**
|
||||
- [Substep]
|
||||
- [Substep]
|
||||
|
||||
2. **[Step name]**
|
||||
- [Substep]
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] [Testable criterion 1]
|
||||
- [ ] [Testable criterion 2]
|
||||
|
||||
## Security Checklist (if applicable)
|
||||
|
||||
- [ ] [Security item 1]
|
||||
- [ ] [Security item 2]
|
||||
|
||||
## Risks & Mitigation
|
||||
|
||||
| Risk | Impact | Mitigation |
|
||||
|------|--------|------------|
|
||||
| [Risk] | [High/Med/Low] | [How to prevent/handle] |
|
||||
|
||||
## Questions for Implementer (Claude One)
|
||||
|
||||
If you encounter these scenarios during implementation:
|
||||
1. [Scenario]: [Guidance]
|
||||
|
||||
## Estimated Effort Breakdown
|
||||
|
||||
- [Task 1]: [Time]
|
||||
- [Task 2]: [Time]
|
||||
|
||||
**Total**: [Hours]
|
||||
|
||||
---
|
||||
|
||||
**Plan approved?** → Move to `.claude/plans/Active/[filename].md`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cost Analysis
|
||||
|
||||
### Dual-Instance vs Single Instance with Corrections
|
||||
|
||||
| Scenario | Single Instance | Dual Instance | Savings |
|
||||
|----------|----------------|---------------|---------|
|
||||
| **Simple feature** (login form) | 1 session × $5 = **$5** | 2 sessions × $3 = $6 | +$1 (single wins) |
|
||||
| **Medium feature** (auth system) | 1 session × $15 + 2 corrections × $10 = **$35** | 2 sessions × $12 = $24 | **$11 saved** |
|
||||
| **Complex feature** (ambiguous spec) | 1 session × $20 + 3 corrections × $15 = **$65** | 2 sessions × $18 = $36 | **$29 saved** |
|
||||
|
||||
**Breakeven point**: Features requiring ≥2 correction loops → dual-instance is cheaper.
|
||||
|
||||
### Monthly Budget Estimates
|
||||
|
||||
**Assumptions**:
|
||||
- 20 working days/month
|
||||
- 2 features per day (mix of simple + complex)
|
||||
- Opus 4.5 pricing (~$15/1M input, $75/1M output)
|
||||
|
||||
| Profile | Features/Month | Single Instance | Dual Instance | Savings |
|
||||
|---------|----------------|----------------|---------------|---------|
|
||||
| **Light user** | 20 simple | $100 | $120 | -$20 (single wins) |
|
||||
| **Moderate user** | 30 mixed (60% medium, 40% simple) | $650 | $480 | **$170 saved** |
|
||||
| **Heavy user** | 40 complex | $2,000 | $1,200 | **$800 saved** |
|
||||
|
||||
**Recommendation**:
|
||||
- Simple features only → Single instance
|
||||
- Medium/complex features → Dual instance saves money and time
|
||||
|
||||
---
|
||||
|
||||
## Tips and Troubleshooting
|
||||
|
||||
### Role Enforcement
|
||||
|
||||
**Problem**: Claude Zero starts editing code.
|
||||
|
||||
**Solution**: Remind in every request:
|
||||
```
|
||||
(to Claude Zero): Remember: you are Claude Zero (Planner only).
|
||||
Do not edit code. Write plan to .claude/plans/Review/
|
||||
```
|
||||
|
||||
**Prevention**: Use CLAUDE.md to enforce roles:
|
||||
|
||||
```markdown
|
||||
# .claude/CLAUDE.md
|
||||
|
||||
## If you are Claude Zero (Planner):
|
||||
- Use /plan mode for all exploration
|
||||
- Save all plans to .claude/plans/Review/[feature].md
|
||||
- NEVER edit code
|
||||
- NEVER commit changes
|
||||
- Review implementations after Claude One completes them
|
||||
|
||||
## If you are Claude One (Implementer):
|
||||
- Read plans from .claude/plans/Active/
|
||||
- Implement exactly as specified
|
||||
- Commit after each logical step
|
||||
- NEVER create plans
|
||||
```
|
||||
|
||||
### Context Pollution
|
||||
|
||||
**Problem**: Claude One's context is polluted with planning discussions.
|
||||
|
||||
**Solution**: Use separate terminal sessions (separate contexts):
|
||||
- Terminal 1 = Claude Zero (planning context)
|
||||
- Terminal 2 = Claude One (implementation context)
|
||||
|
||||
**Never share context** between Claude Zero and Claude One.
|
||||
|
||||
### Plan Drift
|
||||
|
||||
**Problem**: Claude One deviates from plan during implementation.
|
||||
|
||||
**Solution**: Include this in plan:
|
||||
```markdown
|
||||
## Implementation Rules for Claude One
|
||||
|
||||
- Follow plan steps sequentially (don't skip or reorder)
|
||||
- If you encounter blockers, STOP and report (don't improvise)
|
||||
- Commit after each step (granular history)
|
||||
- If unclear, ask user (don't guess)
|
||||
```
|
||||
|
||||
### Overhead Management
|
||||
|
||||
**Problem**: Moving files between directories is manual overhead.
|
||||
|
||||
**Solution**: Create bash aliases:
|
||||
|
||||
```bash
|
||||
# Add to ~/.bashrc or ~/.zshrc
|
||||
|
||||
# Move plan to Active (approve)
|
||||
approve-plan() {
|
||||
mv ".claude/plans/Review/$1.md" ".claude/plans/Active/"
|
||||
echo "✅ Approved: $1.md → Active/"
|
||||
}
|
||||
|
||||
# Move plan to Completed (archive)
|
||||
complete-plan() {
|
||||
mv ".claude/plans/Active/$1.md" ".claude/plans/Completed/"
|
||||
echo "✅ Completed: $1.md → Archived"
|
||||
}
|
||||
|
||||
# List plans by status
|
||||
plans() {
|
||||
echo "📋 Review:"
|
||||
ls -1 .claude/plans/Review/ 2>/dev/null || echo " (empty)"
|
||||
echo ""
|
||||
echo "🔄 Active:"
|
||||
ls -1 .claude/plans/Active/ 2>/dev/null || echo " (empty)"
|
||||
echo ""
|
||||
echo "✅ Completed:"
|
||||
ls -1 .claude/plans/Completed/ 2>/dev/null | tail -5 || echo " (empty)"
|
||||
}
|
||||
```
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
plans # List all plans
|
||||
approve-plan auth-jwt # Approve plan
|
||||
complete-plan auth-jwt # Archive completed plan
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- **Main guide**: [Section 9.17.1](../ultimate-guide.md#alternative-pattern-dual-instance-planning-vertical-separation) — Overview and comparison
|
||||
- **Plan Mode**: [plan-driven.md](plan-driven.md) — Foundation for planning workflows
|
||||
- **Multi-Instance (Boris)**: [Section 9.17](../ultimate-guide.md#917-scaling-patterns-multi-instance-workflows) — Horizontal scaling alternative
|
||||
- **Cost optimization**: [Section 8.10](../ultimate-guide.md#810-cost-optimization) — Budget management
|
||||
|
||||
**External resources**:
|
||||
- [Jon Williams LinkedIn post](https://www.linkedin.com/posts/thatjonwilliams_ive-been-using-cursor-for-six-months-now-activity-7424481861802033153-k8bu) — Original pattern description (Feb 3, 2026)
|
||||
- [10 Tips from Claude Code Team](https://paddo.dev/blog/claude-code-team-tips/) — Team workflows including plan-first approach
|
||||
|
|
@ -250,3 +250,4 @@ Plans in `.claude/plans/` serve as decision documentation:
|
|||
- [spec-first.md](./spec-first.md) — Combine with Spec-First
|
||||
- [iterative-refinement.md](./iterative-refinement.md) — Post-plan iteration
|
||||
- [task-management.md](./task-management.md) — Track plan execution across sessions with Tasks API
|
||||
- [dual-instance-planning.md](./dual-instance-planning.md) — Advanced: Use two Claude instances (planner + implementer) for quality-focused workflows
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue