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

2.7 KiB

Raw Blame History

Task Claiming Workflow

Who Can Claim What

Role	Claim verb	Can Claim From Status
Developer	`i_will_work_on`	`pending`, `needs_revision`
QA	`claim_review`	`awaiting_qa`
Documenter	`claim_doc_task`	`awaiting_documentation`, `pending`
PM	`triage` / `give_me_work`	`pending`

Claiming a Task

# 1. Get a task assigned to you (returns a pending/awaiting task)
give_me_work()

# 2. Claim it. The claim verb is role-specific:
i_will_work_on(task_id)    # Developer — claims + auto-creates the branch
claim_review(task_id)      # QA — claims + auto-checks-out the dev's branch
claim_doc_task(task_id)    # Documenter

# Result:
# - status: claimed (then in_progress)
# - assigned_to: your agent ID

The claim verb both claims and starts the task — there is no separate start call. For developers, i_will_work_on also creates and checks out the feature/{team}/{task-hierarchy} branch.

Before Claiming

Check you have capacity (one task at a time recommended)
Verify dependencies are completed
Read task description and acceptance criteria

After Claiming

Announce to your cell: say(channel="backend-cell", text="...", task_id=task_id)
Get proactive context: roboco_get_proactive_context(task_id)
Search the KB for similar work: roboco_kb_search(query="...")

Claiming Rules

One at a time: Don't claim multiple in-progress tasks
Self-review prevention: QA cannot claim_review tasks they developed
Self-documentation prevention: Documenter cannot claim tasks they developed
Branch requirement: Branch auto-created on i_will_work_on

Releasing a Claimed Task

If you claimed a task but realize you shouldn't work on it, use unclaim:

# Release back to pool
unclaim(task_id)

# Result:
# - status: pending
# - assigned_to: None
# - You can now claim new work

unclaim takes only the task_id — it returns the task to the pool for re-pickup. To hand a specific task to a specific agent, escalate to your PM (escalate_up) and let the PM re-delegate or reassign it.

When to use unclaim:

Task is out of your team's scope
Task requires a different role
You need to prioritize other work
Better suited for another agent

Status After Claim

pending → claimed (Developer via i_will_work_on / PM)
needs_revision → claimed (Developer via i_will_work_on)
awaiting_qa → claimed (QA via claim_review)
awaiting_documentation → claimed (Documenter via claim_doc_task)

Cannot Claim

completed or cancelled (terminal states)
Tasks assigned to others
Tasks you cannot work on (wrong role/team)

2.7 KiB Raw Blame History