morpheus-brain/COLLABORATION.md

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.