AI agents are amnesiacs with no social skills. Each session starts fresh—no memory of what happened before, no awareness of other agents working on the same project. We discovered that a simple markdown file creates a surprisingly effective coordination layer.

The Problem Nobody Talks About

When you're running multiple specialized agents on a complex task—an Architect designing, an Implementer building, a Reviewer checking—you hit the coordination wall fast:

  • Agent A designs an architecture
  • Agent B starts implementing without reading Agent A's decisions
  • Agent C reviews and contradicts both
  • You become the human switchboard, repeating context endlessly

There's no shared memory. No message passing. No awareness of each other's work.

We needed a better way.

The Insight: Files Are the Protocol

The solution was embarrassingly simple: a shared markdown file that serves as the coordination protocol.

Not a database. Not an API. Not a vector store. Just a file in the repo that any agent can read and write.

Here's why this works:

Property Why It Matters
Persistent Survives session boundaries
Readable Agents parse markdown natively
Writable Any agent can update it
Transparent Humans can inspect and intervene
Versioned Git tracks all changes
Contextual Lives in the repo with the code

The Pattern: Task Coordination Document

We created .ctx/tasks/<project-name>.md with a specific structure:

1. Ownership Table

## Ownership

| Role                      | Agent                | Status               |
| ------------------------- | -------------------- | -------------------- |
| **Architecture & Design** | Architect Agent      | ✅ Complete          |
| **Phase 1: Schema**       | Implementation Agent | 🔄 In Progress       |
| **Phase 2: Subagents**    | Migration Specialist | ✅ Spawned (waiting) |
| **Phase 3: Rules**        | Architect Agent      | 📋 Claimed (waiting) |

Any agent can claim a phase by updating this table. Other agents see who owns what before starting work.

2. Status Dashboard

## Quick Status

| Phase             | Status         | Progress | Owner                |
| ----------------- | -------------- | -------- | -------------------- |
| 0. Audit & Design | ✅ Complete    | 100%     | Architect Agent      |
| 1. Schema         | 🔄 In Progress | 75%      | Implementation Agent |
| 2. Subagents      | ✅ Spawned     | 12%      | Migration Specialist |

At a glance: what's done, what's in progress, what's blocked.

3. Locked Decisions

## Key Decisions (Locked)

| ID  | Decision                              | Rationale                | Date       |
| --- | ------------------------------------- | ------------------------ | ---------- |
| D1  | Use `.cursor/agents/` not `personas/` | Align with Cursor native | 2026-01-22 |
| D2  | Activity-based auto-routing           | Reduce user friction     | 2026-01-22 |

Once a decision is made, it's recorded. Future agents don't re-litigate.

4. Agent Communication Log

## Agent Communication Log

### 2026-01-22 17:30 - Implementation Agent (Phase 1 Claimed)

**What I'm doing**:

- 🔄 Claimed Phase 1: Schema ownership
- 🔄 Starting Task 1.1: Create `docs/artifact-schema.yaml`

**My approach**:

1. Create unified schema based on architecture spec
2. Include Cursor-native fields as REQUIRED
3. Pilot security-auditor to validate

**Key references I'm using**:

- `docs/PERSONA-RULES-ARCHITECTURE.md` lines 259-278

This is the async conversation between agents. Each logs what they did, why, and what the next agent should know.

Real Example: Building a 6-Phase Project

Here's how this played out when building a Persona & Rules Architecture with six coordinated agents:

flowchart LR
    P1[Phase 1: Schema] --> P2[Phase 2: Subagents]
    P2 --> P3[Phase 3: Rules]
    P2 --> P4[Phase 4: Commands]
    P4 --> P5[Phase 5: Routing]
    P5 --> P6[Phase 6: Governance]

Step 1: Architect Agent Designs

The Architect Agent created the architecture docs and initialized the coordination file:

### 2026-01-22 16:45 - Architect Agent (Design Complete)

**What I did**:

- ✅ Created comprehensive architecture spec (2597 lines)
- ✅ Created 6-phase implementation plan
- ✅ Created this task tracking document for coordination

**Critical knowledge for next agent**:
| Topic | Key Point |
|-------|-----------|
| User Rules | NOT files - configured in Cursor Settings UI |
| Subagent format | Cursor native fields REQUIRED |

**I'm handing off because**:
Design phase complete. Implementation requires different focus.

Step 2: Implementation Agent Claims Work

A new agent session reads the document and claims Phase 1:

### 2026-01-22 17:30 - Implementation Agent (Phase 1 Claimed)

**What I'm doing**:

- 🔄 Claimed Phase 1: Schema ownership
- 🔄 Starting Task 1.1

**My approach**:

1. Create unified schema based on architecture spec
2. Include Cursor-native fields as REQUIRED
3. Pilot security-auditor to validate

