Collaborating Agents | Mechanics

The Problem

Most teams overbuild orchestration too early. Start simple.

The common failure: 5 agents all touching the same service files.

The fix: Parallelize by bounded context, not by "task type" alone. Each agent owns a module with clear interfaces. Handoffs are artifacts, not chat.

Current Options

Option	Pros	Cons
Single Agent (Start Here)One agent does everything. Simple, no coordination overhead.	Zero coordination complexity Full context in one place Easy to debug Good for most tasks	Bottleneck on large features No parallelization Single point of failure
Orchestrator + SpecialistsPoint guard coordinates specialist agents.	Parallel work on non-overlapping slices Each agent focused on one concern Scales with feature complexity	Coordination overhead Handoff artifacts required More complex debugging
Swarm / Autonomous AgentsAgents discover and claim work dynamically.	Highly scalable Self-organizing Resilient to failures	Hard to reason about Can thrash on conflicts Overkill for most teams

Future Outlook

Multi-agent systems are powerful but most teams start too complex. Begin with one agent. Add coordination only when you hit scaling limits.

The progression:

Single agent for small/medium features
Orchestrator + 2-3 specialists for large features
Full multi-agent swarm only for massive codebases

Most teams never need step 3.

Our Decision

✓Why we chose this

ParallelizationNon-overlapping slices can be implemented simultaneously.
SpecializationSpec agent thinks differently than coder agent. Each optimized for its role.
Bounded blast radiusOne agent failing does not block others. Restart and retry.

×Trade-offs we accept

Coordination overheadHandoffs, artifacts, merge conflicts. Real costs.
Same-file conflictsTwo agents editing one file = merge hell. Avoid.
Debugging complexityWhich agent introduced the bug? Harder to trace.

Motivation

Agent roles that scale well:

Spec Agent — Clarifies requirements, finds ambiguity
Contract Agent — Defines API/schema/types
Test Agent — Generates acceptance/contract/unit tests
Implementation Agent — Writes code to pass tests
Review Agent — Checks diff vs spec and coding standards
Integration Agent — Handles merge conflicts, CI failures, wiring

Orchestrator responsibilities:

Decompose work into independent slices
Assign owners/agents
Enforce handoff artifacts (spec, schema, tests, diff)
Run validation gates
Block merges on failing checks
Re-plan when specs change

Recommendation

Parallelize by bounded context, not by task type.

Bad: 5 agents all touching the same service files. Good: 5 agents each owning separate modules with clear interfaces.

Canonical engineering spec: View / download the Markdown spec (Rust + gRPC + MCP connector + TUI, with negative tests and property tests)

Handoffs Are Artifacts, Not Chat

Use explicit files:

spec.md — Requirements
openapi.yaml or schema.ts — Contract
*.test.ts — Test cases
Implementation diff
Review findings

Artifacts make the system robust and auditable. Chat is ephemeral.

Multi-Agent Orchestration Checklist (Minimum)

Before starting

Feature decomposed into 3-10 slices
Slice dependencies and owned file paths defined
Required handoff artifacts listed per slice
Escalation rules defined (who/when)
Branch/PR names assigned per slice

Before handoff (every slice)

Artifact written to file (not chat-only)
Artifact passes local validation (lint/typecheck/schema checks)
Owned-path boundaries respected (no out-of-scope edits)
Open questions / risks recorded for the next agent

Before merge

Reviewer checks diff against spec (not just style)
Required gates pass
Compatibility checks pass for API changes
Integration agent confirms no unresolved same-file conflicts

A Scalable Pattern That Works

Break feature into 3-10 spec slices
For each slice: contract + tests first
Run implementation agents in parallel on non-overlapping slices
Run reviewer agent on each diff
Use one integration agent to merge/rebase/fix CI
Land slices continuously

This is much more reliable than "one giant agent builds the whole feature."

Quality Gates (Required Before Merge)

✓ Lint
✓ Typecheck
✓ Unit tests
✓ Contract tests
✓ Integration tests (for changed flows)

For API changes, add compatibility checks.

Branch and PR Naming (Recommended)

Use slice-aware names so the orchestrator and humans can track ownership.

Branch: feat/<feature-key>/<slice-id>-<short-desc>
PR title: [<feature-key>][S<id>][<role>] <imperative summary>

Examples:

feat/orchestrator/s1-contracts-proto
feat/orchestrator/s4-mcp-connector
[orchestrator][S4][impl] Add MCP connector timeout + allowlist