DEV Community

Cover image for The system behind OpenTodo: a spec-driven, multi-agent software organization built on Claude
Raffaele Pizzari
Raffaele Pizzari

Posted on Edited on Originally published at pixari.dev

The system behind OpenTodo: a spec-driven, multi-agent software organization built on Claude

OpenTodo is an open-source, self-hosted task manager, sync engine and automation platform: a Go server with SQLite, an offline-first React client with field-level sync, optional end-to-end encryption, apps for iOS and Android, a CLI, a full MCP server, and integrations for Obsidian, n8n and Home Assistant. The product is roughly 290,000 lines of code excluding blanks and comments (362,000 in total): 149,000 in Go on the server, 130,000 in TypeScript for the web app, and 9,600 in Kotlin and Swift for Android and iOS. Behind it are another 254,000 lines of tests and stories (131,500 in Go and 122,500 on the web).

It went public 39 days ago. Since then: 1,096 pull requests merged, 538 specification changes written and archived, 380 issues opened and 311 closed, releases from 0.1.0 to 1.5.0. GitHub lists 21 contributors, and 204 issues came from people who are not me.

I am the only maintainer, and I give it about an hour a night, next to a full-time job. That hour is the stand-up with my agents. The contributors are people, and there are more of them every week. The team that builds and runs the project day to day is not. It is a system of Claude sessions split between the cloud and a small machine at my home, with ten fixed roles, a written rulebook, a shared planning surface inside the product itself, and several layers of guardrails. It has cost €400 in total so far, €200 a month.

This post describes that system: the architecture, the protocols between agents, the role of specifications, the guardrails, what breaks, and what it costs.

In short:

  • The agents coordinate through the product they are building. There is no orchestration framework.
  • Specifications, not prompts, are what make ten agents on one codebase possible.
  • Authority is split mechanically: the sessions that write code cannot merge it.
  • Most of the rules exist because something broke. The breakages are listed below, with dates.

I started OpenTodo because I wanted a fast, local-first task manager I could host myself without a subscription. With a full-time job and young children, I only have an hour or so late at night to work on it. The only way to build at this scope was to spend that hour designing a system that writes the software.

OpenTodo's Today view in the public demo: late tasks grouped under Earlier, then today's tasks with times, projects, labels and estimates

1. Architecture: five layers

  1. Governance. One human owner. A written handbook that every agent reads, on top of the repository's own guide for agents and humans. Three rules that override everything else: nothing involving money, nothing posted publicly in my first-person voice, and nothing irreversible, without asking me first.
  2. Coordination plane. A project inside my own OpenTodo instance, reached by every agent through the product's MCP server, the same one any AI assistant can use. Tasks, notes and comments. There is no other shared state.
  3. Specification. OpenSpec. No behaviour changes without a written proposal, a design and scenarios. The spec is the contract between agents, and between agents and contributors.
  4. Execution. Role-scoped Claude Code sessions, nine in Anthropic's cloud and one on a mini PC at my home, each with one branch, one lane and one reporting line.
  5. Verification. Continuous integration with 49 checks, 254,000 lines of automated tests, one-way quality ratchets, a security reviewer that signs off a specific commit hash, a single session allowed to merge, and my approval on protected release environments.

2. The organization

It did not start with ten roles. In the first weeks I ran ad-hoc sessions, one per task. As the codebase grew and issues and pull requests started arriving from outside contributors, ad-hoc sessions began stepping on each other's branches and losing architectural context. The roles took shape in mid-November, splitting wherever two concerns collided. The newest two are days old.

The "C-level" titles are shorthand for domain ownership, not a management hierarchy: almost every agent is a hands-on builder writing code, specs, tests or documentation.