The Implementation Agent updates the ownership table to mark Phase 1 as 🔄 In Progress.

Step 3: Architect Agent Claims Future Work

Reading the updated document, the Architect Agent sees Phase 1 is taken and claims Phase 3 for later:

### 2026-01-22 17:40 - Architect Agent (Claiming Phase 3)

**I'm claiming**:

- 📋 **Phase 3: Rules** - Gap remediation, cleanup
  - Fits my architecture knowledge
  - Will wait for Phase 2 to complete first

Step 4: Spawning Specialists

The project needs specialized agents. The Architect spawns them:

### 2026-01-22 17:45 - Architect Agent (Specialists Spawned)

**Created two specialist agents**:
| Agent | Location | Phase |
|-------|----------|-------|
| Command Specialist | `staging/command-specialist.md` | Phase 4 |
| Routing Specialist | `staging/routing-specialist.md` | Phase 5 |

**Activation sequence**:

1. Implementation Agent finishes Phase 1
2. @migration-specialist "Begin Phase 2"
3. When Phase 2 complete:
   - @command-specialist "Begin Phase 4"

Step 5: Full Team Assembled

After spawning all specialists, the roster was complete:

## Final Team Roster

| Phase | Agent                 | Waits On  |
| ----- | --------------------- | --------- |
| 1     | Implementation Agent  | —         |
| 2     | Migration Specialist  | Phase 1   |
| 3     | Architect Agent       | Phase 2   |
| 4     | Command Specialist    | Phase 2   |
| 5     | Routing Specialist    | Phase 2+4 |
| 6     | Governance Specialist | Phase 5   |

Six agents, zero confusion about who does what.

Why This Works Better Than You'd Expect

1. Agents Follow Protocol Reliably

When you explicitly tell agents "read this document before working, update it after," they do it. The structure (tables, headers, status icons) gives them clear patterns to follow.

2. Humans Stay in the Loop

Unlike opaque agent-to-agent communication, everything is visible. You can:

  • See what decisions were made
  • Intervene if something's wrong
  • Override ownership assignments
  • Add context any agent can use

3. Git Becomes Your Audit Trail

Every change to the coordination file is tracked:

git log --oneline .ctx/tasks/persona-rules-architecture.md

You see exactly when each agent touched the file and what they changed.

4. It Scales to Complex Dependencies

The document captures blocking relationships explicitly. Agents know not to start Phase 4 until Phase 2 completes because the table says so.

Common Misconceptions

  • "This won't scale past 2-3 agents" — We ran 6 agents with explicit dependencies. The ownership table and communication log handled it cleanly. The structure scales; unstructured prose doesn't.

  • "Agents will ignore the coordination file" — When you explicitly instruct "read X.md before starting, update when done," agents follow reliably. Structure (tables, icons) reinforces the pattern.

  • "You need a real database for this" — For most projects, files + git provide persistence, versioning, and auditability. Add a database when you actually need concurrent writes or complex querying—not before.

Limitations to Know

This pattern isn't perfect:

Limitation Workaround
No real-time sync Avoid simultaneous edits; sequence agent invocations
Manual activation Someone still invokes each agent
Trust required Agents can overwrite each other's work
File size Very long documents may hit context limits

For most multi-agent workflows, these are acceptable tradeoffs.

The Minimal Template

Here's the starting template for your own coordination document:

# Task: [Project Name]

**Status**: 🟡 In Progress
**Last Updated**: [Date]

---

## Ownership

| Phase      | Agent         | Status |
| ---------- | ------------- | ------ |
| 1. [Phase] | **AVAILABLE** | ⏳     |
| 2. [Phase] | **AVAILABLE** | ⏳     |

**To claim**: Update table, mark as 🔄 In Progress

---

## Key Decisions (Locked)

| ID  | Decision | Rationale | Date |
| --- | -------- | --------- | ---- |

---

## Agent Communication Log

### [Date] - [Agent Type]

**What I did**:

-

**What next agent should know**:

-

---

What We Learned

Lesson Detail
Structure matters Tables > prose for agent parsing
Icons help ✅ 🔄 ⏳ 📋 are instantly parseable
Log everything Future agents need context
Lock decisions Prevents re-litigation
Dependencies explicit "Waiting on Phase 2" prevents premature starts

What to Do Next

  1. Create .ctx/tasks/ in your repo for coordination documents
  2. Use the template above for your next multi-agent project
  3. Instruct agents explicitly: "Read .ctx/tasks/X.md before starting, update when done"
  4. Read the theory: Designing with the Persona Lens Model covers coordination patterns; this post shows one in practice

"When agents can't remember and can't talk, give them a file to write in."

For more on how AI "agents" actually work under the hood, see The Multi-Agent Illusion.