Skip to main content

Agent Orchestration Protocol

How agents collaborate to complete roadmap tasks with comprehensive multi-dimensional verification.

Last Updated: February 2, 2026

Overview​

This protocol defines how agents work together to complete tasks from the product roadmap. It ensures quality, consistency, and comprehensive verification across all dimensions (functionality, design, accessibility, security, performance, etc.) before any code is committed.

Key Principle: Multi-Dimensional Verification​

Not all tasks need the same verification. The orchestrator assigns verifiers based on task type:

  • API tasks → @verifier-api + @security-audit + @reviewer
  • Frontend tasks → @verifier-frontend + @design-audit + @a11y-audit + @responsive-audit + @perf-audit + @reviewer
  • Full features → All verifiers + @verifier-e2e + @ship-check
  • Design system → @verifier-design + @design-audit + @qa-coverage + @storybook-audit

Agent Roles​

1. Orchestrator Agent (@orchestrator)​

Responsibilities:

  • Pick up tasks from BACKLOG.md
  • Assign tasks to appropriate worker agents
  • Track task status
  • Coordinate multi-agent tasks
  • Review verification reports
  • Commit code when satisfied
  • Update documentation
  • Move tasks to COMPLETED.md

2. Worker Agents​

Examples: @api-wirer, @endpoint-builder, @component-builder, @auth-implementer

Responsibilities:

  • Accept assigned tasks
  • Implement the work
  • Follow acceptance criteria
  • Create verification report
  • Request verification

3. Verifier Agents (@verifier-*)​

Examples: @verifier-api, @verifier-frontend, @verifier-e2e

Responsibilities:

  • Verify worker agent's implementation
  • Run tests
  • Check acceptance criteria
  • Generate verification report
  • Approve or request changes

4. Reviewer Agent (@reviewer)​

Responsibilities:

  • Review code quality
  • Check best practices
  • Verify consistency
  • Approve or request changes

Task Lifecycle​

BACKLOG → ASSIGNED → IN_PROGRESS → VERIFICATION → REVIEW → APPROVED → COMMITTED → COMPLETED

States​

  1. BACKLOG - Task in BACKLOG.md, ready to be picked up
  2. ASSIGNED - Orchestrator assigned task to worker agent(s)
  3. IN_PROGRESS - Worker agent(s) actively working
  4. VERIFICATION - Verifier agent checking work
  5. REVIEW - Reviewer agent reviewing code
  6. APPROVED - All checks passed, ready to commit
  7. COMMITTED - Code committed to git
  8. COMPLETED - Task moved to COMPLETED.md, documentation updated

Workflow​

Step 1: Orchestrator Picks Up Task​

Orchestrator Agent:

  1. Read BACKLOG.md
  2. Select highest priority task
  3. Create task file in active/ directory: TASK-XXX.md
  4. Move task from BACKLOG.md to ACTIVE.md
  5. Assign to appropriate worker agent(s)

Task File Format:

# TASK-XXX: [Task Name]

**Status:** ASSIGNED
**Assigned To:** @agent-name
**Priority:** P0
**Estimated Effort:** 2 days

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Implementation Notes
[Worker agent adds notes here]

## Verification Report
[Verifier agent adds report here]

## Review Notes
[Reviewer agent adds notes here]

Step 2: Worker Agent Implements​

Worker Agent:

  1. Read task file
  2. Understand acceptance criteria
  3. Implement the work
  4. Update task file with implementation notes
  5. Mark acceptance criteria as complete
  6. Change status to VERIFICATION
  7. Request verification from appropriate verifier agent

Implementation Notes Format:

## Implementation Notes

**Files Changed:**
- `src/api/endpoints.ts`
- `src/types/api.ts`

**Key Changes:**
- Added feature flag check
- Implemented endpoint logic
- Added error handling

**Testing:**
- Manual testing completed
- Unit tests added

Step 3: Multi-Dimensional Verification​

Orchestrator assigns appropriate verifiers based on task type:

Verification Matrix​

Task TypeRequired VerifiersOptional Auditors
API Endpoints@verifier-api, @reviewer@security-audit
Frontend Components@verifier-frontend, @reviewer@design-audit, @a11y-audit, @responsive-audit, @perf-audit
Full Features (E2E)@verifier-e2e, @verifier-api, @verifier-frontend, @reviewer@ship-check (runs all audits)
Design System@verifier-design, @design-audit, @reviewer@qa-coverage, @storybook-audit, @a11y-audit
Infrastructure@verifier-infra, @reviewer@security-audit
Documentation@verifier-docs, @docs-audit-

