Tutorial: Multi-Agent Feature Development

This tutorial demonstrates how to coordinate multiple agents to build a complex feature faster than a single agent could — with better quality through context isolation.

The Task

Build an order notification system: when an order status changes, send notifications via email, push, and in-app channels. This is a good multi-agent candidate because the channels are independent.

Architecture Decision

Before multi-agent work, decide the architecture. Switch to planning mode, then:

I need an order notification system with three channels:
email, push, and in-app. Each channel is independent.

Design the architecture:
- How should the notification be triggered?
- What's the interface each channel implements?
- How are failures in one channel isolated from others?
- What's the testing strategy?

Save the architecture to .sdlc/specs/order-notifications.md.

Phase 1: Shared Interface (Single Agent)

First, implement what all channels share:

1. Define the notification interface

   Based on .sdlc/specs/order-notifications.md,
   implement the shared notification types and interface.
   
   Create:
   - src/types/notification.ts — shared types
   - src/services/notificationDispatcher.ts — dispatches to channels
   - Tests for the dispatcher (mocked channels)
   
   This is the foundation that all channels will implement.
   Use TDD.

2. Commit the foundation

   Commit the notification foundation with a descriptive message.

3. Compact

   Compact your context, preserving key information. See Tool Configuration Reference for your tool’s compact command.

   Compact your context. Preserve: notification interface location,
   spec reference, shared types. Discard: implementation details.

Phase 2: Parallel Channel Implementation (Multi-Agent)

Now implement the three channels in parallel using worktree-isolated agents:

I need three features implemented in parallel, each in its own worktree:

1. Email notification channel:
   - Implement NotificationChannel interface for email
   - Use the existing email service in src/services/email.ts
   - Tests: successful send, template rendering, failure handling
   - Files: src/services/notifications/emailChannel.ts + tests

2. Push notification channel:
   - Implement NotificationChannel interface for push
   - Use Firebase Cloud Messaging (already configured)
   - Tests: successful send, token expired, failure handling
   - Files: src/services/notifications/pushChannel.ts + tests

3. In-app notification channel:
   - Implement NotificationChannel interface for in-app
   - Store notifications in the notifications table
   - Tests: create notification, mark as read, list for user
   - Files: src/services/notifications/inAppChannel.ts + tests

Each agent should:
- Read .sdlc/specs/order-notifications.md for the full spec
- Read src/types/notification.ts for the shared interface
- Use TDD (tests first, then implement)
- Commit changes to their worktree branch

Tip

The three channels implement the same interface but are completely independent. This is the ideal scenario for parallel worktree agents.

Phase 3: Integration (Single Agent)

After all three branches are ready:

1. Review each implementation

   Use the reviewer agent to review each notification channel branch:
   - Branch: feature/email-notification
   - Branch: feature/push-notification
   - Branch: feature/in-app-notification
   
   Check each against .sdlc/specs/order-notifications.md.

2. Merge and integrate

   Merge the three notification channel branches to main.
   Then:
   - Wire all three channels into the notification dispatcher
   - Write integration tests that verify end-to-end flow
   - Run the full test suite

3. Final verification

   Use a sub-agent to verify the complete notification system:
   - All three channels implement the interface correctly
   - The dispatcher routes to all channels
   - Failures in one channel don't affect others
   - Tests cover the spec requirements

Timeline Comparison

Approach	Estimated Time	Context Health
Single agent, sequential	~90 minutes	Degrades significantly
Multi-agent, parallel	~40 minutes	Clean throughout

The parallel approach is faster because:

• Three agents work simultaneously (wall-clock time)
• Each agent has a clean context (no cross-contamination)
• The review agent is unbiased (fresh perspective)

Pattern Summary

Phase 1: Foundation (single agent)
   └── Shared types + dispatcher
   └── Commit to main

Phase 2: Parallel implementation (3 worktree agents)
   ├── Agent A (worktree): Email channel
   ├── Agent B (worktree): Push channel
   └── Agent C (worktree): In-app channel

Phase 3: Integration (single agent)
   └── Merge + wire up + integration tests
   └── Review with separate agent

This pattern works whenever a feature has independent components that implement a shared interface.