freightdesk/AGENTS.md

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