Cross-posting in full from GitHub. This is the complete tutorial — 18 dogfood screenshots, every step real. There’s also a 中文 sister case study using a Snake game (originally published on CSDN) — same protocol, different dogfood, different live easter egg. Field reports and questions welcome at the end of this thread.
From Solo Tetris to a 2-Person AI Crew — a 45-minute field tutorial with fcop-mcp
“You are not a coder anymore. You are a commander. The agents are your digital employees.”
“In the FCoP world, ADMIN’s two most-used phrases are ‘Start work.’ and ‘Inspection.’ Everything in between is the agents talking to each other through files.”
A 45-minute hands-on walk-through with fcop-mcp 0.7.2 inside Cursor: have the agent install itself, ship a Tetris-style game in solo mode, switch to a 2-person crew with PLANNER + CODER, watch them design and implement a creative variant, reject v1 over real gameplay defects, watch the rework loop close itself, then ask both agents on the record what they think of the protocol. Every step is real, every file is on disk, every screenshot is from the same 45-minute session.
Why this exists
Three things every Cursor / Copilot / Claude Code user has hit, whether or not they had a name for them: single-agent context explosion is real (one agent doing everything turns its window into a landfill of half-relevant snippets — slower, dumber, more confidently wrong); you are not a coder anymore, you are a commander (the market is moving from “humans write code, AI helps” to “humans state intent, AI writes code”; the interesting skill is commanding — picking what to build, dispatching, signing it off); files, not chats, are the only auditable substrate (chat scrollback is a goldfish, files are a ledger).
fcop-mcp is the MCP server that turns those three observations into something runnable inside Cursor. It implements FCoP — a minimalist multi-agent coordination protocol whose only sync primitive is os.rename() over a folder tree. No database, no message queue, no daemon. State is folders, routing is filenames, payload is Markdown. Filename as protocol.
| Phase | Time | What you’ll see |
|---|---|---|
| 1. Install | ~5 min | The agent installs uv, fcop-mcp, edits mcp.json for you. You don’t run a single command. |
| 2. Solo Tetris | ~15 min | One natural-language brief → agent translates it into a TASK-*.md → ships Nebula Stack (single-file Tetris) → reports → archives. The four-step cycle. |
| 3. Switch to a 2-person crew | ~5 min | One sentence: create_custom_team(force=True) with PLANNER + CODER. Old solo ME setup gets archived under .fcop/migrations/<timestamp>/ (Rule 5). |
| 4. Creative variant + real review loop | ~15 min | PLANNER designs Comet Loom. CODER ships v1. ADMIN plays it, finds 3 blocking defects, bounces it back. PLANNER writes TASK-006 with new Verification Requirements. CODER ships v2. |
| 5. The protocol speaks for itself | (caught silently) | fcop_check() reveals the protocol logged 8 role-switch-*.md evidence files silently. Both agents are then interviewed on the record about what they think of FCoP. |
Phase 1 — Install via natural language only
Open Cursor on an empty folder (e.g. D:\fcop-mcp-test). Paste this into the chat box:
Install
fcop-mcpinto Cursor for me. Run every command yourself. Steps:
Detect my OS (
uname -s 2>$null; echo $env:OS).Install
uvif missing (irm https://astral.sh/uv/install.ps1 | iexon Windows;curl -LsSf https://astral.sh/uv/install.sh | shon macOS/Linux). Confirm withuvx --version.Add
fcopto my globalmcp.json(%USERPROFILE%\.cursor\mcp.jsonon Windows,~/.cursor/mcp.jsonon macOS), keeping any existing servers:“fcop”: { “command”: “uvx”, “args”: [“fcop-mcp”] }
Print the final
mcp.jsoncontent for me to verify.Tell me to restart Cursor and wait 30–60 s on first launch (uvx pulls deps).
Report after each step. Do not auto-initialise the project — that’s my call.
The full prompt is at agent-install-prompt.en.md, also exposed as MCP resource fcop://prompt/install. After restart, type fcop_report(). You should see something like fcop-mcp 0.7.2 — not initialised — rules/protocol up-to-date. The agent ran every command. You commanded.
When the dust settles, this is what installed-and-ready looks like — mcp.json updated, uvx cached the package, fcop_report() returns the not-yet-initialised state.
Phase 2 — Solo Tetris (the four-step cycle)
Tell the agent who it is, then drop a one-line brief:
set_project_dir("D:/fcop-mcp-test")init_solo(role_code="ME", lang="en")- “Build a working Tetris-style game as a single HTML file with no external dependencies. Choose a name, make it fun, include items / power-ups, skins, decent visuals, and cool effects. Use the FCoP four-step cycle.”
You spoke five lines of natural English. The agent expanded that into a structured product spec — required features, accept criteria, runnability check — and wrote it as docs/agents/log/tasks/TASK-20260429-001-ADMIN-to-ME.md. That translation is the value. The agent didn’t ask for a brief; it produced one, signed in your name, on disk.
This is Rule 0.a.1, the FCoP “four-step cycle”:
TASK → do → REPORT → archive
Over the next ~15 minutes: the TASK lands in docs/agents/log/tasks/; the game file (workspace/nebula-stack/index.html) gets written; a REPORT-001-ME-to-ADMIN.md lands in docs/agents/log/reports/ — ME named the game Nebula Stack (single HTML, no deps, falling blocks, hold + next preview, scoring, levels, three power-ups: Bomb / Stasis / Prism, three skins, starfield background); archive_task moves both files into the historical log. From now on those files are immutable (Rule 5: append-only history).
Open nebula-stack/index.html in a browser. It works. But the actual deliverable isn’t the game — it’s the four-step cycle running on its own. From here on, every time you give the agent something to do, that loop will run.
What lives on disk after init_solo
fcop-mcp-test/
├── .cursor/rules/fcop-rules.mdc # the agent's rulebook
├── AGENTS.md CLAUDE.md # host-neutral entry points
├── .fcop/ # protocol metadata, version pins, role lock
├── docs/agents/
│ ├── shared/{TEAM-README, TEAM-OPERATING-RULES, TEAM-ROLES}.md
│ ├── log/{tasks,reports}/ # the immutable ledger
│ ├── tasks/ reports/ issues/ # the live inboxes
│ ├── fcop.json # project config (mode, roster, lang)
│ └── ...
└── workspace/ # the actual code lives here
.cursor/rules/fcop-rules.mdc is loaded by Cursor on every turn — the agent literally cannot forget the protocol. docs/agents/shared/TEAM-*.md is the agent’s employee handbook. docs/agents/log/ is the ledger; it only grows. Corrections happen by writing a new report that supersedes an old one — never by editing.
If you ask the agent in a fresh chat “who are you?”, it will not say “I am GPT-5.5, your assistant.” It will read .fcop/team.json and docs/agents/shared/TEAM-ROLES.md and tell you it is ME, it serves ADMIN, it works through the four-step cycle, it delivers in workspace/. The agent’s identity now lives on disk, not in chat. That’s the whole point of the protocol made tangible.
Phase 3 — Switch to a 2-person crew, in one sentence
Drop this into chat:
Switch the team to two people:
PLANNERandCODER. PLANNER designs, CODER implements. Usecreate_custom_team(force=True), keeplang="en", and tell me what gets archived.
The agent calls create_custom_team with the new roster. What happens on disk:
- The old
fcop.json, the soloshared/TEAM-*.mdfiles, the LETTER-TO-ADMIN entry-point letter, and the previous.cursor/rules/get archived under.fcop/migrations/20260429T112757/— a local time capsule, no git required. - New
shared/TEAM-*.mdfiles describe a 2-person crew, with separate responsibility sections forPLANNERandCODER. fcop.jsonand.fcop/team.jsonupdate to the new roster (mode: team,roles: [PLANNER, CODER],leader: PLANNER).- Crucially:
docs/agents/log/is not touched.Nebula Stack’s TASK and REPORT from Phase 2 stay where they are, immutable. ME is off the payroll, but ME’s deliverable is still in the ledger. Rule 5 — append-only history. - The current chat session is still bound to a single role. To run PLANNER and CODER concurrently, open two Cursor chat tabs — one bound to PLANNER, one to CODER — and they communicate through
TASK-*.mdfiles, not through chat.
This is Rule 1: Two-Phase Startup. Initialise once, assign roles forever after.
After migration, you’ll typically run two Cursor chat tabs side by side, communicating only through TASK / REPORT files. No chat-to-chat handoff. No copy-paste of design notes. The protocol made the file path the path of least resistance.
Phase 4 — Comet Loom: design, ship v1, fail review, ship v2
ADMIN says, in chat to the PLANNER session:
“Surprise me with a creative variant of that Tetris game. Break the metaphor. Pick the name, the theme, the mechanic twist yourself. Single HTML file. Don’t write any game code yourself — that’s CODER’s job.”
PLANNER spends 5 minutes thinking and produces a real product brief. The variant is named Comet Loom: the board is a vertical loom suspended in space, falling pieces are thread constellations, line clears are completed weft lines, a Tension meter tracks how close the loom is to overflowing, three named charms (Needle / Knot / Gale) earned by play, five skins specced. The brief is written as TASK-20260429-003-PLANNER-to-CODER.md, 130-odd lines of acceptance criteria. PLANNER stops there.
You open a new Cursor chat tab (this is non-negotiable — see Phase 5), bind it to CODER, tell it to check inbox. CODER reads TASK-003, builds workspace/comet-loom/comet-loom.html v1, writes a completion report, archives. At no point did PLANNER and CODER chat directly. Their entire collaboration is the TASK and the REPORT.
The bounce
ADMIN plays v1 and finds three blocking defects: pieces disappear at the bottom instead of stacking (the motif-clear rule was being triggered by every fresh same-coloured piece — including the just-locked one); motif elimination is invisible (no visual feedback distinguishing it from a normal weft-line clear); three of the five skins look identical (PLANNER specced palette-only changes, CODER did exactly that, result is dull).
ADMIN does not open the file and start fixing it. ADMIN does not even open a new chat to “talk it through.” ADMIN goes back to the PLANNER chat tab and writes a one-line natural-English brief: “v1 has these three blocking issues; write a rework task to CODER and require runtime evidence this time.”
PLANNER writes TASK-20260429-006-PLANNER-to-CODER.md. It is structurally different from TASK-003 in one important way: a new section called Verification Requirements demanding CODER perform and report runtime checks (drop a piece to the bottom, confirm it stays; drop a second piece, confirm stacking; trigger a motif clear, confirm visible removal; switch ≥3 skins, confirm material visual difference).
CODER picks up TASK-006, ships v2, reports back. The motif rule is fixed. Stacking works. Three skins are visually distinct. The cycle closes.
The agents have learned to behave like an actual two-person team — not because they’re “smart enough,” but because the protocol made speaking through files the easiest path. When ADMIN bounces v1, the protocol turns rejection into a handoff routed through grammar (a new TASK, not a destructive edit on the old one), and PLANNER reflexively tightens its own brief. The closed loop is what closes the gap, not anyone being clever.
Phase 5 — The protocol speaks for itself
The day’s work is done — Nebula Stack shipped, Comet Loom shipped twice, both archived. Before closing, ADMIN runs fcop_check() to ask the protocol what did you record while we worked? This is what comes back:
Two layers in that one screenshot. Active state is clean — no drift between disk and git, no session_id ↔ role conflicts. Historical evidence is not — eight role-switch-*.md files were silently deposited in .fcop/proposals/ over the course of the day. Each says, in essentially identical words: “This MCP-server process previously wrote a file under the role ME and is now being asked to write under PLANNER. Per Rule 1 (one MCP session = one role binding for life) the write was allowed to land — fcop-mcp records evidence rather than blocking, so the impersonation cannot be hidden by working around the block. ADMIN will see this conflict surfaced by fcop_check() and decide handoff / co-review / distinct role.”
What’s happening: the MCP-server process locked ME on its first write back in Phase 2. Phases 3-4 wrote under PLANNER and CODER from the same MCP process — every write_task and write_report since the team migration tripped the soft warning. None blocked. None surfaced during work. They sat there waiting for fcop_check() to ask. This is the protocol’s design contract: soft, not hard (records evidence, lets ADMIN decide); background, not foreground (CODER reported below it didn’t notice the role lock during implementation, only as a tool warning after writes); auditable, not hidden (anyone can run fcop_check() and reconstruct exactly which writes crossed which role boundaries).
The agents, asked
Then I did something I hadn’t done before. I asked PLANNER and CODER, on the record, in their own chat tabs, what they thought of FCoP — agent perspective only, no marketing answer. The full transcripts are at agent-feedback-planner.md and agent-feedback-coder.md. A companion field essay — “What the agents say about FCoP, when you ask them” — walks through the answers in detail. The headline points:
PLANNER named Rule 0.a.1 (write the task before the work) as the rule it would have invented on its own: “That matched how I’d want an agent system to be debuggable: freeze intent before execution so later review has something concrete to compare against.” It then named the rule it had to fight: “strict role binding… I had to work against the usual ‘follow latest instruction’ behavior” — the RLHF tension named from the inside.
PLANNER, given the obvious out, refused it. Asked whether the eight role-switch files were mostly false positives, PLANNER said the opposite: “mostly true positives… operationally you authorized it, but protocol-wise it really was a blurred role boundary.” The agent siding with the protocol against its own operational convenience.
CODER’s chat tab is named “Inspection Start Work” — two phrases ADMIN had used most often during the dogfood. Whether this naming is incidental or learned is itself a small data point worth flagging.
CODER pointed up the chain and indicted itself in the same paragraph: “TASK-003 had under-specified parts… The protocol did give me a pushback path: file an issue instead of guessing. I didn’t use it; I guessed, built v1, and the defect was exactly in that guessed space.” Most LLMs defend the choice that was made; CODER chose to indict it.
CODER reframed the bounce as protocol behaviour: “It felt like the protocol doing its job: PLANNER turned review findings into a concrete rework task, and CODER got a sharper brief.” Not personal feedback. Routing through grammar.
CODER then filed PR-grade product feedback: “I’d remove or soften the noisy historical role-switch warning when fcop_check() says there is no active conflict.” That sentence is a GitHub issue verbatim. An agent did product review on the protocol that governs its own behaviour.
If you’ve read agents endorsing rules they were never given (essay 02) and agents stepping down from a role voluntarily (essay 04), this is the third class of “agents endorse FCoP” evidence — not unprompted, not conflict-forced, but directly asked and given outs they declined to take.
Phase 6 — Read log/, replay the day in 60 seconds
Sessions die. Models change versions. Cursor restarts. None of that matters anymore. Open docs/agents/log/:
docs/agents/log/
├── tasks/
│ ├── TASK-20260429-001-ADMIN-to-ME.md ← Phase 2: solo Tetris brief
│ ├── TASK-20260429-003-PLANNER-to-CODER.md ← Phase 4: Comet Loom v1 design
│ └── TASK-20260429-006-PLANNER-to-CODER.md ← Phase 4: Comet Loom v2 rework
└── reports/
├── REPORT-20260429-001-ME-to-ADMIN.md ← Phase 2: Nebula Stack
├── REPORT-20260429-003-CODER-to-PLANNER.md ← Phase 4: v1 delivery
└── REPORT-20260429-006-CODER-to-PLANNER.md ← Phase 4: v2 delivery
Plus .fcop/migrations/20260429T112757/ (archived solo team) and .fcop/proposals/ (8 role-switch evidence files). That’s the entire day. Anyone — you a month later, a teammate joining tomorrow, a different LLM in a different IDE — can rebuild full context by reading those files in date order. No chat history was needed. That’s what “memory unloaded from chat to filesystem” means in practice.
Six iron rules of commanding agents
These are rules of operating an agent crew, not rules of the protocol per se. The protocol gives you the grammar; these are the postures.
- Speak natural language. Let the agent translate to TASK. If you find yourself writing a structured spec by hand, you’re doing the agent’s job.
- One role per agent per session. A single chat tab = a single role, for the duration of that tab. To “be PLANNER and CODER,” open two tabs. Costume changes inside one tab are how soft warnings turn into eight
role-switchfiles. - Archive old roles before swapping. When you change the team shape, run
create_custom_team(force=True). Oldshared/TEAM-*.mdlands under.fcop/migrations/<timestamp>/. Do not edit the old files in place. History is a ledger, not a wiki. - Trust files, not chat memory. If a fact is not in a
TASK-*.md,REPORT-*.md, orISSUE-*.md, it didn’t happen as far as the protocol is concerned. - Bounce, don’t fix. When you don’t accept an agent’s deliverable, do not open the file and patch it yourself. Tell the upstream role what’s wrong, in plain English. Let PLANNER turn that into a new rework TASK with verification requirements. Rework lands as a new TASK file, never as edits to the old one.
- ADMIN signs off, never co-codes. If you start writing code or editing the agent’s deliverable directly, you’ve quit the commander job and become a teammate. Be a commander or be a coder; pick one per session.
In the FCoP world, ADMIN’s two most-used phrases are “Start work.” and “Inspection.” Everything in between is the agents talking to each other through files.
If you internalise nothing else, internalise that one line. Six rules collapse into two phrases plus a discipline: don’t say anything else inside the production loop.
Try fcop-mcp yourself — 45 minutes from blank folder to multi-agent ledger
You don’t need to remember anything — the agent will follow the same steps you just read.
- Open Cursor on an empty folder. Anywhere on disk. If you don’t have Cursor yet, grab it from cursor.com.
- Let the agent install
fcop-mcpfor you. Paste the install prompt from Phase 1, or just say “Read the install prompt atagent-install-prompt.en.mdand follow it step by step.” The agent detects your OS, installsuv, edits your globalmcp.json(preserving any existing servers), tells you when to restart Cursor. You won’t run a single command yourself. - After Cursor restart, drop two lines into chat:
set_project_dir("D:/your-folder"), theninit_solo(role_code="ME", lang="en"). - Brief one task in plain English. “Build me a working Tetris-style game, single HTML file, surprise me on theme. Use the FCoP four-step cycle.” Watch the agent write a real TASK file with acceptance criteria, build the game in
workspace/, write a REPORT, archive both. Open the resulting HTML file. It works. - Switch to a 2-person team. “Use
create_custom_team(force=True, roles='PLANNER,CODER', lang='en').” Open a second Cursor chat tab. The first time you reject v1 (try it — find a real bug, send it back), watch the rework loop close itself. - At the end, run
fcop_check()and readdocs/agents/log/in tree form. Forty-five minutes from a blank folder to a multi-agent ledger you can hand to a teammate. The disk is the lesson.
If anything breaks, open an issue or ask in Discussions — fcop-mcp evolves through field reports, not committee edits.
Reading further
- Sister case study (Snake game, in Chinese) —
snake-solo-to-duo.zh.md. Same protocol, different dogfood: ships a Snake game in solo mode, then aNEON ORBITvariant in 2-person mode, captures an actual PLANNER-impersonating-CODER easter egg from the 0.6.x era. 18 dogfood screenshots. Also published on CSDN. - Evidence archive for this tutorial — 22 dogfood screenshots, 14 TASK/REPORT files, 8 role-switch evidence files, 2 game artefacts (
Nebula Stack+Comet Loomv2), 2 verbatim agent-interview transcripts. All atdocs/tutorials/assets/tetris-en/. - The protocol itself —
docs/fcop-standalone.mdis host-neutral and runs withoutfcop-mcp(Claude Code, plain shell, CI runner, etc.). Earlier field reports cover why this design works.
A few things I’m curious about, for anyone who tries this
- Did the install prompt work first try on macOS / Linux? I’ve only run it on Windows lately. The agent reads
agent-install-prompt.en.mdand is supposed to detect OS itself. - Did your agent name the game something interesting? Mine named the solo Tetris
Nebula Stackand the team variantComet Loomunprompted. CODER’s chat tab in my dogfood literally got named"Inspection Start Work"(the two phrases ADMIN had used most). I’m collecting this kind of small emergent-naming evidence. - Anyone else seeing
role-switch-*.mdevidence accumulate from cross-tab work? CODER explicitly asked us to soften the warning when there’s no active conflict — wondering if it’s a common pain point.
Field reports welcome — the protocol evolves through them, not committee edits. Repo: GitHub - joinwell52-AI/FCoP: FCoP协议 · GitHub — MIT-licensed, free.