From c2f82efe39fc616a0f562f04b45df375bcf8461a Mon Sep 17 00:00:00 2001
From: Hermes Agent <agent@hermes.local>
Date: Sun, 7 Jun 2026 19:05:51 +0000
Subject: [PATCH] chore[agent]: initialize agent collaboration framework

- Add AGENTS.md with git workflow and agent responsibilities
- Add AGENT_NOTES.md for work queue and change tracking
---
 AGENTS.md      | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++
 AGENT_NOTES.md | 16 +++++++++++
 2 files changed, 91 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 AGENT_NOTES.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..4e2c544
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,75 @@
+# 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 |
+|-------|----------------|--------------|
+| 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`
\ No newline at end of file
diff --git a/AGENT_NOTES.md b/AGENT_NOTES.md
new file mode 100644
index 0000000..3d629e1
--- /dev/null
+++ b/AGENT_NOTES.md
@@ -0,0 +1,16 @@
+# Agent Collaboration Logs
+
+## Active Agents
+\n- `claude-code`: @claude-code
+- `codex`: @codex
+- `opencode`: @opencode
+
+## Work Queue
+\n1. `agent/claude-code/driver-management` [claude-code]
+2. `agent/opencode/login-page` [codex]
+3. `agent/default/refactor` [default]
+
+## Change Notes
+\n- Current Supabase migrations completed in agent/codex/20231010-initial-schema
+- New driver search functionality requires additional index creation (claude-code)
+- UI/UX improvements planned for shipping dashboard
\ No newline at end of file