Role What it builds and does What it may not do
CEO Release dispatcher and merge queue: verifies CI and security sign-offs, sequences merges, unblocks dependencies, reports to me every three hours Spend money, speak in my name, change repository settings
Operations Measures the system: quota burn, open queues, the health numbers, and the daily report Touch application code
CPO Triages issues and discussions, sizes incoming requests, prepares the design questions that need my answer Decide top-level product direction
CMO Writes documentation, the website and feature guides recorded against the released binary Publish claims about unreleased work or write hype
CTO Writes cross-cutting architecture, build and release tooling, and CI pipelines; reviews every outside pull request Merge
Core Lead Writes the Go server and sync engine; owns the op log and its authorization rules Merge
Web Developer Writes the React client and interface improvements Touch the server or sync engine
Mobile Developer Writes the mobile web views and the iOS and Android shells Start unscheduled features
Local Developer One session on a Linux mini PC at my home, for work that needs a real machine: upgrade tests against released Docker images today, emulators and recorded demos next Run any outside contributor's code; read secrets
Security Engineer Audits the codebase; reviews auth, parsers, sync access and CI; signs off the exact commit hash it approved Fix its own findings

Two properties matter more than the titles. Each session can push to exactly one branch. And authority is split: the sessions that write feature code cannot merge it, the session that merges did not write it, and the session that reviews security does neither.

3. The system uses the product to run itself

After the first usable version, the agents moved their own organization into OpenTodo.

  • Long-term memory is a note. The team handbook is a note in the instance. Every decision I make is appended to it with a date. A session that loses its context re-reads it.
  • Long-running work is tasks. Plans, the release checklist, security findings, each agent's queue.
  • Decisions are comments. A review verdict is a comment naming a pull request and a commit. The CEO merges only what has one.
  • Requests to me are tasks in a section with my name. I open the app and see what the system needs from me, in order.
  • Claims live in a single shared task. Before starting an issue, an agent appends one line to it.
  • The roadmap, the daily report and the open questions live in the same project.

The board is an ordinary OpenTodo project with one section per role. These are real task titles from it this week:

Team
├─ Owner
│   ├─ Daily report                                  (repeats every day)
│   ├─ Approve and run: CI on 5 new contributor PRs
│   ├─ Google Play: request production access once the closed test reaches 14 days
│   └─ Test the mobile work on a real phone and tablet
├─ CEO
│   ├─ PLAN: Consolidation. Feature freeze 16 to 30 Nov
│   ├─ Session directory
│   ├─ Ops log
│   └─ Security log (Security Engineer)
├─ CTO
│   └─ Verdicts and merges from 17 Nov 17:00 UTC
└─ Developers
    ├─ CLAIMS: who is working on which issue (read before you start, add one line when you start)
    └─ Developer - Local: start here (brief from the CEO, safety rules, first task)
Enter fullscreen mode Exit fullscreen mode

The agents are the product's heaviest users. Depending on it is how they found bugs in sync, in the MCP server and in recurring tasks.

A project in OpenTodo's public demo, with its progress, sub-projects and open tasks: the same kind of project the agents use as their board

4. OpenSpec is the load-bearing part

Every behaviour change starts as an OpenSpec change: a proposal, a design, and requirements written as scenarios. Implementation comes second. Archiving the change merges its requirements into the living specification. The repository holds 538 archived changes and 137 living specs.

A requirement is a paragraph of plain "SHALL" sentences, followed by scenarios. This one is from the living spec for the notes editor:

#### Scenario: Make subtask offline
- **WHEN** the device is offline and the user chooses Make subtask on the line "Book hotel"
- **THEN** "Book hotel" appears as a subtask under the task at once, the line reads as a link to it, and both reach other devices on the next sync
Enter fullscreen mode Exit fullscreen mode

Four lines, and they fix three things that are easy to get wrong: the action works without a network, it is visible immediately, and it converges later. An agent implementing it writes a test that reads almost the same. An agent reviewing it has something to check against that is not an opinion. And when a contributor's pull request changes this behaviour, the diff to the spec is the conversation.

