docs[agent]: add collaboration playbook for consistent agent workflows

COLLABORATION.md

@@ -0,0 +1,74 @@
+# 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.*