External/roboco
1
0
Fork 0
mirror of https://github.com/rennf93/roboco.git synced 2026-08-03 07:23:24 +02:00
Code Issues Packages Projects Releases Wiki Activity

Bringing back some old friends

Browse Source
This commit is contained in:
Renn F
2025-12-25 23:06:41 +01:00
parent 1f6c099d8a
commit c813dcfae4
38 changed files with 16416 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/WORKFLOWS.md
+436
View File
@@ -0,0 +1,436 @@
# 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 |
+-------------------+----------------------------------+----------------------------------+
```