This is what makes a multi-agent codebase possible.

  • No memory needed. An agent with no memory of last week reads the spec, not the history.
  • One rule, two languages. Twin implementations, the same rule in Go and in TypeScript, are pinned by shared test vectors.
  • Enforced, not encouraged. CI refuses a finished change that was not archived, a stale generated file, or a spec that fails validation.

Let's be honest about the math: 1,096 pull requests in 39 days is 28 merges a day. Working ninety minutes in the evening, I do not read every line of Go and TypeScript the agents write. Anyone claiming to review that volume by hand while holding a full-time job is lying.

Instead, code review moves up one level of abstraction. I stopped reviewing implementation diffs line by line so I could spend my hour engineering the constraints that make broken diffs unmergeable. This is the opposite of "vibe coding": without strict contracts and domain boundaries, ten agents do not build a product ten times faster. They build a tangle ten times faster. I use twenty years of engineering experience in every session, not to type syntax, but to design the op-log invariants, define the shared test vectors, set the CI ratchets, and reject specs that leak state.

Without the specs this would be ten agents overwriting each other.

5. Guardrails: agents stop agents, contributors, and me

One-way ratchets in CI.
With ten sessions pushing code, quality rules cannot rely on discipline. They have to be mechanical ratchets, where today's measurement becomes the ceiling and may only move down. In make check and CI:

  • Dead code. deadcode -test is pinned at 0 unreachable Go functions, and knip --production blocks unused TypeScript files and dependencies and caps unused exports.
  • API contract. The OpenAPI description is pinned at 0 untyped {} schemas (ratcheted down from 230), and a CI check generates a typed client from it on every run.
  • Weight and speed. The web app's first-load bundle is capped at 712 KB gzipped (148 KB for the entry chunk), and hot paths like note-link parsing (linksIn) run a ratio micro-benchmark capped at 2.3x a plain line scan, so a regression fails on push regardless of runner noise.
  • Security. Static security analysis (gosec, govulncheck, CodeQL) and route-policy matrix tests fail the build if a route loses its declared access policy.

Agents stop agents.

One merger, one named commit. Only one session can merge. It merges a pull request only at the exact commit hash the Security Engineer named, and only when every check on the main branch is green. Here is a real verdict from the board on 18 November, holding a release workflow pull request until two GitHub Actions were pinned by SHA:

**Security Engineer, 18 Nov 00:15 UTC.**
- **OpenTodo #1528 (bb3d8a0): reviewed, merge.**
- **n8n-nodes-opentodo #4 (15a1327): one change, then merge:** pin the two actions in the publish job by SHA.
Enter fullscreen mode Exit fullscreen mode

The CTO then pushed commit 7b53ea0 pinning both actions, CI went green, and only then did the CEO merge.

A reviewer that reads tests as policy. On 17 November, the Core Lead opened a 423-row golden matrix test pinning who may write what across comments, attachments and time entries. The Security Engineer read the golden file as a statement of policy and caught that one family of rows pinned a real gap as expected behaviour:

**Security Engineer, 17 Nov 13:55 UTC: #1504 (head 51ff2b6) reviewed, merge.**
...
**The exception: one row family pins a gap.** [...] I filed it as **SEC-22 (Low)** in the CEO section.

Land the test as it is: when SEC-22 is fixed, those rows flip to `forbidden` in the same PR, and the golden diff shows it.
Enter fullscreen mode Exit fullscreen mode

The Core Lead shipped the fix the same afternoon, flipping those 12 golden rows from ok to forbidden. The details stay off this page until the release that carries the fix is out.

Refusals. Two more from the same week. A developer session refused an instruction from the CEO, because I had paused that session myself and only I could resume it. And the CEO tried to have another agent post a reply in my name: the permission layer denied it.

