name	plan-approval
description	Plan-approval workflow patterns for user control over AI actions in Claude Code Waypoint Plugin. Use when planning complex changes, need user approval before execution, want to prevent mistakes, or need to document proposed changes. Covers plan creation, approval checkpoints, plan deviation tracking, revision management, and learning from approved/rejected plans.

Plan-Approval Skill

Purpose

Enable user control over AI actions by requiring explicit approval for complex or risky changes, preventing mistakes and ensuring alignment with user intent.

When to Use This Skill

Automatically activates when you mention:

Creating or reviewing plans
Approval or confirmation needed
Proposed changes or approach
Want to see plan before execution
Complex or risky operations
Need user sign-off

The Problem: No User Control

Without plan approval:

❌ AI jumps straight to implementation
❌ No chance to review approach
❌ Mistakes expensive to undo
❌ User left out of decision process
❌ No learning from rejections

With plan approval:

✅ User reviews before execution
✅ Can modify or reject approach
✅ Prevents costly mistakes
✅ User maintains control
✅ AI learns from feedback

Core Principles

1. User is Always in Control

Never execute without approval for:

Database schema changes
Breaking API changes
Dependency updates
Architecture refactors
File deletions
Deployment actions

2. Plans are Detailed

Good plans include:

What will be done (specific files/changes)
Why this approach (rationale)
What alternatives were considered
What risks exist
What the impact is
How long it will take

3. Approval is Explicit

Require clear user response:

✅ "approve", "yes", "proceed", "looks good"
❌ Silence, vague response, "maybe"
⚠️ "modify: [changes]" triggers plan revision

4. Learning from Feedback

Track approved/rejected plans:

Store approved approaches (do more like this)
Store rejected approaches (avoid in future)
Learn user preferences over time

When to Require Approval

Always Require Approval

✅ Database changes:

Schema migrations
RLS policy changes
Data migrations
Index additions

✅ Breaking changes:

API signature changes
Function signature changes
Component prop changes

✅ Architecture changes:

New dependencies
Framework changes
State management approach
Routing structure

✅ Risky operations:

File deletions
Bulk updates
Production deployments

Optional Approval

⚠️ Complex features (> 5 files affected) ⚠️ Refactoring (multiple components) ⚠️ Performance optimization (cache strategies)

No Approval Needed

❌ Simple changes:

Bug fixes (< 10 lines)
Documentation updates
Code formatting
Minor UI tweaks

Rule of Thumb: If user might say "wait, not like that!", require approval.

Plan Structure

Minimal Plan Template

# [Feature/Change Name]

## Summary
[1-2 sentence overview]

## What Will Change
- File 1: [what changes]
- File 2: [what changes]
- Database: [migrations if any]
- Dependencies: [new packages if any]

## Why This Approach
[Rationale for chosen approach]

## Risks
- Risk 1: [description + mitigation]
- Risk 2: [description + mitigation]

## Estimated Time
[How long to implement]

---
**Approve to proceed**, or reply with modifications

Comprehensive Plan Template

# [Feature/Change Name]

## Summary
[2-3 sentence overview of the change and its purpose]

## Requirements
- [ ] Requirement 1
- [ ] Requirement 2
- [ ] Requirement 3

## Proposed Approach

### Architecture
[High-level architecture description]

### Implementation Steps
1. **Step 1**: [Description]
   - Files: [list]
   - Changes: [brief description]
   - Risk: [if any]

2. **Step 2**: [Description]
   - Files: [list]
   - Changes: [brief description]
   - Risk: [if any]

[Continue for all steps...]

### Files to Create (3)
1. `path/to/file1.ts` - [Purpose]
2. `path/to/file2.ts` - [Purpose]
3. `path/to/file3.ts` - [Purpose]

### Files to Modify (2)
1. `path/to/existing1.ts` - [What will change]
2. `path/to/existing2.ts` - [What will change]

### Database Changes
**Migration**: `supabase/migrations/xxx_add_feature.sql`
- Add table: `feature_table`
- Add column: `users.feature_flag`
- Add RLS policy: `feature_access_policy`

### Dependencies
**New**:
- package-name@^1.0.0 (Purpose: [why])

**Updates**:
- existing-package: 1.0.0 → 2.0.0 (Reason: [why])

## Alternatives Considered

### Alternative 1: [Name]
**Approach**: [Description]
**Pros**: [Benefits]
**Cons**: [Drawbacks]
**Why not chosen**: [Reason]

### Alternative 2: [Name]
**Approach**: [Description]
**Pros**: [Benefits]
**Cons**: [Drawbacks]
**Why not chosen**: [Reason]

## Risks & Mitigations

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| [Risk 1] | Medium | High | [How to prevent/handle] |
| [Risk 2] | Low | Medium | [How to prevent/handle] |

## Breaking Changes

⚠️ **API Changes**:
- `oldFunction()` → `newFunction()` signature changed
- Migration path: [How to update]

⚠️ **Database Changes**:
- Table `old_name` renamed to `new_name`
- Migration script: [Path]

