Workflow: Plan Approval Flow

Type: Implementation | Complexity: Medium-High | Team Size: 1-3 teammates

High-Risk Tasks

For complex or risky work, require teammates to create and submit implementation plans before coding begins. Lead reviews and approves, rejects with feedback, or requests modifications.

When to Use

• Database migrations - High risk, hard to undo
• Authentication/security changes - Impact is critical
• Infrastructure refactoring - Affects all services
• Performance optimizations - Need to avoid regressions
• High-stakes business logic - Errors are costly

When NOT to Use

• Simple bug fixes
• Low-risk features
• Routine maintenance
• When speed is critical and plan review would delay

How It Works

Step-by-Step Guide

Step 1: Spawn Teammate with Plan Approval

Create an agent team with 1 teammate to refactor the authentication module.
REQUIRE PLAN APPROVAL before they make any changes.
Teammate should submit their implementation plan first.
Lead will review and approve before they proceed with coding.

Claude will:

1. Spawn teammate in planning mode (read-only)
2. Teammate cannot edit files yet
3. Teammate must create plan first
4. Plan is submitted to lead

Step 2: Teammate Creates Plan

Teammate will analyze work and create detailed plan:

Plan for Authentication Module Refactoring:

1. Analysis Phase
   - Audit current JWT implementation
   - Identify technical debt
   - Map dependencies

2. Design Phase
   - Propose new token structure
   - Design refresh strategy
   - Plan migration from old to new

3. Implementation Phase
   - Update token generation
   - Update validation logic
   - Update refresh endpoint
   - Add new tests

4. Verification Phase
   - Test with existing tokens
   - Test token refresh
   - Performance check
   - Security audit

5. Rollback Plan
   - Keep old validation working
   - Gradual migration strategy
   - Revert command if needed

Step 3: Lead Reviews Plan

Plan appears in lead's session:

Teammate has submitted a plan for review. Approve or request changes.

Lead reviews:

• ✓ Does it make sense?
• ✓ Does it address all concerns?
• ✓ Are edge cases covered?
• ✓ Is there a rollback strategy?
• ✓ Are tests planned?

Step 4: Lead Approves or Provides Feedback

Option A: Approve

Approve the plan. Proceed with implementation.

Teammate transitions from planning to implementation mode and can now edit files.

Option B: Request Changes

Request changes to the plan:
1. Need explicit rollback procedure - what if we need to revert?
2. Performance testing section is missing
3. How will we handle existing tokens?

Please revise and resubmit.

Teammate:

1. Receives feedback
2. Revises plan
3. Resubmits for approval
4. Loop continues until approved

Option C: Reject and Redirect

I'd like a different approach. Instead of gradual migration,
let's do an atomic cutover with versioning. Please redesign
the plan with this strategy and resubmit.

Teammate redesigns from scratch with new direction.

Step 5: Implementation Begins

Once approved, teammate can:

• Create/edit files
• Write tests
• Make commits
• Run verification

Lead can monitor:

Show me the current implementation progress

Step 6: Verification

After implementation:

Verify that implementation matches the approved plan

Check:

• All steps from plan completed
• Tests written
• Edge cases handled
• Performance acceptable
• Rollback procedure documented

Step 7: Sign Off

Implementation complete and verified. Ready to merge.

Real-World Example

Scenario: Database Migration

Task: Migrate from single-tenant to multi-tenant database schema.

Teammate's Initial Plan:

# Database Migration Plan: Single to Multi-Tenant

## Current State
- Single table: users (user_id, name, email, ...)
- Single DB: everything together

## Proposed State
- New table: organizations (org_id, name, ...)
- New table: org_members (org_id, user_id, role)
- Migrate users → org_members
- Add org_id foreign key to all tables

## Implementation Steps
1. Create new schema in migration file
2. Run migration to prod
3. Update app code to use org_id
4. Remove old schema

## Rollback
Drop new tables, revert code

## Concerns
- Downtime during migration
- Data consistency
- User experience

Lead's Feedback:

Plan needs major revisions:

1. CRITICAL: You're planning downtime. This needs zero-downtime migration.
   Strategy: Keep old schema, add new schema in parallel, gradual cutover

2. Rollback is too simple. We need:
   - Ability to fallback from new schema to old mid-migration
   - Data validation between schemas
   - Rollback doesn't mean data loss

3. Data consistency: What happens to requests during migration?
   Plan for dual-write period?

4. Testing: No testing strategy for millions of records.
   Need load test plan.

5. Timing: Can you do this during low-traffic window?
   Document the window and monitoring strategy.

