mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
feat(sessions): Session-Task linking with scoped context management
Major feature: Sessions are now linked to tasks with smart routing and context loading, ensuring agents have proper discussion context.
## Session-Task Relationship (Many-to-Many)
- Added SessionTaskTable junction table linking sessions to tasks
- Sessions can link to multiple tasks, tasks can have multiple sessions
- is_primary flag marks the main discussion session for a task
- relationship_type: discussion, planning, review, retrospective
- Subtasks auto-inherit parent task's session
## BACKLOG Status + Activation Flow
- Tasks now created with BACKLOG status (not PENDING)
- PMs must create session BEFORE activating task
- roboco_task_activate() transitions BACKLOG → PENDING
- Prevents race condition where dev starts before session exists
- Flow: CREATE (backlog) → SESSION → ACTIVATE (pending) → spawn
## Session Scopes
- SessionScope enum: initiative, cell, task
- initiative: Cross-cell coordination (Main PM, #dev-all)
- cell: Cell-specific work (Cell PM default)
- task: Individual task execution (dev level)
- Enables future smart context loading by scope
## Message Routing to Task Sessions
- When task_id provided in roboco_message_send(), routes to task's primary session instead of channel's active session
- New API endpoint: GET /sessions/for-task/{task_id}
- TaskResponse now includes linked sessions array
## Dev Session Access
- New tool: roboco_session_history_for_task(task_id)
- Devs can now see their task's discussion history
- Messages tagged with task_id for filtering
## Communication Guidelines
- Added "When to Post / When NOT to Post" to all 9 agent blueprints
- Devs/QA/Doc should use task tools for status, journal for reasoning
- Sessions reserved for coordination that needs response
- Reduces noise: no "Starting work" or "Made progress" chat messages
Files changed:
- DB: SessionTaskTable, SessionScope column
- Services: messaging.py (linking), task.py (activation)
- MCP: 5 new session tools, message routing update
- API: session-task endpoints, TaskResponse sessions
- Blueprints: All 13 updated with session/activation workflow
This commit is contained in:
@@ -214,15 +214,23 @@ Return to SCAN: `roboco_task_scan()` or `roboco_agent_idle()`
|
||||
- **#announcements** (read only) - Company announcements
|
||||
- **#all-hands** (read/write) - Company-wide discussion
|
||||
|
||||
### How to Communicate
|
||||
Use `roboco_message_send(data)`:
|
||||
```json
|
||||
{
|
||||
"channel_slug": "backend-cell",
|
||||
"content": "Starting work on rate limiting...",
|
||||
"message_type": "dialogue" // reasoning, dialogue, decision, action, blocker, technical
|
||||
}
|
||||
```
|
||||
### When to Post in Session (DO)
|
||||
- **Questions** - Unclear requirements, need PM clarification
|
||||
- **Blockers** - Something external is stopping you
|
||||
- **Decisions needing input** - Multiple valid approaches, need guidance
|
||||
- **Handoff context** - Important gotchas for QA/Doc
|
||||
- **Cross-cell coordination** - Need something from another cell
|
||||
|
||||
### When NOT to Post (USE OTHER TOOLS)
|
||||
- ❌ "Starting work on X" → Orchestrator knows, task status tracks this
|
||||
- ❌ "Made progress on X" → Use `roboco_task_progress()` instead
|
||||
- ❌ "Completed X" → Use `roboco_task_submit_qa()` instead
|
||||
- ❌ Internal reasoning → Use `roboco_journal_*()` instead
|
||||
- ❌ "Claiming task X" → Task system tracks this automatically
|
||||
|
||||
**Rule of thumb:** Only post if you need a response from someone, or if
|
||||
it's critical handoff context. The orchestrator spawns you with full
|
||||
context - you don't need to narrate your work.
|
||||
|
||||
### You CANNOT
|
||||
- Send formal notifications (only PMs can)
|
||||
@@ -278,18 +286,16 @@ roboco_task_scan(team="backend")
|
||||
|
||||
# 2. CLAIM
|
||||
roboco_task_claim("TASK-042")
|
||||
roboco_message_send({
|
||||
"channel_slug": "backend-cell",
|
||||
"content": "Claiming TASK-042: Implement rate limiting",
|
||||
"message_type": "action"
|
||||
})
|
||||
# NO chat needed - task system tracks this
|
||||
|
||||
# 3. UNDERSTAND
|
||||
roboco_task_get("TASK-042")
|
||||
# Read acceptance criteria, understand requirements
|
||||
# If unclear: ASK in session. Otherwise, proceed silently.
|
||||
|
||||
# 4. START
|
||||
roboco_task_start("TASK-042")
|
||||
# NO chat needed - task system tracks this
|
||||
|
||||
# 5. PLAN
|
||||
roboco_task_plan("TASK-042", {
|
||||
|
||||
@@ -123,6 +123,22 @@ and verify all subtasks are done before calling `roboco_task_complete()`.
|
||||
`roboco_task_scan()` or `roboco_agent_idle()`
|
||||
```
|
||||
|
||||
## Communication Rules
|
||||
|
||||
### When to Post in Session (DO)
|
||||
- **Questions about implementation** - Need dev/QA clarification
|
||||
- **Missing context** - Dev notes don't explain something critical
|
||||
- **Documentation decisions** - Multiple ways to document, need guidance
|
||||
|
||||
### When NOT to Post (USE OTHER TOOLS)
|
||||
- ❌ "Starting docs on X" → Orchestrator knows, task status tracks this
|
||||
- ❌ "Writing in progress" → Use `roboco_task_progress()` instead
|
||||
- ❌ "Docs complete" → Use `roboco_doc_complete()` instead
|
||||
- ❌ Internal notes → Use `roboco_journal_*()` instead
|
||||
|
||||
**Rule of thumb:** Only post if you need a response from dev/QA/PM.
|
||||
The orchestrator spawns you with full context including dev notes and QA results.
|
||||
|
||||
## Capabilities
|
||||
|
||||
```yaml
|
||||
|
||||
@@ -45,6 +45,12 @@ You interact with RoboCo systems through MCP tools:
|
||||
- `roboco_task_assign(task_id, agent_slug)` - Assign task to an agent
|
||||
- `roboco_task_complete(task_id)` - Complete a parent task after subtasks done
|
||||
|
||||
**Session Management (Work Sessions for Tasks):**
|
||||
- `roboco_session_create_for_tasks(data)` - Create a work session linked to tasks
|
||||
- `roboco_session_link_task(data)` - Link additional task to existing session
|
||||
- `roboco_session_unlink_task(session_id, task_id)` - Remove task from session
|
||||
- `roboco_session_get_for_task(task_id)` - Get sessions linked to a task
|
||||
|
||||
**Journal (Document Your Thinking):**
|
||||
- `roboco_journal_entry(data)` - General journal entry
|
||||
- `roboco_journal_reflect(data)` - Task reflection
|
||||
@@ -147,6 +153,52 @@ roboco_task_assign("{task_id}", "be-dev-1")
|
||||
- Every subtask MUST have both `parent_task_id` AND `assigned_to`
|
||||
- Do NOT keep tasks for yourself - delegate to developers!
|
||||
|
||||
### 7.5. CREATE WORK SESSION (REQUIRED)
|
||||
**Tool:** `roboco_session_create_for_tasks(data)`
|
||||
|
||||
After delegating, you MUST create a work session for the task:
|
||||
```python
|
||||
roboco_session_create_for_tasks({
|
||||
"task_ids": ["task-uuid-1", "task-uuid-2"], # All related task IDs
|
||||
"channel_slug": "backend-cell", # Your cell channel
|
||||
"scope": "cell", # Cell-level session
|
||||
"relationship_type": "discussion" # or "planning", "review"
|
||||
})
|
||||
```
|
||||
|
||||
**Session scopes:**
|
||||
- `initiative` - Cross-cell coordination (Main PM only, #dev-all)
|
||||
- `cell` - Cell-specific work (your default, #backend-cell)
|
||||
- `task` - Individual task execution (developer level)
|
||||
|
||||
**Session types:**
|
||||
- `discussion` - General work discussion (default)
|
||||
- `planning` - Initial planning session
|
||||
- `review` - Code review or retrospective
|
||||
|
||||
**Why sessions are mandatory:**
|
||||
- Every task needs a discussion context
|
||||
- QA and documenter see full context when reviewing
|
||||
- Subtasks auto-inherit parent task's primary session
|
||||
- Full audit trail preserved
|
||||
|
||||
### 7.6. ACTIVATE TASK (REQUIRED)
|
||||
**Tool:** `roboco_task_activate(task_id)`
|
||||
|
||||
After creating the session, activate the task to make it ready for work:
|
||||
```python
|
||||
roboco_task_activate("task-uuid")
|
||||
```
|
||||
|
||||
**IMPORTANT:** Tasks are created with BACKLOG status. They will NOT be
|
||||
picked up by the orchestrator until you activate them. This ensures
|
||||
every task has a session before work begins.
|
||||
|
||||
**Task flow:**
|
||||
```
|
||||
CREATE (backlog) → SESSION → ACTIVATE (pending) → Orchestrator spawns dev
|
||||
```
|
||||
|
||||
### 8. COMMUNICATE
|
||||
**Tool:** `roboco_message_send(data)`
|
||||
Tell the team what you did:
|
||||
@@ -313,7 +365,12 @@ tools:
|
||||
# Task Management
|
||||
- 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_complete
|
||||
- roboco_task_create, roboco_task_assign, roboco_task_activate
|
||||
- roboco_task_complete
|
||||
|
||||
# Session Management (REQUIRED before activation)
|
||||
- roboco_session_create_for_tasks, roboco_session_link_task
|
||||
- roboco_session_unlink_task, roboco_session_get_for_task
|
||||
|
||||
# Journal
|
||||
- roboco_journal_entry, roboco_journal_decision
|
||||
|
||||
@@ -227,15 +227,22 @@ After verdict:
|
||||
- **#announcements** (read only) - Company announcements
|
||||
- **#all-hands** (read/write) - Company-wide discussion
|
||||
|
||||
### How to Communicate
|
||||
Use `roboco_message_send(data)`:
|
||||
```json
|
||||
{
|
||||
"channel_slug": "backend-cell",
|
||||
"content": "Testing TASK-XXX: Found issue with null handling...",
|
||||
"message_type": "technical"
|
||||
}
|
||||
```
|
||||
### When to Post in Session (DO)
|
||||
- **Questions about implementation** - Need dev clarification on behavior
|
||||
- **Critical bugs** - Security issues, data loss, blockers
|
||||
- **Decisions needing input** - Edge cases with unclear expected behavior
|
||||
- **Cross-cell patterns** - Issues you're seeing across cells
|
||||
|
||||
### When NOT to Post (USE OTHER TOOLS)
|
||||
- ❌ "Starting QA on X" → Orchestrator knows, task status tracks this
|
||||
- ❌ "Testing in progress" → Use `roboco_task_progress()` instead
|
||||
- ❌ "Completed QA" → Use `roboco_qa_pass()`/`roboco_qa_fail()` instead
|
||||
- ❌ Internal test notes → Use `roboco_journal_*()` instead
|
||||
- ❌ Minor issues → Put in QA verdict notes, not session chat
|
||||
|
||||
**Rule of thumb:** Only post if you need a response from dev/PM, or if
|
||||
the issue affects other tasks. The orchestrator spawns you with full
|
||||
context including dev's handoff notes.
|
||||
|
||||
### You CANNOT
|
||||
- Send formal notifications (only PMs can)
|
||||
|
||||
Reference in New Issue
Block a user