## Testing Strategy
- [ ] Unit tests for [components]
- [ ] Integration tests for [flows]
- [ ] Manual testing: [scenarios]

## Rollback Plan
If this fails:
1. [Step to revert]
2. [Step to restore]
3. [Data recovery if needed]

## Estimated Time
- Implementation: [X hours]
- Testing: [Y hours]
- **Total**: [Z hours]

---

## Approval

**Reply with**:
- `approve` - Proceed with this plan
- `reject` - Cancel, don't proceed
- `modify: [your changes]` - Adjust plan first

Approval Workflow

Step 1: Generate Plan

User: "Add Stripe payment integration"

Claude:
"I'll create a plan for Stripe integration first.

[Generates detailed plan using template]

Review the plan above. Reply:
- 'approve' to proceed
- 'reject' to cancel
- 'modify: [changes]' to adjust
"

Step 2: Wait for Explicit Approval

Valid approvals:

"approve"
"yes, proceed"
"looks good"
"go ahead"
"lgtm" (looks good to me)

Modifications:

"modify: use Stripe Checkout instead of Elements"
"change: store payment methods in Supabase"
"add: webhook handling"

Rejections:

"reject"
"no"
"cancel"
"let's do something different"

Step 3: Execute or Revise

If approved:

Save plan to .claude/memory/plans/approved/
Execute implementation
Track progress in dev docs
Mark complete when done

If modified:

Update plan with user's changes
Re-present revised plan
Wait for approval again

If rejected:

Save to .claude/memory/plans/rejected/ with reason
Learn from rejection
Don't proceed

Step 4: Track Execution

## Plan Execution Status

**Plan ID**: stripe-integration-2025-01-15
**Status**: In Progress
**Approved**: 2025-01-15 10:00
**Started**: 2025-01-15 10:05

**Progress**:
- [x] Step 1: Install Stripe SDK
- [x] Step 2: Create Stripe client
- [ ] Step 3: Implement checkout flow (IN PROGRESS)
- [ ] Step 4: Add webhook handler
- [ ] Step 5: Test payment flow

**Current**: Implementing checkout flow in app/api/checkout/route.ts
**Next**: Add webhook handler for payment events

Plan Storage

Directory Structure

.claude/memory/plans/
├── proposed/                    # Plans awaiting approval
│   └── stripe-integration-2025-01-15.json
├── approved/                   # Approved plans
│   └── stripe-integration-2025-01-15.json
├── rejected/                   # Rejected plans (learn from these)
│   └── alternative-approach-2025-01-14.json
└── completed/                  # Completed implementations
    └── stripe-integration-2025-01-15.json

Plan File Schema

{
  "plan_id": "stripe-integration-2025-01-15",
  "created": "2025-01-15T10:00:00Z",
  "status": "approved" | "proposed" | "rejected" | "in_progress" | "completed",
  "summary": "Add Stripe payment integration for subscriptions",
  "approved_at": "2025-01-15T10:05:00Z",
  "started_at": "2025-01-15T10:10:00Z",
  "completed_at": null,
  "user_modifications": [
    "Use Stripe Checkout instead of Elements",
    "Store payment methods in Supabase"
  ],
  "files_to_create": [
    "lib/stripe/client.ts",
    "app/api/checkout/route.ts"
  ],
  "files_to_modify": [
    "package.json",
    "lib/supabase/schema.sql"
  ],
  "risks": [
    "Webhook reliability",
    "Payment state synchronization"
  ],
  "estimated_hours": 4,
  "actual_hours": null,
  "outcome": null,
  "lessons_learned": []
}

Learning from Plans

Track Approval Patterns

{
  "approval_patterns": {
    "stripe_payments": {
      "preferred_approach": "Stripe Checkout (not Elements)",
      "storage": "Supabase tables",
      "reason": "User approved this twice, rejected Elements once",
      "confidence": "high"
    },
    "database_changes": {
      "requires_approval": true,
      "wants_rollback_plan": true,
      "prefers_separate_migration_file": true,
      "confidence": "high"
    }
  }
}

Apply Learnings

Future similar requests:

User: "Add subscription billing"

Claude:
"Based on previous approvals, I'll plan to use:
- Stripe Checkout (you preferred this over Elements)
- Supabase tables for subscription state
- Separate webhook handler

[Presents plan following learned preferences]

Track Rejections

{
  "rejections": [
    {
      "plan_id": "complex-state-management-2025-01-10",
      "reason": "Too complex, prefer simpler approach",
      "rejected_approach": "Redux Toolkit",
      "preferred_instead": "React Context",
      "lesson": "User prefers simpler solutions when possible"
    }
  ]
}

Plan Deviations

When Implementation Differs from Plan

Acceptable deviations:

Minor implementation details
Better solution discovered
Library API changed

Require new approval:

Different architecture approach
More files affected than planned
Additional dependencies
Higher risk than estimated

Handling Deviations

User: "Continue with Stripe integration"

Claude:
"⚠️ PLAN DEVIATION DETECTED

