A minimalist protocol that lets multiple AI agents collaborate through a shared filesystem.
Core innovation: Filename as Protocol.
简体中文 ·
60-second Primer ·
Field Report ·
Natural Protocol ·
Rules (.mdc) ·
Standalone
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.mdtells 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."
In engineering terms, you get a serializable, versionable collaboration surface instead of relying on proprietary, heavyweight infrastructure.
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.
Then something stranger happened: a single agent, on an unrelated task (generating an AI music video in a folder with no connection to any then-open project workspace), spontaneously split itself into PM / DEV / ADMIN and wrote four FCoP-format memos to itself — then cited and sublimated our scattered rules into a single moral principle we had not written anywhere.
Both stories are written up as field reports in the essays index below.
| # | Title | Versions | One-liner |
|---|---|---|---|
| 01 | When AI Organizes Its Own Work | English · 中文 (GitHub) · 中文 (CSDN) | A 4-agent team (PM / DEV / QA / OPS), 48 hours, nothing but a folder — and six coordination patterns we never wrote down. |
| 02 | An unexplainable thing I saw: the agent didn't just comply with rules — it endorsed them | GitHub 中文 · GitHub English · CSDN 中文 · Dev.to · Cursor Forum | A single agent, on a completely unrelated task, spontaneously split into 4 FCoP roles and sublimated our scattered rules into one principle we had never written. Ships with a full evidence archive (4 screenshots, 4 memos, raw JSONL transcript). |
| 03 | Why the Natural Protocol Holds Up — FCoP's lineage from TMPA | GitHub 中文 · GitHub English | Companion to essay 02. Where that one shows that the principle emerged, this one explains why it holds up: FCoP was extracted from TMPA (a multi-AI architecture spec whose core bet is replacing distributed coordination with a plain-text temporal sequence), and the agent's sentence is the minimal-viable-form of an AI ethics mandate already written there. |
| 04 | Saying "No" Is the Hardest Thing for an LLM — FCoP Gives It Grammar | GitHub English · GitHub 中文 · Evidence archive · CSDN 中文 · Dev.to · Cursor Forum | One machine, two Cursor sessions, two GPT-5 minor versions (5.4 and 5.5). After I told the original PM "I went and found a deputy PM," it stepped down on its own — all the way to UNBOUND. Meanwhile the new PM.TEMP walked an undocumented protocol path with one body line: "PM.TEMP acting as PM, kept for FCoP tool compatibility." I expected a conflict. None happened — the agents finished the unwritten parts of the spec themselves. Ships with 15 screenshots + 2 full JSONL transcripts. |
| 05 | Tutorial: From Solo to a 2-Person AI Crew — Disciplining the AI Team with FCoP-MCP (two parallel case studies) | English (Tetris case): tetris-solo-to-duo.en.md · Dev.to · Cursor Forum · 中文译本（俄罗斯方块案例）: tetris-solo-to-duo.zh.md · 中文母语原创（贪吃蛇案例）: snake-solo-to-duo.zh.md · CSDN 中文版 |
The first tutorial-style entry in this index, shipping as two parallel case studies — the protocol is the same, the games and the live easter egg are different. Both are 45-minute hands-on dogfoods: get the agent to install fcop-mcp in Cursor, ship a working game in solo mode, switch to a 2-person team where PLANNER designs and CODER implements a creative variant, then read the disk. The Chinese case uses Snake → NEON ORBIT (original-themed) and captures an actual PLANNER-impersonating-CODER easter egg from the 0.6.x era. The English case uses Tetris → Nebula Stack (solo) → Comet Loom (team), and adds a full review-and-rework cycle (ADMIN plays v1, finds 3 blocking defects, bounces it back; PLANNER writes TASK-006 with a new Verification Requirements section; CODER ships v2) plus an end-of-day on-the-record interview where both agents are asked what they think of the protocol. 22 dogfood screenshots, 14 TASK/REPORT files, 8 silent role-switch evidence files, 2 game artefacts, 2 verbatim agent transcripts — all archived under docs/tutorials/assets/tetris-en/. |
| 06 | What the Agents Say About FCoP, When You Ask Them | GitHub English · GitHub 中文 · Evidence archive (Tetris-en dogfood) | The third class of "agents endorse FCoP" evidence, after essay 02 (unprompted, off-task) and essay 04 (conflict-forced): now directly asked. At the end of the English Tetris dogfood (companion to the row-05 tutorial), both agents (PLANNER and CODER) were asked agent-perspective takes on FCoP — no marketing tone. PLANNER named the RLHF instinct it had to fight ("follow latest instruction") to honour FCoP's role lock and called eight of its own role-switch evidence files true positives, against its own operational convenience. CODER admitted it had a protocol primitive (write_issue) it didn't use, traced the v1 defect to that exact uncovered space, and filed PR-grade product feedback on the protocol. Three different elicitation conditions, the same phenomenon — agents endorse FCoP when given the room to. Also includes a small empirical observation: across the entire 45-minute dogfood, ADMIN's two most-used phrases were "Start work." and "Inspection." |
New reports are welcome. If you tried FCoP in your own setup and something surprising happened — good or bad — open an issue or a PR against
essays/. The protocol evolves through field notes, not committee edits.
The repo is not only Markdown specs: the PyPI package fcop lives
under src/fcop/, fcop-mcp is a separate subproject under mcp/, and
there are tests/, docs/, and adr/ alongside the essays and specs.
FCoP/
├── src/fcop/ # `fcop` package: Project API; `rules/_data/`
│ # bundles fcop-rules / fcop-protocol (templates for `init` deploy)
├── mcp/ # `fcop-mcp` subproject (MCP server; has its own pyproject)
├── tests/ # pytest for `fcop` and `fcop-mcp`
├── spec/ # Human spec + legacy URL stub
│ ├── codeflow-core.mdc # Deprecated stub (keeps old URLs); real rules: `src/.../fcop-*`
│ ├── fcop-spec.md # Spec index (Chinese)
│ └── fcop-spec-v1.0.3.md # Long human spec (non-normative)
├── docs/ # Migrations, releases, [`fcop-standalone.en.md`](docs/fcop-standalone.en.md)
├── adr/ # Architecture decision records
├── .github/workflows/ # CI
├── pyproject.toml # Root `fcop` package and tooling
├── primer/
│ ├── fcop-primer.en.md
│ └── fcop-primer.md
├── essays/
│ ├── when-ai-organizes-its-own-work.en.md
│ ├── when-ai-organizes-its-own-work.md
│ ├── fcop-natural-protocol.en.md
│ ├── fcop-natural-protocol.md
│ ├── fcop-natural-protocol-evidence/
│ ├── fcop-tmpa-lineage.en.md
│ ├── fcop-tmpa-lineage.md
│ ├── when-ai-vacates-its-own-seat.en.md
│ ├── when-ai-vacates-its-own-seat.md
│ ├── when-ai-vacates-its-own-seat-evidence/
│ ├── what-agents-say-about-fcop.en.md
│ └── what-agents-say-about-fcop.md
├── examples/workspace-example/
├── integrations/windows-file-association/
├── assets/
├── LICENSE
└── README.md / README.zh.md
FCoP is adopted, not a long-running daemon. The current rule split
is fcop-rules.mdc (charter) plus
fcop-protocol.mdc
(commentary) — both belong under .cursor/rules/. The single file
spec/codeflow-core.mdc is a deprecated stub so
old links do not 404 — it is not the full protocol text for 0.6+.
Path A — fcop library (recommended). One shot creates
docs/agents/ and fcop.json:
from fcop import Project
Project(".").init() # default dev-team; use .init_solo() for single-AIPath B — rules only, no Python. Copy the two .mdc files from this repo
into .cursor/rules/. If the tree is empty, at least create the five
buckets the library uses:
mkdir -p docs/agents/{tasks,reports,issues,shared,log}With the rules in place, agents know how to claim work, name reports, raise
issues, and stay out of other roles' files. Deeper structure and team
templates: packages below and examples/workspace-example/.
The protocol is filesystem-first. If you need programmatic task/report/issue
I/O or an IDE bridge, use the two official PyPI packages (since 0.6.0):
| Package | Install | Purpose | Depends on |
|---|---|---|---|
fcop |
pip install fcop |
Pure Python library. Read/write tasks, reports, issues programmatically. Zero MCP dependency. | pyyaml |
fcop-mcp |
pip install fcop-mcp |
MCP server. Exposes the library over stdio so Cursor / Claude Desktop can call it as tools. | fcop>=0.6,<0.7, fastmcp, websockets |
Pointers (one row each, no version baked in):
| You want to… | Go to |
|---|---|
Install fcop-mcp into Cursor / Claude Desktop step-by-step |
mcp/README.md |
| Have an agent do the install for you (zero JSON editing) | agent-install-prompt.en.md · 中文 (also live as MCP resource fcop://prompt/install) |
Upgrade an existing 0.6.x install (both packages in lockstep + protocol-rule refresh) |
docs/upgrade-fcop-mcp.md |
| Browse all 26 MCP tools and 12 resources by category | docs/mcp-tools.md |
| Read the per-release record (what changed when, why) | CHANGELOG.md and docs/releases/ |
Recent releases (full notes in docs/releases/):
| Version | One-line |
|---|---|
| 0.7.2 (notes) | Metadata patch: fixes fcop-rules.mdc frontmatter stale at 1.7.0 (body was already 1.8.0); adds frontmatter↔body consistency tests + minor-lockstep test so the class of "multi-line edit, one edit dropped" bug (ISSUE-006 / ISSUE-007) becomes unshippable. No protocol or API change. |
| 0.7.1 (notes) | Hotfix for fcop-mcp 0.7.0 dependency-pin bug (fcop>=0.6,<0.7 → <0.8) plus three protocol clarifications: Rule 1 sub-agent identity (session_id ↔ role audit), Rule 0.a.1 applies to every write path (not just MCP tools), Rule 5 drops AMEND-* / -v2 (use sequential reports + amends:). New: Project.audit_drift() + fcop_check() MCP tool + soft per-process role lock. Protocol bump: rules 1.7.0 → 1.8.0, protocol 1.5.0 → 1.6.0. |
| 0.7.0 (notes) | Role uniqueness is now a first-class protocol invariant: Project.role_occupancy() + RoleOccupancy data model, fcop_report() emits a [Role occupancy] block, unbound_report removed (was deprecated since 0.6.3). Rule 1 hardened: a role is OCCUPIED iff at least one on-disk file has it as sender. Protocol bump: rules 1.6.0 → 1.7.0, protocol 1.4.0 → 1.5.0. Note: 0.7.0's fcop-mcp shipped with a stale fcop pin — install 0.7.1+ instead. |
| 0.6.5 (notes) | Rule 0.a.1 (task → do → report → archive) wired into the tool layer: new_workspace warns when no open TASK-*.md mentions the slug, fcop_report (initialised) ends with the four-step template. Bilingual, additive. |
| 0.6.4 (notes) | Init-deposit gap closed: every init_* lands its full promised set (letter, three-layer team docs, rules quartet) in one transaction. New fcop://prompt/install zh+en resources. force parameter on every init_*. |
| 0.6.3 (notes) | Canonical fcop_report (with [Versions] drift block); host-neutral redeploy_rules writing .cursor/rules/*.mdc + AGENTS.md + CLAUDE.md (ADR-0006); unbound_report deprecated (removed in 0.7.0). |
Watch out — wrong
fcopon PyPI shadows the library. Both packages here are published from this repository. Iffrom fcop import Project, Issuefails afterpip install fcop, you most likely installed an unrelatedfcopdistribution or another local project shadows the library. Fix: clean venv + reinstall both packages from PyPI in lockstep. The verify commands are inmcp/README.md.
Library — use from any Python script or agent:
from fcop import Project
proj = Project(".") # project root; no fcop.json until init
proj.init() # dirs + shared/ + log/ + writes fcop.json
task = proj.write_task(sender="PM", recipient="DEV", priority="P1",
title="Add auth middleware", body="...")
print(proj.list_tasks(recipient="DEV"))MCP server — add to mcp.json (Cursor) or claude_desktop_config.json:
{
"mcpServers": {
"fcop": {
"command": "uvx",
"args": ["fcop-mcp"]
}
}
}Don't want to edit JSON yourself? Have an agent do it. Open a fresh
chat with any shell-capable AI and paste the canonical install prompt
(agent-install-prompt.en.md
· 中文) — the agent
detects your OS, installs uv, edits your mcp.json (preserving
existing servers), and tells you when to restart. After install the
same prompt is also available as the MCP resource
fcop://prompt/install. The prompt explicitly forbids the agent from
auto-initialising a project after install — initialisation is ADMIN's
three-way choice (solo / preset team / custom).
Stability contract: additive-only for the full 0.6.x minor. Details in adr/ADR-0003-stability-charter.md.
Upgrading from 0.5.x? The MCP server moved from
fcoptofcop-mcp— update yourmcp.jsontouvx fcop-mcp. Seedocs/MIGRATION-0.6.mdfor the full migration guide and the 0.6.0 release record for what shipped.
- Filename is the single source of truth. Directory + filename define the state; frontmatter is redundant metadata.
- Atomicity comes from
rename(). Nothing else. No locks, no transactions. - Human-machine isomorphism. The same artefact a human reads with
catis what agents parse. No debug mode, no admin console. - 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.
- Infrastructure-free. If you have a filesystem, you have FCoP. Works on a laptop, on a cluster, across machines via
rsync.
Two official reference implementations, both MIT-licensed:
fcop/fcop-mcp— Python library + MCP server for the protocol. Source in this repository undersrc/fcop/andmcp/src/fcop_mcp/. Installed via PyPI (see section above).- Stub path:
spec/codeflow-core.mdcis only a URL placeholder (no full body). Normative rules aresrc/fcop/rules/_data/fcop-rules.mdc+fcop-protocol.mdc.
- Current spec: v1.0.3 (2026-04-19)
- Agent rules (
.mdc) in this repo:src/fcop/rules/_data/fcop-rules.mdc+fcop-protocol.mdc(spec/codeflow-core.mdcis a deprecated stub) - Change log is embedded in
spec/fcop-spec-v1.0.3.md(Chinese). - Research snapshot:
research-snapshot-2026-04-29archived on Zenodo with a citable DOI (see How to cite below).
If FCoP — the protocol, the field-report essays, the tutorials, or the reference implementations — informs your research, software, or writing, please cite the Zenodo research snapshot:
- DOI:
10.5281/zenodo.19886036 - Snapshot tag:
research-snapshot-2026-04-29(commit7f59395) - Machine-readable metadata:
CITATION.cff(GitHub auto-renders a Cite this repository button from this file in the right sidebar)
@misc{fcop2026snapshot,
author = {Zhu, Wei},
title = {{FCoP}: A Filename-as-Protocol coordination layer for multi-agent {AI} development (Research Snapshot, April 2026)},
month = apr,
year = 2026,
publisher = {Zenodo},
version = {research-snapshot-2026-04-29},
doi = {10.5281/zenodo.19886036},
url = {https://doi.org/10.5281/zenodo.19886036}
}For citations of individual essays or tutorials, the same DOI applies — please reference the essay's filename (e.g. essays/what-agents-say-about-fcop.en.md) and the snapshot version in your citation note.
This repository is intentionally small and stable. Protocol evolution happens through real-world reports, not committee edits. The highest-leverage contributions are:
- Field reports. Try FCoP on your own agent team and open an issue with what broke, what the agents invented, what naming conventions emerged.
- Ports & SDKs. Thin wrappers for Python / TypeScript / Go that implement the filename parser and
rename()state transitions. - Editor / MCP integrations. Syntax highlighting for
.fcopfiles, MCP bridges that expose the folder to other agent runtimes.
PRs to the spec itself should link to the concrete problem they're solving.
MIT — see LICENSE.
FCoP emerged from hands-on collaboration with multi-agent Cursor-style workflows. Many of the conventions in this spec were first invented by those agents and then codified here. Details are in the field report.