AI Agent Handoff Guide

If you're an AI agent picking up this codebase, read this first.

Agents & Roles

| Agent | Role | Channel | |-------|------|---------| | Jerry | Orchestration + David's direct assistant | Telegram (main session) | | Phil | CFO/ops — contacts, JT, Airtable, job costing | Spawned by Jerry as needed | | Mickey | All software development — Field, Crew, Mission Control, APIs | Spawned by Jerry as needed | | Bobby | Client comms — email + SMS outreach | Spawned by Jerry as needed |

Workspaces

| Agent | Workspace | |-------|-----------| | Jerry | ~/.openclaw/workspace/ | | Mickey | ~/.openclaw/workspace-mickey/ | | Phil | ~/.openclaw/workspace-phil/ | | Bobby | ~/.openclaw/workspace-bobby/ |

Key Files to Read Before Working

| File | Where | What | |------|-------|------| | MEMORY.md | Jerry's workspace | Long-term memory, standing rules, architecture decisions | | AGENTS.md | Each workspace | Agent role + working style | | FIELD_BRIEF.md | Jerry's workspace | Field app overview | | SMS_SPEC.md | cdb-field repo | Twilio SMS spec | | CALENDAR_SPEC.md | cdb-field repo | Google Calendar spec | | SETTINGS_AND_DOCS_SPEC.md | cdb-field repo | This spec |

Credentials

All secrets live at ~/.openclaw/workspace/secrets/:

| File | What | |------|------| | supabase-service-key.txt | Supabase service role key | | supabase-mgmt-token.txt | Supabase management API token | | vercel-token.txt | Vercel deploy token | | google-tokens.json | Google OAuth tokens | | google-oauth-client.json | Google OAuth client credentials | | jobtread-grant-key.txt | JobTread API grant key | | airtable-pat.txt | Airtable personal access token |

Standing Rules (Always Follow)

Every new contact → push to Google Contacts immediately
- Via /api/contacts which auto-calls Google People API
- sync_to_google = true on new contacts by default
Every outbound SMS → send report copy to David (+14152606570)
- Bobby handles this for client-facing comms
- Field's /api/sms/send does this for Field-originated messages
Transactions are NEVER deleted
- Use status = 'excluded' to hide from inbox
- Deleting breaks audit trail
Markup (not margin) in all estimating UI
- Markup = profit / cost (e.g., 35% markup = charge $1.35 for $1.00 cost)
- Margin = profit / revenue — do NOT use this in any UI facing David
All external comms go through Bobby
- Jerry, Phil, Mickey never send email or SMS to clients directly
- Bobby coordinates client-facing outreach
When building AI-driven processes → flag for offload to Vercel scripts
- Long-running AI tasks should be cron jobs or triggered scripts
- Not blocking API routes (Vercel 10s function timeout)

Deploy Process

# Field
cd ~/.openclaw/workspace/cdb-field
vercel --token $(cat ~/.openclaw/workspace/secrets/vercel-token.txt) --prod

# Mission Control
cd ~/.openclaw/workspace/mission-control
git push origin main  # GitHub Actions auto-deploys

Common Tasks

Add a new API route to Field

Create app/api/<name>/route.ts
Follow the auth pattern (check ALLOWED_USERS env var)
Use supabase client with service key
Test locally: npm run dev
Deploy

Query Supabase directly

curl -X POST \
  "https://api.supabase.com/v1/projects/evfgrjslfrjwyopyzqzx/database/query" \
  -H "Authorization: Bearer $(cat ~/.openclaw/workspace/secrets/supabase-mgmt-token.txt)" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT count(*) FROM contacts;"}'

Check Vercel env vars

Ask Jerry to read them from Vercel dashboard, or check the project settings at vercel.com/dashboard.

Architecture Quick Reference

buildbase.vercel.app        — Field (Next.js, App Router)
fieldcrew.vercel.app         — Crew (Next.js, PWA)
cdb-mission-control.vercel.app — Mission Control (vanilla JS + Vercel functions)

All → Supabase (evfgrjslfrjwyopyzqzx)

Integrations:
  Google Contacts ← /api/contacts (auto-sync)
  Twilio SMS ← /api/sms/send + /api/sms/inbound
  Google Calendar ← /api/calendar
  Finta/Plaid → Supabase (external, automated)
  JobTread → Phil queries on demand