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

Files

T

Renn F ecea593a51 docs(rag): rewrite the KB docs to the real gateway verb surface

The RAG knowledge base (indexed and queried by agents at runtime)
described entire fictional MCP tool surfaces — roboco_task_*,
roboco_journal_*, roboco_message_send, roboco_notify_send, roboco_agent_*,
roboco_session_*, roboco_workspace_*, roboco_project_* — that don't exist,
so agents searching the KB were handed invented tool names.

Rewrite every affected doc (tools, roles, workflows, troubleshooting, and
the stale architecture snippets) to the real surface: the gateway intent
verbs (give_me_work, i_will_work_on, open_pr, i_am_done, claim_review,
pass, fail, claim_doc_task, i_documented, triage, delegate, i_will_plan,
unblock, complete, escalate_up, escalate_to_ceo, ...) and content tools
(commit, note(scope=...), say, dm, evidence, notify*, open_session,
channels). Also reconcile the access-control docs to code: CEO can cancel
(Board/Auditor cannot); the management-channel membership and the
Auditor's silent-but-present status now match communications.py.

2026-06-05 17:20:36 +02:00

4.9 KiB

Raw Blame History

Task Management Tools

There is no roboco_task_* tool surface. Tasks move through the lifecycle via flow verbs on the roboco-flow MCP server. Each verb is role-scoped — you only see the ones your role is allowed to call (the spawn manifest registers them per role). Every verb returns an Envelope whose next field tells you what to call next; trust it rather than guessing state.

The verbs below are grouped by who calls them.

Developer flow

give_me_work()                  # returns your most-actionable pending task
i_will_work_on(task_id, plan="...")
                                # claims + sets plan + starts; auto-creates and
                                # checks out feature/{team}/{task-hierarchy}
commit(message, files=None)     # content tool — repeat per change (auto-pushed)
open_pr(task_id)                # pushes branch + opens the PR
i_am_done(task_id, notes="")    # verifying -> awaiting_qa (PR must already be open)
i_am_blocked(task_id, reason)   # external dependency; cell PM unblocks
unclaim(task_id)                # release a claimed task back to the queue
resume(task_id)                 # recover a paused task after compact/restart
i_am_idle()                     # no work in your queue right now

There is no separate claim / start / pause verb — i_will_work_on composes claim + set-plan + start atomically, and i_am_done composes verify + submit-qa. Branches are auto-created on i_will_work_on; do not checkout by hand.

QA flow

give_me_work()                  # returns an awaiting_qa task
claim_review(task_id)           # claim for review (auto-checks-out dev branch)
pass(task_id, notes)            # awaiting_qa -> awaiting_documentation
fail(task_id, issues=[...])     # awaiting_qa -> needs_revision (dev gets it back)
unclaim(task_id) / resume(task_id) / i_am_idle()

notes (on pass) and issues (on fail) must be substantive — the enforcement layer rejects empty or near-empty content. QA cannot review its own dev work (self-review guard rejects on claim_review).

Documenter flow

give_me_work()                  # returns an awaiting_documentation task
claim_doc_task(task_id)         # claim the doc phase
commit(message, files)          # commit the doc files you write
i_documented(task_id, notes, files)
                                # awaiting_documentation -> awaiting_pm_review

Documentation tasks are not delegated — the lifecycle auto-creates the doc phase after a code task passes QA.

Cell PM flow

triage()                        # list actionable tasks in your cell
i_will_plan(task_id, plan, approach)
                                # claim + plan + start a parent task
delegate(parent_task_id, title, description, assigned_to, team,
         task_type, nature, estimated_complexity, acceptance_criteria)
                                # create a subtask under the current task
unblock(task_id)                # blocked -> in_progress (PM only)
submit_up(task_id, notes)       # open cell->root PR; -> awaiting_pm_review
complete(task_id, notes)        # awaiting_pm_review -> completed (merges leaf PR)
escalate_up(task_id, reason)    # escalate to your escalation target

Delegation rules (enforced): main_pm -> cell_pm; cell_pm -> its team's devs. Cell PMs receive planning-typed parent tasks; devs get code/research (UX devs also design). Always create subtasks via delegate with parent_task_id set — there is no standalone task-create verb for agents.

Main PM flow

The Main PM has the Cell PM verbs plus:

triage_all()                    # list actionable tasks across all teams
escalate_to_ceo(task_id, reason)
                                # awaiting_pm_review -> awaiting_ceo_approval
give_me_work()                  # Main PM may also pull work directly

complete for the Main PM merges the root PR. Only the CEO merges to master; agents stop at escalate_to_ceo.

Board flow (Product Owner / Head of Marketing)

triage()                        # list actionable tasks in scope
escalate_to_ceo(task_id, reason)
i_am_idle()

The Board cannot claim, create, complete, or cancel tasks. Strategic decisions are escalated to the CEO.

Auditor flow

triage()                        # read-only list of actionable tasks
i_am_idle()

The Auditor is a silent observer: read-only triage, no say/dm/ notify, no claim/complete/cancel.

Cancel

Cancelling a task (any non-terminal status -> cancelled) is restricted to PM roles and the CEO. There is no agent verb to cancel — it is a PM/CEO operation through the lifecycle.

Progress

Record progress against your plan with the progress content tool (on roboco-do), not a task verb:

progress(task_id, message="API skeleton landed", plan_step="2")

Your plan's steps are the progress checklist; the percentage is derived from completed steps — you do not set it.

4.9 KiB Raw Blame History