74 lines
No EOL
3.4 KiB
Markdown
74 lines
No EOL
3.4 KiB
Markdown
# 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.* |