**Original plan**: Use Stripe Elements
**Current need**: Stripe Checkout is better for our use case

**Reason**: Elements requires more frontend work, Checkout is simpler

**Impact**:
- Different files affected
- Simpler implementation
- Less custom UI needed

**Do you approve this deviation?**
- 'yes' - Proceed with Checkout
- 'no' - Stick to original plan
- 'revise' - Create new plan
"

Commands

Provide these commands:

# Create plan
/create-plan [feature-name]       # Generate plan for approval

# Review plans
/show-plans                       # Show all plans
/show-plan [plan-id]              # Show specific plan

# Approve/reject
/approve [plan-id]                # Approve a plan
/reject [plan-id]                 # Reject a plan

# Track progress
/plan-status [plan-id]            # Show execution progress

# History
/approved-plans                   # Show approved plans
/rejected-plans                   # Show rejected (learn from these)

Integration with Other Skills

With memory-management

memory-management stores long-term preferences. plan-approval handles one-time decisions.

Example:

Memory: "User always prefers TypeScript" (permanent)
Plan: "Use Stripe Checkout for payments" (this feature)

With context-persistence

context-persistence tracks implementation progress. plan-approval handles pre-implementation planning.

Workflow:

Plan approval: Generate and approve plan
Context persistence: Track implementation in dev docs
Memory: Store outcome and learnings

Best Practices

DO ✅

Present clear, detailed plans
Wait for explicit approval
Track plan execution progress
Learn from approvals and rejections
Notify user of deviations
Store plans for future reference
Include rollback strategy for risky changes

DON'T ❌

Don't skip approval for complex changes
Don't assume silence means approval
Don't deviate significantly without asking
Don't forget to track approved plans
Don't make plans too vague
Don't proceed if user is uncertain

Example: Complete Plan-Approval Flow

User Request

User: "Add Stripe subscription billing to the app"

Plan Generation

Claude: "I'll create a detailed plan for Stripe subscriptions.

# Stripe Subscription Billing Plan

## Summary
Add Stripe subscription billing with monthly/yearly plans, customer portal, and webhook handling.

## What Will Change

### Files to Create (5)
1. `lib/stripe/client.ts` - Stripe client initialization
2. `lib/stripe/subscriptions.ts` - Subscription management
3. `app/api/stripe/webhook/route.ts` - Webhook handler
4. `app/api/checkout/route.ts` - Checkout session creation
5. `app/pricing/page.tsx` - Pricing page

### Files to Modify (3)
1. `package.json` - Add stripe package
2. `.env.example` - Add Stripe keys
3. `lib/supabase/schema.sql` - Add subscriptions table

### Database Changes
**Migration**: `supabase/migrations/20250115_subscriptions.sql`
- Table: `subscriptions` (user_id, stripe_subscription_id, status, plan_id)
- Table: `subscription_plans` (name, price, interval)
- RLS policies for subscription access

## Why This Approach
- Stripe Checkout: Hosted, PCI-compliant, less frontend work
- Webhooks: Reliable payment event handling
- Supabase storage: Sync subscription state with user data

## Alternatives Considered
- **Stripe Elements**: More control but more work. Rejected: Overkill for MVP
- **Manual billing**: Can't scale. Rejected: Need automation

## Risks
- ⚠️ Webhook reliability: Mitigate with retry logic + monitoring
- ⚠️ State sync: Mitigate with idempotent webhook handlers

## Estimated Time
- Implementation: 3 hours
- Testing: 1 hour
- **Total**: 4 hours

---

**Do you approve this plan?**
Reply: 'approve', 'modify: [changes]', or 'reject'

User Approval

User: "approve"

Execution

Claude: "✅ Plan approved. Starting implementation.

Saving plan to: .claude/memory/plans/approved/stripe-subscriptions-2025-01-15.json

Creating dev docs: /create-plan stripe-subscriptions

Starting with Step 1: Install Stripe SDK..."

[Proceeds with implementation while tracking progress]

Completion

Claude: "✅ Stripe subscription billing complete!

**Completed**:
- ✅ All 5 files created
- ✅ Database migration applied
- ✅ Webhooks tested with Stripe CLI
- ✅ Checkout flow working

**Time**: 3.5 hours (30 min under estimate)

Marking plan as completed.
Storing lessons learned:
- Stripe Checkout works well for subscriptions
- Webhook testing critical (caught 2 bugs)

Summary

Plan-approval workflow enables:

✅ User control over AI actions
✅ Prevention of costly mistakes
�� Clear communication of approach
✅ Learning from user feedback
✅ Transparent decision making

Key steps:

Generate detailed plan
Wait for explicit approval
Execute or revise based on feedback
Track progress
Learn from outcome

Storage: .claude/memory/plans/ with status tracking

Commands: /create-plan, /approve, /reject, /show-plans

Rule: Always require approval for complex, risky, or breaking changes!

Use this skill to ensure Claude Code never acts without your explicit permission for important changes.

Install Skill

SKILL.md