# SADD Plugin - Usage Examples

Real-world scenarios demonstrating effective use of the Subagent-Driven Development plugin.

## Examples

### Sequential Plan Execution

**Scenario**: You have an implementation plan for a user authentication feature with 4 dependent tasks.

```bash
# Start SADD with the plan
> I have a plan at specs/auth/plan.md with these tasks:
  1. Create user model and database migrations
  2. Implement registration endpoint
  3. Implement login endpoint with JWT
  4. Add password reset flow
  Please use SADD skill to implement it sequentially.
```

**Expected Flow**:

1. SADD loads the plan and creates TodoWrite
2. Dispatches subagent for Task 1 (user model)
3. Subagent reports: "Created User model, migrations, 3/3 tests passing"
4. Code reviewer validates: "Strengths: Good schema design. No issues."
5. Task 1 marked complete, proceeds to Task 2
6. Repeats for all tasks with review between each

**Sample Code Reviewer Output**:

```
Task 2 Review: Registration Endpoint

Strengths:
- Input validation covers all edge cases
- Password hashing uses bcrypt with appropriate rounds
- Clear error messages for validation failures

Issues:
- (Important) Missing rate limiting on registration endpoint
- (Minor) Consider adding email format validation regex

Assessment: Ready to proceed after adding rate limiting
```

```bash
# SADD dispatches fix subagent
> Fix subagent: Added express-rate-limit middleware, 100 requests/15 min per IP
> Verified: Rate limiting active, all tests passing
```

### Parallel Test Failure Investigation

**Scenario**: After a major refactoring, 6 tests fail across 3 independent test files.

```bash
> We have test failures in 3 independent areas:
  - src/auth/auth.test.ts (2 failures): Token validation timing
  - src/payments/stripe.test.ts (3 failures): Webhook signature verification
  - src/notifications/email.test.ts (1 failure): Template rendering
  Use parallel investigation to fix all three.
```

**Expected Flow**:

1. SADD identifies 3 independent domains
2. Dispatches 3 agents in parallel:
   - Agent 1: "Fix auth.test.ts - token validation timing issues"
   - Agent 2: "Fix stripe.test.ts - webhook signature verification"
   - Agent 3: "Fix email.test.ts - template rendering"
3. All agents work concurrently
4. Results integrated and verified

**Agent Reports**:

```
Agent 1 (auth): Found race condition in token refresh. Added proper async/await
              handling. 2/2 tests now passing.

Agent 2 (stripe): Webhook signature was using wrong timestamp format.
                 Updated to Unix seconds. 3/3 tests now passing.

Agent 3 (email): Template engine needed handlebars helpers registered.
                Added setup in test beforeEach. 1/1 test now passing.
```

```bash
# SADD runs full test suite
> Integration: All fixes applied, no conflicts detected
> Full suite: 47/47 tests passing
> Done!
```

### Batch Execution with Checkpoints

**Scenario**: Large refactoring plan with 9 tasks, executed in batches of 3.

```bash
> Use subagent-driven development to execute specs/refactor/plan.md
  Execute in batches of 3 tasks with review between batches.
```

**Expected Flow**:

```
Batch 1 (Tasks 1-3):
- Task 1: Extract database layer to separate module
- Task 2: Create repository interfaces
- Task 3: Implement PostgreSQL repository

[Batch 1 Complete]
Verification: All migrations run, 12/12 tests passing
Ready for feedback.

> User: Looks good, continue.

Batch 2 (Tasks 4-6):
- Task 4: Update services to use repositories
- Task 5: Add dependency injection
- Task 6: Update controller layer

[Batch 2 Complete]
Verification: Integration tests updated, 28/28 tests passing
Ready for feedback.

> User: The DI setup looks complex. Can you simplify?

[Applies feedback, re-runs Task 5 with simpler approach]

Batch 3 (Tasks 7-9):
- Task 7: Remove legacy database calls
- Task 8: Update documentation
- Task 9: Clean up unused code

[All Batches Complete]
Final verification: Full suite 45/45 passing
Ready for final review.
```

### Microservices Feature Rollout

**Scenario**: Same feature needs implementation across 3 independent microservices.

```bash
> Implement the new audit logging feature across our microservices:
  - user-service: Log all authentication events
  - order-service: Log all order state changes
  - payment-service: Log all payment transactions
  Each service is independent. Use parallel execution.
```

**Expected Flow**:

1. SADD dispatches 3 agents in parallel
2. Each agent works in its service directory
3. No conflicts since services are separate
4. Final integration verifies all services

**Agent Prompts (generated by SADD)**:

```markdown
Agent 1 - User Service:
Implement audit logging for authentication events in user-service/
- Log: login, logout, password change, token refresh
- Use existing LogService
- Add tests for each event type
- Do NOT modify other services

Agent 2 - Order Service:
Implement audit logging for order events in order-service/
- Log: created, updated, shipped, delivered, cancelled
- Use existing LogService
- Add tests for each state transition
- Do NOT modify other services

Agent 3 - Payment Service:
Implement audit logging for payment events in payment-service/
- Log: initiated, processed, completed, failed, refunded
- Use existing LogService
- Add tests for each payment state
- Do NOT modify other services
```

**Results**:

```
Agent 1: Implemented auth logging, 8 events covered, 8/8 tests passing
Agent 2: Implemented order logging, 5 states covered, 10/10 tests passing
Agent 3: Implemented payment logging, 5 states covered, 12/12 tests passing

Integration: No conflicts, all services deployable independently
Full suite: 30/30 new tests passing
```