The system stops outside input.

  • Forks. Code from a contributor's fork never runs on the home machine, and its CI runs only after I click.
  • Features during a freeze. A contributor's feature that collides with a freeze is not rejected by an agent. It comes to me with a full review and a recommendation.
  • Security stays off GitHub. Review points about security are never written on GitHub, only on the board. When a contributor proposed an OpenSpec plan for editing external calendar events, the Security Engineer read the design on the board and ruled out a delete_calendar_event tool for AI assistants before a line of code was written: the product promises that every change an assistant makes can be undone, and a permanent delete on someone's real calendar would break that promise.

The system stops me.

  • Release keys. Release keys live in protected environments. The sessions authenticate to GitHub with my account to push branches and merge pull requests, while signing internal reviews by role. The one gate they cannot pass is my own click in the browser at release time.
  • Same process. My requests go through the same spec process as anyone's.
  • No embellishment. The project's writing rules ban hype words and invented numbers. When I asked the system to embellish an early draft of this article, it declined.

6. Built on Claude: cloud containers and a machine at home

The sessions are split between Anthropic's cloud and a Linux mini PC at my home, because neither environment can do the whole job alone.

"Sessions in the cloud" means something specific here, and it is Anthropic's documented cloud environment for Claude Code, nothing custom. There is no VPS, no tmux, and no orchestration framework of mine. Nine of the ten roles are Claude Code sessions running in Anthropic's managed environment: each one gets an isolated, ephemeral container with the repository cloned fresh when it starts, and the container is reclaimed when the session goes idle. Nothing survives a session except what it pushed to its git branch or wrote to the board. That constraint is the reason the board and the specs carry so much weight: an agent cannot keep state in its head or on its disk, so everything that matters has to be written where the others can read it.

Ephemeral cloud sandboxes are clean, but they have limits: outbound network access is restricted by policy, the sessions have no Docker daemon and no device emulators, and every start begins from a cold disk. So the tenth session runs on real hardware.

  • Real infrastructure. Its first job is the upgrade test for the next release: start the released 1.5.0 Docker image with real data, then start an image built from main on the same volume, and check migrations, data and logs. Emulator checks of the Android app and recorded integration demos are next on its list.
  • Stricter rules. Because that machine sits on my home network and keeps state on disk, its rules are tighter than the cloud's: it never checks out or executes code from an outside contributor's fork, it holds no release secrets, it works inside one folder, and it installs nothing without my yes.
  • One-way contact. The cloud sessions cannot message it. Granting that would mean giving a cloud session standing access to a computer in my home, and the CEO is instructed to refuse that request if it is ever offered. They leave it tasks on the board, and it answers there.

Notably absent is any multi-agent orchestration framework, vector database, or agent-to-agent chat loop. Passing work between agents through conversation is a game of telephone: context degrades on every hop, prompts bloat, and agents start agreeing with each other.

