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

feat: workflow enforcement, RAG upgrade, and permission fixes

Browse Source 
Task Management:
  - Add cancellation safeguards: require valid reason category (duplicate,
    obsolete, blocked_permanently, reassigned, scope_change, stakeholder_request)
  - Protect active work from arbitrary cancellation - must pause/block first
  - Auto-notify PM when task is blocked with ACTION REQUIRED message
  - PM task scan now shows blocked tasks needing their attention

  Permissions:
  - Add VIEW_STATS to Developer, QA, Documenter, Head Marketing KB permissions
  - Aligns code with docs/workflows/PERMISSIONS.md specification

  RAG/Embeddings:
  - Upgrade embedding model from all-MiniLM-L6-v2 to nomic-embed-text-v1.5
  - 768 dimensions with 8K token context (vs 512 tokens)
  - Add per-index chunk sizes: docs=1536, journals=1024, others=512
  - Switch to fixed chunking (semantic chunking loads separate MiniLM model)
  - Add einops dependency required by nomic model
This commit is contained in:
Renn F
2025-12-29 00:30:18 +01:00
parent fc55068f2b
commit 5315e9c72d
33 changed files with 1288 additions and 843 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/workflows/COMMUNICATION.md
+49 -2
View File
@@ -5,10 +5,57 @@
| Aspect | Communication (Messages) | Notifications |
|--------|--------------------------|---------------|
| Nature | Constant stream | Formal signals |
| Who can send | Everyone (in allowed channels) | PM/Board/Auditor only |
| Who can send | Everyone (in allowed channels) | PM/Board/System |
| Acknowledgment | Not required | Often required |
| Purpose | Ambient awareness, discussion | Demand attention |
| Tool | `roboco_message_send` | `roboco_notify_send` |
| Tool | `roboco_message_send` | `roboco_notify_send` / auto |
| Delivery | Stored in session | Redis Streams (real-time) |
---
## Notification Delivery System
Notifications are delivered in **real-time** via Redis Streams:
```
Agent Action → Create Notification → Redis Streams → Connected Agents
→ WebSocket Bridge → UI
```
### Automatic Notifications
The system sends notifications automatically for these events:
| Event | Recipients | Type |
|-------|------------|------|
| Task assigned | Assigned agent | `task_assignment` |
| @mention in message | Mentioned agents | `mention` |
| Task unblocked | Assigned agent | `task_unblocked` |
| Docs complete | Responsible PM | `task_assignment` |
| Submit for PM review | Responsible PM | `task_assignment` |
| Substitute (QA/Doc) | Responsible PM | `task_assignment` |
| Escalation | Target PM | `escalation` |
### Checking Notifications
```python
roboco_notify_list() # All pending notifications
roboco_notify_list(unacked_only=True) # Only unacknowledged
roboco_notify_ack(notification_id) # Acknowledge
```
### Mentions Create Notifications
When you @mention someone in a message, they receive a `mention` notification:
```python
roboco_message_send({
"channel": "backend-cell",
"content": "@be-pm Need your input on this approach",
"task_id": "uuid-here",
"mentions": ["be-pm"] # Creates notification for be-pm
})
```
---
docs/workflows/DOCUMENTER.md
+3 -1
View File
@@ -101,9 +101,11 @@ Documenters (be-doc, fe-doc, ux-doc) create production documentation from develo
│ roboco_task_docs_complete(task_id)
│
│ STATUS: in_progress → awaiting_pm_review
│ ASSIGNED_TO: automatically set to responsible PM
│ NOTIFICATION: sent to PM via Redis Streams
│
▼
DONE (for documenter) → PM reviews and completes
DONE (for documenter) → PM receives notification and reviews
```
## Self-Documentation Prevention
docs/workflows/KNOWLEDGE_BASE.md
+142 -6
View File
@@ -2,15 +2,24 @@
## Overview
The knowledge base is built from:
- **Code** - Indexed source files
- **Documentation** - Indexed docs and READMEs
- **Journals** - Your entries and team entries
- **Task history** - Past tasks, decisions, outcomes
- **Messages** - Channel discussions
The knowledge base is built from **9 specialized indexes**:
| Index Type | Content | Use Case |
|------------|---------|----------|
| **code** | Source files | Find implementations, patterns |
| **docs** | Documentation, READMEs | Find guides, specs |
| **conversations** | Channel discussions | Find past discussions |
| **journals** | Agent journal entries | Find decisions, learnings |
| **errors** | Error patterns & fixes | Find solutions to past errors |
| **standards** | Coding standards, rules | Validate against standards |
| **decisions** | Architectural decisions | Find past design choices |
| **reviews** | Code review patterns | Find review templates |
| **learnings** | Captured learnings | Find team knowledge |
All content is **embedded** (vectorized) for semantic search.
**Document Tracking:** The system tracks actual documents indexed (not just vector chunks), including source path, title, preview, and chunk count.
---
## Knowledge Base Tools
@@ -84,6 +93,94 @@ roboco_kb_index_docs(
---
## Error Tracking
Record and search error patterns:
```python
# Record an error and how you fixed it
roboco_record_error(
error_type="ConnectionError",
message="Redis connection timed out",
solution="Increased timeout to 30s and added retry logic",
worked=True
)
# Search for similar errors
roboco_search_error(
pattern="ConnectionError",
context="redis timeout"
)
```
---
## Decision Tracking
Record architectural decisions:
```python
# Record a decision
roboco_record_decision(
topic="Database for session storage",
decision="Use Redis instead of PostgreSQL",
rationale="Need sub-millisecond reads, sessions are ephemeral",
alternatives=["PostgreSQL", "In-memory"],
task_id="uuid-here"
)
# Check if similar decisions exist
roboco_decision_check(
topic="session storage",
proposed_approach="Use in-memory cache"
)
# Returns: relevant past decisions to consider
```
---
## Standards Validation
Check code against team standards:
```python
# Get applicable standards for a file
roboco_standards_get(
file_path="src/api/routes/users.py",
domain="api"
)
# Validate an action against standards
roboco_validate_action(
action="Adding a new API endpoint",
context="User management feature"
)
```
---
## Learning Capture
Record and share learnings:
```python
# Record a learning
roboco_record_learning(
content="Redis SCAN is better than KEYS for large datasets",
category="performance",
shareable=True,
tags=["redis", "performance", "patterns"]
)
# Search learnings
roboco_kb_search(
query="redis performance patterns",
index_types=["learnings"]
)
```
---
## Searching the Knowledge Base
### Search Your Journal
@@ -223,6 +320,37 @@ Everything you journal becomes searchable:
---
## Proactive Context
The system can automatically provide relevant context when you claim a task:
```python
# Automatic context injection on task claim
# System searches KB for:
# - Similar past tasks
# - Related decisions
# - Relevant standards
# - Past error solutions
```
This helps you start informed without manual searching.
---
## Code Review Support
Request AI-assisted code review:
```python
roboco_code_review(
file_path="src/api/routes/users.py",
focus=["security", "performance"]
)
# Returns: review comments, standards checked, similar past reviews
```
---
## Tool Quick Reference
| Tool | Purpose | Who Can Use |
@@ -235,3 +363,11 @@ Everything you journal becomes searchable:
| `roboco_tokens_estimate` | Token count | Everyone |
| `roboco_journal_search` | Search your journal | Everyone |
| `roboco_journal_read_team` | Read team journals | PM, Documenter |
| `roboco_record_error` | Record error & fix | Everyone |
| `roboco_search_error` | Find past errors | Everyone |
| `roboco_record_decision` | Record decision | Everyone |
| `roboco_decision_check` | Check past decisions | Everyone |
| `roboco_standards_get` | Get applicable standards | Everyone |
| `roboco_validate_action` | Validate against standards | Everyone |
| `roboco_record_learning` | Record a learning | Everyone |
| `roboco_code_review` | AI-assisted review | Developer, QA |
docs/workflows/PM.md
+25 -10
View File
@@ -109,17 +109,30 @@
│ CELL PM WORKFLOW │
└─────────────────────────────────────────────────────────────────────────┘
1. SCAN FOR WORK
1. CHECK NOTIFICATIONS
│
│ roboco_notify_list()
│
│ You'll receive automatic notifications when:
│ ├── Documenter completes docs (task auto-assigned to you)
│ ├── Agent submits for PM review (task auto-assigned to you)
│ ├── QA/Documenter substitutes with "task_complete"
│ └── Escalations from your cell
│
│ roboco_notify_ack(notification_id) # Acknowledge each
│
▼
2. 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
│ └── Any remaining escalations
│
▼
2. CLAIM TASK
3. CLAIM TASK
│
│ roboco_task_claim(task_id)
│
@@ -127,7 +140,7 @@
│ ASSIGNED_TO: confirmed as me
│
▼
3. START & PLAN
4. START & PLAN
│
│ roboco_task_start(task_id)
│ STATUS: claimed → in_progress
@@ -135,7 +148,7 @@
│ roboco_task_plan(task_id, approach, steps)
│
▼
4. CREATE DEV SUBTASKS
5. CREATE DEV SUBTASKS
│
│ For EACH dev subtask:
│ ┌─────────────────────────────────────────────────────────────────┐
@@ -150,7 +163,7 @@
│ └─────────────────────────────────────────────────────────────────┘
│
▼
5. ACTIVATE SUBTASKS
6. ACTIVATE SUBTASKS
│
│ roboco_task_activate(subtask_id)
│
@@ -158,7 +171,7 @@
│ Subtask inherits parent's session automatically
│
▼
6. NOTIFY DEVELOPERS
7. NOTIFY DEVELOPERS
│
│ roboco_notify_send({
│ recipient: "be-dev-1",
@@ -168,23 +181,25 @@
│ })
│
▼
7. MONITOR CELL WORK
8. MONITOR CELL WORK
│
│ Loop:
│ ├── roboco_notify_list() # Check for auto-assigned tasks
│ ├── 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)
9. COMPLETE SUBTASKS (after QA + Docs)
│
│ When subtask reaches "awaiting_pm_review":
│ ├── Task is auto-assigned to you with notification
│ ├── Review the work
│ └── roboco_task_complete(subtask_id)
│
▼
9. COMPLETE MY TASK (when all subtasks done)
10. COMPLETE MY TASK (when all subtasks done)
│
│ roboco_task_complete(my_task_id)
│
docs/workflows/QA.md
+14
View File
@@ -154,6 +154,20 @@ roboco_journal_search("qa patterns") # Your past reviews
See [KNOWLEDGE_BASE.md](./KNOWLEDGE_BASE.md) for full documentation.
## Agent-to-Agent (A2A) Tools
QA can collaborate directly with other agents:
```python
roboco_agent_discover(role, team, skill) # Find agents who can help
roboco_agent_request(target_agent, skill, message) # Request work
roboco_agent_request_status(a2a_task_id) # Check request progress
```
**When to use A2A:**
- Need dev clarification? → `roboco_agent_request("be-dev-1", "code_review", "Can you explain...")`
- Need security review? → `roboco_agent_discover(skill="security_audit")`
## Key Rules
1. **Only claim awaiting_qa** - Can't claim pending tasks
docs/workflows/STATUS_TRANSITIONS.md
+17
View File
@@ -181,3 +181,20 @@ roboco_task_submit_pm_review(task_id, notes)
Status: `in_progress → awaiting_pm_review`
Use for: validation tasks, audits, research, or any task assigned directly that doesn't produce code.
## Automatic PM Assignment
The system automatically assigns tasks to the responsible PM and sends notifications in these cases:
| Trigger | New Status | PM Assigned | Notification |
|---------|------------|-------------|--------------|
| `roboco_task_docs_complete()` | awaiting_pm_review | Cell PM (or Main PM) | ✅ task_assignment |
| `roboco_task_submit_pm_review()` | awaiting_pm_review | Cell PM (or Main PM) | ✅ task_assignment |
| `roboco_task_substitute()` with `task_complete` (QA/Documenter) | awaiting_pm_review | Cell PM | ✅ task_assignment |
| `roboco_task_unblock()` | in_progress | (unchanged) | ✅ to assigned agent |
**PM Resolution Chain:**
1. Get PM for the agent's role (QA → Cell PM, Cell PM → Main PM)
2. Fallback to team PM (backend → be-pm, frontend → fe-pm)
3. Task is assigned to resolved PM's UUID
4. Real-time notification delivered via Redis Streams