mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
Renn F
2fb63fed1f
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.
90 lines
4.8 KiB
Markdown
90 lines
4.8 KiB
Markdown
# 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.
|
|
|
|
```mermaid
|
|
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:
|
|
|
|
```mermaid
|
|
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_pass`es** it on to the PM merge or **`pr_fail`s** 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](agent-gateway.md).
|
|
|
|
## Next
|
|
|
|
→ **[The merge model](merge-model.md)** — how a task's branch travels up to `master`.
|