# FreightDesk AI Agent Coordination

This document defines the operational framework for AI agent collaboration on the FreightDesk project via git.

## Project Overview
- **Purpose**: Freight Forwarding Commission Agent Management
- **Main Stack**: Node.js/Express, EJS templates, Supabase
- **Frontend**: EJS server-side templates
- **Backend**: Express server with Supabase integration
- **Database**: PostgreSQL via Supabase

## Git Workflow

### Branch Naming Convention
- `agent/{agent-name}/{feature}` - New features (e.g., `agent/claude-code/driver-management`)
- `agent/{agent-name}/fix/{issue}` - Bug fixes (e.g., `agent/codex/fix/login-error`)
- `agent/{agent-name}/docs/{topic}` - Documentation updates

### Collaboration Protocol
1. **Claim Work**: Check AGENT_NOTES.md before starting work
2. **Create Branch**: Fork from `main` with agent-specific prefix
3. **Commit Messages**: Use conventional commits with `[agent]` prefix
   - Example: `feat[agent]: add driver search functionality`
4. **Pull Requests**: Reference agent name in PR description
5. **Review**: Self-review before requesting human review

## Agent Responsibilities

| Agent | Primary Domains | Review Scope |
|-------|----------------|--------------|
| OWL (owl-alpha) | Full-stack: routes, views, parser, styling, deployment | All changes |
| claude-code | Backend logic, API routes, server config | Routes, middleware |
| codex | Database schema, migrations, seed data | SQL, Supabase client |
| opencode | Frontend/EJS templates, CSS, UI components | Views, layouts |
| default | Cross-cutting concerns, project config | All changes |

## Code Standards

### JavaScript/Node.js
- Use `const`/`let` (no `var`)
- Prefer arrow functions for callbacks
- Use async/await (no callbacks)
- Destructure objects when used 2+ times

### EJS Templates
- Use `<%- %>` for unescaped HTML
- Use `<%= %>` for escaped content
- Keep logic minimal; prefer passing data from routes

### Supabase
- Use the singleton pattern from `src/services/supabase.js`
- Handle errors with try/catch
- Use `.from('table').select('*')` pattern

## File Structure Reference
```
freightdesk/
├── webapp/
│   ├── src/
│   │   ├── server.js          # Main Express server
│   │   ├── routes/            # Route handlers
│   │   ├── views/             # EJS templates
│   │   └── services/          # Supabase client
│   ├── public/                # Static assets
│   └── package.json
├── supabase/
│   └── migrations/            # Database schema
└── docker-compose.yml
```

## Getting Started
1. Clone the repository
2. Install dependencies: `npm install`
3. Copy `.env.example` to `.env` and configure
4. Run database migrations
5. Start dev server: `npm run dev`