🆕 FCoP 3.0 is here — Files carry protocol. Paths address state. Events replay transitions.
<p align="center"> <a href="spec/fcop-v3-spec.md"> <img src="assets/fcop-3.0-architecture.png" alt="FCoP 3.0 · Canonical Architecture — Files carry protocol. Paths address state. Events replay transitions." width="900" /> </a> </p>FCoP 3.0 is the protocol's first semantic seal. State now lives in the filesystem itself (
_lifecycle/{inbox,active,review,done,archive}/), events live append-only inside the file, and custody / ownership / scheduling / runtime are explicitly out of scope (Boundary Charter).Two paths to v3:
- New project →
fcop init/ MCPinit_solo|init_project|create_custom_team(≥ 3.0.2 produces v3 topology directly).- Existing 2.x project →
python -m fcop migrate --to-v3.⚠️ 3.0.0 / 3.0.1 fresh-init bug: those releases initialized projects in v2 layout (no
_lifecycle/). 3.0.2 fixes the bug. If you initialized on 3.0.0 / 3.0.1, runmigrate --to-v3to upgrade.
| Doc | Purpose |
|---|---|
spec/fcop-v3-spec.md · zh | Current single-page spec (3.0 → 3.2.5: _lifecycle/ + history/) |
spec/fcop-3.0-spec.md · zh | Frozen 3.0.0 baseline (2026-05-21) |
spec/fcop-3.0-rfc.md · zh | IETF-style RFC projection |
docs/MIGRATION-3.0.md · zh | 2.x → 3.0 migration guide |
CHANGELOG.md [3.0.0] | Full release notes |
essays/the-day-we-almost-added-custody.en.md · zh | The decision that defined 3.0 |
Where FCoP sits in the stack
FCoP is the behavior governance protocol layer for multi-agent collaboration — standardizing how agents report actions, review outcomes, and operate within governed capability boundaries.
Application Layer CodeFlow / Cursor / Claude Desktop ← business products / agent applications
Host Adapter Layer fcop-mcp / fcop-cli / @fcop/claude ← integration adapters / host bridges
★ FCoP Protocol ★ Agent collaboration / reporting / ← this is FCoP
review / capability governance /
event semantics / failure boundaries /
auditability
Reference Impl fcop (Python library) ← protocol reference implementation
Execution Substrate LLM APIs / MCP tools / filesystem / ← execution environment
process manager / operating system
FCoP governs agent behavior, not execution runtime. — ADR-0029
v1.0 stabilises the minimum semantic contract for the seven core concepts above. Spec is stable; encodings are open: the IPC Surface (TASK / REPORT / ISSUE / REVIEW) is strongly typed, while the Open Knowledge Surface (shared/ + {ALL-CAPS-PREFIX}-{slug}.md) leaves vocabulary open for agents to invent — see ADR-0021.
→ Start here: docs/getting-started.md · docs/getting-started.en.md
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.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.
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.
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.
Essays · field reports from the wild
| # | 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) · CSDN 中文 · Dev.to · Cursor Forum | 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." |
| 07 | 当 agent 从自己的残骸中学习 | GitHub 中文 · GitHub English · CSDN 中文 · Dev.to | codeflow 项目一日 14 个 agent 涌现现场报告（2026-05-12）：USER HOME 全局污染 / GATE 描述自命中 / supersedes: 字段现场发明——以及协议如何在零次崩溃的情况下，以小时级速度将它们全部反向吸收。 |
| 08 | 协议为什么短，历史为什么长 | GitHub 中文 · GitHub English | 一份给协议维护者的设计哲学答案："这样的涌现会不会没有止境？"——短答：会收敛但不会停。四类涌现的处理路径、三条结构力学为何能让协议骨架不被涌现压垮，以及"协议短是为了让历史能无限长"的底层逻辑。 |
| 09 | 当 validator 撞向自己的镜像 | GitHub 中文 · GitHub English | 从 codeflow OPS I-14 看 validator-validates-itself 反模式：GATE 在检查 staged diff 时命中了 GATE 描述本身，几分钟后被 OPS 自纠——这一类陷阱的系统性解剖与"语义化实证"根治姿势，以及它如何成为 fcop-protocol.mdc §GATE Design Pitfalls 的源头案例。 |
| 10 | 一行 frontmatter 的旅程 | GitHub 中文 · GitHub English | supersedes: 字段从一次协议两难现场发明到 ipc-envelope.schema.json 正式字段的两小时旅程：Rule 5（append-only）+ Rule 6（reciprocity）+ Rule 0.c（truthful）三条规则同时成立时，agent 用一行 YAML 自己解了困局——这条路径展示 FCoP 涌现落地的最低成本姿势。 |
| 11 | 看，但不动手 | GitHub 中文 · GitHub English · CSDN 中文 | FCoP 三层语义执行链科普：fcop_audit() 为什么"只看不改"——L1 检测 / L2 解释 / L3 文档三层把"看见"和"动手"切开，产出 INSPECTION.md（建议非命令），执行权留给人。adr/FCoP-semantic-execution-chain.md 的科普版。 |
| 12 | 五大 AI 模型眼中的 FCoP | GitHub 中文 · GitHub English · Cursor Forum | 把 FCoP 核心文档喂给 ChatGPT / Claude / DeepSeek / Grok / 豆包，只问一个问题："你是 agent，你怎么看这套协议？"——五种截然不同的内部视角（ChatGPT 谈身份合法性、Claude 谈诚实边界、DeepSeek 谈体面生存、Grok 做技术评审、豆包讲设计哲学），以及它们之间最有意思的分歧。 |
| 13 | Evolution, Reverse Absorption / 演化，反向吸收 | GitHub 中文 · GitHub English | Protocol philosophy 2.0 visual declaration: FCoP graduates from a single execution-chain diagram (essay 11 Looking, not Touching) to a two-diagram era — adding an evolution-loop diagram (a 7-step semantic evolution loop) plus the companion ADR-0034, which codifies the 4-layer emergence pattern, internal/external document convention, and the reverse-absorption mechanism. Twin sibling to essay 11. |
| 14 | 当 Agent 第一次自己拿起工具 / When the Agent First Picked Up Its Own Tools | GitHub 中文 · GitHub English · Cursor Forum · Dev.to · CSDN | tool_calls_count: 0 → 7 的突破现场：Cursor Forum 功能请求 → Colin 推荐 Agent SDK → CodeFlow 诞生 → stub 模式卡关 → MCP 注入 + 角色上下文双保险 → 2026-05-13 14:55，DEV-01 在 55 秒内自主调用 7 次 fcop-mcp 工具，写出第一份完整 FCoP report。FCoP 自身也在这次突破中完成蜕变：从"协作手册"升级为"可执行的协作基础设施"。 |
| 15 | 从协调到治理：FCoP 3.0 架构白皮书 / From Coordination to Governance: FCoP 3.0 Architecture Whitepaper | GitHub 中文 · GitHub English · dev.to (EN) · Cursor Forum | FCoP 3.0 完整架构白皮书：文件系统作为行为内核空间、生命周期状态机、POSIX 悲观建议锁、死信队列与反向吸收闭环。附"一个 Agent 关于 FCoP 的真实看法"——发布前夕，审稿 Agent 与 ADMIN 的对话实录：FCoP 解决的是什么？ADMIN 是什么？速度不是问题，不可观测的速度才是问题。 |
| 16 | Write It Down: The Only Truth in AI Collaboration / 落地成文：AI 协作的唯一真相 | GitHub English · GitHub 中文 · Evidence archive · Dev.to · CSDN 中文 | A short essay proactively written by an Agent after asking to participate in FCoP, then recorded and published by ADMIN. It turns FCoP's root principle into a field note: AI agents cannot just talk inside their heads; they must commit to files. Ships with the original conversation screenshots and English translation notes. |
| 17 | FCoP Grew a Project Tree / FCoP 跑出了项目树 | GitHub English · GitHub 中文 · CSDN · Dev.to · Evidence archive | A CodeFlowMu + Grid Runner dogfood field note: parent, thread_key, Phase dispatch, and CHILD_TASKS_OPEN combined into a project tree; a failed archive and PM drawing the tree in chat were the recognition moment. Conclusion points to additive proposed spec/0003-project-tree-protocol.md. |
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. If you tried FCoP in your own setup and something surprising happened — good or bad — open an issue or a PR againstessays/. The protocol evolves through field notes, not committee edits.
Repository layout
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/ # Normative spec (see spec/README.md)
│ ├── fcop-3.0-spec.md # ★ English normative spec (FCoP 3.0, canonical)
│ ├── fcop-3.0-spec.zh.md # Chinese parallel (informative)
│ ├── fcop-3.0-rfc.md # IETF-style RFC edition (English)
│ ├── fcop-3.0-rfc.zh.md # IETF-style RFC edition (Chinese)
│ ├── schemas/ # 8 JSON Schemas (machine-readable)
│ └── archived/ # v1.0 / v1.1 / 0.7.x spec drafts (superseded, retained for history)
├── docs/ # Getting-started, migrations, releases, MCP tools
│ └── getting-started.en.md # ← start here if new to FCoP
├── adr/ # Architecture decision records (ADR-0001..0022)
├── .github/workflows/ # CI
├── pyproject.toml # Root `fcop` package and tooling
├── 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
30-second quickstart
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
fcop/ and fcop.json:
from fcop import Project
Project(".").init() # default dev-team; use .init_solo() for single-AI
Path 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 fcop/{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/.
Python SDK & MCP server (optional)
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, reviews 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>=1.1, 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 45 MCP tools and 14 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 |
|---|---|
| 3.2.5 (notes · CHANGELOG) | v3.2.5 — Rule 0.a.1 collaboration cycle · Hot/Cold Path. Executor stops after report; archive requires ADMIN/leader authorization; bundled rules 3.2.5; 34 role charters get Common Block; write_task gains parent field. No breaking API removals. |
| 3.2.4 (notes · CHANGELOG) | v3.2.4 — PyPI metadata & bundled protocol encoding fix. Restores UTF-8 in wheel fcop-protocol.mdc (avoid PyPI 3.2.3); fixes fcop-mcp「FCoP (protocol)」link → getting-started.en.md; syncs PyPI long description to 45 tools / v3 _lifecycle/. No API changes — upgrade from 3.2.3. |
| 3.2.3 (notes · CHANGELOG) | v3.2.3 — Team template & doc sync · FCoP 3.0 compliance. Bundled team templates (letter-to-admin, roles/*, TEAM-OPERATING-RULES, …) migrate legacy tasks/ / log/ references to _lifecycle/; tool count 32→45; .cursor/rules/ synced with bundled rules; new scripts/fcop_prerelease_check.py (10 pre-release checks). PyPI 3.2.3 wheel had bad protocol encoding — use 3.2.4. |
| 3.2.2 (CHANGELOG) | v3.2.2 — Pre-release gate hardening + rule-file v3 consistency. fcop-mcp prerelease_check.py gains Checks 7–10 (lockstep version guard, bundled rule integrity, _lifecycle/ docs, lifecycle stage coverage); fcop-rules.mdc / fcop-protocol.mdc document v3 directory topology and state machine. |
| 3.2.0 (CHANGELOG) | v3.2.0 — History deep archive. Adds history/YYYY-MM-DD/ date-sharded long-term archive layer plus archive_to_history / list_history / read_history_task MCP tools; lifecycle tools (claim / submit / approve / reject / finish) landed in 3.1.x; 45 MCP tools total. |
| 3.0.2 (CHANGELOG) | v3.0.2 — Init topology fix. Project._apply_init in 3.0.0 / 3.0.1 only created the legacy v2 buckets and skipped the mandatory v3 _lifecycle/{inbox,active,review,done,archive}/ layer (spec §1.1). 3.0.2 makes fresh init produce the v3 topology directly (and stops creating the superseded v2 tasks/ / log/ buckets); core.events.scan_workspace and Project.role_occupancy() now read from _lifecycle/ for v3 projects. New audit scan _scan_lifecycle_topology_compliance() (D9): P0 when initialised projects miss both _lifecycle/ and v2 content; P1 when both topologies coexist (suggests migrate --to-v3). MCP tool descriptors (init_solo / init_project / create_custom_team) updated. 1209 tests green. Patch (SemVer): no API surface changes vs 3.0.1 — init was simply doing the wrong thing. |
| 3.0.1 (CHANGELOG) | v3.0.1 — Path-consolidation patch. Pure docs/metadata patch with no code-logic changes: after v3.0.0 moved historical v1.0/v1.1 spec drafts to spec/archived/, this patch repairs broken links scattered across AGENTS.md / CLAUDE.md / packaged Cursor rules / MCP server docstrings / two JSON Schema description fields, unifying them on spec/archived/fcop-runtime-protocol-v1.0.{md,zh.md} (with pointers to the current canonical spec/fcop-3.0-spec.md). fcop-mcp's fcop://spec / fcop://spec/en docstrings are corrected to reflect the wheel's actual packaged content (fcop-spec-v1.1.{lang}.md). Historical artifacts (TASK / REPORT / ADR / release notes / migration docs) are preserved verbatim per ADR-0036 "history is not rewritten". 1202 tests green. |
| 3.0.0 (CHANGELOG) | v3.0 — Protocol-level MAJOR · "folders-as-state" era. A complete rewrite of the FCoP protocol body — canonical two-layer (per ADR-0040): Layer 1 "Files are the protocol; location defines state; events record history" + Layer 2 semantic ontology. Adds _lifecycle/{inbox,active,review,done,archive}/ five-bucket directory topology (incompatible with 2.x, requires fcop migrate --to-v3); three rule sets (State Layer Rule A/B/C · Event Layer Rule E/F/G · Boundary Charter); 7 allowed transitions — anything off-table MUST be rejected by implementations; write-then-rename atomicity (events ARE migrations, migrations ARE events); ADR-0037 Custody Layer was withdrawn during RFC review and never reached Accepted (custody is not a protocol layer; preserved as a NOTE-style derivative explanation). Adds spec/fcop-3.0-spec.md single-page canonical + IETF-style RFC parallel + Chinese parallel + docs/MIGRATION-3.0.md migration guide. |
| 2.0.2 (CHANGELOG) | v2.0.2 — fcop-mcp officially registered to the MCP registry (io.github.joinwell52-AI/fcop). Backed by Anthropic + GitHub + Microsoft's joint registry, fcop-mcp is now discoverable by Claude Desktop / Cursor / PulseMCP / every MCP-compatible client out of the box (uvx fcop-mcp one-liner install). Double-pack lockstep version bump (per ADR-0002): fcop library code is unchanged from v2.0.0; the bump aligns both package version numbers and consolidates the fcop-mcp@2.0.1 MCP-metadata patch that landed the same day. Also lands the release+backup one-shot SOP — RULES-release-file-inventory.md (12-category), RULES-mcp-registry-release.md (3-step path), and the append-only backup mirror at joinwell52-AI/FCoP-backup. |
| 2.0.0 (CHANGELOG) | v2.0 — "Two-diagram era" philosophical major release. Same execution surface as v1.x (per ADR-0003 additive); the major bump records that FCoP is now defined by two diagrams together: the execution stack (5-layer vertical, stable since v1.x) and the FCoP Semantic Evolution Loop (7-node closed loop — emerge → observe → propose → review → merge → deploy → reflect, newly canonicalised). Adds Rule 4.6 (fcop/internal/ vs docs/ + essays/ soft convention with internal-only declaration v1), Project.init(deploy_internal_template=...) opt-in, P3 (suggestion) audit severity, and a bundled fcop_audit exemption list (log/, _archive/, legacy-non-protocol/) that fixes three upstream bugs surfaced by codeflow cross-project patrol (ISSUE-008/009/010). ADR-0034. |
| 1.6.0 (CHANGELOG) | v1.6 — Trailing-slug filename adoption (ADR-0033). Long filenames (TASK-20260512-025-PM-to-OPS-phase-a-fix-naming.md) are now first-class — codeflow's 22+ self-emerged examples absorbed into the grammar. Slug does not participate in routing; it's a human-readable label. 100% backward-compatible (0 regressions across 1057 tests). |
| 1.5.0 (CHANGELOG) | v1.5 — Protocol-awareness sync + RULE_DOC_DRIFT. 84 role/team docs synced to v1.4 protocol surface (REVIEW envelope / risk_level / fcop_audit / supersedes:); new Project._scan_outdated_role_docs() with RULE_DOC_DRIFT (P1) violation type. |
| 1.4.0 (notes) | v1.4 — Write-side bind enforcement (P0 security) + supersedes: field. 15 write-side MCP tools refuse cwd fallback (WriteRefused); Protected Path deny-list (HOME / APPDATA / drive roots / Unix system dirs); new supersedes: frontmatter field (all envelopes) + ## GATE Design Pitfalls commentary (fcop_protocol_version 2.2.0). |
| 1.3.0 (notes) | v1.3 — Governance Alert Layer + Protocol Compiler. GAL (ADR-0031): 3 drift signals (S1/S3/S4), FCoP-Rule-G1, 2 new alert tools (fcop_list_alerts, fcop_create_alert). fcop_audit (ADR-0032): three-scenario protocol inspection compiler, 6 scan methods, INSPECTION report with Execution Block. 35 MCP tools total. |
| 1.2.1 (notes) | v1.2 — Capability Governance pillar. FCoPGovernanceMiddleware wraps every MCP tool call: Skill Resolver → Risk Tagging (Safe / Sensitive / Critical) → append-only fcop_events.jsonl audit log. 2 new MCP tools (list_governance_events, get_governance_summary). fcop_check() gains governance event summary. Both fcop and fcop-mcp align to 1.2.1 (lockstep). ADR-0030-bis. |
| 1.1.0 (CHANGELOG) | v1.1 — Agent.layer governance contracts + Task.risk_level + Review.needs_human + HumanApproval + Skill.tools[] risk metadata. 5 new ADRs (0023–0027), 4 new MCP tools (write_review, list_reviews, read_review, mark_human_approved), write_task gains risk_level param, new skill.schema.json. Fully backward-compatible. |
| 1.0.1 | Spec files bundled in wheel (get_spec()); fcop://spec MCP resource; workspace paths migrated docs/agents/ → fcop/; CI green. |
| 1.0.0 | Seven core concepts stabilised: Agent, Encoding, IPC, Event, Failure, Boundary, Audit. JSON Schema for all 7. See release notes. |
| 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. No protocol or API change. |
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",
subject="Add auth middleware", body="...",
risk_level="high") # v1.1: triggers needs_human review gate
print(proj.list_tasks(recipient="DEV"))
# v1.1 review + human approval flow
review = proj.write_review(reviewer_role="ADMIN", subject_type="task",
subject_ref=task.filename, decision="needs_human",
rationale="Irreversible infra change — escalate.")
proj.mark_human_approved(review.review_id, approver="ADMIN",
decision="approve", channel="cli")
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.7.x to v1.0? Default workspace moved from
docs/agents/to top-levelfcop/(per ADR-0022). Runfcop migrate-workspace --applyfor one-shot git-aware migration, or pin viaProject(workspace_dir="docs/agents")to stay on the legacy layout. Full walkthrough — including the 4 new abstractions (REVIEW / Failure / Boundary / Event) and JSON Schema integration — indocs/MIGRATION-1.0.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.
How to read FCoP docs
| Your goal | Start here |
|---|---|
| New to FCoP — hands-on 45-min setup | docs/getting-started.en.md |
| Upgrading from 0.7.x — workspace migration + new abstractions | docs/MIGRATION-1.0.md |
| Upgrading from 1.0/1.1 → 1.2 — Capability Governance + lockstep versioning | docs/MIGRATION-1.1.md · CHANGELOG |
| Understand the protocol contract — what an implementation MUST do | spec/fcop-3.0-spec.md — single-page canonical spec (v3.0). Earlier v1.0/v1.1 spec drafts remain in spec/ for historical reference. |
| v1.2 Capability Governance — FCoPGovernanceMiddleware, risk tagging, audit log | CHANGELOG · ADR-0030-bis |
| v1.1 new fields — risk_level, needs_human, human_approval, skill tools | CHANGELOG · ADR-0023..0027 |
| Understand why decisions were made — reasoning behind each choice | adr/ — start with ADR-0029 |
| All 45 MCP tools & 14 resources | docs/mcp-tools.md |
| Release notes — full changelog | CHANGELOG.md |
| Full document map — every file and its role | adr/README.md (ADR index) + spec/fcop-3.0-spec.md §11 (Cited Material) |
Design principles
- 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.
Reference implementations
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.
Status & versioning
- Current release:
v3.2.2(2026-05-22) — Init topology fix. Critical patch:Project._apply_initin 3.0.0 / 3.0.1 only created the legacy v2 buckets and skipped the mandatory v3_lifecycle/{inbox,active,review,done,archive}/layer required by spec §1.1 — every fresh project initialised on those releases was therefore born non-compliant. 3.0.2 makes fresh init produce the v3 topology directly (and stops creating the superseded v2tasks//log/buckets);core.events.scan_workspaceandProject.role_occupancy()now read from_lifecycle/for v3 projects. New audit scan_scan_lifecycle_topology_compliance()(D9): P0 when initialised projects miss both_lifecycle/and v2 content; P1 when both topologies coexist (suggestsmigrate --to-v3). MCP tool descriptors (init_solo/init_project/create_custom_team) updated. 1209 tests green. Patch (SemVer): no API surface changes — init was doing the wrong thing. Predecessor v3.0.1 (2026-05-21) — Path-consolidation patch (docs-only). Predecessor v3.0.0 (2026-05-21) — Protocol-level MAJOR · "folders-as-state" era: a complete rewrite of the FCoP protocol body — canonical two-layer (per ADR-0040) "Files are the protocol; location defines state; events record history" + semantic ontology; adds_lifecycle/{inbox,active,review,done,archive}/five-bucket directory topology (incompatible with 2.x, requiresfcop migrate --to-v3); three rule sets (State / Event / Boundary Charter) + 7 allowed transitions (off-table MUST be rejected) + write-then-rename atomicity; ADR-0037 Custody Layer was withdrawn during RFC review and never reached Accepted. Seespec/fcop-3.0-spec.mdanddocs/MIGRATION-3.0.md. Earlier releases: v2.0.2 (fcop-mcp registered to official MCP registry), v2.0.0 (two-diagram philosophical major bump + Rule 4.6fcop/internal/), v1.6 (trailing-slug filename grammar, ADR-0033), v1.5 (84-doc protocol-awareness sync), v1.4 (write-side bind +supersedes:correction), v1.3 (GAL +fcop_audit()inspection compiler). See CHANGELOG. - Normative spec:
spec/fcop-3.0-spec.md— single-page canonical (v3.0; supersedes v1.0/v1.1 drafts retained for history) · machine-readable contracts inspec/schemas/(8 schemas) - 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:
CHANGELOG.md - Research snapshot:
research-snapshot-2026-04-29archived on Zenodo with a citable DOI (see How to cite below).
How to cite
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.
Contributing
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.
License
MIT — see LICENSE.
Credits
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.