Please revise with zero-downtime approach and resubmit.

Teammate's Revised Plan:

# Database Migration Plan v2: Zero-Downtime Approach

## Phase 0: Setup (Low Traffic Window)
- Create new schema tables in parallel
- Deploy dual-write code (writes to both schemas)

## Phase 1: Backfill
- Migrate existing data in small batches
- Validate data consistency
- Monitor performance

## Phase 2: Gradual Cutover
- Redirect reads to new schema (5% → 25% → 50% → 100%)
- Monitor for inconsistencies
- Have instant rollback ready

## Phase 3: Cleanup
- Once 100% on new schema for 24 hours
- Mark old schema for deprecation
- Remove old schema after 1 week retention

## Rollback at Any Point
- Switch reads back to old schema
- Disable dual-write
- No data loss
- Instant recovery

## Testing
- Load test: 10M record migration in staging
- Consistency check: Compare old/new schema during phase 1
- Performance test: Query latency before/after

## Monitoring
- Real-time alerts for schema divergence
- Query latency tracking
- Error rate monitoring
- Rollback trigger: If errors exceed 0.1%, auto-rollback

Lead's Approval:

Much better! This addresses the critical concerns.

Approve with minor notes:
- Document monitoring dashboard before starting
- Have quick communication plan if issues arise
- Consider backing up database before phase 0

Proceed with implementation.

Teammate Implements:

1. Creates migration scripts
2. Writes data validation code
3. Sets up monitoring
4. Implements dual-write logic
5. Tests thoroughly
6. Ready to execute

Plan Quality Criteria

What Makes a Good Plan

✓ Comprehensive

• Covers all phases
• Identifies risks
• Has rollback strategy

✓ Realistic

• Achievable in stated time
• Considers real constraints
• Has contingencies

✓ Testable

• Can verify each step
• Has clear success criteria
• Includes verification steps

✓ Reversible

• Can undo if needed
• Doesn't burn bridges
• Has fallback options

What to Reject

✗ Too vague

"Update authentication code"
(Need specific steps)

✗ No rollback

"Delete old table, replace with new"
(What if data is corrupted?)

✗ Missing edge cases

"Migrate user data"
(What about admins? Service accounts? Archived users?)

✗ No testing strategy

"Deploy to production"
(Without staging verification first)

Approval Criteria Checklist

Lead should verify plan includes:

• ✓ Clear phases/stages
• ✓ Success criteria for each phase
• ✓ Risk identification
• ✓ Rollback procedure
• ✓ Testing strategy
• ✓ Monitoring/observability
• ✓ Communication plan
• ✓ Edge case handling
• ✓ Performance impact analysis
• ✓ Timing/scheduling considerations

Mark as approved only if most are present.

Variations

Plan Approval for Multiple Teammates

Spawn 3 teammates to refactor different modules.
Each must submit plan for approval before implementation.

Lead reviews all 3 plans, approves, requests changes, or redirects.

Partial Approval

Approve phases 1-2. Resubmit plan for phases 3-4 after phase 2 verification.

Good for long projects - verify early phases work before committing to later ones.

Criteria-Based Approval

Tell lead approval criteria:

Only approve plans that:
1. Include zero-downtime migration strategy
2. Have rollback tested in staging
3. Include performance benchmarks
4. Pass security review

Lead uses these criteria to evaluate.

Troubleshooting

Q: Plan rejection causes frustration A:

1. Be constructive: "Great start! Here's what's missing..."
2. Provide direction: "Consider approaching like [example]"
3. Allow revision: "Take time to revise and resubmit"

Q: Teammate keeps resubmitting same plan A:

1. Get more specific feedback
2. Show example of what you need
3. Consider pairing: "Let's discuss the approach together"

Q: Plan approval slowing us down A:

1. This is the point - catch issues early
2. Plan time < fix time usually
3. Can approve quickly for low-risk work

Q: What if plan is rejected multiple times? A:

1. Consider different approach
2. Or direct teammate: "Implement according to [specific design]"
3. Sometimes discussion is better than iteration

Performance Impact

Plan approval adds overhead but saves rework:

Metric	No Plan Approval	With Plan Approval
Plan time	0 min	20-40 min
Implementation	3 hours	3 hours
Rework	2 hours	0-30 min
Total	5 hours	3.5-4.5 hours
Risk	High	Low

Plan approval typically saves time and reduces risk for complex work.

See Also

• SOP-004: Spawn and Manage Teammates
• Parallel Code Review Workflow
• Delegate Mode Workflow