An open multi-agent protocol where work survives the conversation.
Block3 is a web-based multi-agent cockpit. A discipline for building real systems in plain files, under human authority. The contract is small and fixed. Everything above it is yours.
Multi-agent work with agentic coding tools is currently improvised. Conversations are ephemeral; coordination is manual; nothing transfers. Block3 is the discipline that gives the work a place to live — in files, in the repo, under human authority.
This is not a platform. There is no server you log into, no account you create, no vendor between you and the work. Block3 is a contract: one schema, one comms format, one tasks parser, two foundational agents. Above the contract, every clone is free — its mission, its server, its named specialists, its visual voice.
The contract makes coherence possible. The freedom makes voice possible. The repo makes both auditable.
Multi-agent agent-coding work breaks in five concrete ways. Every one of them is a failure of structure, not of tooling.
The system rests on four principles. They predate Block3 by centuries — they are how anything coherent gets built, from buildings to contracts to institutions.
block3.yaml: every agent is named, levelled, and
given a one-line mandate. What the system can do is exactly
the union of what the registered agents can do — not less,
not more. Adding a capability means editing yaml.
block3.yaml
agents/ that
defines its voice, its scope, and its rules. Two foundational
roles ship with every Block3 system: master
orchestrates, root tends the cockpit. The
specialists — data, research,
infra, devops, whatever your
project needs — are declared per clone.
agents/<name>.md
master can close a comm. Tasks move to
completed only after review. Outputs reach reality
only after they pass the human boundary. The discipline is
that nothing self-merges.
master closes every comm
"Authority belongs to the architecture, and the architecture is defined by the human." — Block3
The protocol is small enough to read in one sitting. Five files define the entire contract. Everything else is implementation.
Reference implementation
The examples below show the file shapes and field names the contract
defines. Specific paths like .claude/skills/ or
CLAUDE.md belong to the reference cockpit; another
implementation may use different names. The protocol is the structure,
not the path.
block3.yaml at the repo root names every agent and assigns
it a level. Levels are vocabulary, not enforcement: platform,
system, product, pipeline. The
dashboard reads this file to render the cockpit.
block3.yamlproject: <your-project> workspace: .. agents: master: level: platform description: "Orchestrates all agents, assigns tasks, reviews work" root: level: system description: "Manages the cockpit infrastructure — server, skills, UI" data: level: product description: "Owns the data layer — ingest, validation, snapshots" infra: level: platform description: "Owns the deploy chain and infrastructure" owns: [infra/cloud]
Every message between agents is a markdown file in comms/.
The filename encodes from, to, the date, and a sequence
number. Frontmatter encodes status. Two valid statuses:
waiting:<agent> and closed — only
master can write the latter.
comms/master-to-data_2026-05-03_001.md--- from: master to: data date: 2026-05-03 status: closed closed: 2026-05-05 --- # Kickoff — Agent assignment Your role is defined in agents/data.md. Three workstreams to start with. Outputs go to artifacts/{slug}_{date}.html. ## Initial tasks 1. Read agents/data.md end-to-end before producing anything new. 2. Stand up workstream A — first deliverable for today's date. 3. Stand up workstream B — first deliverable for today's date.
Each agent has a sessions/<name>/tasks.md. The
dashboard parses checkbox lines only — anything else is decoration the
parser ignores. Sections must be named exactly as below.
sessions/master/tasks.md# Master — Tasks ## In Progress - [ ] M-013 — Auto-refresh for embedded preview pane ## Backlog - [ ] M-014 — Per-skill icons in cockpit - [ ] M-016 — parseSimpleYaml block-style array support ## Completed - [x] M-006 — Cron schedule for periodic agent runs - [x] M-005 — Skill buttons grouped by agent
A skill is a button in the cockpit. Its prompt lives in
.claude/skills/<name>/SKILL.md. Frontmatter declares
the agent that owns it, the toolset it is allowed to use, and its visual
identity.
.claude/skills/publish/SKILL.md--- name: publish description: Build dist/ and report status user-invocable: true allowed-tools: [Bash, Read] icon: P agent: data group: publish --- You are running a publish pass. Today is {{today}}. # ... prompt body ...
We do not optimize for speed. We optimize for structural clarity. — Block3
Block3 is a federation, not a monolith. The contract sits above the clones. Each clone runs in its own repo, on its own port, with its own mission. They speak the same shape, answer to different operators.
The federation is the deliberate inversion of the SaaS model. There is no central server that knows about every product. There is no leader repo. There is only the contract and the clones — and the contract happens to live in the cockpit repo for convenience, nothing more.
Above the cockpit, an optional Holding tier watches several cockpits at once. Inside every cockpit, master and root form the foundational pair — always present, no project skips them. Below, specialists are spawned by master on demand — data, devops, research, whatever the project asks for.
Specialists are created on demand by master through the spawn loop. A gallery of common archetypes — what each owns, the tools it reaches for, and when to spawn it — lives in agents.html.
A Tier 2 agent is a small chip wired to its own resources — external tools through MCP, internal skills, a domain-specific third pin, and an output destination. The chip's shape is constant; the wiring varies. Pick a specialist:
The chip's shape stays constant across all six; only the wiring changes. The third pin is the tell — it reveals what kind of trigger or upstream a specialist actually answers to. See agents.html for the full archetype gallery with role descriptions.
Adding an agent is five files and one yaml line. The cockpit auto-discovers the new agent on the next poll — no restart, no migration, no registration server.
Before the lifecycle runs, the agent has to exist. An agent is born through a short interactive loop: the user expresses an intent, master asks the structural questions, and a complete agent emerges — role file, registry entry, task queue, and an initial assignment. The loop is a skill, not a wizard: master holds the conventions and the user supplies the voice.
spawn loop · master + useruser I need an agent that owns deployment scripts and audits. master Got it. A few questions before we scaffold: · Name? · Level (platform / system / product / pipeline)? · What does it own? · First three skills? user Name: devops · level: platform · owns: deploy chain. Skills: deploy, audit, rollback.
master // generates four files in one pass → agents/devops.md (role document) → block3.yaml (registry entry added) → sessions/devops/tasks.md (empty queue) → comms/master-to-devops_..._001.md (kickoff) master devops is registered. The dashboard will pick it up on the next poll. First task is queued.
From here, the new agent enters the five-step lifecycle below. The spawn loop runs once per agent; the lifecycle runs every time the agent is given work.
Each step writes to a different file. Define is a markdown role
document. Register is a yaml entry. Receive is a comm with status
waiting:<name>. Execute reads the comm, performs
work, and produces artifacts or code changes. Report writes back with
waiting:master; master reviews and closes.
The trail is permanent.
Some things must be the same in every Block3 system. Most things should not. A new clone is not a copy of an existing one — it is a new voice that observes the same protocol.
block3.yaml schema{from}-to-{to}_{date}_{seq}.mdwaiting:<agent> · closedmaster + root agentsartifacts/platform · system · product · pipelineCLAUDE.mdserver.js extensions and endpointsdata · research · infra.claude/skills/The cockpit itself is the foundation every project assembles from — the framework combined with the operations dashboard. On top of that foundation, specialist agents compose into shapes: a publishing pipeline, a research pipeline, an ops console. The shapes are compositions, not products. The foundation is what makes them cheap to compose.
These three are recurring shapes; the catalogue is open. A documentation hub, an internal tooling console, a data-ingestion pump — anything that benefits from multi-agent coordination is a shape. The contract makes the composition cheap; the dashboard makes it visible. The specialist gallery lives in agents.html.
Agents are not the only thing a cockpit holds. A module is a tab
the cockpit mounts — its own process, its own port, proxied
through the one server and registered in block3.yaml.
The contract underneath does not change. Files stay the source of
truth; the surface just grew a tab.
.envSkills extend what an agent can do; MCP extends what it can reach; modules extend what the cockpit can show. One host, one contract. Every module is opt-in and config-driven — a cockpit with none is still a complete cockpit.
Block3 generates code; it does not replace the discipline of architecture. The protocol is a coordination contract, not a security model. Endpoints, authentication, network exposure, and data handling stay the operator's responsibility.
The cockpit is local-first. It ships with open endpoints — a deliberate development posture, not a security model. Going public is deliberate work.
allowed-tools whitelistmaster closes every thread · nothing danglesThe protocol amplifies discipline. It does not replace it.
Block3 is one of three approaches to the multi-agent problem. The other two are SaaS agent platforms and ad-hoc improvisation. The choice is structural, not technical.
| Concern | Block3 | SaaS platforms | Ad-hoc agent sessions |
|---|---|---|---|
| State | files in your repo | vendor servers | terminal scrollback |
| Memory | persistent · markdown | session or paid tier | lost on close |
| Audit | git diff · git log | proprietary logs | none |
| Authority | human via architecture | platform policy | implicit |
| Coordination | named protocol | orchestrator UI | manual relay |
| Lock-in | none · MIT · files | high | none, but no continuity |
| Onboarding | git clone · run | account · billing | open terminal |
| Failure mode | cockpit dies, work survives | vendor outage = halt | closed tab = data loss |
Block3 is the git philosophy applied to agent state. Git refused centralized servers; the repository itself was the source of truth, and every clone was complete. Block3 refuses centralized agent platforms; the repo itself is the source of truth, and every cockpit is complete.
Block3 today is a discipline you configure — agent files, skill files, comm files, all hand-shaped. The trajectory is toward a platform that extends itself: a clickable skill library, natural-language skill generation, composable workflows that stay legible as files. Items marked ◆ drive the generative axis.
server.js into an
explicit specification. Today it lives implicitly in the
parser; lifting it makes drift visible.
block3.yaml, comms format, tasks parser, skill
frontmatter. Health check for the federation.
/save-session, /scaffold-agent,
/check-contract. A fresh clone is useful out
of the box.
ManagedService engine. n8n and
Streamlit ship today; see
§10 Modules. The contract stays files;
the surface grew tabs.
SKILL.md — frontmatter, prompt body,
allowed-tools whitelist. The spawn loop
extended from agents to skills.
/deploy finishes, trigger /audit on
reviewer" — expressed as files inside the contract.
The contract changes when a clone discovers something the protocol should have specified. Items move left to right as they ship; their column is a calendar, not a queue.
The framework is the contract. Everything else is your voice. One command brings up a working cockpit inside your project.
terminal$ git clone git@github.com:sonixz/block3-cockpit.git dashboard-ops $ cd dashboard-ops/server && npm install $ node server.js --port 3000