Verification Process​

Primary Verifier (e.g., @verifier-api):

  1. Read task file and implementation notes
  2. Check each acceptance criterion
  3. Run tests (unit, integration)
  4. Test manually if needed
  5. Verify build succeeds
  6. Generate verification report
  7. Mark status as VERIFIED or NEEDS_CHANGES

Specialized Auditors (if applicable):

  • @design-audit - Design system compliance, component usage
  • @a11y-audit - Accessibility (WCAG 2.1 AA)
  • @responsive-audit - Mobile/tablet/desktop testing
  • @perf-audit - Performance (Core Web Vitals, bundle size)
  • @security-audit - Security vulnerabilities, data protection
  • @seo-audit - SEO optimization (for public pages)
  • @qa-coverage - Test coverage, story coverage
  • @storybook-audit - Storybook quality

Ship Check (for release-critical tasks):

  • @ship-check runs comprehensive quality gates:
    • All verifiers pass
    • All audits pass
    • E2E tests pass
    • Performance targets met
    • Security checks pass
    • Documentation updated

Verification Report Format:

## Verification Report

**Status:** ✅ VERIFIED / ⚠️ NEEDS_CHANGES

**Primary Verification (@verifier-api):**
- [x] Acceptance criteria met
- [x] Unit tests: ✅ All pass
- [x] Integration tests: ✅ All pass
- [x] Manual testing: ✅ Works as expected
- [x] Build: ✅ Success

**Specialized Audits:**
- [x] @design-audit: ✅ Pass (if applicable)
- [x] @a11y-audit: ✅ Pass (if applicable)
- [x] @security-audit: ✅ Pass (if applicable)
- [x] @perf-audit: ✅ Pass (if applicable)

**Issues Found:**
- [List any issues]

**Recommendations:**
- [Any recommendations]

Step 4: Reviewer Agent Reviews​

Reviewer Agent:

  1. Read task file, implementation notes, and verification report
  2. Review code quality
  3. Check best practices
  4. Verify consistency with codebase
  5. Generate review notes
  6. Mark status as APPROVED or NEEDS_CHANGES

Review Notes Format:

## Review Notes

**Status:** ✅ APPROVED / ⚠️ NEEDS_CHANGES

**Code Quality:**
- ✅ Follows TypeScript best practices
- ✅ Error handling is appropriate
- ⚠️ Missing JSDoc comments

**Consistency:**
- ✅ Matches existing patterns
- ✅ Uses design system components

**Issues:**
- [List any issues]

**Recommendations:**
- [Any recommendations]

Step 5: Orchestrator Commits​

Orchestrator Agent:

  1. Check task status is APPROVED
  2. Review all reports
  3. Commit code with descriptive message
  4. Push to repository
  5. Update task status to COMMITTED
  6. Update documentation (if needed)
  7. Move task to COMPLETED.md
  8. Update product-status.md or product-roadmap-matrix.md (if needed)

Commit Message Format:

feat: [feature name] - TASK-XXX

- [Brief description]
- [Key changes]

Verified by: @verifier-agent
Reviewed by: @reviewer-agent

Multi-Agent Tasks​

Some tasks require multiple agents. The orchestrator coordinates:

Example: TASK-012 (Booking Creation Flow)

  • @api-wirer - Wire API calls (worker)
  • @verifier-api - Verify API endpoints
  • @verifier-frontend - Verify frontend UI
  • @verifier-e2e - Verify end-to-end flow
  • @design-audit - Verify design system compliance
  • @a11y-audit - Verify accessibility
  • @security-audit - Verify payment security
  • @reviewer - Code quality review

Coordination:

  1. Orchestrator assigns to primary worker agent (@api-wirer)
  2. Primary agent coordinates with other worker agents if needed
  3. All worker agents update task file
  4. Orchestrator assigns verifiers based on task type
  5. All verifiers verify their parts in parallel
  6. Orchestrator ensures all quality gates pass before committing

Task Dependencies​

Tasks may depend on other tasks. Orchestrator ensures:

  1. Dependency Check: Before assigning, check if dependencies are completed
  2. Sequential Execution: Don't start dependent task until dependency is completed
  3. Documentation: Update task file with dependency status

Example:

  • TASK-003 (API Client Library) must complete before TASK-004 (Supabase Auth)
  • TASK-001 (Feature Flags) must complete before any feature-flagged tasks

Quality Gates​

