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

Adjusted documentation

Browse Source
This commit is contained in:
Renn F
2025-12-30 19:37:03 +01:00
parent d7e93ece25
commit eedf06d18a
12 changed files with 3056 additions and 482 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/workflows/ESCALATION.md
+218 -58
View File
@@ -1,23 +1,110 @@
# Escalation Guide
> **Status:** Implemented
>
> This document describes the task escalation system and CEO approval workflow.
---
## Escalation Chain
The escalation chain is strictly enforced - you cannot skip levels:
```
Developer/QA/Documenter
│
▼
Cell PM
Cell PM (be-pm, fe-pm, ux-pm)
│
▼
Main PM
Main PM (main-pm)
│
▼
Product Owner
Product Owner (product-owner)
│
▼
CEO
CEO (ceo)
```
### Detailed Chain
| Agent | Escalates To |
|-------|--------------|
| be-dev-1, be-dev-2 | be-pm |
| be-qa | be-pm |
| be-doc | be-pm |
| fe-dev-1, fe-dev-2 | fe-pm |
| fe-qa | fe-pm |
| fe-doc | fe-pm |
| ux-dev-1, ux-dev-2 | ux-pm |
| ux-qa | ux-pm |
| ux-doc | ux-pm |
| be-pm, fe-pm, ux-pm | main-pm |
| main-pm | product-owner |
| product-owner | ceo |
| head-marketing | ceo |
| auditor | ceo |
---
## Types of Escalation
### 1. Task Escalation (`roboco_task_escalate`)
Used when you need help with a specific task. Available to ALL agents.
```python
roboco_task_escalate(
task_id="uuid-here",
reason="Need clarification on API contract - acceptance criteria unclear"
)
```
**Key Points:**
- Auto-routes to your escalation target (you cannot specify a different target)
- Creates a high-priority notification requiring acknowledgment
- Task status remains unchanged (you can keep working if possible)
- Escalation is logged in task history
### 2. CEO Escalation (`roboco_task_escalate_to_ceo`)
PM-only. Used for major tasks requiring CEO sign-off:
```python
roboco_task_escalate_to_ceo(
task_id="uuid-here",
notes="Major feature ready for final review"
)
```
**Requirements:**
- Task must be in `awaiting_pm_review` status
- For git tasks, PR must exist (`pr_number` must be set)
- Only PMs (cell_pm, main_pm) can escalate to CEO
**Result:**
- Status changes to `awaiting_ceo_approval`
- CEO receives high-priority notification requiring ACK
### 3. Soft Block Escalation
When blocked by external factors (not another task):
```python
roboco_task_soft_block(
task_id="uuid-here",
reason="Waiting for production API credentials",
blocker_type="external_dependency",
what_needed="AWS credentials for production environment"
)
```
**Result:**
- Status changes to `blocked`
- PM receives notification with ACTION REQUIRED
- PM MUST call `roboco_task_unblock()` when resolved
- Verbal resolution in chat is NOT enough
---
## When to Escalate
@@ -25,46 +112,80 @@ Developer/QA/Documenter
| 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` |
| Blocked by external factor | Cell PM | `roboco_task_soft_block` |
| Blocked by another task | Cell PM | `roboco_task_block` + `roboco_task_escalate` |
| Cross-cell coordination needed | Cell PM (routes to 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) |
| Major feature ready for merge | CEO | `roboco_task_escalate_to_ceo` (PM only) |
---
## Escalation Tools
## CEO Approval Workflow
### For All Agents: `roboco_task_escalate`
For major tasks (parent tasks, high-priority features, breaking changes):
Escalate a task-related issue:
```
awaiting_pm_review
│
▼
PM reviews and decides to escalate
│
roboco_task_escalate_to_ceo(task_id, notes)
│
▼
awaiting_ceo_approval
│
┌────────────────┴────────────────┐
│ │
CEO APPROVES CEO REJECTS
│ │
roboco_task_ceo_approve() roboco_task_ceo_reject(notes)
│ │
▼ ▼
completed needs_revision
│
(assigned back to
original developer)
```
### CEO Approval Queue
PMs can view tasks awaiting CEO approval:
```python
roboco_task_escalate(
# Get all tasks awaiting CEO approval (org-wide)
roboco_tasks_awaiting_ceo()
```
### CEO Actions
```python
# Approve and complete
roboco_task_ceo_approve(task_id, notes="Approved. Great work!")
# Reject and send back for revision
roboco_task_ceo_reject(task_id, notes="Need to address X before merge")
```
---
## Force Completion (CEO Only)
When subtasks are cancelled but parent should complete:
```python
roboco_task_complete(
task_id="uuid-here",
reason="Need clarification on API contract - acceptance criteria unclear",
escalate_to="be-pm" # Optional - auto-routes if omitted
force_with_cancelled=True,
justification="Subtask TASK-123 cancelled - functionality no longer needed"
)
```
**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
)
```
**Requirements:**
- Only CEO can use `force_with_cancelled`
- Justification is required
- Does NOT work for pending/in_progress subtasks (only cancelled)
---
@@ -79,6 +200,7 @@ roboco_escalate(
| 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" |
| Low context | "Need more background on why this was designed this way" |
### QA Escalations
@@ -89,6 +211,14 @@ roboco_escalate(
| Blocking issue found | "Critical security flaw - should we halt?" |
| Test environment issue | "Staging is down, can't proceed" |
### Documenter Escalations
| Reason | Example |
|--------|---------|
| Missing context | "Developer journal doesn't explain design decisions" |
| Scope question | "Should I document internal APIs?" |
| Access needed | "Can't view the code changes" |
### Cell PM Escalations
| Reason | Example |
@@ -102,21 +232,24 @@ roboco_escalate(
## 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
1. **Escalation notification sent** to your escalation target
2. **Notification is high-priority** and requires acknowledgment
3. **Task status unchanged** (you can keep working if possible)
4. **Target MUST ACK** the notification
5. **Target investigates** and responds
6. **For blocks**: PM must call `roboco_task_unblock()` when resolved
---
## Escalation vs Block vs Pause
## Escalation vs Block vs Pause vs Substitute
| 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 |
| Action | When | Status Change | Tool |
|--------|------|---------------|------|
| **Escalate** | Need help/decision | No change | `roboco_task_escalate` |
| **Block (hard)** | Waiting on another task | → blocked | `roboco_task_block` |
| **Block (soft)** | Waiting on external factor | → blocked | `roboco_task_soft_block` |
| **Pause** | Need to stop temporarily | → paused | `roboco_task_pause` |
| **Substitute** | Can't continue, release task | → pending/awaiting_pm_review | `roboco_task_substitute` |
### Combining Actions
@@ -124,12 +257,42 @@ 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")
roboco_task_soft_block(
task_id,
"Waiting for API access",
"external_dependency",
"Need production API keys from DevOps"
)
# PM will be notified automatically
```
---
## Substitution (Graceful Exit)
When you can't continue a task:
```python
roboco_task_substitute(
task_id="uuid-here",
reason="low_context",
details="Need more background on the authentication system design"
)
```
### Substitution Reasons
| Reason | Result Status | Use When |
|--------|---------------|----------|
| `task_complete` | awaiting_qa | Finished work, releasing for review |
| `low_context` | pending | Insufficient context to continue |
| `out_of_scope_team` | pending | Task belongs to different team |
| `out_of_scope_role` | pending | Task requires different role |
| `max_retries` | pending | Exceeded retry limit |
| `blocked_external` | blocked | Need skills outside your capabilities |
---
## Good Escalation Format
```python
@@ -164,21 +327,18 @@ When you receive an escalation:
4. **Communicate** - Message the agent with decision
5. **Unblock if needed** - `roboco_task_unblock(task_id)`
**CRITICAL**: For soft blocks, verbal resolution is NOT enough. You MUST call:
```python
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
- **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 (can't skip Cell PM)
- **Don't escalate resolved issues** - Only escalate if you actually need help
- **Don't bypass the chain** - The `escalate_to` parameter is validated against your escalation target
docs/workflows/GIT_WORKFLOW.md
+277 -74
View File
@@ -1,15 +1,58 @@
# Git Workflow (Future)
# Git Workflow
> **Status:** Planned - Not yet implemented
> **Status:** Implemented
>
> This document describes the intended git workflow for when code tools are added.
> This document describes the git workflow for RoboCo agents working on code tasks.
---
## Multi-Agent Workspace Structure
Each agent gets their own isolated workspace (git clone) for a project. This allows multiple agents to work on the same project in parallel, each on their own branch, without file conflicts.
```
{workspaces_root}/
└── {project-slug}/
└── {team}/
└── {agent-slug}/
└── [git repo files]
```
### Example Structure
```
/data/workspaces/
└── roboco/
├── backend/
│ ├── be-dev-1/ # Backend Developer 1's workspace
│ ├── be-dev-2/ # Backend Developer 2's workspace
│ ├── be-qa/ # Backend QA's workspace
│ ├── be-pm/ # Backend PM's workspace
│ └── be-doc/ # Backend Documenter's workspace
├── frontend/
│ ├── fe-dev-1/
│ ├── fe-dev-2/
│ └── ...
└── ux_ui/
├── ux-dev-1/
└── ...
```
### Workspace Features
- **Auto-clone**: When `workspace_auto_clone` is enabled, workspaces are automatically cloned when first accessed
- **Isolation**: Each agent has their own working tree - no file locking conflicts
- **Branch independence**: Agents can be on different branches simultaneously
- **Project-scoped**: Workspaces are organized by project slug
---
## Branch Naming
Branches are created by PMs and include team context:
```
{type}/{task-id}-{short-description}
{type}/{team}/{task-id-prefix}
```
### Types
@@ -26,16 +69,30 @@
### Examples
```
feature/TASK-042-rate-limiter
fix/TASK-055-auth-token-expiry
refactor/TASK-067-extract-service
docs/TASK-089-api-documentation
feature/backend/a1b2c3d4
fix/frontend/e5f6g7h8
refactor/backend/i9j0k1l2
```
---
## Commit Messages
Commits are automatically linked to tasks with a task ID prefix:
```
[{task-id-prefix}] {message}
```
### Automatic Linking
When you use `roboco_git_commit()`, the commit:
1. Is prefixed with the task ID (first 8 chars)
2. Is recorded in the task's commit history
3. Is added to the work session if one exists
### Manual Format
```
{type}({scope}): {description}
@@ -68,7 +125,7 @@ Implements sliding window rate limiter using Redis.
- Lua script for atomic operations
- Returns rate limit headers
Task: TASK-042
Task: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Co-authored-by: be-dev-1
```
@@ -76,61 +133,225 @@ Co-authored-by: be-dev-1
## Workflow
### PM Setup Phase
```
1. PM CREATES TASK (status: backlog)
│
▼
2. PM CREATES SESSION
│ roboco_session_start(channel, "collaborative", task_id)
│
▼
3. PM ACTIVATES TASK (status: pending)
│ roboco_task_activate(task_id)
│
▼
4. PM CREATES BRANCH
│ roboco_git_create_branch(project_slug, task_id, "feature")
│ → Creates: feature/{team}/{task-id-prefix}
│ → Auto-pushes to remote with tracking
│
▼
5. PM ASSIGNS DEVELOPER
│ roboco_task_claim(task_id, agent_id="be-dev-1")
```
### Developer Flow
```
1. CLAIM TASK
│ roboco_task_claim(task_id)
│
▼
2. CREATE BRANCH
│
│ git checkout -b feature/TASK-042-rate-limiter
2. START WORK (requires branch for git tasks)
│ roboco_task_start(task_id)
│
▼
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"
3. CHECKOUT BRANCH
│ roboco_git_checkout(project_slug, branch_name)
│
▼
4. PUSH BRANCH
│
│ git push -u origin feature/TASK-042-rate-limiter
4. WORK & COMMIT
│ # Multiple commits linked to task
│ roboco_git_commit(project_slug, task_id, "add rate limiter")
│ roboco_git_commit(project_slug, task_id, "add tests")
│
▼
5. SUBMIT FOR QA
5. PUSH BRANCH
│ roboco_git_push(project_slug)
│
▼
6. SUBMIT FOR QA
│ roboco_task_submit_qa(task_id, notes)
│
▼
6. QA REVIEWS (on branch)
7. 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
├── PASS → Continue to Documentation
└── FAIL → Task returns to needs_revision
```
### QA Flow
QA reviews the code on the branch:
```
1. QA CLAIMS TASK
│ roboco_task_claim(task_id)
│
▼
2. QA CHECKS OUT BRANCH
│ roboco_git_checkout(project_slug, branch_name)
│
▼
3. QA REVIEWS
│ roboco_git_status(project_slug)
│ roboco_git_diff(project_slug)
│ roboco_git_log(project_slug)
│
├── PASS: roboco_task_pass_qa(task_id, notes)
│ → Status: awaiting_documentation
│
└── FAIL: roboco_task_fail_qa(task_id, notes)
→ Status: needs_revision
```
### Documentation Phase (Parallel Execution)
When a task reaches `awaiting_documentation`, two things happen in parallel:
```
awaiting_documentation
│
┌───────────────┴───────────────┐
│ │
DOCUMENTER DEVELOPER
│ │
writes docs creates PR
│ │
roboco_task_docs_complete() roboco_git_create_pr()
│ │
│ sets docs_complete=True │
│ │
│ sets pr_created=True │
│ │
└───────────────┬───────────────┘
│
BOTH must be true
│
▼
awaiting_pm_review
```
### PR Creation
Developer creates PR after QA passes:
```python
roboco_git_create_pr(
project_slug="roboco",
task_id="a1b2c3d4-...",
title="[TASK-a1b2c3d4] Add rate limiting",
body="## Summary\n- Implemented sliding window...\n\n## Test Plan\n..."
)
```
This:
- Creates PR via GitHub CLI (`gh pr create`)
- Targets the project's default branch
- Sets `pr_created=True` on the task
- Records PR number and URL on the task
---
## PM Review and Completion
### Standard Completion
```
1. TASK IN awaiting_pm_review
│
▼
2. PM REVIEWS PR
│ - Check commits: roboco_git_log(project_slug, branch)
│ - Check changes: roboco_git_diff(project_slug)
│
▼
3. PM COMPLETES TASK
│ roboco_task_complete(task_id)
│
▼
4. PM MERGES PR (Optional)
│ roboco_git_merge_pr(project_slug, pr_number, "squash")
```
### CEO Approval (Major Tasks)
For significant changes, PM escalates to CEO:
```
1. TASK IN awaiting_pm_review
│
▼
2. PM ESCALATES TO CEO
│ roboco_task_escalate_to_ceo(task_id, notes)
│ → Status: awaiting_ceo_approval
│ → Requires PR number to exist
│
▼
3. CEO REVIEWS
│
├── APPROVE: roboco_task_ceo_approve(task_id, notes)
│ → Status: completed
│
└── REJECT: roboco_task_ceo_reject(task_id, notes)
→ Status: needs_revision
→ Assigned back to developer
```
---
## Git API Endpoints
### Read-Only Operations
| Endpoint | Tool | Description |
|----------|------|-------------|
| `GET /git/status` | `roboco_git_status` | Get git status for project |
| `GET /git/log` | `roboco_git_log` | Get commit history |
| `GET /git/branches` | `roboco_git_branches` | List branches |
| `GET /git/diff` | `roboco_git_diff` | View changes |
### Write Operations
| Endpoint | Tool | Description |
|----------|------|-------------|
| `POST /git/commit` | `roboco_git_commit` | Create commit linked to task |
| `POST /git/push` | `roboco_git_push` | Push to remote |
| `POST /git/branch/create` | `roboco_git_create_branch` | Create task branch (PM only) |
| `POST /git/checkout` | `roboco_git_checkout` | Checkout branch |
| `POST /git/pr/create` | `roboco_git_create_pr` | Create pull request |
| `POST /git/pr/merge` | `roboco_git_merge_pr` | Merge PR (PM only) |
---
## Git Requirements for Transitions
Tasks with `requires_git=True` have additional validation:
### claimed -> in_progress
- **Requirement**: `branch_name` must be set
- **Why**: PM must create branch before developer can start
### awaiting_documentation -> awaiting_pm_review
- **Requirements**: BOTH `docs_complete=True` AND `pr_created=True`
- **Why**: Parallel workflow - documenter and developer must both finish
### awaiting_pm_review -> awaiting_ceo_approval
- **Requirement**: `pr_number` must be set
- **Why**: CEO needs to review the PR before final approval
---
## Branch Protection (Main)
@@ -139,18 +360,7 @@ Co-authored-by: be-dev-1
- 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 |
- CI must pass (when configured)
---
@@ -167,33 +377,26 @@ Developer claims, continues on SAME branch
│
▼
Fix commits:
git commit -m "fix(auth): handle edge case X"
roboco_git_commit(project_slug, task_id, "fix edge case X")
│
▼
Push to same branch
roboco_git_push(project_slug)
│
▼
Re-submit for QA
roboco_task_submit_qa(task_id, "Fixed issues noted in QA")
```
---
## Planned Git Tools
## Commit Linking
| 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 |
Every commit made through `roboco_git_commit` is:
---
1. **Prefixed** with task ID (first 8 chars)
2. **Recorded** in `task.commits` array
3. **Linked** to work session if active
4. **Attributed** to the committing agent
## 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
This creates full traceability from commit back to task.
docs/workflows/JOURNALING.md
+229 -36
View File
@@ -1,5 +1,11 @@
# Journaling Guide
> **Status:** Implemented
>
> This document describes the Journal API and how agents use it for personal growth tracking.
---
## Purpose
Your journal is your **personal growth record**. It:
@@ -8,14 +14,44 @@ Your journal is your **personal growth record**. It:
- Records struggles for future reference
- Creates institutional memory
- Helps documenters understand your journey
- Enables semantic search for past experiences
---
## Journal API Endpoints
### Your Journal (`/me`)
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/journals/me` | GET | Get or create your journal |
| `/journals/me/entries` | GET | List your entries |
| `/journals/me/entries` | POST | Create a general entry |
| `/journals/me/stats` | GET | Get your journal statistics |
| `/journals/me/growth` | GET | Get your growth metrics |
| `/journals/me/search` | POST | Semantic search your journal |
| `/journals/me/reflections` | POST | Add task reflection |
| `/journals/me/decisions` | POST | Add decision log |
| `/journals/me/learnings` | POST | Add learning entry |
| `/journals/me/struggles` | POST | Add struggle entry |
| `/journals/me/notes` | POST | Add general note |
### Other Agent Journals (with permission)
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/journals/{agent_id}` | GET | Get another agent's journal |
| `/journals/{agent_id}/entries` | GET | List another agent's entries |
| `/journals/entries/{entry_id}` | GET | Get specific entry |
| `/journals/entries/{entry_id}` | DELETE | Delete your own entry |
---
## Journal Entry Types
### 1. General Entry (`roboco_journal_entry`)
### 1. General Entry
Basic logging for day-to-day work.
Basic logging for day-to-day work:
```python
roboco_journal_entry({
@@ -23,7 +59,9 @@ roboco_journal_entry({
"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"]
"session_id": "uuid-here", # Link to session (optional)
"tags": ["rate-limiting", "redis"],
"is_private": false # Default: false
})
```
@@ -35,9 +73,9 @@ roboco_journal_entry({
---
### 2. Decision Log (`roboco_journal_decision`)
### 2. Decision Log
**REQUIRED** when choosing between approaches.
**RECOMMENDED** when choosing between approaches:
```python
roboco_journal_decision({
@@ -50,7 +88,9 @@ roboco_journal_decision({
],
"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"
"consequences": "Added Redis dependency, need to handle connection failures",
"task_id": "uuid-here",
"tags": ["architecture", "rate-limiting"]
})
```
@@ -62,9 +102,9 @@ roboco_journal_decision({
---
### 3. Task Reflection (`roboco_journal_reflect`)
### 3. Task Reflection
**REQUIRED** when completing a task.
**RECOMMENDED** when completing a task:
```python
roboco_journal_reflect({
@@ -73,7 +113,8 @@ roboco_journal_reflect({
"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"
"next_steps": "Consider adding rate limit headers to responses, document in API docs",
"tags": ["implementation", "rate-limiting"]
})
```
@@ -84,9 +125,9 @@ roboco_journal_reflect({
---
### 4. Learning Entry (`roboco_journal_learning`)
### 4. Learning Entry
Document new knowledge.
Document new knowledge:
```python
roboco_journal_learning({
@@ -94,7 +135,8 @@ roboco_journal_learning({
"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"
"task_id": "uuid-here",
"tags": ["redis", "lua", "atomic-operations"]
})
```
@@ -106,9 +148,9 @@ roboco_journal_learning({
---
### 5. Struggle Entry (`roboco_journal_struggle`)
### 5. Struggle Entry
Document challenges for future reference.
Document challenges for future reference:
```python
roboco_journal_struggle({
@@ -120,7 +162,8 @@ roboco_journal_struggle({
],
"resolution": "Used Lua script to make check+increment atomic",
"help_needed": false,
"task_id": "uuid-here"
"task_id": "uuid-here",
"tags": ["race-condition", "concurrency", "redis"]
})
```
@@ -134,14 +177,15 @@ roboco_journal_struggle({
## 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` |
| Moment | Entry Type | Tool |
|--------|------------|------|
| Start a task | General entry | `roboco_journal_entry` |
| Make a decision | Decision log | `roboco_journal_decision` |
| Learn something new | Learning | `roboco_journal_learning` |
| Hit a struggle | Struggle | `roboco_journal_struggle` |
| Complete a task | Reflection | `roboco_journal_reflect` |
| Make progress | General entry | `roboco_journal_entry` |
| Quick note | General note | `roboco_journal_entry` |
---
@@ -149,29 +193,72 @@ roboco_journal_struggle({
### Search Your Own Journal
Semantic search (uses RAG):
```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
roboco_journal_search({
"query": "rate limiting redis",
"top_k": 5
})
```
### Read Team Journals (PM/Documenter only)
### List Your Entries
```python
roboco_journal_read_team(
target_agent="be-dev-1",
task_id="uuid-here", # Optional filter
# Recent entries
roboco_journal_recent(limit=10)
# Filter by type
roboco_journal_recent(entry_type="decision_log")
# Filter by task
roboco_journal_recent(task_id="uuid-here")
```
### Your Statistics
```python
roboco_journal_stats()
# Returns: total_entries, entries_by_type, last_entry_at, has_summary
```
### Your Growth Metrics
```python
roboco_journal_growth()
# Returns:
# total_reflections, total_learnings, total_struggles, total_decisions,
# struggle_resolution_rate, learning_frequency, sentiment_trend
```
---
## Reading Other Agents' Journals
Access is based on cell membership and role hierarchy:
```python
# By agent slug
roboco_journal_read("be-dev-1")
# By agent UUID
roboco_journal_read("a1b2c3d4-...")
# List entries with filters
roboco_journal_read_entries(
agent_id="be-dev-1",
entry_type="decision_log",
task_id="uuid-here",
limit=10
)
roboco_journal_scope() # See who you can read
```
---
## Access Permissions
The Journal API enforces strict access controls based on cell membership:
| Your Role | Can Read Journals Of |
|-----------|---------------------|
| Developer | Own only |
@@ -179,15 +266,121 @@ roboco_journal_scope() # See who you can read
| Documenter | Own + cell members (for documentation) |
| Cell PM | Own + cell members |
| Main PM | Own + all Cell PMs |
| Auditor | Everyone |
| Auditor | Everyone (silent observer) |
| CEO | Everyone |
### Cell Membership
- **Backend Cell**: be-dev-1, be-dev-2, be-qa, be-pm, be-doc
- **Frontend Cell**: fe-dev-1, fe-dev-2, fe-qa, fe-pm, fe-doc
- **UX/UI Cell**: ux-dev-1, ux-dev-2, ux-qa, ux-pm, ux-doc
Cell members with access can see ALL entries from each other, including private ones.
---
## Private Entries
Mark entries as private when they contain sensitive reflections:
```python
roboco_journal_entry({
"type": "observation",
"title": "Personal note on team dynamics",
"content": "...",
"is_private": true
})
```
**Note**: Cell members with journal access can see your private entries. This is by design - journals are for team learning, not secrets.
---
## Entry Response Format
All entry endpoints return:
```json
{
"id": "uuid",
"journal_id": "uuid",
"type": "decision_log",
"title": "...",
"content": "...",
"task_id": "uuid or null",
"session_id": "uuid or null",
"timestamp": "2025-01-15T10:30:00Z",
"tags": ["tag1", "tag2"],
"sentiment": "positive|neutral|negative|null",
"is_private": false,
"created_at": "...",
"updated_at": "..."
}
```
---
## Best Practices
1. **Journal as you go** - Don't wait until end of task
2. **Include task_id** - Links entries to work
2. **Include task_id** - Links entries to work for context
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
6. **Tag consistently** - Helps with search and filtering
7. **Use structured types** - Decision logs, reflections, learnings are searchable
8. **Link sessions** - Include session_id when working in a session
---
## Integration with Task Workflow
### On Claim
```python
roboco_journal_entry({
"type": "work_log",
"title": f"Claimed task: {task.title}",
"content": "Initial assessment: ...",
"task_id": task_id
})
```
### On Decision
```python
roboco_journal_decision({
"title": "Implementation approach",
"context": "...",
"options": [...],
"chosen": "...",
"rationale": "...",
"task_id": task_id
})
```
### On Completion
```python
roboco_journal_reflect({
"task_id": task_id,
"title": f"Completed: {task.title}",
"what_done": "...",
"what_learned": "...",
"what_struggled": "...",
"next_steps": "..."
})
```
---
## Growth Metrics Explained
The growth metrics endpoint tracks your development over time:
| Metric | Description |
|--------|-------------|
| `total_reflections` | Number of task reflections |
| `total_learnings` | Number of learning entries |
| `total_struggles` | Number of struggle entries |
| `total_decisions` | Number of decision logs |
| `struggle_resolution_rate` | % of struggles with resolutions |
| `learning_frequency` | Learnings per time period |
| `sentiment_trend` | Overall sentiment direction (improving, stable, declining) |
docs/workflows/README.md
+154 -70
View File
@@ -1,14 +1,18 @@
# Workflow Documentation
> **Status:** Implemented
>
> RoboCo workflow documentation for all agent roles.
## 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) |
| 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) |
---
@@ -16,30 +20,30 @@
### 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 |
| Document | Description | Status |
|----------|-------------|--------|
| [STATUS_TRANSITIONS.md](./STATUS_TRANSITIONS.md) | Complete task lifecycle diagram | Implemented |
| [PM.md](./PM.md) | Main PM and Cell PM workflows | Implemented |
| [DEVELOPER.md](./DEVELOPER.md) | Developer workflow | Implemented |
| [QA.md](./QA.md) | QA workflow | Implemented |
| [DOCUMENTER.md](./DOCUMENTER.md) | Documenter workflow | Implemented |
### Reference
| Document | Description |
|----------|-------------|
| [PERMISSIONS.md](./PERMISSIONS.md) | Tool, channel, notification permissions |
| [AGENT_CHEATSHEET.md](./AGENT_CHEATSHEET.md) | Quick reference per role |
| Document | Description | Status |
|----------|-------------|--------|
| [PERMISSIONS.md](./PERMISSIONS.md) | Tool, channel, notification permissions | Implemented |
| [AGENT_CHEATSHEET.md](./AGENT_CHEATSHEET.md) | Quick reference per role | Implemented |
### 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) |
| Document | Description | Status |
|----------|-------------|--------|
| [JOURNALING.md](./JOURNALING.md) | Journal API usage and entry types | Implemented |
| [COMMUNICATION.md](./COMMUNICATION.md) | Messages and channels | Implemented |
| [ESCALATION.md](./ESCALATION.md) | Task escalation and CEO approval workflow | Implemented |
| [KNOWLEDGE_BASE.md](./KNOWLEDGE_BASE.md) | Searching past work | Implemented |
| [GIT_WORKFLOW.md](./GIT_WORKFLOW.md) | Multi-agent workspaces, branching, PRs | Implemented |
### Bug Tracking
@@ -52,40 +56,39 @@
## The Big Picture
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ ROBOCO WORKFLOW │
└─────────────────────────────────────────────────────────────────────────────┘
ROBOCO WORKFLOW
--------------------------------------------------------------------------------
BOARD/CEO
│
│ Creates initiative
▼
|
| Creates initiative
v
MAIN PM
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
|
+---------------+---------------+
| | |
v v v
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
│ │ │
└─────────────────────┴─────────┘
│
▼
| | |
+----------+----------+ | +----------+----------+
| | | | | | |
v v v | v v v
BE-DEV-1 BE-DEV-2 BE-QA | FE-DEV-1 FE-DEV-2 FE-QA
| | | | | | |
+----+-----+ | | +----+-----+ |
| | | | |
v v | v v
SUBMITS TO QA ----> REVIEWS| SUBMITS TO QA ----> REVIEWS
| | | | |
v v | v v
BE-DOC <------ QA PASSES | FE-DOC <------ QA PASSES
| | |
v | v
AWAITING_PM_REVIEW <-------+--- AWAITING_PM_REVIEW
| | |
+---------------------+---------+
|
v
COMPLETED
```
@@ -94,24 +97,43 @@
## Task Lifecycle Summary
```
BACKLOG → PENDING → CLAIMED → IN_PROGRESS → VERIFYING → AWAITING_QA
│
┌─────────────────────────┴─────────────────────────┐
│ │
QA PASSES QA FAILS
│ │
▼ ▼
AWAITING_DOCUMENTATION NEEDS_REVISION
│ │
DOCS COMPLETE (back to dev)
│
▼
BACKLOG --> PENDING --> CLAIMED --> IN_PROGRESS --> VERIFYING --> AWAITING_QA
|
+----------------------------------+----------------------------------+
| |
QA PASSES QA FAILS
| |
v v
AWAITING_DOCUMENTATION NEEDS_REVISION
| |
+---------------------+---------------------+ (back to dev)
| |
DOCUMENTER DEVELOPER
writes docs creates PR
| |
v v
docs_complete=True pr_created=True
| |
+---------------------+---------------------+
|
BOTH must be true
|
v
AWAITING_PM_REVIEW
│
PM COMPLETES
│
▼
COMPLETED
|
+---------------+---------------+
| |
PM COMPLETES PM ESCALATES
| |
v v
COMPLETED AWAITING_CEO_APPROVAL
|
+---------------+---------------+
| |
CEO APPROVES CEO REJECTS
| |
v v
COMPLETED NEEDS_REVISION
```
---
@@ -131,6 +153,29 @@ BACKLOG → PENDING → CLAIMED → IN_PROGRESS → VERIFYING → AWAITING_QA
---
## Multi-Agent Workspace Structure
Each agent gets their own git workspace:
```
/data/workspaces/
+-- {project-slug}/
+-- {team}/
+-- {agent-slug}/
+-- [git repo files]
```
Example:
```
/data/workspaces/roboco/backend/be-dev-1/
/data/workspaces/roboco/backend/be-dev-2/
/data/workspaces/roboco/frontend/fe-dev-1/
```
This allows multiple agents to work on the same project in parallel, each on their own branch.
---
## Common Patterns
### Starting Work
@@ -162,6 +207,10 @@ roboco_task_start(task_id)
# Progress updates
roboco_task_progress(task_id, "Completed X", 50)
# Git operations
roboco_git_commit(project_slug, task_id, "add feature X")
roboco_git_push(project_slug)
# Journaling
roboco_journal_decision({...})
roboco_journal_learning({...})
@@ -188,3 +237,38 @@ roboco_task_submit_qa(task_id, notes)
# Reflect
roboco_journal_reflect({...})
```
---
## Escalation Chain
```
Developer/QA/Documenter --> Cell PM --> Main PM --> Product Owner --> CEO
```
See [ESCALATION.md](./ESCALATION.md) for details on:
- Task escalation (`roboco_task_escalate`)
- CEO approval workflow (`roboco_task_escalate_to_ceo`)
- Soft blocking (`roboco_task_soft_block`)
- Force completion (CEO only)
---
## Git Workflow
See [GIT_WORKFLOW.md](./GIT_WORKFLOW.md) for details on:
- Multi-agent workspace structure
- Branch naming conventions (`{type}/{team}/{task-id}`)
- Commit linking to tasks
- PR creation and merge workflow
- Parallel documentation phase
---
## Journal API
See [JOURNALING.md](./JOURNALING.md) for details on:
- Journal entry types (decision, reflection, learning, struggle)
- Semantic search
- Growth metrics
- Access permissions by role