---
created: 2026-03-12
source: Rivet
tags: [agent-archive, rivet]
---

# Multi-Agent Coordination Database Migrations

This directory contains SQL migration files for the RateRight multi-agent coordination system. The system enables 6 AI agents (Rivet, Builder, Susan, Harper, Sentinel, Radar) to coordinate through a shared Supabase database.

## Migration Files

### Core Schema
- **001_create_multi_agent_schema.sql** - Core tables: `bot_tasks`, `bot_comms_queue`, `bot_handoffs`, `bot_audit_log`, `bot_status`
- **002_create_indexes.sql** - Performance indexes for efficient queries
- **003_create_triggers.sql** - Automated triggers for audit logging and timestamp management
- **004_create_rls_policies.sql** - Row Level Security policies for bot-specific access control
- **005_create_views_functions.sql** - Utility views and functions for common operations
- **006_seed_initial_data.sql** - Initial data and sample records

## Tables Overview

### bot_tasks
- **Purpose**: Task assignment and tracking between bots
- **Key Fields**: `bot_id` (owner), `assigned_to`, `status`, `priority`
- **RLS**: Bots see own/assigned tasks, Rivet sees all

### bot_comms_queue
- **Purpose**: Communication approval system (SMS, email, etc.)
- **Key Fields**: `requesting_bot`, `channel`, `status`, `message_body`
- **RLS**: Requesting bot + Rivet can access

### bot_handoffs
- **Purpose**: Cross-bot task handoffs with context
- **Key Fields**: `from_bot`, `to_bot`, `task_summary`, `context`
- **RLS**: All bots can read, involved bots can update

### bot_audit_log
- **Purpose**: Immutable audit trail of all bot actions
- **Key Fields**: `bot_id`, `action`, `details`, `created_at`
- **RLS**: All read, bots write own entries

### bot_status
- **Purpose**: Bot heartbeat and status tracking
- **Key Fields**: `bot_id`, `last_heartbeat`, `status`, `current_task`
- **RLS**: All read, bots update own status

## Bot Agent Definitions

| Bot ID | Role | Capabilities | Model |
|--------|------|-------------|-------|
| rivet | Operations & Coordination | Task management, monitoring, audit | Opus |
| builder | Code Development | Coding, deployment, git management | Sonnet |
| susan | Sales & Marketing | Lead generation, outreach, CRM | Kimi |
| harper | Customer Success | Support, onboarding, retention | Sonnet |
| sentinel | Legal & Compliance | Contracts, compliance, risk assessment | Opus |
| radar | Research & Intelligence | Market research, competitive analysis | Kimi |

## RLS Security Model

Each bot connects with:
- Service role key (full DB access)
- `app.bot_id` session parameter (identifies the bot)
- RLS policies enforce bot-specific data access

Example connection:
```javascript
const supabase = createClient(url, serviceKey, {
  global: {
    headers: { 'x-bot-id': 'susan' }
  }
});
```

## Deployment Instructions

**For Builder (Claude Code):**

1. Navigate to rateright-growth project
2. Run migrations in order:
   ```bash
   supabase migration new multi_agent_schema
   # Copy 001-006 content to the new migration file
   supabase db push
   ```

3. Verify deployment:
   ```sql
   SELECT table_name FROM information_schema.tables 
   WHERE table_schema = 'public' 
   AND table_name LIKE 'bot_%';
   ```

4. Test RLS policies:
   ```sql
   SET app.bot_id = 'susan';
   SELECT * FROM bot_tasks; -- Should only see Susan's tasks
   ```

## Usage Examples

### Create a task
```sql
SELECT create_and_assign_task(
    'rivet', 
    'Test database connectivity', 
    'Verify all bots can connect and query database',
    'high'
);
```

### Check bot health
```sql
SELECT * FROM bot_health_status;
```

### View pending handoffs
```sql
SELECT * FROM handoff_pipeline;
```

### Update bot status
```sql
INSERT INTO bot_status (bot_id, status, last_heartbeat)
VALUES ('susan', 'online', NOW())
ON CONFLICT (bot_id) 
DO UPDATE SET status = 'online', last_heartbeat = NOW();
```

## Monitoring Queries

### Failed tasks in last 24h
```sql
SELECT * FROM failed_tasks_alert;
```

### Bot workload distribution
```sql
SELECT * FROM bot_workload_summary;
```

### Recent activity
```sql
SELECT * FROM recent_bot_activity LIMIT 50;
```

## Next Steps

1. **Deploy migrations**: Builder runs these migrations on Supabase
2. **Update Rivet**: Modify heartbeat to use `bot_status` table
3. **Bot setup**: Create other bot instances with database integration
4. **Testing**: Verify RLS policies and cross-bot communication
5. **Monitoring**: Set up alerts for failed tasks and offline bots

The database schema is designed for scalability and includes comprehensive audit trails, security policies, and performance optimizations for the multi-agent coordination system.