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:
Renn F
2025-12-22 18:04:31 +01:00
parent 4e06bdb842
commit b7611c24fc
36 changed files with 2118 additions and 92 deletions
+20 -14
View File
@@ -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
+58 -1
View File
@@ -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
+16 -9
View File
@@ -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)