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 uses a knock protocol via .groove/coordination.md:

• Before an agent performs a destructive action on a file owned by another agent, it writes a knock entry
• The owning agent is notified and can acknowledge or object
• This prevents surprise deletions and conflicting modifications

The knock protocol is lightweight — it adds minimal overhead while preventing the most common multi-agent conflict scenarios.

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.