# Collaboration Playbook

## Purpose
Provide a clear, shared process for all agents working on the freight logistics platform. Ensures consistent work tracking, reduces duplication, and enables smooth hand‑offs.

## Prerequisites
- **AGENTS.md** – defines branch naming, role matrix, commit conventions.
- **AGENT_NOTES.md** – the work ledger; must be consulted before any task.
- **Git** access with write permissions to the repository.

## Branch Naming Convention
```
agent/{agent-name}/{area}/{short-description}
```
- **agent-name**: e.g., `hermes`, `claude`, `codex`
- **area**: e.g., `backend`, `ui`, `bidding`, `deployment`
- **short-description**: concise, kebab‑case (e.g., `auth-middleware`, `bid-feed-ui`)

*Example*: `agent/hermes/bidding/bid-feed-status`

## Claiming Work
1. **Read** `AGENT_NOTES.md` to see current tasks and active claims.  
2. **Create** a new branch using the naming convention above.  
3. **Update** `AGENT_NOTES.md`:
   - Add a row with your name, the task description, `in-progress`, today’s date, and a brief note.
   - Mark the task as claimed atomically (edit the same row).
4. **Commit** with the `[agent]` prefix, e.g., `feat[agent]: add bid status colors`.

## Commit Conventions
- Prefix commit messages with `[agent]`.
- Keep messages short (≤ 50 chars) and descriptive.
- Include a reference to the task ID if applicable (e.g., `Task #42`).

## Pull Request Process
1. Push your branch.
2. Open a PR targeting `main`.
3. Ensure the PR description references the task in `AGENT_NOTES.md`.
4. Tag at least one reviewer (or the skill author) for review.
5. After approval, merge via “Squash and merge” to keep history clean.

## Skill Usage
- When implementing a feature covered by a skill (e.g., `freight-bidding-system`), **link** the skill name in the PR description and in the commit message.
- Refer to the skill’s `references/` folder for schema, component snippets, and pitfalls.
- If a skill feels insufficient, open an issue in the repo and tag `@hermes-agent` (or the relevant skill maintainer).

## Logging Decisions
- Record major architectural choices in `AGENT_NOTES.md` **before** implementation.
- Include:
  - What was decided.
  - Why the alternative was rejected.
  - Any trade‑offs considered.
- Update the ledger when a task moves from `in-progress` → `completed`.

## Common Pitfalls & How to Avoid Them
| Pitfall | Why it Happens | Fix |
|---------|----------------|-----|
| Working directly on `main` | Bypasses the ledger and branch workflow. | Always create a feature branch first. |
| Forgetting to claim a task | Leads to duplicate work. | Always update `AGENT_NOTES.md` before starting. |
| Inconsistent commit messages | Hard to trace work. | Always use `[agent]` prefix and concise messages. |
| Ignoring skill references | Missed best‑practice patterns. | Link skill names in PRs and commit messages. |
| Stale ledger entries | Causes confusion about ownership. | Update `AGENT_NOTES.md` on every status change. |

## Quick Reference Checklist (before pushing)
- [ ] Read `AGENT_NOTES.md` and claim the task.  
- [ ] Create a correctly named branch.  
- [ ] Update `AGENT_NOTES.md` with claim info.  
- [ ] Implement the change.  
- [ ] Commit with `[agent]` prefix.  
- [ ] Run any required tests / lint.  
- [ ] Open a PR with clear description and skill reference.  

---  
*Last updated: 2026‑06‑10*  
*Maintained by the Hermes Agent team.*