mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
437 lines
24 KiB
Markdown
437 lines
24 KiB
Markdown
# RoboCo Workflows & Permissions
|
|
|
|
Visual documentation of task lifecycles, permissions, and workflows.
|
|
|
|
## 0. Terminology Dictionary
|
|
|
|
**CRITICAL: Understand these concepts before reading further.**
|
|
|
|
### Communication Hierarchy
|
|
|
|
```
|
|
Channel → Group → Session → Messages
|
|
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|
│ CHANNEL (e.g., "backend-cell") │
|
|
│ A named communication space for a team/topic │
|
|
│ │
|
|
│ ┌───────────────────────────────────────────────────────────────────┐ │
|
|
│ │ GROUP (e.g., "Sprint 5 Backend Work") │ │
|
|
│ │ A collection within a channel (project, sprint, topic) │ │
|
|
│ │ │ │
|
|
│ │ ┌───────────────────────────────────────────────────────────┐ │ │
|
|
│ │ │ SESSION (e.g., "TASK-123 Discussion") │ │ │
|
|
│ │ │ A conversation thread, usually tied to a task │ │ │
|
|
│ │ │ │ │ │
|
|
│ │ │ ┌─────────────────────────────────────────────────┐ │ │ │
|
|
│ │ │ │ MESSAGES │ │ │ │
|
|
│ │ │ │ Individual messages within a session │ │ │ │
|
|
│ │ │ │ Types: action, dialogue, blocker, question │ │ │ │
|
|
│ │ │ └─────────────────────────────────────────────────┘ │ │ │
|
|
│ │ └───────────────────────────────────────────────────────────┘ │ │
|
|
│ └───────────────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────┘
|
|
|
|
Tools:
|
|
- roboco_channel_list() → List channels you can access
|
|
- roboco_channel_history() → Get messages from a channel's sessions
|
|
- roboco_session_history_for_task() → Get messages for a specific task's session
|
|
- roboco_message_send() → Send to channel (routes via task_id to session)
|
|
```
|
|
|
|
### Journal vs Documentation
|
|
|
|
```
|
|
┌─────────────────────────────────────┬─────────────────────────────────────┐
|
|
│ JOURNAL │ DOCUMENTATION │
|
|
├─────────────────────────────────────┼─────────────────────────────────────┤
|
|
│ WHAT: Agent's personal reflections │ WHAT: Project/codebase docs │
|
|
│ │ │
|
|
│ WHERE: Database (journal entries) │ WHERE: /app/docs/ files │
|
|
│ │ │
|
|
│ WHO WRITES: Each agent, for self │ WHO WRITES: Documenter agents │
|
|
│ │ │
|
|
│ PURPOSE: │ PURPOSE: │
|
|
│ - Track decisions & rationale │ - API documentation │
|
|
│ - Record learnings & struggles │ - README updates │
|
|
│ - Reflect on task completion │ - Changelog entries │
|
|
│ - Build context for future sessions │ - Component/feature docs │
|
|
│ │ │
|
|
│ AUDIENCE: Self + cell members │ AUDIENCE: All developers, users │
|
|
│ │ │
|
|
│ TOOLS: │ TOOLS: │
|
|
│ - roboco_journal_entry() │ - Write tool to /app/docs/ │
|
|
│ - roboco_journal_reflect() │ - roboco_task_docs_complete() │
|
|
│ - roboco_journal_decision() │ │
|
|
│ - roboco_journal_learning() │ │
|
|
│ - roboco_journal_read_team() │ │
|
|
└─────────────────────────────────────┴─────────────────────────────────────┘
|
|
|
|
KEY DISTINCTION:
|
|
- Journal = "What I learned/decided while doing this task" (internal notes)
|
|
- Documentation = "How this feature works for others" (external docs)
|
|
|
|
Documenter reads journals to UNDERSTAND what was built, then writes documentation.
|
|
```
|
|
|
|
### Task Notes vs Journals
|
|
|
|
```
|
|
┌─────────────────────────────────────┬─────────────────────────────────────┐
|
|
│ TASK NOTES │ JOURNALS │
|
|
│ (dev_notes, qa_notes) │ │
|
|
├─────────────────────────────────────┼─────────────────────────────────────┤
|
|
│ Attached to the task record │ Separate entries linked by task_id │
|
|
│ │ │
|
|
│ Brief handoff summaries │ Detailed journey records │
|
|
│ │ │
|
|
│ Set via: │ Set via: │
|
|
│ - roboco_task_submit_qa(notes) │ - roboco_journal_*() tools │
|
|
│ - roboco_task_qa_pass(notes) │ │
|
|
│ - roboco_task_docs_complete(notes) │ │
|
|
│ │ │
|
|
│ Examples: │ Examples: │
|
|
│ "Implemented X, tested Y" │ "Decided to use pattern X because Y"│
|
|
│ "QA passed, verified all criteria" │ "Struggled with Z, solved via W" │
|
|
└─────────────────────────────────────┴─────────────────────────────────────┘
|
|
```
|
|
|
|
## 1. Task Lifecycle State Machine
|
|
|
|
```mermaid
|
|
stateDiagram-v2
|
|
[*] --> pending: Task Created
|
|
|
|
pending --> claimed: Developer claims
|
|
pending --> cancelled: PM cancels
|
|
|
|
claimed --> in_progress: Developer starts
|
|
claimed --> pending: Developer unclaims
|
|
claimed --> cancelled: PM cancels
|
|
|
|
in_progress --> blocked: Developer blocked
|
|
in_progress --> paused: Developer pauses
|
|
in_progress --> verifying: Developer self-verifies
|
|
in_progress --> cancelled: PM cancels
|
|
|
|
blocked --> in_progress: Unblocked
|
|
blocked --> cancelled: PM cancels
|
|
|
|
paused --> in_progress: Developer resumes
|
|
paused --> cancelled: PM cancels
|
|
|
|
verifying --> awaiting_qa: Submit for QA
|
|
verifying --> needs_revision: Self-found issues
|
|
verifying --> awaiting_documentation: Skip QA (small tasks)
|
|
verifying --> cancelled: PM cancels
|
|
|
|
awaiting_qa --> awaiting_documentation: QA PASS
|
|
awaiting_qa --> needs_revision: QA FAIL
|
|
awaiting_qa --> blocked: Blocked during QA
|
|
awaiting_qa --> cancelled: PM cancels
|
|
|
|
needs_revision --> in_progress: Developer resumes
|
|
needs_revision --> cancelled: PM cancels
|
|
|
|
awaiting_documentation --> awaiting_pm_review: Documenter marks docs done
|
|
awaiting_documentation --> cancelled: PM cancels
|
|
|
|
awaiting_pm_review --> completed: PM completes
|
|
awaiting_pm_review --> cancelled: PM cancels
|
|
|
|
completed --> [*]
|
|
cancelled --> [*]
|
|
|
|
quarantined --> pending: Un-quarantined
|
|
```
|
|
|
|
## 2. Agent Hierarchy & Roles
|
|
|
|
```
|
|
+-------+
|
|
| CEO |
|
|
+-------+
|
|
|
|
|
+---------------+---------------+
|
|
| | |
|
|
+---------+ +-----------+ +---------+
|
|
| Product | | Head | | Auditor |
|
|
| Owner | | Marketing | | (silent)|
|
|
+---------+ +-----------+ +---------+
|
|
| | |
|
|
+-------+-------+ |
|
|
| |
|
|
+---------+ |
|
|
| Main PM |<-----------------+
|
|
+---------+ (observes all)
|
|
|
|
|
+-----------+-----------+
|
|
| | |
|
|
+-------+ +-------+ +-------+
|
|
| BE PM | | FE PM | | UX PM |
|
|
+-------+ +-------+ +-------+
|
|
| | |
|
|
+-------+ +-------+ +-------+
|
|
|Backend| |Frontend| | UX/UI |
|
|
| Cell | | Cell | | Cell |
|
|
+-------+ +-------+ +-------+
|
|
|
|
Each Cell:
|
|
- 2 Developers (BE/FE) or 1 Developer (UX)
|
|
- 1 QA Engineer
|
|
- 1 Documenter
|
|
- 1 Cell PM
|
|
```
|
|
|
|
## 3. Notification Permissions
|
|
|
|
```
|
|
WHO CAN SEND NOTIFICATIONS:
|
|
|
|
+------------------+-------------+----------------------------------------------+
|
|
| Sender Role | Can Send? | Scope |
|
|
+------------------+-------------+----------------------------------------------+
|
|
| CEO | YES | Anyone |
|
|
| Auditor | YES | Anyone |
|
|
| Main PM | YES | Anyone |
|
|
| Product Owner | YES | main-pm, head-marketing, auditor, ceo |
|
|
| Head Marketing | YES | main-pm, product-owner, auditor, ceo |
|
|
| Cell PM | YES | Own cell only |
|
|
+------------------+-------------+----------------------------------------------+
|
|
| Developer | NO | - |
|
|
| QA | NO | - |
|
|
| Documenter | NO | - |
|
|
+------------------+-------------+----------------------------------------------+
|
|
|
|
TOOLS VISIBILITY:
|
|
|
|
+----------------------+------------+----------+---------+---------+---------+
|
|
| Tool | Dev/QA/Doc | Cell PM | Main PM | Board | Aud/CEO |
|
|
+----------------------+------------+----------+---------+---------+---------+
|
|
| roboco_notify_list | YES | YES | YES | YES | YES |
|
|
| roboco_notify_get | YES | YES | YES | YES | YES |
|
|
| roboco_notify_ack | YES | YES | YES | YES | YES |
|
|
| roboco_notify_send | HIDDEN | YES | YES | YES | YES |
|
|
| roboco_escalate | HIDDEN | YES | YES | HIDDEN | HIDDEN |
|
|
| roboco_request_appr | HIDDEN | YES | YES | YES | HIDDEN |
|
|
+----------------------+------------+----------+---------+---------+---------+
|
|
|
|
Note: "Board" = Product Owner + Head Marketing. Auditor/CEO can send but not escalate or request approval.
|
|
```
|
|
|
|
## 4. QA Workflow (Full Detail)
|
|
|
|
### QA Status Acceptance
|
|
|
|
QA can call `qa_pass` or `qa_fail` from ANY of these statuses:
|
|
- `awaiting_qa` (initial)
|
|
- `claimed` (after QA claims)
|
|
- `in_progress` (after QA starts)
|
|
|
|
This allows QA to follow the full workflow: SCAN → CLAIM → PLAN → START → TEST → VERDICT
|
|
|
|
### QA Workflow Diagram
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Dev as Developer
|
|
participant Task as Task System
|
|
participant QA as QA Engineer
|
|
participant Doc as Documenter
|
|
participant PM as Cell PM
|
|
|
|
Dev->>Task: Submit for QA (awaiting_qa)
|
|
Note over Task: assigned_to = QA<br/>quick_context = original_developer:Dev
|
|
|
|
QA->>Task: roboco_task_claim() → status = claimed
|
|
QA->>Task: roboco_task_plan() → save test plan
|
|
QA->>Task: roboco_task_start() → status = in_progress
|
|
QA->>Task: Test work against criteria
|
|
|
|
alt QA PASS
|
|
QA->>Task: roboco_task_qa_pass(qa_notes)
|
|
Task->>Task: status = awaiting_documentation
|
|
Note over Task: HANDOFF TO DOCUMENTER
|
|
Doc->>Task: roboco_task_claim() → status = claimed
|
|
Doc->>Task: roboco_task_plan() → save doc plan
|
|
Doc->>Task: roboco_task_start() → status = in_progress
|
|
Doc->>Task: GATHER info (see section 4a)
|
|
Doc->>Task: WRITE docs to /app/docs/
|
|
Doc->>Task: roboco_task_docs_complete()
|
|
Task->>Task: status = awaiting_pm_review
|
|
PM->>Task: roboco_task_complete()
|
|
Task->>Task: status = completed
|
|
else QA FAIL
|
|
QA->>Task: roboco_task_qa_fail(qa_notes, issues)
|
|
Task->>Task: status = needs_revision
|
|
Task->>Task: assigned_to = original Dev
|
|
Dev->>Task: roboco_task_start() → status = in_progress
|
|
Dev->>Task: Fix issues, resubmit
|
|
end
|
|
```
|
|
|
|
### 4a. Documenter Information Gathering
|
|
|
|
```
|
|
DOCUMENTER MUST GATHER FROM 3 SOURCES:
|
|
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ SOURCE 1: TASK DETAILS (roboco_task_get) │
|
|
│ ───────────────────────────────────────── │
|
|
│ • description, acceptance_criteria │
|
|
│ • dev_notes (developer's handoff summary) │
|
|
│ • qa_notes (QA's verification notes) │
|
|
│ • quick_context (original developer, etc.) │
|
|
├─────────────────────────────────────────────────────────────────────────────┤
|
|
│ SOURCE 2: TEAM JOURNALS (roboco_journal_read_team) │
|
|
│ ───────────────────────────────────────────────── │
|
|
│ Read developer's journey: │
|
|
│ roboco_journal_read_team("be-dev-1", task_id=task_id, limit=20) │
|
|
│ │
|
|
│ What to look for: │
|
|
│ • Decisions made and WHY │
|
|
│ • Struggles encountered and how solved │
|
|
│ • Learnings documented │
|
|
│ • Design/architecture choices │
|
|
├─────────────────────────────────────────────────────────────────────────────┤
|
|
│ SOURCE 3: SESSION MESSAGES (roboco_session_history_for_task) │
|
|
│ ──────────────────────────────────────────────────────────── │
|
|
│ Read discussion context: │
|
|
│ roboco_session_history_for_task(task_id) │
|
|
│ │
|
|
│ What to look for: │
|
|
│ • Questions asked and answers given │
|
|
│ • Clarifications from PM/dev │
|
|
│ • Blockers discussed and resolutions │
|
|
│ • Design decisions made in discussion │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
NOTE: Journals are INPUT for understanding. Documentation is OUTPUT to /app/docs/.
|
|
```
|
|
|
|
## 5. Block/Unblock Workflow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Dev as Developer
|
|
participant Task as Task System
|
|
participant PM as Cell PM
|
|
|
|
Dev->>Task: Working on task (in_progress)
|
|
|
|
Note over Dev: Encounters blocker
|
|
|
|
Dev->>Task: roboco_task_block(reason, type, what_needed)
|
|
Task->>Task: POST /tasks/{id}/soft-block
|
|
Task->>Task: status = blocked
|
|
Task->>Task: dev_notes += blocker info
|
|
|
|
Note over Dev: Can work on other tasks
|
|
|
|
alt Blocker resolved
|
|
Dev->>Task: roboco_task_unblock()
|
|
Task->>Task: POST /tasks/{id}/unblock
|
|
Task->>Task: status = in_progress
|
|
Dev->>Task: Continue working
|
|
else Need PM help
|
|
Dev->>PM: roboco_report_blocker() via message channel
|
|
PM->>Task: Resolves blocker
|
|
Dev->>Task: roboco_task_unblock()
|
|
end
|
|
```
|
|
|
|
## 6. Task Role Restrictions
|
|
|
|
```
|
|
ROLE-BASED TRANSITIONS:
|
|
|
|
+-------------------------------+-------------------------------------------+
|
|
| Transition | Allowed Roles |
|
|
+-------------------------------+-------------------------------------------+
|
|
| awaiting_qa → awaiting_doc | QA only |
|
|
| awaiting_qa → needs_rev | QA only |
|
|
| awaiting_doc → awaiting_pm | Documenter only |
|
|
| awaiting_pm → completed | Cell PM, Main PM, Product Owner, Head Mkt |
|
|
| * → cancelled | Cell PM, Main PM, Product Owner, Head Mkt |
|
|
+-------------------------------+-------------------------------------------+
|
|
|
|
Note: CEO and Auditor are NOT in the cancel/complete roles list - they observe but don't directly act on tasks.
|
|
|
|
VALID START STATUSES (for roboco_task_start):
|
|
|
|
+------------------+------------------------------------------+
|
|
| Status | Who Can Start |
|
|
+------------------+------------------------------------------+
|
|
| claimed | Assigned agent (requires plan) |
|
|
| paused | Assigned agent (resume) |
|
|
| needs_revision | Original developer (fix QA issues) |
|
|
+------------------+------------------------------------------+
|
|
|
|
QA VERDICT ACCEPTANCE (qa_pass/qa_fail):
|
|
|
|
+------------------+------------------------------------------+
|
|
| Status | Reason |
|
|
+------------------+------------------------------------------+
|
|
| awaiting_qa | Task submitted for QA review |
|
|
| claimed | QA claimed the task |
|
|
| in_progress | QA started working (plan + start) |
|
|
+------------------+------------------------------------------+
|
|
|
|
All three statuses are valid because QA follows the full workflow:
|
|
awaiting_qa → claim → plan → start → test → verdict
|
|
|
|
DOCUMENTER COMPLETION ACCEPTANCE (docs_complete):
|
|
|
|
+----------------------+------------------------------------------+
|
|
| Status | Reason |
|
|
+----------------------+------------------------------------------+
|
|
| awaiting_documentation | Task ready for documentation |
|
|
| claimed | Documenter claimed the task |
|
|
| in_progress | Documenter started (plan + start) |
|
|
+----------------------+------------------------------------------+
|
|
|
|
All three statuses are valid because Documenter follows the full workflow:
|
|
awaiting_documentation → claim → plan → start → gather → write → docs_complete
|
|
```
|
|
|
|
## 7. Escalation Chain
|
|
|
|
```
|
|
Developer/QA/Doc → Cell PM → Main PM → Product Owner → CEO
|
|
|
|
+------------+ +---------+ +---------+ +---------------+ +-----+
|
|
| be-dev-1 |---->| | | | | | | |
|
|
| be-dev-2 |---->| be-pm |---->| | | | | |
|
|
| be-qa |---->| | | | | | | |
|
|
| be-doc |---->| | | | | | | |
|
|
+------------+ +---------+ | | | | | |
|
|
| main-pm |---->| product-owner |---->| CEO |
|
|
+------------+ +---------+ | | | | | |
|
|
| fe-dev-1 |---->| | | | | | | |
|
|
| fe-dev-2 |---->| fe-pm |---->| | | | | |
|
|
| fe-qa |---->| | | | | | | |
|
|
| fe-doc |---->| | | | | | | |
|
|
+------------+ +---------+ +---------+ +---------------+ +-----+
|
|
```
|
|
|
|
## 8. Communication vs Notification
|
|
|
|
```
|
|
+-------------------+----------------------------------+----------------------------------+
|
|
| Mechanism | Who Can Use | Purpose |
|
|
+-------------------+----------------------------------+----------------------------------+
|
|
| Messages | Everyone | Constant stream, logged |
|
|
| (roboco_message) | | discussions, updates |
|
|
+-------------------+----------------------------------+----------------------------------+
|
|
| Blocker Reports | Everyone | Signal blocked status |
|
|
| (roboco_report_ | | PM auto-notified |
|
|
| blocker) | | |
|
|
+-------------------+----------------------------------+----------------------------------+
|
|
| Notifications | PM, Board, Auditor, CEO | Formal signals requiring |
|
|
| (roboco_notify) | | acknowledgment |
|
|
+-------------------+----------------------------------+----------------------------------+
|
|
| Escalations | PMs only | High-priority issues |
|
|
| (roboco_escalate) | | up the chain |
|
|
+-------------------+----------------------------------+----------------------------------+
|
|
```
|