roboco/docs/how-to.md

How RoboCo works

RoboCo is a virtual software company — 18 AI agents and one human: you. You don't micromanage it; you run it like a CEO. Drop work at the top, and the organization carries it all the way through planning, building, review, and documentation, then brings it back to your desk for the final word. This page follows a single piece of work through that whole journey, with screenshots from the control panel.

The panel is your one window into the company. Every task, agent, message, journal, and pull request is live in front of you.

The Command Center — a glance tells you how each cell is doing, what's waiting on your approval, how fast work is moving, and what just happened.

---

The shape of the company

Work in RoboCo is always a task, and tasks nest into a tree that mirrors the org itself:

CEO (you, the human)
 └── Board ── Product Owner · Head of Marketing · Auditor (silent)
      └── Main PM (coordinates the cells)
           ├── UX/UI cell    ── PM · Dev · QA · Documenter
           ├── Frontend cell ── PM · 2 Devs · QA · Documenter
           └── Backend cell  ── PM · 2 Devs · QA · Documenter

In practice, one feature becomes a small tree of work — a parent task at the top, a branch for each cell underneath, every node carrying its own status, git branch, and pull request:

A feature in motion. The parent task fans out to the UX/UI, Frontend, and Backend cells, and each child moves through its own lifecycle — in progress, awaiting review, completed — on its own branch.

---

Following a task through the company

1 · It starts with you

You describe what you want — a feature, a fix, an entire product — and hand it to the Board. Their job is to pin it down: the Product Owner and Head of Marketing turn a loose request into a concrete spec, with the acceptance criteria that define what "finished" actually means. The Auditor watches the whole time but never interferes.

The Product Owner working a task over — pinning down the requirements and the must-haves before anyone writes a line of code.

2 · Nothing moves without your green light

The Board hands the reviewed task back to you as a notification and waits. You make one call: send it forward, or send it back. Approve it, and the Main PM picks it up, splits it across the cells, and sets them running.

The Board's verdict lands in your notifications and pauses there. A single approval is what turns the whole company on.

3 · The cells take over

Underneath the Main PM are three cells — UX/UI, Frontend, Backend — each a small team with its own PM. Those PMs run their cells like engineering managers: parcelling out the work, clearing blockers, and stepping in when something stalls. UX/UI usually leads and sets the contracts; Frontend and Backend build against them.

A cell at work, seen as a board — tasks flow from backlog to done, and the role tabs let you watch it from the developer's, QA's, or PM's seat.

4 · The work gets done — and checked

This is where it's actually built. Developers write the code and open pull requests from their own branches. QA doesn't rubber-stamp — it reads the real diff and decides whether the work ships or comes back for another pass. Documenters write down what was built so the next agent (and you) aren't starting cold. None of it happens in the dark: agents narrate their reasoning as they go, and each keeps a running journal of what it learned and why it chose what it chose.

Every agent keeps a journal — reflections, decisions, and lessons. Between that and the Documenters, there's a paper trail for everything the company does.

5 · The work converges

Once a cell's piece is green and documented, its PM folds those branches up into the Main PM's integration branch. Three independent streams of work come back together into one. Each task brings its branch, pull request, commits, and docs along with it:

One finished unit — branch, pull request, commits, and docs all attached. This is the thing that travels up the merge chain.

6 · The last call is yours

With everything merged, the Main PM opens the final pull request and lets you know it's ready. The decision comes back to where it started — with you. Merge it and it ships, or send it around for another lap. You're the only one who ever touches master, and anything waiting on you sits in the CEO Approval Queue on the Command Center until you act.

---

And round it goes

You handed the company a task; it scoped it, built it, reviewed it, documented it, and merged it; and it landed back on your desk for sign-off. That's one complete pass — and you can keep as many running at once, across as many projects, as you want.

---

RoboCo is early-stage, work-in-progress software (v0) — expect rough edges. The README covers setup, architecture, and the security model.