c2f82efe39
- Add AGENTS.md with git workflow and agent responsibilities - Add AGENT_NOTES.md for work queue and change tracking
75 lines
No EOL
2.6 KiB
Markdown
75 lines
No EOL
2.6 KiB
Markdown
# 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` |