mirror of https://github.com/rennf93/roboco.git synced 2026-08-03 07:23:24 +02:00

Files

T

Renn F 2fb63fed1f docs: add the user-facing MkDocs documentation site

Build a complete user-facing documentation site (MkDocs Material) under docs/, served at roboco.dev/docs via a new gh-pages deploy workflow.

- Sections: Get Started, The Company, the Tour, Operating the Panel, Choosing & Running Models, Cost & Observability, Optional Subsystems, Configure & Deploy, API Reference, Troubleshooting & Security (55 pages).
- mkdocs.yml (Material theme; excludes the agent-facing rag/ corpus, internal scratch, and orphaned stub trees) and .github/workflows/docs.yml (mkdocs gh-deploy to gh-pages).
- Retire the stale root usage.md and deployment.md to redirect stubs into the site.
- Fix the docs tooling: add the pymarkdownlnt dependency + .pymarkdown.json, run serve-docs/lint-docs/fix-docs under the docs extra, add a build-docs strict gate.
- Fix the roboco console-script entry point (cli, not the un-awaited async main).
- README: correct the project-structure tree (optimal.py, alembic) and link the docs site.

2026-06-22 15:53:00 +02:00

4.8 KiB

Raw Blame History

The task lifecycle

Everything in RoboCo is a task, and every task walks the same path. Each step is gated by role — only QA can pass QA, only the CEO can merge to master — so work can't skip a stage or land unreviewed. This is the backbone that makes the company trustworthy.

stateDiagram-v2
    direction LR
    [*] --> backlog
    backlog --> pending: PM activates
    pending --> claimed: agent claims
    claimed --> in_progress: start work
    in_progress --> verifying: self-verify
    verifying --> awaiting_qa: submit (PR is open)
    awaiting_qa --> awaiting_documentation: QA passes
    awaiting_qa --> needs_revision: QA fails
    needs_revision --> in_progress: rework
    awaiting_documentation --> awaiting_pm_review: docs done
    awaiting_pm_review --> completed: PM merges
    awaiting_pm_review --> awaiting_ceo_approval: escalate
    awaiting_ceo_approval --> completed: CEO approves & merges
    awaiting_ceo_approval --> needs_revision: CEO requests changes
    completed --> [*]

    in_progress --> blocked: external dependency
    in_progress --> paused: temporarily stopped
    blocked --> in_progress: unblocked
    paused --> in_progress: resumed

The states

State	What it means	Who owns the next move
`backlog`	PM setup phase — dependencies or session setup still needed.	PM
`pending`	Ready for work; the orchestrator can spawn an agent for it.	the matching role
`claimed`	An agent has locked the task.	the assignee
`in_progress`	Active development.	the assignee
`blocked`	An external dependency is blocking progress.	whoever clears it
`paused`	Temporarily stopped; can resume.	the assignee
`verifying`	The developer is self-verifying before handing off.	the developer
`awaiting_qa`	Submitted for QA — a pull request is already open so QA reviews the real diff.	QA
`needs_revision`	QA, a PR reviewer, or the CEO asked for changes.	the developer
`awaiting_documentation`	The Documenter writes up what was built (the PR is already open).	Documenter / Developer
`awaiting_pr_review`	The in-path PR-review gate: a reviewer checks an assembled pull request before the PM merges it.	PR reviewer
`awaiting_pm_review`	Docs are done; the PM reviews and merges.	PM
`awaiting_ceo_approval`	A major task escalated to you for the final call.	you
`completed`	Terminal — work done and merged.	—
`cancelled`	Terminal — work cancelled.	—

!!! note "The PR comes before QA" A pull request is opened before QA review, not after. That lets QA read the actual PR diff on GitHub, and means the whole downstream approval chain — PM, then you — is signing off on a pull request that already exists.

When work is rejected

Rejection isn't a dead end — it's a loop. When QA fails a task, or a PR reviewer rejects an assembled pull request, the task drops back to needs_revision, the developer reworks it, and it re-enters the flow. The same is true when you request changes from the CEO Approval Queue. Nothing is lost; the task carries its history, branch, and pull request with it the whole way around.

The in-path PR-review gate

Most leaf developer tasks are reviewed by QA and never need a separate PR review. But when work is assembled and pushed up the chain as a pull request, it stops for a dedicated review before any PM merges it:

stateDiagram-v2
    direction LR
    in_progress --> awaiting_pr_review: submit_up / submit_root
    awaiting_pr_review --> awaiting_pm_review: pr_pass
    awaiting_pr_review --> needs_revision: pr_fail

A cell PM runs submit_up to open the cell → root pull request.
The Main PM runs submit_root to open the root → master pull request.
Both land in awaiting_pr_review, where a PR reviewer either pr_passes it on to the PM merge or pr_fails it back to needs_revision.

This gives the merge step a real reviewer with the power to reject — the one thing a PM otherwise lacks. Leaf dev tasks and branchless coordination roots skip the gate.

Role-gated transitions

Transitions aren't suggestions; they're enforced. A handful of the rules:

Activating a task (backlog → pending) is PM-only.
Passing or failing QA is QA-only, and a pass requires real review notes.
pr_pass / pr_fail are PR-reviewer-only.
Merging (awaiting_pm_review → completed) is PM-only; escalating to the CEO and the final approve / request-changes / cancel are CEO-only.
Cancelling is PM-only.

How those role boundaries are enforced — and why a developer literally cannot call the merge verb — is the subject of How agents are sandboxed.

→ The merge model — how a task's branch travels up to master.

4.8 KiB Raw Blame History