diff --git a/docs/how-to.md b/docs/how-to.md index 42698eb5..5c0b2cda 100644 --- a/docs/how-to.md +++ b/docs/how-to.md @@ -1,11 +1,26 @@ # 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. +RoboCo is a virtual software company — 18 AI agents and one human: you. Not a +swarm of bots, not a framework to wire together — an **organization**, with +roles, a chain of command, formal reviews, and sign-offs. You don't micromanage +it; you run it like a CEO. Drop work in at the top and the company carries it all +the way through planning, building, review, and documentation, then brings it +back to your desk for the final word. You act at the two ends; the organization +fills in everything between. + +What keeps eighteen agents from dissolving into noise is that RoboCo is +relentlessly opinionated about *how* work happens: everything is a task, no task +moves without acceptance criteria, and every task walks the same strict lifecycle +— built, QA'd, documented, PM-reviewed, approved — each step gated by role. The +structure is the point. It is what turns a roster of models into a company that +actually ships. + +And the proof is this page. The screenshots below aren't a mock-up: they follow +RoboCo building one of its *own* features — the **Prompter**, the task-authoring +page now living in this very control panel. RoboCo's agents scoped it, built it +across three cells, failed and re-ran its QA, documented it, and opened the real +pull request you'll see at the end. RoboCo builds RoboCo — that is the whole +proof of concept. > The panel is your one window into the company. Every task, agent, message, > journal, and pull request is live in front of you. @@ -71,6 +86,13 @@ nothing is implicit and nothing is lost.* *The Product Owner working a task over — pinning down the requirements and the must-haves before anyone writes a line of code.* +![A Board review session for the Prompter feature, with the Product Owner and Head of Marketing each recording their take — positioning, naming, the model-selector UX — against the task.](images/po_hom_review.png) + +*Two seats at the table. The Product Owner and the Head of Marketing review the +same task from their own angles and put their reasoning on the record — this is +the Board building the actual spec for the Prompter, the feature this whole +walkthrough follows.* + ### 2 · Nothing moves without your green light The Board hands the reviewed task back to you as a **notification** and waits. @@ -82,6 +104,13 @@ 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.* +![The board-review-complete notification for the Prompter task: the Product Owner and Head of Marketing have both reviewed it, and it is now ready for the CEO's Approve & Start decision or rejection.](images/ceo_review_notif.png) + +*The notification itself, spelled out: the Board has finished, the task is +recorded, and nothing happens until you say so — Approve & Start hands it to the +Main PM; reject it and it goes back. This is the first of the only two moments +the company needs you.* + ![The CEO's pending-approval queue with a task card showing the green "Approve & Start" button.](images/approve_task.png) ![The task detail panel opened from the approval queue, with the Approve & Start action alongside the task brief.](images/approve_task_detail.png) @@ -109,6 +138,13 @@ 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. +![A task's notes after a QA review: the developer's notes, a QA section marked Failed, and a silent Auditor column — all on the same task.](images/qa_fail.png) + +*QA earning its seat. On this Prompter task it read the work, marked it +**failed**, and sent it back — the developer's notes and the QA verdict sit side +by side on the record, with the Auditor watching the whole exchange. Real review, +not a rubber stamp; the gate only opens when the work is right.* + ![Agent Journals: per-agent reflections, decision logs, and learnings.](images/journaling.png) *Every agent keeps a journal — reflections, decisions, and lessons. Between that @@ -126,24 +162,68 @@ along with it: *One finished unit — branch, pull request, commits, and docs all attached. This is the thing that travels up the merge chain.* +![The integrated pull request's commit list: one verified commit per cell — the UX/UI design specs and the backend chat endpoint — each co-authored by the agent that wrote it.](images/opened_final_pr_commits.png) + +*Three streams becoming one history. Each cell's work lands as its own +**verified** commit, co-authored by the agent that wrote it — the UX/UI design, +the backend endpoint, the frontend page — folded together into the single pull +request that comes back to you.* + ### 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. +The cells' work is folded up, the Main PM opens the **final pull request** into +`master`, and the company goes quiet. The decision comes back to exactly where it +started — with you. You're the only one who ever touches `master`, and anything +waiting on you sits in the **CEO Approval Queue** until you act. -![The final CEO approval notification: the integrated PR waiting for the merge, with the Approve & Merge action surfaced.](images/ceo_approval_notif.png) +![The final CEO approval notification: the integrated Prompter PR is ready, all three cells delivered and QA-passed, awaiting the CEO's review and merge.](images/ceo_approval_notif.png) + +*The hand-off back to you. The integrated PR is open, every cell has delivered, +QA is green — and it waits. Nothing reaches `master` without your word.* + +![The integrated pull request open on GitHub, in the repository's Pull Requests list.](images/opened_final_pr.png) + +*And it is a real pull request, on the real repository — not a simulation. The +company's work shows up exactly where any engineer would look for it.* + +![The pull request's description: the objective, what the task builds, the per-cell breakdown, and the notes the company wrote for it.](images/opened_final_pr_body.png) + +*Open it and the whole brief is there — the objective, what was built, the +board-led split across the three cells, and the company's own notes — written by +RoboCo, for you to read before you decide.* + +![The pull request's Files changed tab: the actual diff — migrations, API, and panel components — the company is asking to merge.](images/opened_final_pr_changes.png) + +*The real diff, laid out for you to inspect — the migrations, the endpoints, the +panel components. This is the substance you are signing off on.* + +![The CEO's actions on the awaiting-approval task: Approve & Merge, Request Changes, or Cancel.](images/approve_button_merge_rework.png) + +*Your two words. **Approve & Merge** and it ships to `master`; **Request Changes** +and it goes around for another lap. The last call has the same shape as the first +— one decision, yours alone.* --- ## 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. +You handed the company a task; it scoped it, built it, failed and re-ran its own +QA, documented it, and brought it back as a single pull request for your +sign-off. That's one complete pass. + +![The full task table for the Prompter feature: a parent task awaiting CEO approval over its completed UX/UI, Frontend, and Backend child tasks.](images/all_tasks_final_state.png) + +*The whole tree in its final state — the parent waiting on your approval, every +cell's task done beneath it. One feature, start to finish, with you at only the +two ends.* + +And the feature in these screenshots is the proof. The **Prompter** wasn't built +for a demo — it's a real page RoboCo's agents shipped to RoboCo's own control +panel. A company building its own product, in front of you, is the whole point of +RoboCo. What makes that hold together isn't a clever model or a lucky run; it's +the **organization** — the roles, the gated lifecycle, the reviews and the +sign-offs that keep eighteen agents moving as a company instead of a crowd. Run +as many of these passes as you like, across as many projects as you like. --- diff --git a/docs/images/all_tasks_final_state.png b/docs/images/all_tasks_final_state.png new file mode 100644 index 00000000..babafbb6 Binary files /dev/null and b/docs/images/all_tasks_final_state.png differ diff --git a/docs/images/approve_button_merge_rework.png b/docs/images/approve_button_merge_rework.png new file mode 100644 index 00000000..e8b53809 Binary files /dev/null and b/docs/images/approve_button_merge_rework.png differ diff --git a/docs/images/ceo_approval_notif.png b/docs/images/ceo_approval_notif.png index 62d33aa7..84d91ea9 100644 Binary files a/docs/images/ceo_approval_notif.png and b/docs/images/ceo_approval_notif.png differ diff --git a/docs/images/ceo_review_notif.png b/docs/images/ceo_review_notif.png new file mode 100644 index 00000000..62d33aa7 Binary files /dev/null and b/docs/images/ceo_review_notif.png differ diff --git a/docs/images/opened_final_pr.png b/docs/images/opened_final_pr.png new file mode 100644 index 00000000..ab591a5a Binary files /dev/null and b/docs/images/opened_final_pr.png differ diff --git a/docs/images/opened_final_pr_body.png b/docs/images/opened_final_pr_body.png new file mode 100644 index 00000000..e7ba58bf Binary files /dev/null and b/docs/images/opened_final_pr_body.png differ diff --git a/docs/images/opened_final_pr_changes.png b/docs/images/opened_final_pr_changes.png new file mode 100644 index 00000000..ff6382e6 Binary files /dev/null and b/docs/images/opened_final_pr_changes.png differ diff --git a/docs/images/opened_final_pr_commits.png b/docs/images/opened_final_pr_commits.png new file mode 100644 index 00000000..3c0d9e00 Binary files /dev/null and b/docs/images/opened_final_pr_commits.png differ diff --git a/docs/images/po_hom_review.png b/docs/images/po_hom_review.png new file mode 100644 index 00000000..2263f554 Binary files /dev/null and b/docs/images/po_hom_review.png differ diff --git a/docs/images/qa_fail.png b/docs/images/qa_fail.png new file mode 100644 index 00000000..989fc290 Binary files /dev/null and b/docs/images/qa_fail.png differ