Architecture for terminal-based AI coding agents.
Terminal-based AI coding agents are changing how software gets built. What's still missing is a shared architecture for how repositories, capabilities, knowledge, workflows and coding agents should evolve together. Block3 is an exploration of that architecture.
Terminal-based coding agents are making it possible to build in a different way. Each new tool is useful on its own — the open question is how the work around them should be structured.
A repository can be modified from a terminal. A workflow can automate part of a process. A dashboard can expose a capability. A document can preserve context. And there are so many brilliant repositories a builder would want to understand and bring into a research project, an MVP, or even production — each one a way to add real value.
Block3 explores how builders and architects can more easily integrate modules — like a repository — into their projects. It doesn't replace those repositories, and it doesn't absorb them natively — it gives them a place inside the architecture itself. It isn't trying to define a universal way of building; it is an Alpha exploration of a practical architecture where repositories, capabilities, knowledge, workflows and coding agents can evolve together.
The work stays close to the project: visible in files, versioned with the repository, understandable by coding agents, and kept under human authority.
Building this way breaks down 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
agents/<name>.md
master closes every comm
The contract isn't an API or a platform — it's a handful of plain files in the repo. Each shape covers one concern: what the project is made of, how an agent is defined, how agents coordinate, how work and context are preserved, and how a capability is declared. The point isn't the files themselves; it's that the whole thing stays legible, versioned, and under your eyes.
What the project is made of — every agent, named and given a level.
project: <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]
How an agent is defined — its role, scope and rules, in plain markdown. The registry lists them; each one is a file.
# Master Agent ## Role The orchestrator. Manages agents, assigns tasks, reviews work. ## Rules - Read sessions/master/tasks.md at the start of each session. - Every active comm has someone who must act next. - Only master can close a communication.
# Root Agent ## Role Tends the cockpit itself — server, skills, UI — not the project it orchestrates. ## Rules - Operate inside the cockpit only; never touch project code. - Keep the server backward-compatible when possible. - Read the relevant files before modifying them.
# Data Agent ## Role Owns the data layer — ingest, validation, snapshots. ## Rules - Validation runs before any data is published. - Snapshots are immutable — never edit a past snapshot in place. - Outputs go to artifacts/{slug}_{date}.html.
# Infra Agent ## Role Owns the deploy chain and infrastructure. ## Rules - No change reaches production without master's review. - Infrastructure is described in code, never configured by hand. - Read agents/infra.md before touching the deploy chain.
# <name> Name it in block3.yaml, drop a role file in agents/. The cockpit picks it up — that's it.
How agents coordinate — every message is a file; the name says who's writing to whom, the frontmatter who owes the next move.
--- from: master to: data status: closed --- # Kickoff — Agent assignment Your role is defined in agents/data.md. Outputs go to artifacts/{slug}_{date}.html. ## Initial tasks 1. Read agents/data.md end-to-end first. 2. Stand up workstream A.
--- from: master to: root status: waiting:root --- # Cockpit — preview auto-refresh The embedded preview pane doesn't refresh on save. Can you wire a file-watcher reload?
--- from: data to: master status: closed --- # Snapshot ready Weekly snapshot validated and published. artifacts/report_2026-06-18.html — ready for review.
How work is tracked — each agent keeps its own list. Checkbox lines are the entire format.
# Master — Tasks ## In Progress - [ ] M-013 — Auto-refresh for embedded preview pane ## Backlog - [ ] M-014 — Per-skill icons in cockpit ## Completed - [x] M-006 — Cron schedule for periodic agent runs
# Root — Tasks ## In Progress - [ ] R-021 — Kept-alive iframe workspaces in the shell ## Backlog - [ ] R-022 — Per-skill icons in the cockpit UI ## Completed - [x] R-018 — WebSocket file watcher for live reload
# Data — Tasks ## In Progress - [ ] D-007 — Nightly ingest + validation pass ## Backlog - [ ] D-008 — Snapshot diff viewer ## Completed - [x] D-004 — Schema validation on publish
# Infra — Tasks ## In Progress - [ ] I-012 — Blue/green deploy for the cockpit ## Backlog - [ ] I-013 — Rotate secrets via the vault ## Completed - [x] I-009 — Caddy → cockpit reverse proxy
# <name> — Tasks
Same shape as the rest — checkbox lines under In Progress,
Backlog and Completed. Its own list, tracked like everyone else's.How context survives — each agent leaves a log, so the next session starts warm instead of cold.
# Master — Session 2026-06-25 #1 ## Context entering the session Entered clean: working tree clean, main at 154b1ed, no open comms. ## Work delivered Reviewed and merged feat/multi-workspace-shell — top tab bar, kept-alive iframe workspaces. ## Open threads - Modules concept (Streamlit / n8n as config-driven modules) — deferred.
# Root — Session 2026-06-20 #1 ## Context entering the session Shell branch pushed from the VM; asked to review before merge. ## Work delivered Reviewed the workspace shell: lazy iframes, localStorage tabs. Verdict: safe. ## Open threads - Per-skill icons still in the backlog.
# Data — Session 2026-06-18 #1 ## Context entering the session New snapshot requested for the weekly report. ## Work delivered Ran ingest + validation; published artifacts/report_2026-06-18.html. ## Open threads - Snapshot diff viewer not started.
# Infra — Session 2026-06-15 #1 ## Context entering the session Cockpit moved behind Caddy on the new VM. ## Work delivered Wired Caddy → cockpit:3001; only 443 exposed on the NSG. ## Open threads - Blue/green deploy still manual.
# <name> — Session Its own log, written by save-session. Next time, this agent starts warm too.
A capability, declared — where a tool or a repo becomes something the cockpit can use.
--- 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 ...
master and root ship with every cockpit — Block3's word for a project's installation: these files, the agents they define, and the web dashboard that drives them. data and infra are examples — you define the rest.
And because the contract is just files, it travels. Clone the structure into any repository and the conventions arrive with it — the folder layout, the file shapes, the foundational pair. Starting a new project stops meaning starting over: the scaffolding you kept rebuilding becomes the part you inherit.
Five agents shouldn't mean five conversations. Without structure, every update routes through you — the operator becomes the message bus. Here you talk to master, and master runs the rest: one owner per task, one reviewer per output, one status line naming who moves next. No diagram enforces it; the files do. Watch one loop run.
One conversation. You talk to master — not to five terminals.
you › The staging deploy has been failing since this morning. Can someone own it? master › On it. That's devops territory — I'll open a thread, queue the task, and come back to you once the fix is reviewed.
master delegates by writing a file. The status line names who must act next — that line is the hierarchy.
--- from: master to: devops status: waiting:devops ← who owes the next move --- # Staging deploy — failing since 09:00 deploy.sh exits 1 on staging. Own it end-to-end. Report in this thread when a fix is ready. # queued → sessions/devops/tasks.md · - [ ] D-021
master doesn't do the work — it spawns a specialist in its own session, hands it the thread, then stands by.
master › Thread open, task queued. Spawning the owner. $ block3 spawn devops ✓ devops session started — own terminal, own context ✓ kickoff delivered: comms/master-to-devops_..._001.md $ block3 ps SESSION PTY STATUS THREAD master #1 ○ standing by watching comms/ devops #2 ● running master-to-devops_..._001 master › I coordinate — I don't code. I wake up when this thread returns waiting:master.
Meanwhile, in its own terminal: devops works, replies in the same thread — and hands the loop back. It cannot write closed.
session devops · pty #2 · ● running · master is standing by $ bash scripts/deploy.sh --target staging ✗ exit 1 — STAGING_TOKEN missing at env switch $ git commit -m "fix(deploy): source staging env before token check" # appends to comms/master-to-devops_2026-07-02_001.md status: waiting:master ← a specialist can only hand back ## Fix ready Root cause: token read before env switch. Patch on fix/staging-token — over to you.
Only master closes a thread. Review first, then the one word a specialist may never write.
--- from: master to: devops status: closed ← only master writes this --- ## Review — approved Patch read, tested against staging, merged after your sign-off. Thread closed. # sessions/devops/tasks.md - [x] D-021 — Fix staging deploy failure
What remains when the loop ends — the hierarchy leaves a paper trail by construction.
comms/master-to-devops_2026-07-02_001.md closed sessions/devops/tasks.md D-021 · [x] sessions/devops/session_2026-07-02_1.md written # who asked, who acted, who approved, when — # answered by files, not by memory.
This is why the coordination overhead dissolves. The state of the project stops living in the operator's head: who owns what is in the registry, what each agent is doing is in its task file, who owes the next move is a status line on disk. Two specialists never need to see each other — they need the same files.
Authority, here, is a write permission. A specialist can only
hand the loop back; the word closed belongs to
master, and the merge belongs to you. The relay work is a role,
and the role has an owner.
When one project becomes several, the same idea repeats one level up: an optional oversight tier can watch many cockpits at once. A single-project setup never needs to know it exists.
An agent is born in five files, works in loops, remembers between sessions, and retires when its job is done. Everything it learns outlives it — because none of it lives in the terminal.
No rewrite, no migration, no scaffolding around your code. The cockpit sits in one folder, its agents work on your project, and everything else stays where it was.
your-project/ ├── src/ your code — agents work here ├── package.json └── block3/ ← the cockpit, in its corner ├── block3.yaml aims the agents at your code ├── agents/ · comms/ · sessions/ └── server/ the dashboard
your-new-project/ ← born from the template ├── src/ your code grows here ├── README.md └── block3/ ← the cockpit, same corner ├── block3.yaml aims the agents at your code ├── agents/ · comms/ · sessions/ └── server/ the dashboard
Same structure either way — the agents can't tell the difference.
Everything you've seen so far runs in terminals — but you drive it from the browser. The cockpit is a web interface: one URL, one tab bar, and any tool can become a tab — declared, not glued. Watch our favourite one at work.
Declared in the registry like any module — a command, a port, an env. Streamlit is pair-programmed live; n8n is driven through its MCP and API; and anything that serves a page can take the next tab. All of it in the browser, behind one URL you own.
Block3 coordinates agents that write code; the discipline of architecture stays with you. The protocol is a coordination contract, not a security model. Endpoints, authentication, network exposure, and data handling stay the operator's responsibility.
The cockpit runs wherever you put it — a laptop, a VM, a sandboxed cloud box. What it ships is open endpoints and no auth layer of its own: the perimeter is the environment you wrap around it. Going public is deliberate work.
allowed-tools whitelistmaster closes every thread · nothing danglesGoing public has a sane shape: one exposed port, a reverse proxy in front, auth at the door — everything else stays internal.
The 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. A health check for any cockpit.
/save-session, /scaffold-agent,
/check-contract. A fresh clone is useful out
of the box.
n8n and
Streamlit ship today; see
§08 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 block3 $ cd block3/server && npm install $ node server.js --port 3000