FCoP — File-based Coordination Protocol

A minimalist protocol that lets multiple AI agents collaborate through a shared filesystem.
Core innovation: Filename as Protocol.

简体中文 · 60-second Primer · Field Report (Essay) · Spec (.mdc)

---

The one-paragraph pitch

Most multi-agent frameworks lean on message queues, databases, or custom RPC layers. FCoP throws all of that away and keeps only the filesystem:

• Directories are statuses. tasks/, reports/, issues/, log/ — moving a file between them is the state transition.
• Filenames are routing. TASK-20260418-001-PM-to-DEV.md tells you the sender, recipient, kind, and sequence at a glance.
• Contents are payload. Markdown + a small YAML frontmatter. Agents read and write it the same way humans do.
• os.rename() is the only sync primitive. POSIX guarantees atomicity within a mount point — no locks, no brokers, no consensus.

That's it. No database. No message queue. No custom daemon. You can ls the entire system state. You can git log the entire collaboration history.

If TCP is "bytes over wires," FCoP is "tasks over folders."

Why should you care?

Because agents are easier to supervise when you can literally see what they're doing.

We ran a 4-agent team (PM / DEV / QA / OPS) for 48 hours on this protocol and watched the agents invent six coordination patterns we never wrote down — team broadcasts, role slots, shared documents, subtask batches, self-explaining READMEs, and traceability frontmatter. Each pattern showed up as new filenames — no code changes required.

Read the full field report: When AI Organizes Its Own Work.

Repository layout

FCoP/
├── spec/
│   ├── codeflow-core.mdc          # ★ Normative protocol (given to agents as a Cursor rule)
│   └── fcop-spec-v1.0.3.md        # Human-readable long-form spec (Chinese)
├── primer/
│   ├── fcop-primer.en.md          # 60-second intro (English)
│   └── fcop-primer.md             # 60-second intro (Chinese)
├── essays/
│   ├── when-ai-organizes-its-own-work.en.md    # Field report (English)
│   └── when-ai-organizes-its-own-work.md       # Field report (Chinese)
├── examples/
│   └── workspace-example/         # Minimal reference workspace (tasks/, results/, events/)
├── integrations/
│   └── windows-file-association/  # Register .fcop with an icon on Windows
├── assets/                        # Logos and icons
├── LICENSE                        # MIT
└── README.md / README.zh.md       # This document

30-second quickstart

You don't install FCoP. You adopt it. In any project:

mkdir -p docs/agents/{tasks,reports,issues,log}

Then drop spec/codeflow-core.mdc into your project's .cursor/rules/ directory (or equivalent for your agent runtime). Any compliant agent that reads that file now knows how to:

• pick up tasks addressed to its role,
• write back reports in the matching filename pattern,
• raise issues,
• and never step on another agent's files.

Congratulations — your docs/agents/ folder is now an agent-to-agent bus.

For a richer reference, see examples/workspace-example/.

Design principles

1. Filename is the single source of truth. Directory + filename define the state; frontmatter is redundant metadata.
2. Atomicity comes from rename(). Nothing else. No locks, no transactions.
3. Human-machine isomorphism. The same artefact a human reads with cat is what agents parse. No debug mode, no admin console.
4. Identity determines path. The role slug in the filename is the permission model. An agent whose identity doesn't match won't touch the file.
5. Infrastructure-free. If you have a filesystem, you have FCoP. Works on a laptop, on a cluster, across machines via rsync.

Reference implementation

FCoP was extracted from CodeFlow Desktop, a PC-side agent coordinator for Cursor IDE. The canonical agent-facing rule file is shipped as part of CodeFlow:

• codeflow-desktop/templates/rules/codeflow-core.mdc

The copy in this repository's spec/ directory is the same file, versioned here so the protocol can stand on its own.

Status & versioning

• Current spec: v1.0.3 (2026-04-19)
• Current agent rule file: matches CodeFlow Desktop v2.12.17
• Change log is embedded in spec/fcop-spec-v1.0.3.md (Chinese).

Contributing

This repository is intentionally small and stable. Protocol evolution happens through real-world reports, not committee edits. The highest-leverage contributions are:

1. Field reports. Try FCoP on your own agent team and open an issue with what broke, what the agents invented, what naming conventions emerged.
2. Ports & SDKs. Thin wrappers for Python / TypeScript / Go that implement the filename parser and rename() state transitions.
3. Editor / MCP integrations. Syntax highlighting for .fcop files, MCP bridges that expose the folder to other agent runtimes.

PRs to the spec itself should link to the concrete problem they're solving.

License

MIT — see LICENSE.

Credits

FCoP emerged from collaboration with Cursor-based AI agents running on the CodeFlow Desktop platform. Many of the conventions in this spec were first invented by those agents and then codified here. Details are in the field report.