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
This commit is contained in:
Hermes Agent 2026-06-07 19:05:51 +00:00
parent 1a4eaaa040
commit c2f82efe39
2 changed files with 91 additions and 0 deletions

75
AGENTS.md Normal file
View file

@ -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`

16
AGENT_NOTES.md Normal file
View file

@ -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