Before a task can be committed:

  1. ✅ All acceptance criteria met
  2. ✅ Primary verifier report shows VERIFIED
  3. ✅ All applicable specialized audits pass (design, a11y, security, perf, etc.)
  4. ✅ Review notes show APPROVED
  5. ✅ All tests pass (unit, integration, E2E if applicable)
  6. ✅ Build succeeds
  7. ✅ No blocking issues
  8. ✅ Documentation updated (if needed)

Quality Gate Matrix​

DimensionVerifier/AuditorWhen Required
Functionality@verifier-*Always
Code Quality@reviewerAlways
Design System@design-auditFrontend/Design tasks
Accessibility@a11y-auditUser-facing features
Security@security-auditAPI/auth/payment tasks
Performance@perf-auditFrontend/public pages
Responsive@responsive-auditFrontend components
SEO@seo-auditPublic pages
E2E@verifier-e2eFull user flows
Ship Ready@ship-checkRelease-critical tasks

Error Handling​

If Verification Fails:​

  1. Verifier marks status as NEEDS_CHANGES
  2. Orchestrator reassigns to worker agent
  3. Worker agent fixes issues
  4. Process repeats from Step 2

If Review Fails:​

  1. Reviewer marks status as NEEDS_CHANGES
  2. Orchestrator reassigns to worker agent
  3. Worker agent fixes issues
  4. Process repeats from Step 2

If Tests Fail:​

  1. Verifier marks status as NEEDS_CHANGES
  2. Worker agent fixes tests
  3. Process repeats from Step 2

Communication Protocol​

Task File Updates​

  • All agents update the task file with their work
  • Use clear sections for each agent's contribution
  • Timestamp important updates

Status Updates​

  • Always update task status when moving to next step
  • Use consistent status values
  • Update ACTIVE.md when status changes

Blockers​

  • If a blocker is found, mark task as BLOCKED in task file
  • Document the blocker
  • Notify orchestrator
  • Orchestrator decides: fix blocker, skip task, or reassign

Integration with Linear​

Linear Issue Tracking​

Option 1: Manual Sync (Recommended for now)

  • Create Linear issue for each task
  • Reference Linear issue in task file: Linear: JUN-XXX
  • Update Linear issue status when task status changes
  • Orchestrator updates Linear manually

Option 2: API Integration (Future)

  • Orchestrator creates Linear issue automatically
  • Updates Linear status automatically
  • Links task file to Linear issue

Example Workflow​

TASK-001: Feature Flags Infrastructure​

  1. Orchestrator: Picks up TASK-001, creates active/TASK-001.md, assigns to @endpoint-builder
  2. @endpoint-builder: Implements feature flags, updates task file, requests verification
  3. Verification Phase:
    • @verifier-api: Verifies endpoints work, tests pass, generates report
    • @security-audit: Verifies admin-only access, data protection
    • @reviewer: Reviews code quality, patterns, consistency
  4. All verifiers mark VERIFIED/APPROVED
  5. Orchestrator: Commits code, updates docs, moves to COMPLETED

Total Time: 2 days (as estimated)

TASK-012: Booking Creation Flow (Full Feature Example)​

  1. Orchestrator: Assigns to @api-wirer (primary worker)
  2. @api-wirer: Implements booking flow with payment flag support
  3. Verification Phase (Parallel):
    • @verifier-api: API endpoints work correctly
    • @verifier-frontend: UI renders, forms work
    • @verifier-e2e: Full booking flow works end-to-end
    • @design-audit: Uses design system components correctly
    • @a11y-audit: Accessible forms and buttons
    • @security-audit: Payment data handling secure
    • @perf-audit: Page load performance acceptable
    • @reviewer: Code quality review
  4. All verifiers mark VERIFIED/APPROVED
  5. @ship-check: Final quality gate (optional, for release-critical)
  6. Orchestrator: Commits code, updates docs, moves to COMPLETED

Best Practices​

  1. One Task at a Time: Orchestrator focuses on one task until completion
  2. Clear Communication: All agents document their work clearly
  3. Quality First: Don't skip verification or review
  4. Documentation: Always update docs when features are added
  5. Testing: Always include tests for new features
  6. Feature Flags: Always use feature flags for new features

Next Steps​

  1. Review and approve this protocol
  2. Set up task management structure (BACKLOG.md, ACTIVE.md, active/ directory)
  3. Create orchestrator agent definition
  4. Begin with Phase 1, Task 1.1

This protocol ensures:

  • ✅ Quality code through verification and review
  • ✅ Consistent process across all tasks
  • ✅ Clear accountability for each step
  • ✅ Proper documentation updates
  • ✅ Sequential task completion
  • ✅ Integration with existing tools (Linear, git)