### Complex Feature with SDD Integration

**Scenario**: Building a complete payment processing feature using SDD for planning and SADD for execution.

```bash
# Phase 1: Create the spec and plan with SDD
> /sdd:01-draft-spec
  "Implement Stripe payment processing with subscription support"

> /sdd:02-design
  # Reviews technical approach, creates data models

> /sdd:03-plan
  # Creates detailed implementation plan with 7 tasks
```

**Generated Plan** (specs/payments/plan.md):

```markdown
## Tasks

1. Create payment models and migrations
2. Implement Stripe client wrapper
3. Add one-time payment endpoint
4. Implement subscription creation
5. Add webhook handlers for payment events
6. Implement payment history API
7. Add retry logic for failed payments
```

```bash
# Phase 2: Execute with SADD
> Use subagent-driven development to execute specs/payments/plan.md
```

**Execution Flow**:

```
Task 1: Payment models
- Subagent: Created Payment, Subscription, PaymentEvent models
- Reviewer: Good normalization, add index on customer_id
- Fix: Added index, migrations updated

Task 2: Stripe wrapper
- Subagent: Created StripeService with typed methods
- Reviewer: Good error handling, add retry logic stub

Task 3: One-time payment
- Subagent: POST /api/payments endpoint with validation
- Reviewer: Missing idempotency key handling
- Fix: Added idempotency_key to prevent duplicates

Task 4: Subscription creation
- Subagent: Subscription CRUD with Stripe sync
- Reviewer: Good webhook integration points

Task 5: Webhook handlers
- Subagent: Handlers for payment_intent.succeeded, etc.
- Reviewer: Add signature verification (Critical)
- Fix: Added stripe.webhooks.constructEvent verification

Task 6: Payment history
- Subagent: GET /api/payments with pagination
- Reviewer: Add filtering by date range

Task 7: Retry logic
- Subagent: Exponential backoff for failed payments
- Reviewer: Good circuit breaker pattern

Final Review: All requirements met, ready for merge
```

```bash
# Phase 3: Finish with additional quality checks
> /reflexion:reflect
> /reflexion:memorize "Payment integration patterns"
> /git:create-pr
```

### Handling Subagent Failures

**Scenario**: A subagent fails to complete its task due to unclear requirements.

```bash
> Use subagent-driven development to execute specs/analytics/plan.md
```

**Task Failure**:

```
Task 3: Implement dashboard aggregations

Subagent: Unable to complete task. The plan references "standard aggregation
         periods" but these are not defined. Found multiple possible
         interpretations:
         - Last 7/30/90 days
         - Current week/month/quarter
         - Rolling averages

Requesting clarification before proceeding.
```

**Resolution**:

```bash
> Use daily/weekly/monthly aggregations with these periods:
  - Daily: last 30 days
  - Weekly: last 12 weeks
  - Monthly: last 12 months
```

```
[SADD updates context and dispatches new subagent with clarification]

Subagent: Implemented aggregations with specified periods.
         Created AggregationService with configurable windows.
         12/12 tests passing.

Reviewer: Good implementation, clear period handling. Ready to proceed.
```

### Production Bug Investigation

**Scenario**: Three unrelated production bugs reported simultaneously.

```bash
> Production issues need immediate fixes:
  1. Users report images not loading on profile page (storage)
  2. Password reset emails arriving 10+ minutes late (queue)
  3. Search returns stale results (cache)
  Use parallel investigation - these are completely independent systems.
```

**Agent Dispatch**:

```markdown
Agent 1 - Storage Issue:
Investigate profile image loading failures.
- Check CloudFront/S3 configuration
- Review image URL generation
- Check for CORS issues
- Return: Root cause and fix

Agent 2 - Queue Delay:
Investigate email delivery delays.
- Check Redis queue depth
- Review worker processing times
- Check for retry storms
- Return: Root cause and fix

Agent 3 - Cache Staleness:
Investigate stale search results.
- Check Elasticsearch sync
- Review cache invalidation logic
- Check for missed webhooks
- Return: Root cause and fix
```

**Results**:

```
Agent 1: Root cause - S3 bucket policy changed during deploy.
        Fix: Restored public-read on profile-images prefix.
        Verified: Images loading correctly.

Agent 2: Root cause - Email worker crashed, wasn't restarted by supervisor.
        Fix: Restarted worker, added health check to supervisor.
        Verified: Queue cleared in 2 minutes, emails delivering instantly.

Agent 3: Root cause - Product update webhook failing silently.
        Fix: Added error logging, fixed webhook URL typo.
        Verified: Search index now updating within 30 seconds.

All issues resolved in parallel - 15 minutes total vs ~45 minutes sequential.
```

## Integration with Other Plugins

### With Reflexion

```bash
# After SADD completes a complex implementation
> /reflexion:reflect
# Captures patterns learned during multi-task execution

> /reflexion:memorize "Subagent coordination patterns"
# Saves insights about effective task decomposition
```

### With Code Review

```bash
# Run additional review after SADD completes
> /review-local-changes

# Address any additional findings
> claude "Fix the medium priority issues from code review"

# Final verification
> /reflexion:reflect
```

### With SDD (Spec-Driven Development)

```bash
# Full workflow: Spec -> Design -> Plan -> Execute
> /sdd:01-draft-spec "Build notification system"
> /sdd:02-design
> /sdd:03-plan

# Hand off to SADD for execution
> Use subagent-driven development to execute specs/notifications/plan.md

# Document the completed feature
> /sdd:05-document
```
