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.

# 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

# 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.

> 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.

# 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.

> 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.

> 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):

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.

# 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):

## 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

# 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

# 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.

> 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:

> 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.

> 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:

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

# 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

# Run additional review after SADD completes
> /code-review: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)

# 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