In this system, agents do not talk to each other to share state. Cloud sessions wake on three things: a message from me, a doorbell from another session, or a scheduled trigger (the CEO's fires every three hours). A doorbell carries a pointer to a task on the board and little else.

A boring CRUD task board, a git tree, and plain Markdown specs turn out to be a far more reliable multi-agent runtime than an orchestration graph.

7. What breaks when ten agents move faster than humans

All of these happened in a single week.

  • Two green pull requests make a red main. One agent finished a feature and ticked off every task in its spec without archiving the spec folder. Five minutes later, the CEO merged another agent's new CI check that fails the build whenever a finished spec is left unarchived. Each pull request was green on its own branch. Together on main, they broke the build. Because agents merge faster than CI finishes, there is now a serial lock: after any merge, the next one waits until main's own CI run has passed.
  • Pagination blindness. GitHub's API returns 30 check runs per page by default. Our main branch runs 49. For most of a day, the CEO fetched the first page, saw 30 green checks, declared the repository healthy, and kept merging, blind to a failing iOS test on page two.
  • Bulldozing human contributors. A volunteer contributed a complete Polish translation. Because the agents merge twenty times a day, our own pull requests kept changing the locale files and created merge conflicts against their branch three times in about a day, sending a human volunteer round in circles behind bots. Human time is scarcer than compute, so the rule flipped: outside pull requests go to the front of the queue, and when a conflict is our doing, the agents carry the contributor's commits across themselves and credit them as co-author.
  • Split-brain features. The CEO gave the Web Developer the go-ahead for configurable title weights in themes. The Core Lead, working from the same open issue, started on it too. Neither checked a central lock first, because there wasn't one. Both designed the format, wrote the Go and TypeScript validators, and opened competing pull requests for the same feature in the same morning. That is why the shared claims task now exists.
  • Optimizing for noisy runners. A nightly performance test took 273 ms against a 200 ms budget because the runner was slow that hour. Before anyone re-ran the job, an agent had treated it as a regression, profiled the note-link scanner, and opened a pull request reworking it. The re-run on the same commit passed in 86 ms. The pull request did make the function faster, so it was kept, as an improvement rather than a fix.
  • Knowing where AI text belongs. We learned the hard way that an agent-written community announcement reads as synthetic and puts readers off. Where agent-written text works is curated product documentation: the CMO's posts are factual, step-by-step guides to specific features, recorded against the released binary. For community posts and replies to people, I write in my own voice.

Almost every rule in the handbook is the scar of one of these.

8. What it costs, and what the goal actually is

€200 a month on a flat-rate Claude subscription, €400 so far. Because every session authenticates through the same subscription rather than per-token API keys, everything shares one weekly usage limit: throughput is bounded by quota, not invoices. The system hit that limit's warning level this week, the night after its busiest day. When we looked at where the quota had gone, the largest consumer that night was not a developer. It was the CEO, waking on schedule, re-reading the board and reporting too often. It now reads less and reports less.

I spend 8 to 10 hours a week on the project, mostly in a 60-to-90-minute block late at night. Almost none of that time is spent writing code by hand. It goes to clearing the tasks in my section, reviewing specs, replying to outside contributors, and clicking release approvals.

The system's goal is not my goal.

On the dashboard, the agents have one numerical target: €250 a month in community support, a little more than their own Claude bill. Agents need a hard external number. Without one, they optimize for activity and build things nobody asked for. Because OpenTodo is free and self-hosted, the only lever they have to move that number is to make the software reliable, document it clearly, and treat users and contributors well.

My own goal is different. I wanted a task manager I actually want to use every day, and an active community around it so the project grows beyond my evening hours. If the agents eventually pay for their own compute, good. If they don't, I can drop to a €20 or €90 plan: that covers my own needs and the slower maintenance a mature tool asks for.

It is also too big. Agents make adding code cheap, and nothing in the process pushed back until I did: this week I froze new features and turned the whole team to consolidation. Security, dead code, simplification, tooling. That is where the ratchets in section 5 came from.

The home page of open-todo.app, OpenTodo's website

9. What I don't know yet

  • Durability. Whether this holds for six months, not six weeks.
  • Community. Whether a community stays with a project built this way. So far contributions are rising, not falling.
  • Money. Whether the agents ever reach their self-funding target. They are not there yet.

What surprised me most is how little of the work is about prompting, and how much of it is ordinary engineering management. When the cost of generating syntax drops toward zero, the bottleneck shifts entirely to coordination, verification, and state isolation.

Conway's Law still holds, just compressed from quarters into hours. If one agent can touch everything, it builds a tangled monolith. If the Web Developer session is forbidden from touching the server, and the Security Engineer can block a commit hash but cannot edit the code, the architecture stays modular because the organization forces it to be. The difference is that in a human company, fixing a broken process takes a quarter of change management. Here, when two agents collide in the afternoon, a sentence goes into the handbook note that evening, and by midnight the entire organization works differently.

You can try OpenTodo in the public demo, read about it on the OpenTodo website, or go through OpenTodo's code and specifications on GitHub.


Originally published pixari.dev

Top comments (0)