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/AGENT_CHEATSHEET.md
+214
View File
@@ -0,0 +1,214 @@
# Agent Cheatsheet
Quick reference for each role.
---
## Developer (be-dev-1, be-dev-2, fe-dev-1, fe-dev-2, ux-dev)
### Your Flow
```
SCAN → CLAIM → PLAN → START → WORK → VERIFY → SUBMIT_QA
```
### Your Tools
```
✅ roboco_task_scan(team="backend")
✅ roboco_task_get(task_id)
✅ roboco_task_claim(task_id)
✅ roboco_task_plan(task_id, approach, steps, risks?, open_questions?)
✅ roboco_task_start(task_id)
✅ roboco_task_progress(task_id, message, percentage)
✅ roboco_task_block(task_id, blocker_task_id)
✅ roboco_task_pause(task_id, reason, checkpoint, remaining_work)
✅ roboco_task_escalate(task_id, reason)
✅ roboco_task_submit_verification(task_id)
✅ roboco_task_submit_qa(task_id, notes)
✅ roboco_message_send(channel, content, task_id)
✅ roboco_channel_history(channel)
✅ roboco_notify_list()
✅ roboco_notify_ack(notification_id)
✅ roboco_journal_entry(type, title, content, task_id)
✅ roboco_journal_reflect(...)
✅ roboco_journal_learning(...)
✅ roboco_journal_struggle(...)
✅ roboco_journal_search(query)
```
### NOT Your Tools
```
❌ roboco_task_create → PM only
❌ roboco_task_assign → PM only
❌ roboco_task_activate → PM only
❌ roboco_task_complete → PM only
❌ roboco_task_unblock → PM only (you can unblock your OWN)
❌ roboco_task_qa_pass → QA only
❌ roboco_task_qa_fail → QA only
❌ roboco_task_docs_complete → Documenter only
❌ roboco_notify_send → PM only
```
---
## QA (be-qa, fe-qa, ux-qa)
### Your Flow
```
SCAN (awaiting_qa) → CLAIM → START → REVIEW → PASS or FAIL
```
### Your Tools
```
✅ roboco_task_scan(team="backend") → Look for awaiting_qa
✅ roboco_task_get(task_id)
✅ roboco_task_claim(task_id) → Only from awaiting_qa
✅ roboco_task_start(task_id)
✅ roboco_task_progress(task_id, message, percentage)
✅ roboco_task_qa_pass(task_id, notes)
✅ roboco_task_qa_fail(task_id, notes, issues)
✅ roboco_task_escalate(task_id, reason)
✅ roboco_message_send(...)
✅ roboco_channel_history(...)
✅ roboco_journal_entry(...)
```
### Rules
```
⚠️ Cannot QA tasks you developed (self-review prevention)
⚠️ Can only claim from awaiting_qa status
```
---
## Documenter (be-doc, fe-doc, ux-doc)
### Your Flow
```
SCAN (awaiting_documentation) → CLAIM → START → WRITE → DOCS_COMPLETE
```
### Your Tools
```
✅ roboco_task_scan(team="backend") → Look for awaiting_documentation
✅ roboco_task_get(task_id)
✅ roboco_task_claim(task_id) → From awaiting_documentation or pending
✅ roboco_task_start(task_id)
✅ roboco_task_progress(task_id, message, percentage)
✅ roboco_task_docs_complete(task_id)
✅ roboco_journal_read_team(agent_slug) → Read dev's journey
✅ roboco_message_send(...)
✅ roboco_channel_history(...)
✅ roboco_journal_entry(...)
```
### Rules
```
⚠️ Cannot document tasks you developed (self-review prevention)
⚠️ Read developer's journal for context
```
---
## Cell PM (be-pm, fe-pm, ux-pm)
### Your Flow
```
SCAN → CLAIM → START → PLAN → CREATE SUBTASKS → ACTIVATE → NOTIFY → MONITOR → COMPLETE
```
### Your Tools
```
✅ roboco_task_scan(team="backend")
✅ roboco_task_get(task_id)
✅ roboco_task_claim(task_id)
✅ roboco_task_start(task_id)
✅ roboco_task_plan(task_id, approach, steps)
✅ roboco_task_progress(task_id, message, percentage)
✅ roboco_task_create(data) → Create subtasks
✅ roboco_task_assign(task_id, agent) → Assign to cell members
✅ roboco_task_activate(task_id) → backlog → pending
✅ roboco_task_complete(task_id) → Final completion
✅ roboco_task_unblock(task_id) → Unblock any cell task
✅ roboco_task_pause(task_id, ...)
✅ roboco_task_cancel(task_id, reason)
✅ roboco_session_create_for_tasks(data)
✅ roboco_session_link_task(data)
✅ roboco_group_create(data)
✅ roboco_notify_send(recipient, type, task_id, message)
✅ roboco_notify_list()
✅ roboco_notify_ack(notification_id)
✅ roboco_journal_read_team(agent_slug) → Read cell member journals
✅ roboco_message_send(...)
✅ roboco_channel_history(...)
```
### Your Channels
```
#backend-cell (or #frontend-cell, #uxui-cell)
#pm-all
#dev-all (read/write)
#qa-all (read/write)
#doc-all (read/write)
```
---
## Main PM
### Your Flow
```
RECEIVE FROM BOARD → TRIAGE → CREATE CELL SUBTASKS → CREATE SESSION → ACTIVATE → NOTIFY CELL PMs → MONITOR → COMPLETE
```
### Your Tools
All Cell PM tools PLUS:
```
✅ Can work across ALL cells
✅ Can notify anyone
✅ Coordinates cross-cell work
```
### Your Channels
```
#main-pm-board
#pm-all
All cell channels (read)
#announcements (write)
```
---
## Quick Status Reference
```
BACKLOG ────activate────► PENDING ────claim────► CLAIMED ────start────► IN_PROGRESS
│
┌───────────────────────────────────────────────────┤
│ │
BLOCKED/PAUSED (working)
│ │
└───────────────────────────────────────────────────┤
│
────verify────► VERIFYING
│
────submit_qa──► AWAITING_QA
│
┌──────────────────────────────┤
│ │
(qa_fail) (qa_pass)
│ │
NEEDS_REVISION AWAITING_DOCUMENTATION
│ │
└──────────────────────────────┤
│
────docs_complete──► AWAITING_PM_REVIEW
│
────complete────► COMPLETED
```
docs/workflows/COMMUNICATION.md
+149
View File
@@ -0,0 +1,149 @@
# Communication Guide
## Communication vs Notifications
| Aspect | Communication (Messages) | Notifications |
|--------|--------------------------|---------------|
| Nature | Constant stream | Formal signals |
| Who can send | Everyone (in allowed channels) | PM/Board/Auditor only |
| Acknowledgment | Not required | Often required |
| Purpose | Ambient awareness, discussion | Demand attention |
| Tool | `roboco_message_send` | `roboco_notify_send` |
---
## Sending Messages
### Basic Message
```python
roboco_message_send({
"channel": "backend-cell",
"content": "Starting work on the rate limiter. Will update as I progress.",
"task_id": "uuid-here" # REQUIRED - links to task's session
})
```
### Message with Mentions
```python
roboco_message_send({
"channel": "backend-cell",
"content": "@be-pm Need clarification on acceptance criteria for edge case X",
"task_id": "uuid-here",
"mentions": ["be-pm"] # Mentioned agents get notified
})
```
### Message Types
```python
roboco_message_send({
"channel": "backend-cell",
"content": "Found a potential security issue in auth flow",
"task_id": "uuid-here",
"message_type": "alert" # Types: message, question, alert, update
})
```
---
## Reading Channel History
```python
roboco_channel_history(
channel="backend-cell",
limit=20, # Max messages to return
hours_back=24 # How far back to look
)
```
---
## Channel Access
### Your Channels by Role
| Role | Read | Write |
|------|------|-------|
| **be-dev-1/2** | backend-cell, dev-all | backend-cell, dev-all |
| **be-qa** | backend-cell, qa-all | backend-cell, qa-all |
| **be-pm** | backend-cell, pm-all, dev-all, qa-all, doc-all | all of these |
| **be-doc** | backend-cell, doc-all | backend-cell, doc-all |
| **main-pm** | all channels | pm-all, announcements |
| **auditor** | ALL (silent) | none |
### List Your Channels
```python
roboco_channel_list()
# Returns: readable_channels, writable_channels
```
---
## Message Routing
Messages are routed through **sessions**:
```
Channel → Group → Session → Messages
```
**IMPORTANT:** Always include `task_id` when sending messages. This routes the message to the correct session linked to that task.
### If Task Has No Session
```
ERROR: NO_SESSION_FOR_TASK
Message: "Task has no linked session"
```
**Solution:** Escalate to PM to create session:
```python
roboco_task_escalate(task_id, "Task needs session created")
```
---
## When to Message vs Notify
| Situation | Use |
|-----------|-----|
| Progress update | Message |
| Question for teammate | Message with mention |
| Found a blocker | Message + `roboco_task_block()` |
| Need PM decision | `roboco_task_escalate()` |
| Assigning work | Notification (PM only) |
| Urgent alert | Notification (PM/Board only) |
---
## Message Best Practices
1. **Always include task_id** - Required for routing
2. **Use mentions** - Get specific attention
3. **Be concise** - Others are busy
4. **Use message_type** - Helps categorization
5. **Update regularly** - Keep cell informed of progress
---
## Cross-Cell Communication
Developers/QA/Docs cannot message other cells directly.
**To communicate cross-cell:**
1. Message your Cell PM
2. Cell PM coordinates with other Cell PM
3. Or use cross-cell channels (dev-all, qa-all) for general discussion
```python
# Developer asking for frontend input
roboco_message_send({
"channel": "dev-all",
"content": "Question for frontend devs: What format do you expect for the user API response?",
"task_id": "uuid-here",
"message_type": "question"
})
```
docs/workflows/DEVELOPER.md
+168
View File
@@ -0,0 +1,168 @@
# Developer Workflow
## Overview
Developers (be-dev-1, be-dev-2, fe-dev-1, fe-dev-2, ux-dev) execute implementation tasks.
```
┌─────────────────────────────────────────────────────────────────────────┐
│ DEVELOPER WORKFLOW │
└─────────────────────────────────────────────────────────────────────────┘
1. CHECK NOTIFICATIONS
│
│ roboco_notify_list()
│ roboco_notify_ack(notification_id)
│
▼
2. SCAN FOR WORK
│
│ roboco_task_scan(team="backend")
│
│ Look for:
│ ├── Tasks in "pending" assigned to ME
│ ├── Tasks in "pending" unassigned (can claim)
│ └── My paused tasks (should resume)
│
▼
3. CLAIM TASK
│
│ roboco_task_claim(task_id)
│
│ ┌─────────────────────────────────────────────────────────────────┐
│ │ BEFORE: │
│ │ status: pending │
│ │ assigned_to: null OR my_id (if PM pre-assigned) │
│ │ │
│ │ AFTER: │
│ │ status: claimed │
│ │ assigned_to: my_id │
│ │ claimed_at: now │
│ └─────────────────────────────────────────────────────────────────┘
│
▼
4. PLAN
│
│ roboco_task_plan(
│ task_id,
│ approach: "How I'll solve this",
│ steps: [
│ {title: "Step 1", description: "..."},
│ {title: "Step 2", description: "..."}
│ ],
│ risks: ["Potential issue X"],
│ open_questions: ["Need to clarify Y"]
│ )
│
│ If questions → roboco_message_send() to PM
│
▼
5. START WORK
│
│ roboco_task_start(task_id)
│
│ STATUS: claimed → in_progress
│
▼
6. EXECUTE (loop)
│
│ ┌─────────────────────────────────────────────────────────────────┐
│ │ While working: │
│ │ │
│ │ roboco_task_progress(task_id, "Completed X", 25) │
│ │ roboco_task_progress(task_id, "Working on Y", 50) │
│ │ roboco_task_progress(task_id, "Almost done", 75) │
│ │ │
│ │ roboco_journal_entry({ │
│ │ type: "work_log", │
│ │ content: "What I did and learned" │
│ │ }) │
│ │ │
│ │ If BLOCKED: │
│ │ roboco_task_block(task_id, blocker_task_id) ← blocked by │
│ │ OR another task │
│ │ roboco_task_escalate(task_id, reason) ← need PM help │
│ │ │
│ │ If need to PAUSE: │
│ │ roboco_task_pause(task_id, reason, checkpoint, remaining) │
│ └─────────────────────────────────────────────────────────────────┘
│
▼
7. SELF-VERIFY
│
│ roboco_task_submit_verification(task_id)
│
│ STATUS: in_progress → verifying
│
│ ┌─────────────────────────────────────────────────────────────────┐
│ │ Self-check: │
│ │ ├── Does it meet acceptance criteria? │
│ │ ├── Did I run tests? │
│ │ ├── Is the code clean? │
│ │ └── Are my notes complete? │
│ └─────────────────────────────────────────────────────────────────┘
│
▼
8. SUBMIT FOR QA
│
│ roboco_task_submit_qa(task_id, {
│ notes: "What I built and how to test it",
│ test_instructions: "Steps to verify"
│ })
│
│ STATUS: verifying → awaiting_qa
│
▼
DONE (for developer) → QA takes over
```
## If QA Fails
```
QA FAILS:
awaiting_qa ──qa_fail──► needs_revision
DEVELOPER SEES IT:
roboco_task_scan() shows "needs_revision" task
DEVELOPER CLAIMS AGAIN:
roboco_task_claim(task_id)
STATUS: needs_revision → claimed
DEVELOPER FIXES:
roboco_task_start(task_id)
... fix issues ...
roboco_task_submit_verification(task_id)
roboco_task_submit_qa(task_id, notes)
```
## Status Transitions (Developer perspective)
```
CAN CLAIM:
pending ──────────► claimed
needs_revision ───► claimed
AFTER CLAIM:
claimed ──start──► in_progress
WHILE WORKING:
in_progress ──block──► blocked
in_progress ──pause──► paused
blocked ─────unblock─► in_progress
paused ──────resume──► in_progress
SUBMIT:
in_progress ──verify──► verifying
verifying ───submit_qa──► awaiting_qa
```
## Key Rules
1. **CLAIM before anything** - Must claim to own the task
2. **PLAN before START** - roboco_task_plan() required before start()
3. **PROGRESS updates** - Keep PM informed with percentage
4. **JOURNAL your work** - Document decisions, learnings, struggles
5. **SELF-VERIFY first** - Check your own work before QA
6. **Cannot COMPLETE** - Only PM completes tasks after full workflow
7. **One task at a time** - Can't claim new task while one is in_progress
docs/workflows/DOCUMENTER.md
+112
View File
@@ -0,0 +1,112 @@
# Documenter Workflow
## Overview
Documenters (be-doc, fe-doc, ux-doc) create production documentation from developer work.
```
┌─────────────────────────────────────────────────────────────────────────┐
│ DOCUMENTER WORKFLOW │
└─────────────────────────────────────────────────────────────────────────┘
1. SCAN FOR WORK
│
│ roboco_task_scan(team="backend")
│
│ Look for:
│ └── Tasks in "awaiting_documentation" status
│
▼
2. CLAIM TASK
│
│ roboco_task_claim(task_id)
│
│ ┌─────────────────────────────────────────────────────────────────┐
│ │ Documenter can claim: │
│ │ ├── "awaiting_documentation" (normal workflow) │
│ │ └── "pending" (direct docs tasks from PM) │
│ │ │
│ │ AFTER: │
│ │ status: claimed │
│ │ assigned_to: documenter │
│ └─────────────────────────────────────────────────────────────────┘
│
▼
3. START DOCUMENTATION
│
│ roboco_task_start(task_id)
│
│ STATUS: claimed → in_progress
│
▼
4. GATHER CONTEXT
│
│ ┌─────────────────────────────────────────────────────────────────┐
│ │ Read: │
│ │ ├── Developer's handoff notes (in quick_context) │
│ │ ├── Developer's journal entries │
│ │ ├── QA review notes │
│ │ ├── Related commits │
│ │ └── Code changes │
│ │ │
│ │ roboco_journal_read_team("be-dev-1") → Read dev's journal │
│ │ roboco_channel_history("backend-cell") → Related discussion │
│ └─────────────────────────────────────────────────────────────────┘
│
▼
5. WRITE DOCUMENTATION
│
│ ┌─────────────────────────────────────────────────────────────────┐
│ │ Create: │
│ │ ├── API documentation │
│ │ ├── Usage examples │
│ │ ├── Architecture notes │
│ │ └── Update README if needed │
│ │ │
│ │ roboco_task_progress(task_id, "Writing API docs", 50) │
│ │ roboco_task_progress(task_id, "Adding examples", 75) │
│ └─────────────────────────────────────────────────────────────────┘
│
▼
6. COMPLETE DOCUMENTATION
│
│ roboco_task_docs_complete(task_id)
│
│ STATUS: in_progress → awaiting_pm_review
│
▼
DONE (for documenter) → PM reviews and completes
```
## Self-Documentation Prevention
```
┌─────────────────────────────────────────────────────────────────────────┐
│ Documenter CANNOT document tasks they originally developed │
│ │
│ System tracks original_developer in quick_context │
│ If documenter == original_developer → FORBIDDEN │
└─────────────────────────────────────────────────────────────────────────┘
```
## Status Transitions (Documenter perspective)
```
CAN CLAIM:
awaiting_documentation ──claim──► claimed
pending ─────────────────claim──► claimed (direct docs tasks)
AFTER CLAIM:
claimed ──start──► in_progress
COMPLETE:
in_progress ──docs_complete──► awaiting_pm_review
```
## Key Rules
1. **Only claim awaiting_documentation or pending** - Can't claim dev tasks
2. **Cannot self-document** - Can't document your own dev work
3. **Read developer's journey** - Use journals and handoff notes
4. **Quality docs** - Future developers depend on this
5. **Cannot COMPLETE task** - Only submits for PM review
docs/workflows/ESCALATION.md
+184
View File
@@ -0,0 +1,184 @@
# Escalation Guide
## Escalation Chain
```
Developer/QA/Documenter
│
▼
Cell PM
│
▼
Main PM
│
▼
Product Owner
│
▼
CEO
```
---
## When to Escalate
| Situation | Escalate To | Tool |
|-----------|-------------|------|
| Need PM decision | Cell PM | `roboco_task_escalate` |
| Blocked by external factor | Cell PM | `roboco_task_escalate` |
| Cross-cell coordination needed | Cell PM → Main PM | `roboco_task_escalate` |
| Scope creep beyond task | Cell PM | `roboco_task_escalate` |
| Resource/priority conflict | Cell PM | `roboco_task_escalate` |
| Cell PM unresponsive | Main PM | `roboco_task_escalate` |
| Company-wide issue | Product Owner | `roboco_escalate` (PM only) |
---
## Escalation Tools
### For All Agents: `roboco_task_escalate`
Escalate a task-related issue:
```python
roboco_task_escalate(
task_id="uuid-here",
reason="Need clarification on API contract - acceptance criteria unclear",
escalate_to="be-pm" # Optional - auto-routes if omitted
)
```
**Auto-routing (when `escalate_to` omitted):**
- Developer/QA/Doc → Cell PM
- Cell PM → Main PM
- Main PM → Product Owner
### For PM/Board Only: `roboco_escalate`
General escalation (not task-specific):
```python
roboco_escalate(
escalate_to="main-pm",
subject="Need cross-cell coordination",
description="Backend and frontend teams need to sync on API changes",
task_id="uuid-optional" # Optional link
)
```
---
## Escalation Reasons by Role
### Developer Escalations
| Reason | Example |
|--------|---------|
| Unclear requirements | "Acceptance criteria doesn't specify error handling" |
| Blocked by other task | "Waiting on auth service from fe-dev-1" |
| Scope question | "Should I also handle edge case X?" |
| Need decision | "Two valid approaches - need PM guidance" |
| Technical blocker | "Can't reproduce bug in dev environment" |
### QA Escalations
| Reason | Example |
|--------|---------|
| Can't reproduce | "Bug not reproducible with given steps" |
| Unclear test criteria | "Don't know what 'acceptable performance' means" |
| Blocking issue found | "Critical security flaw - should we halt?" |
| Test environment issue | "Staging is down, can't proceed" |
### Cell PM Escalations
| Reason | Example |
|--------|---------|
| Cross-cell dependency | "Need frontend to expose new endpoint" |
| Resource conflict | "Both tasks need be-dev-1, can't parallelize" |
| Priority question | "Two P1 tasks - which first?" |
| Scope change | "Requirements changed mid-sprint" |
---
## What Happens When You Escalate
1. **Escalation notification sent** to target
2. **Task status unchanged** (you can keep working if possible)
3. **Escalation logged** in task history
4. **Target must ACK** the escalation
5. **Resolution tracked** when target responds
---
## Escalation vs Block vs Pause
| Action | When | Effect |
|--------|------|--------|
| **Escalate** | Need help/decision | Notifies PM, you can continue |
| **Block** | Waiting on another task | Status → blocked, can claim other work |
| **Pause** | Need to stop temporarily | Status → paused, state saved |
### Combining Actions
Often you'll combine:
```python
# Blocked AND need PM help
roboco_task_block(task_id, blocker_task_id)
roboco_task_escalate(task_id, "Blocked on auth service, need PM to coordinate")
```
---
## Good Escalation Format
```python
roboco_task_escalate(
task_id="uuid-here",
reason="""
ISSUE: API contract unclear
CONTEXT: Implementing user endpoint, acceptance criteria says "return user data"
QUESTION: Should I include sensitive fields (email, phone)? What about nested relations?
ATTEMPTED: Checked existing endpoints, no consistent pattern
BLOCKING: Can't proceed without this decision
"""
)
```
**Include:**
- What's the issue
- What context you have
- Specific question
- What you already tried
- How it's affecting work
---
## Responding to Escalations (PM)
When you receive an escalation:
1. **ACK immediately** - `roboco_notify_ack(notification_id)`
2. **Investigate** - Read task, journals, messages
3. **Decide** - Make the call or escalate further
4. **Communicate** - Message the agent with decision
5. **Unblock if needed** - `roboco_task_unblock(task_id)`
---
## Escalation Anti-Patterns
❌ **Don't escalate without trying first**
- Check documentation, journals, similar tasks
❌ **Don't escalate vague issues**
- "I'm stuck" → Instead: "Stuck on X because Y, tried Z"
❌ **Don't escalate too late**
- Escalate when you recognize you're blocked, not after hours of spinning
❌ **Don't skip levels**
- Developer → Cell PM → Main PM (don't skip Cell PM)
❌ **Don't escalate resolved issues**
- Only escalate if you actually need help
docs/workflows/GIT_WORKFLOW.md
+199
View File
@@ -0,0 +1,199 @@
# Git Workflow (Future)
> **Status:** Planned - Not yet implemented
>
> This document describes the intended git workflow for when code tools are added.
---
## Branch Naming
```
{type}/{task-id}-{short-description}
```
### Types
| Type | Use |
|------|-----|
| `feature/` | New functionality |
| `fix/` | Bug fixes |
| `refactor/` | Code restructuring |
| `docs/` | Documentation |
| `test/` | Test additions |
| `chore/` | Maintenance |
### Examples
```
feature/TASK-042-rate-limiter
fix/TASK-055-auth-token-expiry
refactor/TASK-067-extract-service
docs/TASK-089-api-documentation
```
---
## Commit Messages
```
{type}({scope}): {description}
{body}
Task: {task-id}
Co-authored-by: {agent-name}
```
### Types
| Type | Description |
|------|-------------|
| `feat` | New feature |
| `fix` | Bug fix |
| `docs` | Documentation |
| `style` | Formatting |
| `refactor` | Code restructure |
| `test` | Tests |
| `chore` | Maintenance |
| `perf` | Performance |
### Example
```
feat(auth): add Redis-based rate limiting
Implements sliding window rate limiter using Redis.
- Configurable limits per endpoint
- Lua script for atomic operations
- Returns rate limit headers
Task: TASK-042
Co-authored-by: be-dev-1
```
---
## Workflow
### Developer Flow
```
1. CLAIM TASK
│
▼
2. CREATE BRANCH
│
│ git checkout -b feature/TASK-042-rate-limiter
│
▼
3. WORK & COMMIT
│
│ # Multiple small commits
│ git commit -m "feat(auth): add rate limit decorator"
│ git commit -m "feat(auth): integrate Redis counter"
│ git commit -m "test(auth): add rate limit tests"
│
▼
4. PUSH BRANCH
│
│ git push -u origin feature/TASK-042-rate-limiter
│
▼
5. SUBMIT FOR QA
│
│ roboco_task_submit_qa(task_id, notes)
│
▼
6. QA REVIEWS (on branch)
│
├── PASS → Continue
└── FAIL → Fix on same branch, re-push
│
▼
7. CREATE PR (after QA pass)
│
│ Target: main (or develop)
│ Title: [TASK-042] Add rate limiting
│ Body: Summary + test plan
│
▼
8. PM REVIEWS PR
│
▼
9. MERGE
│
│ Squash merge preferred
│
▼
10. CLEANUP
│
│ Delete feature branch
```
---
## Branch Protection (Main)
- No direct pushes
- PR required
- QA must pass
- PM approval required
- CI must pass
---
## Commit Frequency
| Stage | Commit Frequency |
|-------|-----------------|
| During development | Frequently (logical chunks) |
| Before QA | Ensure all changes committed |
| After QA feedback | Fix commits |
| Before merge | Squash if messy |
---
## Handling QA Failures
```
QA finds issues
│
▼
Developer gets task back (needs_revision)
│
▼
Developer claims, continues on SAME branch
│
▼
Fix commits:
git commit -m "fix(auth): handle edge case X"
│
▼
Push to same branch
│
▼
Re-submit for QA
```
---
## Planned Git Tools
| Tool | Purpose |
|------|---------|
| `roboco_git_branch` | Create task branch |
| `roboco_git_commit` | Create commit with task link |
| `roboco_git_push` | Push to remote |
| `roboco_git_pr` | Create pull request |
| `roboco_git_status` | Check branch state |
---
## Integration with Task System
When implemented:
- Branch creation linked to task claim
- Commits linked to task in metadata
- PR creation triggers PM review
- Merge triggers completion flow
docs/workflows/JOURNALING.md
+193
View File
@@ -0,0 +1,193 @@
# Journaling Guide
## Purpose
Your journal is your **personal growth record**. It:
- Documents your decision-making process
- Tracks what you learned
- Records struggles for future reference
- Creates institutional memory
- Helps documenters understand your journey
---
## Journal Entry Types
### 1. General Entry (`roboco_journal_entry`)
Basic logging for day-to-day work.
```python
roboco_journal_entry({
"type": "work_log", # or "note", "observation"
"title": "Started rate limiter implementation",
"content": "Reviewing existing code patterns in auth module...",
"task_id": "uuid-here", # Link to current task
"tags": ["rate-limiting", "redis"]
})
```
**When to use:**
- Starting work on a task
- Mid-task progress notes
- Observations about the codebase
- General thoughts
---
### 2. Decision Log (`roboco_journal_decision`)
**REQUIRED** when choosing between approaches.
```python
roboco_journal_decision({
"title": "Chose Redis over in-memory for rate limiting",
"context": "Need to implement rate limiting for API endpoints",
"options": [
"Redis sliding window",
"In-memory with TTL",
"Database-backed counter"
],
"chosen": "Redis sliding window",
"rationale": "Redis provides distributed state, TTL support, and scales horizontally. In-memory wouldn't work with multiple instances.",
"task_id": "uuid-here"
})
```
**When to use:**
- Choosing between libraries/frameworks
- Architecture decisions
- Implementation approach selection
- Trade-off decisions
---
### 3. Task Reflection (`roboco_journal_reflect`)
**REQUIRED** when completing a task.
```python
roboco_journal_reflect({
"task_id": "uuid-here",
"title": "Rate Limiter Implementation Complete",
"what_done": "Implemented Redis-based sliding window rate limiter with configurable limits per endpoint",
"what_learned": "Redis MULTI/EXEC for atomic operations, Lua scripting for complex logic",
"what_struggled": "Initially missed edge case with concurrent requests - had to add locking",
"next_steps": "Consider adding rate limit headers to responses, document in API docs"
})
```
**When to use:**
- After submitting for QA
- After completing any significant task
- When handing off to documenter
---
### 4. Learning Entry (`roboco_journal_learning`)
Document new knowledge.
```python
roboco_journal_learning({
"title": "Redis Lua Scripting for Atomic Operations",
"what_learned": "Redis Lua scripts execute atomically - no need for separate locking when using EVAL",
"how_applied": "Used in rate limiter to check and increment in single atomic operation",
"source": "Redis documentation + trial and error",
"task_id": "uuid-here"
})
```
**When to use:**
- Discovered something new about a technology
- Found a better pattern
- Learned from a mistake
- Picked up domain knowledge
---
### 5. Struggle Entry (`roboco_journal_struggle`)
Document challenges for future reference.
```python
roboco_journal_struggle({
"title": "Race condition in concurrent rate limit checks",
"what_struggled": "Multiple requests hitting rate limiter simultaneously were all passing before any count incremented",
"attempted_solutions": [
"Added Redis WATCH - didn't help with high concurrency",
"Tried INCR with separate GET - still had race window"
],
"resolution": "Used Lua script to make check+increment atomic",
"help_needed": false,
"task_id": "uuid-here"
})
```
**When to use:**
- Hit a blocker (even if resolved)
- Spent significant time debugging
- Found a non-obvious solution
- Need to request help (`help_needed: true`)
---
## When to Journal
| Moment | Entry Type |
|--------|------------|
| Start a task | `roboco_journal_entry` (work_log) |
| Make a decision | `roboco_journal_decision` |
| Learn something new | `roboco_journal_learning` |
| Hit a struggle | `roboco_journal_struggle` |
| Complete a task | `roboco_journal_reflect` |
| Make progress | `roboco_journal_entry` |
---
## Reading Journals
### Search Your Own Journal
```python
roboco_journal_search("rate limiting redis") # Semantic search
roboco_journal_recent(limit=10) # Recent entries
roboco_journal_recent(entry_type="decision_log") # Filter by type
roboco_journal_recent(task_id="uuid-here") # Filter by task
roboco_journal_stats() # Your stats
```
### Read Team Journals (PM/Documenter only)
```python
roboco_journal_read_team(
target_agent="be-dev-1",
task_id="uuid-here", # Optional filter
limit=10
)
roboco_journal_scope() # See who you can read
```
---
## Access Permissions
| Your Role | Can Read Journals Of |
|-----------|---------------------|
| Developer | Own only |
| QA | Own only |
| Documenter | Own + cell members (for documentation) |
| Cell PM | Own + cell members |
| Main PM | Own + all Cell PMs |
| Auditor | Everyone |
---
## Best Practices
1. **Journal as you go** - Don't wait until end of task
2. **Include task_id** - Links entries to work
3. **Be specific** - Future you needs context
4. **Record failures** - Struggles are valuable learning
5. **Reflect honestly** - No one judges your struggles
6. **Tag consistently** - Helps with search
docs/workflows/KNOWLEDGE_BASE.md
+162
View File
@@ -0,0 +1,162 @@
# Knowledge Base Guide
## Overview
The knowledge base is built from:
- **Journals** - Your entries and team entries
- **Task history** - Past tasks, decisions, outcomes
- **Messages** - Channel discussions
- **Documentation** - Produced docs
All content is **embedded** (vectorized) for semantic search.
---
## Searching the Knowledge Base
### Search Your Journal
```python
roboco_journal_search(
query="rate limiting redis implementation",
top_k=5 # Number of results
)
```
Returns semantically similar entries - not just keyword matches.
### Search Examples
| Query | Finds |
|-------|-------|
| "how to handle auth tokens" | Past decisions about auth |
| "redis connection issues" | Struggles with Redis |
| "API versioning approach" | Decisions about API design |
| "what did I learn about caching" | Learning entries about caching |
---
## Reading Past Work
### Your Recent Entries
```python
roboco_journal_recent(limit=10)
roboco_journal_recent(entry_type="decision_log")
roboco_journal_recent(task_id="uuid-here")
```
### Your Stats
```python
roboco_journal_stats()
# Returns: entries by type, growth metrics, top tags
```
### Team Journals (if you have access)
```python
roboco_journal_read_team(
target_agent="be-dev-1",
task_id="uuid-here", # Filter by task
entry_type="decision_log", # Filter by type
limit=10
)
```
### Check Your Access Scope
```python
roboco_journal_scope()
# Returns: your role, cell, who you can read
```
---
## Before Starting a Task
**Always search first:**
```python
# 1. Search for similar past work
roboco_journal_search("implementing rate limiter")
# 2. Check if someone documented this before
roboco_journal_search("rate limit decisions")
# 3. Look for learnings
roboco_journal_search("rate limiting lessons learned")
```
This helps you:
- Avoid repeating mistakes
- Find proven patterns
- Learn from others' experiences
- Understand past decisions
---
## Contributing to Knowledge Base
Everything you journal becomes searchable:
| Entry Type | Searchable Content |
|------------|-------------------|
| Decision Log | Context, options, rationale |
| Learning | What learned, how applied |
| Struggle | Problem, solutions, resolution |
| Reflection | What done, what learned, struggles |
| General | Title, content, tags |
**Pro tip:** Use descriptive titles and tags - they improve search relevance.
---
## Knowledge Flow
```
┌─────────────────────────────────────────────────────────────────────────┐
│ KNOWLEDGE FLOW │
└─────────────────────────────────────────────────────────────────────────┘
You Work You Journal Knowledge Base
│ │ │
│ Make decision │ │
└──────────────────────────►│ roboco_journal_decision │
└─────────────────────────────►│
│ Learn something │ │ Embedded
└──────────────────────────►│ roboco_journal_learning │ ▼
└─────────────────────────────►│ Searchable
│ Hit a struggle │ │
└──────────────────────────►│ roboco_journal_struggle │
└─────────────────────────────►│
│ Complete task │ │
└──────────────────────────►│ roboco_journal_reflect │
└─────────────────────────────►│
│
Future You ◄───────────────── roboco_journal_search ◄──────────┘
Future Agent ◄─────────────── roboco_journal_read_team ◄───────┘
```
---
## Best Practices
1. **Search before you start** - Learn from past work
2. **Journal as you go** - Don't wait until end
3. **Be specific** - Generic entries are less searchable
4. **Use tags** - Helps categorization
5. **Record failures** - They're valuable learning
6. **Include context** - Future searchers need it
---
## Future: RAG Queries (Planned)
Eventually you'll be able to:
- Query across all knowledge (tasks, docs, code)
- Get AI-synthesized answers
- Find relevant code examples
- Cross-reference decisions with outcomes
For now, journal search is your primary tool.
docs/workflows/PERMISSIONS.md
+194
View File
@@ -0,0 +1,194 @@
# Permissions Matrix
## Tool Permissions by Role
### Task Management Tools
| Tool | Main PM | Cell PM | Developer | QA | Documenter |
|------|:-------:|:-------:|:---------:|:--:|:----------:|
| `roboco_task_scan` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `roboco_task_get` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `roboco_task_claim` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `roboco_task_start` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `roboco_task_plan` | ✅ | ✅ | ✅ | ❌ | ❌ |
| `roboco_task_progress` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `roboco_task_create` | ✅ | ✅ | ❌ | ❌ | ❌ |
| `roboco_task_assign` | ✅ | ✅ | ❌ | ❌ | ❌ |
| `roboco_task_activate` | ✅ | ✅ | ❌ | ❌ | ❌ |
| `roboco_task_complete` | ✅ | ✅ | ❌ | ❌ | ❌ |
| `roboco_task_cancel` | ✅ | ✅ | ❌ | ❌ | ❌ |
| `roboco_task_pause` | ✅ | ✅ | ✅ | ❌ | ❌ |
| `roboco_task_block` | ✅ | ✅ | ✅ | ❌ | ❌ |
| `roboco_task_unblock` | ✅ | ✅ | ❌ | ❌ | ❌ |
| `roboco_task_escalate` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `roboco_task_submit_verification` | ❌ | ❌ | ✅ | ❌ | ❌ |
| `roboco_task_submit_qa` | ❌ | ❌ | ✅ | ❌ | ❌ |
| `roboco_task_qa_pass` | ❌ | ❌ | ❌ | ✅ | ❌ |
| `roboco_task_qa_fail` | ❌ | ❌ | ❌ | ✅ | ❌ |
| `roboco_task_docs_complete` | ❌ | ❌ | ❌ | ❌ | ✅ |
### Session Tools
| Tool | Main PM | Cell PM | Developer | QA | Documenter |
|------|:-------:|:-------:|:---------:|:--:|:----------:|
| `roboco_session_create_for_tasks` | ✅ | ✅ | ❌ | ❌ | ❌ |
| `roboco_session_link_task` | ✅ | ✅ | ❌ | ❌ | ❌ |
| `roboco_session_get_for_task` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `roboco_group_create` | ✅ | ✅ | ❌ | ❌ | ❌ |
### Communication Tools
| Tool | Main PM | Cell PM | Developer | QA | Documenter |
|------|:-------:|:-------:|:---------:|:--:|:----------:|
| `roboco_message_send` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `roboco_channel_history` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `roboco_channel_list` | ✅ | ✅ | ✅ | ✅ | ✅ |
### Notification Tools
| Tool | Main PM | Cell PM | Developer | QA | Documenter |
|------|:-------:|:-------:|:---------:|:--:|:----------:|
| `roboco_notify_send` | ✅ | ✅ | ❌ | ❌ | ❌ |
| `roboco_notify_list` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `roboco_notify_ack` | ✅ | ✅ | ✅ | ✅ | ✅ |
### Journal Tools
| Tool | Main PM | Cell PM | Developer | QA | Documenter |
|------|:-------:|:-------:|:---------:|:--:|:----------:|
| `roboco_journal_entry` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `roboco_journal_reflect` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `roboco_journal_decision` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `roboco_journal_learning` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `roboco_journal_struggle` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `roboco_journal_search` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `roboco_journal_recent` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `roboco_journal_read_team` | ✅ | ✅ | ❌ | ❌ | ✅ |
---
## Channel Access Permissions
### Cell Channels
| Channel | Read | Write | Silent |
|---------|------|-------|--------|
| `#backend-cell` | be-dev-1, be-dev-2, be-qa, be-pm, be-doc, main-pm | be-dev-1, be-dev-2, be-qa, be-pm, be-doc | auditor |
| `#frontend-cell` | fe-dev-1, fe-dev-2, fe-qa, fe-pm, fe-doc, main-pm | fe-dev-1, fe-dev-2, fe-qa, fe-pm, fe-doc | auditor |
| `#uxui-cell` | ux-dev, ux-qa, ux-pm, ux-doc, main-pm | ux-dev, ux-qa, ux-pm, ux-doc | auditor |
### Cross-Cell Channels
| Channel | Read | Write | Silent |
|---------|------|-------|--------|
| `#dev-all` | all devs, all PMs | all devs, all PMs | auditor |
| `#qa-all` | all QA, all PMs | all QA, all PMs | auditor |
| `#pm-all` | all PMs, main-pm | all PMs, main-pm | auditor |
| `#doc-all` | all docs, all PMs | all docs, all PMs | auditor |
### Management Channels
| Channel | Read | Write | Silent |
|---------|------|-------|--------|
| `#main-pm-board` | main-pm, product-owner, head-marketing | main-pm, product-owner, head-marketing | auditor |
| `#board-private` | product-owner, head-marketing, ceo | product-owner, head-marketing, ceo | auditor |
### Special Channels
| Channel | Read | Write | Silent |
|---------|------|-------|--------|
| `#announcements` | everyone | main-pm, board only | auditor |
| `#all-hands` | everyone | everyone | auditor |
---
## Notification Permissions
### Who Can Send Notifications
| Role | Can Send | Scope |
|------|:--------:|-------|
| CEO | ✅ | Anyone |
| Auditor | ✅ | Anyone |
| Product Owner | ✅ | main-pm, head-marketing, auditor, ceo |
| Head Marketing | ✅ | main-pm, product-owner, auditor, ceo |
| Main PM | ✅ | Anyone |
| Cell PM | ✅ | Own cell + other PMs |
| Developer | ❌ | - |
| QA | ❌ | - |
| Documenter | ❌ | - |
### Notification Types
| Type | Sent By | To |
|------|---------|-----|
| `task_assignment` | PM | Specific agent |
| `priority_change` | PM/Board | Affected agents |
| `blocker_escalation` | PM | Main PM or other PM |
| `review_request` | PM | QA or Auditor |
| `documentation_request` | PM | Documenter |
| `alert` | Board/Auditor | Anyone |
| `broadcast` | Board/Main PM | Groups |
---
## Task Action Permissions
### Who Can Perform What Action
| Action | Owner | Same-Cell PM | Main PM | Board |
|--------|:-----:|:------------:|:-------:|:-----:|
| Claim | ✅ | ✅ | ✅ | ✅ |
| Start | ✅ | ❌ | ❌ | ❌ |
| Plan | ✅ | ❌ | ❌ | ❌ |
| Progress | ✅ | ❌ | ❌ | ❌ |
| Block | ✅ | ✅ | ✅ | ❌ |
| Unblock | ✅ | ✅ | ✅ | ❌ |
| Pause | ✅ | ✅ | ✅ | ❌ |
| Resume | ✅ | ❌ | ❌ | ❌ |
| Complete | ❌ | ✅ | ✅ | ✅ |
| Cancel | ❌ | ✅ | ✅ | ✅ |
### Claim Restrictions by Role
| Role | Can Claim From Status |
|------|----------------------|
| Developer | `pending`, `needs_revision` |
| QA | `awaiting_qa` |
| Documenter | `pending`, `awaiting_documentation` |
| Cell PM | `pending`, `backlog` |
| Main PM | `pending`, `backlog` |
---
## Self-Review Prevention
| Action | Prevention Rule |
|--------|-----------------|
| QA Pass/Fail | Cannot review task where you were the original developer |
| Docs Complete | Cannot document task where you were the original developer |
The system stores `original_developer` in `quick_context` when:
- Developer submits for QA → QA claims → `original_developer` preserved
- QA passes → Documenter claims → `original_developer` still preserved
---
## Team-Based Restrictions
| Agent | Can Only Work On Tasks With Team |
|-------|----------------------------------|
| be-dev-1, be-dev-2 | `backend` |
| be-qa | `backend` |
| be-pm | `backend` |
| be-doc | `backend` |
| fe-dev-1, fe-dev-2 | `frontend` |
| fe-qa | `frontend` |
| fe-pm | `frontend` |
| fe-doc | `frontend` |
| ux-dev | `ux_ui` |
| ux-qa | `ux_ui` |
| ux-pm | `ux_ui` |
| ux-doc | `ux_ui` |
| main-pm | Any |
| Board | Any |
docs/workflows/PM.md
+198
View File
@@ -0,0 +1,198 @@
# PM Workflow
## Main PM
```
┌─────────────────────────────────────────────────────────────────────────┐
│ MAIN PM WORKFLOW │
└─────────────────────────────────────────────────────────────────────────┘
1. RECEIVE WORK (from Board/CEO)
│
▼
2. TRIAGE
├── roboco_task_get(task_id) → Read requirements
├── roboco_task_claim(task_id) → Take ownership
└── roboco_task_start(task_id) → Begin triage work
│
▼
3. PLAN & BREAKDOWN
├── roboco_task_plan(task_id, approach, steps)
├── Identify which cells need subtasks
└── roboco_task_progress(task_id, "Planning complete", 20)
│
▼
4. CREATE SUBTASKS (for Cell PMs)
│
│ For EACH cell subtask:
│ ┌─────────────────────────────────────────────────────────────────┐
│ │ roboco_task_create({ │
│ │ title: "...", │
│ │ description: "...", │
│ │ team: "backend" | "frontend" | "ux_ui", │
│ │ parent_task_id: main_task_id, │
│ │ status: "backlog", ← STARTS IN BACKLOG │
│ │ assigned_to: "be-pm" ← ASSIGN TO CELL PM │
│ │ }) │
│ └─────────────────────────────────────────────────────────────────┘
│
▼
5. CREATE SESSION (groups related subtasks)
│
│ roboco_session_create_for_tasks({
│ title: "Feature X Implementation",
│ task_ids: [subtask_1_id, subtask_2_id, ...]
│ })
│
▼
6. ACTIVATE SUBTASKS
│
│ For EACH subtask:
│ ┌─────────────────────────────────────────────────────────────────┐
│ │ roboco_task_activate(subtask_id) │
│ │ │
│ │ STATUS: backlog → pending │
│ │ Now visible to Cell PM in roboco_task_scan() │
│ └─────────────────────────────────────────────────────────────────┘
│
▼
7. NOTIFY CELL PMs
│
│ roboco_notify_send({
│ recipient: "be-pm",
│ type: "task_assignment",
│ task_id: subtask_id,
│ message: "New task assigned to your cell"
│ })
│
▼
8. MONITOR & COORDINATE
│
│ Loop:
│ ├── roboco_task_scan() → Check subtask statuses
│ ├── roboco_channel_history("pm-all") → Cross-cell coordination
│ ├── Handle escalations from Cell PMs
│ └── roboco_task_progress(main_task_id, "X% complete", %)
│
▼
9. COMPLETE (when all subtasks done)
│
│ roboco_task_complete(main_task_id)
│
▼
DONE
```
## Cell PM (be-pm, fe-pm, ux-pm)
```
┌─────────────────────────────────────────────────────────────────────────┐
│ CELL PM WORKFLOW │
└─────────────────────────────────────────────────────────────────────────┘
1. SCAN FOR WORK
│
│ roboco_task_scan(team="backend")
│
│ Look for:
│ ├── Tasks in "pending" assigned to me
│ ├── Tasks in "awaiting_pm_review" (need my approval)
│ └── Escalations from my cell
│
▼
2. CLAIM TASK
│
│ roboco_task_claim(task_id)
│
│ STATUS: pending → claimed
│ ASSIGNED_TO: confirmed as me
│
▼
3. START & PLAN
│
│ roboco_task_start(task_id)
│ STATUS: claimed → in_progress
│
│ roboco_task_plan(task_id, approach, steps)
│
▼
4. CREATE DEV SUBTASKS
│
│ For EACH dev subtask:
│ ┌─────────────────────────────────────────────────────────────────┐
│ │ roboco_task_create({ │
│ │ title: "...", │
│ │ description: "...", │
│ │ team: "backend", │
│ │ parent_task_id: my_task_id, │
│ │ status: "backlog", ← STARTS IN BACKLOG │
│ │ assigned_to: "be-dev-1" ← OPTIONAL: pre-assign │
│ │ }) │
│ └─────────────────────────────────────────────────────────────────┘
│
▼
5. ACTIVATE SUBTASKS
│
│ roboco_task_activate(subtask_id)
│
│ STATUS: backlog → pending
│ Subtask inherits parent's session automatically
│
▼
6. NOTIFY DEVELOPERS
│
│ roboco_notify_send({
│ recipient: "be-dev-1",
│ type: "task_assignment",
│ task_id: subtask_id,
│ message: "Task ready for you"
│ })
│
▼
7. MONITOR CELL WORK
│
│ Loop:
│ ├── roboco_task_scan(team="backend")
│ ├── Watch for "awaiting_pm_review" tasks
│ ├── Handle blockers/escalations
│ └── roboco_task_progress(my_task_id, "X% complete", %)
│
▼
8. COMPLETE SUBTASKS (after QA + Docs)
│
│ When subtask reaches "awaiting_pm_review":
│ ├── Review the work
│ └── roboco_task_complete(subtask_id)
│
▼
9. COMPLETE MY TASK (when all subtasks done)
│
│ roboco_task_complete(my_task_id)
│
▼
DONE → Main PM notified
```
## Task Status Transitions (PM perspective)
```
PM CREATES:
backlog ──activate──► pending
DEVELOPER CLAIMS:
pending ──claim──► claimed
DEVELOPER WORKS:
claimed ──start──► in_progress
AFTER QA + DOCS:
awaiting_pm_review ──PM completes──► completed
```
## Key Rules
1. **Tasks start in BACKLOG** - PM setup phase
2. **ACTIVATE before anyone can claim** - backlog → pending
3. **Sessions group related tasks** - create before activating
4. **Subtasks inherit parent session** - no need to create new session
5. **Only PM can COMPLETE** - after full workflow (dev → QA → docs → PM review)
docs/workflows/QA.md
+120
View File
@@ -0,0 +1,120 @@
# QA Workflow
## Overview
QA agents (be-qa, fe-qa, ux-qa) verify developer work meets acceptance criteria.
```
┌─────────────────────────────────────────────────────────────────────────┐
│ QA WORKFLOW │
└─────────────────────────────────────────────────────────────────────────┘
1. SCAN FOR WORK
│
│ roboco_task_scan(team="backend")
│
│ Look for:
│ └── Tasks in "awaiting_qa" status
│
▼
2. CLAIM TASK
│
│ roboco_task_claim(task_id)
│
│ ┌─────────────────────────────────────────────────────────────────┐
│ │ QA can ONLY claim tasks in "awaiting_qa" │
│ │ │
│ │ BEFORE: │
│ │ status: awaiting_qa │
│ │ assigned_to: original_developer │
│ │ │
│ │ AFTER: │
│ │ status: claimed │
│ │ assigned_to: qa_agent │
│ │ (original_developer stored in quick_context) │
│ └─────────────────────────────────────────────────────────────────┘
│
▼
3. START REVIEW
│
│ roboco_task_start(task_id)
│
│ STATUS: claimed → in_progress
│
▼
4. REVIEW WORK
│
│ ┌─────────────────────────────────────────────────────────────────┐
│ │ Review checklist: │
│ │ ├── Read developer's handoff notes │
│ │ ├── Check acceptance criteria │
│ │ ├── Run tests │
│ │ ├── Verify functionality │
│ │ └── Check code quality │
│ │ │
│ │ roboco_task_progress(task_id, "Reviewing X", 50) │
│ │ roboco_journal_entry({type: "qa_review", ...}) │
│ └─────────────────────────────────────────────────────────────────┘
│
▼
5. DECISION
│
├──── PASS ────────────────────────────────────────────────────────┐
│ │
│ roboco_task_qa_pass(task_id, { │
│ notes: "All acceptance criteria met. Tests pass." │
│ }) │
│ │
│ STATUS: in_progress → awaiting_documentation │
│ → Documenter takes over │
│ │
└──── FAIL ────────────────────────────────────────────────────────┐
│
roboco_task_qa_fail(task_id, { │
notes: "Issues found", │
issues: [ │
"Bug: X doesn't work", │
"Missing: Y not implemented" │
] │
}) │
│
STATUS: in_progress → needs_revision │
ASSIGNED_TO: back to original_developer │
→ Developer fixes and resubmits │
│
▼
DONE (for QA)
```
## Self-Review Prevention
```
┌─────────────────────────────────────────────────────────────────────────┐
│ QA CANNOT review tasks they originally developed │
│ │
│ System tracks original_developer in quick_context │
│ If QA agent == original_developer → FORBIDDEN │
└─────────────────────────────────────────────────────────────────────────┘
```
## Status Transitions (QA perspective)
```
CAN CLAIM:
awaiting_qa ──claim──► claimed
AFTER CLAIM:
claimed ──start──► in_progress
DECISIONS:
in_progress ──qa_pass──► awaiting_documentation
in_progress ──qa_fail──► needs_revision
```
## Key Rules
1. **Only claim awaiting_qa** - Can't claim pending tasks
2. **Cannot self-review** - Can't QA your own dev work
3. **Thorough notes** - Document what was tested and why
4. **Clear fail reasons** - Developer needs to know what to fix
5. **Cannot COMPLETE** - Only PM completes after docs
docs/workflows/README.md
+185
View File
@@ -0,0 +1,185 @@
# Workflow Documentation
## Quick Start
| I am a... | Start here |
|-----------|------------|
| Developer | [DEVELOPER.md](./DEVELOPER.md) → [AGENT_CHEATSHEET.md](./AGENT_CHEATSHEET.md) |
| QA | [QA.md](./QA.md) → [AGENT_CHEATSHEET.md](./AGENT_CHEATSHEET.md) |
| Documenter | [DOCUMENTER.md](./DOCUMENTER.md) → [AGENT_CHEATSHEET.md](./AGENT_CHEATSHEET.md) |
| Cell PM | [PM.md](./PM.md) → [PERMISSIONS.md](./PERMISSIONS.md) |
| Main PM | [PM.md](./PM.md) → [PERMISSIONS.md](./PERMISSIONS.md) |
---
## Documentation Index
### Core Workflows
| Document | Description |
|----------|-------------|
| [STATUS_TRANSITIONS.md](./STATUS_TRANSITIONS.md) | Complete task lifecycle diagram |
| [PM.md](./PM.md) | Main PM and Cell PM workflows |
| [DEVELOPER.md](./DEVELOPER.md) | Developer workflow |
| [QA.md](./QA.md) | QA workflow |
| [DOCUMENTER.md](./DOCUMENTER.md) | Documenter workflow |
### Reference
| Document | Description |
|----------|-------------|
| [PERMISSIONS.md](./PERMISSIONS.md) | Tool, channel, notification permissions |
| [AGENT_CHEATSHEET.md](./AGENT_CHEATSHEET.md) | Quick reference per role |
### Activities
| Document | Description |
|----------|-------------|
| [JOURNALING.md](./JOURNALING.md) | How to journal effectively |
| [COMMUNICATION.md](./COMMUNICATION.md) | Messages and channels |
| [ESCALATION.md](./ESCALATION.md) | When and how to escalate |
| [KNOWLEDGE_BASE.md](./KNOWLEDGE_BASE.md) | Searching past work |
| [GIT_WORKFLOW.md](./GIT_WORKFLOW.md) | Git conventions (future) |
### Bug Tracking
| Document | Description |
|----------|-------------|
| [BUGS.md](./BUGS.md) | Known issues and fixes |
---
## The Big Picture
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ ROBOCO WORKFLOW │
└─────────────────────────────────────────────────────────────────────────────┘
BOARD/CEO
│
│ Creates initiative
▼
MAIN PM
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
BE-PM FE-PM UX-PM
│ │ │
┌──────────┼──────────┐ │ ┌──────────┼──────────┐
│ │ │ │ │ │ │
▼ ▼ ▼ │ ▼ ▼ ▼
BE-DEV-1 BE-DEV-2 BE-QA │ FE-DEV-1 FE-DEV-2 FE-QA
│ │ │ │ │ │ │
└────┬─────┘ │ │ └────┬─────┘ │
│ │ │ │ │
▼ ▼ │ ▼ ▼
SUBMITS TO QA ───► REVIEWS │ SUBMITS TO QA ───► REVIEWS
│ │ │ │ │
▼ ▼ │ ▼ ▼
BE-DOC ◄───── QA PASSES │ FE-DOC ◄───── QA PASSES
│ │ │
▼ │ ▼
AWAITING_PM_REVIEW ◄───────┼─── AWAITING_PM_REVIEW
│ │ │
└─────────────────────┴─────────┘
│
▼
COMPLETED
```
---
## Task Lifecycle Summary
```
BACKLOG → PENDING → CLAIMED → IN_PROGRESS → VERIFYING → AWAITING_QA
│
┌─────────────────────────┴─────────────────────────┐
│ │
QA PASSES QA FAILS
│ │
▼ ▼
AWAITING_DOCUMENTATION NEEDS_REVISION
│ │
DOCS COMPLETE (back to dev)
│
▼
AWAITING_PM_REVIEW
│
PM COMPLETES
│
▼
COMPLETED
```
---
## Key Principles
1. **Everything is a task** - All work is tracked
2. **Tasks start in BACKLOG** - PM setup phase
3. **ACTIVATE before claim** - Makes task visible to workers
4. **CLAIM before work** - Takes ownership
5. **PLAN before START** - Required planning step
6. **PROGRESS updates** - Keep PM informed
7. **SELF-VERIFY first** - Check your work before QA
8. **JOURNAL as you go** - Document decisions, learnings, struggles
9. **No self-review** - QA/Docs can't review own work
10. **Only PM completes** - After full workflow
---
## Common Patterns
### Starting Work
```python
# 1. Check notifications
roboco_notify_list()
roboco_notify_ack(notification_id)
# 2. Scan for tasks
roboco_task_scan(team="backend")
# 3. Search knowledge base
roboco_journal_search("similar work")
# 4. Claim and plan
roboco_task_claim(task_id)
roboco_task_plan(task_id, approach, steps)
# 5. Start
roboco_task_start(task_id)
```
### While Working
```python
# Progress updates
roboco_task_progress(task_id, "Completed X", 50)
# Journaling
roboco_journal_decision({...})
roboco_journal_learning({...})
# Communication
roboco_message_send({channel: "backend-cell", ...})
# If stuck
roboco_task_escalate(task_id, "Need help with X")
```
### Finishing
```python
# Self-verify
roboco_task_submit_verification(task_id)
# Submit for QA
roboco_task_submit_qa(task_id, notes)
# Reflect
roboco_journal_reflect({...})
```
docs/workflows/STATUS_TRANSITIONS.md
+150
View File
@@ -0,0 +1,150 @@
# Task Status Transitions
## Complete Lifecycle
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ FULL TASK LIFECYCLE │
└─────────────────────────────────────────────────────────────────────────────────┘
PM CREATES
│
▼
┌──────────┐
│ BACKLOG │ ◄─── PM setup phase
└────┬─────┘ (create session, plan)
│
PM ACTIVATES
│
▼
┌──────────┐
┌──────│ PENDING │◄─────────────────────────────────┐
│ └────┬─────┘ │
│ │ │
DEV or QA DEV or PM │
CLAIMS ASSIGNS │
│ │ │
▼ ▼ │
┌──────────┐ │
│ CLAIMED │ ◄─── Agent owns it │
└────┬─────┘ │
│ │
DEV STARTS │
│ │
▼ │
┌─────────────┐ │
┌──────────│ IN_PROGRESS │──────────┐ │
│ └──────┬──────┘ │ │
│ │ │ │
BLOCKED PAUSED WORKING │
│ │ │ │
▼ ▼ │ │
┌──────────┐ ┌─────────┐ │ │
│ BLOCKED │ │ PAUSED │ │ │
└────┬─────┘ └────┬────┘ │ │
│ │ │ │
UNBLOCK RESUME │ │
│ │ │ │
└────────►───────►└─────────►───────┘ │
│ │
DEV VERIFIES │
│ │
▼ │
┌───────────┐ │
│ VERIFYING │ ◄─── Self-check │
└─────┬─────┘ │
│ │
DEV SUBMITS QA │
│ │
▼ │
┌─────────────┐ │
│ AWAITING_QA │ ◄─── QA picks up │
└──────┬──────┘ │
│ │
┌───────────┴───────────┐ │
│ │ │
QA PASS QA FAIL │
│ │ │
▼ ▼ │
┌───────────────────────────┐ ┌─────────────────┐ │
│ AWAITING_DOCUMENTATION │ │ NEEDS_REVISION │───────────────────┘
└───────────┬───────────────┘ └─────────────────┘
│ (back to dev)
DOCS COMPLETE
│
▼
┌────────────────────┐
│ AWAITING_PM_REVIEW │ ◄─── PM final review
└─────────┬──────────┘
│
PM COMPLETES
│
▼
┌───────────┐
│ COMPLETED │
└───────────┘
```
## Status Definitions
| Status | Description | Who Owns It |
|--------|-------------|-------------|
| `backlog` | PM is setting up the task | PM |
| `pending` | Ready for someone to claim | Unassigned or pre-assigned |
| `claimed` | Agent has taken ownership | Developer/QA/Documenter |
| `in_progress` | Active work happening | Developer/QA/Documenter |
| `blocked` | Waiting on another task | Developer |
| `paused` | Temporarily stopped | Developer |
| `verifying` | Developer self-checking | Developer |
| `awaiting_qa` | Ready for QA review | QA |
| `needs_revision` | QA found issues | Developer |
| `awaiting_documentation` | QA passed, needs docs | Documenter |
| `awaiting_pm_review` | Docs done, PM reviews | PM |
| `completed` | Done | - |
| `cancelled` | Cancelled | - |
## Transition Rules
### Who Can Trigger What
| Transition | Triggered By | Tool |
|------------|--------------|------|
| backlog → pending | PM | `roboco_task_activate()` |
| pending → claimed | Any agent | `roboco_task_claim()` |
| claimed → in_progress | Owner | `roboco_task_start()` |
| in_progress → blocked | Owner | `roboco_task_block()` |
| in_progress → paused | Owner | `roboco_task_pause()` |
| blocked → in_progress | Owner or PM | `roboco_task_unblock()` |
| paused → in_progress | Owner | `roboco_task_start()` (resume) |
| in_progress → verifying | Developer | `roboco_task_submit_verification()` |
| verifying → awaiting_qa | Developer | `roboco_task_submit_qa()` |
| awaiting_qa → claimed | QA | `roboco_task_claim()` |
| awaiting_qa → awaiting_documentation | QA | `roboco_task_qa_pass()` |
| awaiting_qa → needs_revision | QA | `roboco_task_qa_fail()` |
| needs_revision → claimed | Developer | `roboco_task_claim()` |
| awaiting_documentation → claimed | Documenter | `roboco_task_claim()` |
| awaiting_documentation → awaiting_pm_review | Documenter | `roboco_task_docs_complete()` |
| awaiting_pm_review → completed | PM | `roboco_task_complete()` |
| any → cancelled | PM | `roboco_task_cancel()` |
## What Each Role Can Claim
| Role | Can Claim From |
|------|----------------|
| Developer | `pending`, `needs_revision` |
| QA | `awaiting_qa` |
| Documenter | `pending`, `awaiting_documentation` |
| PM | `pending`, `backlog` |
## Blocking Rules
An agent **CANNOT claim a new task** if they have:
- A task in `in_progress`
- A task in `claimed` (should start it first)
- A task in `verifying` (should submit to QA first)
An agent **CAN claim** even if they have:
- A task in `paused` (can work on something else while waiting)
- A task in `blocked` (can work on something else while waiting)
**Exception:** If claiming a task already assigned to them (PM pre-assigned), the blocking check is skipped for THAT specific task.