Agent Coordination

When multiple AI agents work on the same codebase, conflicts are inevitable without coordination. Groove provides several mechanisms to keep agents aware of each other and prevent collisions.

Scope-Based Ownership

Every agent can be assigned file scopes — glob patterns that define which files it owns:

groove spawn --role backend --scope "src/api/**,src/models/**"
groove spawn --role frontend --scope "src/components/**,src/hooks/**"

Agents are told their scope boundaries on spawn. The lock manager tracks ownership across all agents and flags violations when an agent reaches outside its scope. This is advisory, not a hard lock — agents can still touch other files when necessary, but they are aware of the boundary.

Introduction Protocol

When a new agent spawns, the daemon runs the introduction protocol:

1. AGENTS_REGISTRY.md is regenerated in the project root, listing every active agent with its role, scope, and current status
2. Existing agents are notified about the new arrival
3. The new agent receives a full context brief including the project map, team composition, and file ownership

This ensures every agent knows who else is working, what they own, and what they have done.

Completed Agent Visibility

Agents that have finished their work remain visible in the registry. New agents can see what was already built and avoid re-doing completed work.

Knock Protocol

For destructive or cross-scope actions, Groove offers two coordination mechanisms:

HTTP-Enforced Protocol (recommended)

When an agent needs to perform a shared action — running npm install, restarting the server, modifying package.json — it declares intent via the daemon and receives an exclusive lock on the resources involved:

POST http://127.0.0.1:31415/api/coordination/declare
{
  "agentId": "bk-3",
  "operation": "npm install",
  "resources": ["package.json", "node_modules"]
}

If another agent already holds any of the requested resources, the response is 423 Locked with full owner details (who holds it, which resource collided, when the lock expires). The agent can wait, pick up other work, or route a handoff.

When the operation finishes, the agent releases the lock:

POST /api/coordination/complete
{ "agentId": "bk-3" }

Operations auto-expire after 10 minutes to prevent deadlock if an agent crashes mid-operation. Introducer docs pushed to every new agent include the full protocol so nothing extra needs to be wired — agents know how to coordinate on spawn.

File-Based Advisory (.groove/coordination.md)

The original advisory protocol still exists for manual coordination and audit. Agents write their current intent to the shared markdown file; other agents read it to stay aware. This is lightweight and useful for humans to inspect, but carries no enforcement.

Cross-Scope Handoffs

When an agent needs changes in files outside its scope, it can write a handoff request:

.groove/handoffs/backend.md

The file name is the target role. The content describes what needs to change, which files, and why. Groove automatically:

1. Detects the handoff file when the agent completes
2. Finds the target agent (matching role, same team)
3. Resumes the target agent with the handoff context
4. Deletes the handoff file

This enables natural cross-scope collaboration without manual routing. A frontend agent that discovers it needs a backend API change simply writes the handoff file and continues with its own work.

Single Active Agent

When only one agent is running (no parallel work), scope rules are relaxed. The agent can edit files outside its scope if needed. Handoffs are primarily useful during parallel team execution.

Task Negotiation

When duplicate roles spawn (e.g., two backend agents), Groove runs a headless query to negotiate task boundaries:

• The daemon detects the role overlap
• A headless call asks the new agent to review the existing agent's scope and task
• The response is used to differentiate their work areas

This prevents two agents with the same role from doing the same work.

Project Files Section

New agents receive a "Project Files" section in their introduction context that tells them what to read before starting work:

• Key configuration files (package.json, tsconfig, etc.)
• The Journalist's project map and decision log
• Files recently modified by other agents
• The agent registry

This orients the agent immediately, reducing exploratory token spend.

Memory Containment

Groove explicitly tells agents to ignore stale auto-memory from previous sessions. AI tools often persist memory files (like .claude/memory) that contain outdated context from past work. Groove's introduction protocol includes a directive to rely on the current project map and registry instead of cached memory.

Coordination is Automatic

You do not need to configure coordination manually. Every spawn triggers the introduction protocol, scopes are tracked automatically, and the knock protocol activates when needed. Just assign scopes at spawn time and Groove handles the rest.