# Task Branching Feature for Makima
## Overview
Add the ability to branch/spin off tasks that resume from where another task ended, preserving both worktree state (file changes) and conversation context (what Claude discussed/discovered).
**Key requirement:** The branched task should "remember" what was previously discussed, enabling exploration of alternative approaches from the same starting point.
## Integration with Contracts
Tasks are grouped under **contracts** - organizational units with phases (research → specify → plan → execute → review). When branching:
- **Inherit contract**: Branched tasks stay in the same contract as the source task by default
- **Optional override**: User can choose to place the branch in a different contract
- **Phase awareness**: The branch inherits the contract's current phase context
## Architecture Summary
Since Claude Code is stateless (each invocation is fresh), we cannot replay the actual conversation. Instead, we:
1. Capture and store conversation turns (user messages + assistant responses)
2. When branching, inject a formatted transcript as context in the new task's plan
3. Copy the worktree state using existing `continue_from_task_id` mechanism
## Implementation Plan
### Phase 1: Capture Conversation History
**1.1 Database Migration**
Create `makima/migrations/20250111000000_add_task_conversations.sql`:
```sql
CREATE TABLE IF NOT EXISTS task_conversations (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
task_id UUID NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
turn_index INTEGER NOT NULL,
role VARCHAR(32) NOT NULL, -- 'user', 'assistant'
content TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_task_conversations_task_id ON task_conversations(task_id);
```
**1.2 Capture User Messages**
Modify `makima/daemon/src/task/manager.rs`:
- When sending initial plan to Claude, emit a `ConversationTurn` message to server
- When forwarding user messages from `input_rx`, emit a `ConversationTurn` message
**1.3 Capture Assistant Responses**
Modify `makima/src/server/handlers/mesh_daemon.rs`:
- Aggregate `TaskOutputEntry` messages with `message_type='assistant'` into conversation turns
- Store in `task_conversations` table when a user message arrives (marks end of assistant turn)
**1.4 New Protocol Message**
Add to `makima/daemon/src/ws/protocol.rs` and `makima/src/server/protocol.rs`:
```rust
ConversationTurn {
task_id: Uuid,
turn_index: i32,
role: String, // "user" or "assistant"
content: String,
}
```
### Phase 2: Branching Infrastructure
**2.1 Database Migration**
Create `makima/migrations/20250111000001_add_branching_fields.sql`:
```sql
ALTER TABLE tasks ADD COLUMN branched_from_task_id UUID REFERENCES tasks(id) ON DELETE SET NULL;
CREATE INDEX idx_tasks_branched_from ON tasks(branched_from_task_id) WHERE branched_from_task_id IS NOT NULL;
```
**2.2 Update Task Model**
Modify `makima/src/db/models.rs`:
```rust
pub struct Task {
// ... existing fields ...
pub branched_from_task_id: Option<Uuid>,
}
pub struct BranchTaskRequest {
pub name: Option<String>,
pub plan: String,
pub include_conversation: bool, // default true
pub include_worktree: bool, // default true
pub contract_id: Option<Uuid>, // if None, inherit from source task
}
```
**2.3 New Branch Endpoint**
Add to `makima/src/server/handlers/mesh.rs`:
- `POST /api/v1/mesh/tasks/{id}/branch` handler
- Validates source task exists and user has permission
- Fetches conversation history from `task_conversations`
- Creates new task with:
- `branched_from_task_id` = source task ID
- `continue_from_task_id` = source task ID (for worktree copying)
- `contract_id` = request.contract_id OR source task's contract_id
- Plan = formatted conversation context + new instructions
### Phase 3: Context Injection
**3.1 Format Conversation Transcript**
Add helper function in `makima/src/server/handlers/mesh.rs`:
```rust
fn format_conversation_context(turns: Vec<ConversationTurn>) -> String {
// Format as:
// ## Previous Conversation Context
//
// **User:** {message}
// **Assistant:** {response}
// ...
//
// ---
}
```
**3.2 Prepend to Branched Task Plan**
When creating a branched task, construct the plan as:
```
{formatted_conversation_context}
## New Instructions
{user's new plan}
```
### Phase 4: Frontend Integration
**4.1 API Client**
Add to `makima/frontend/src/lib/api.ts`:
```typescript
branchTask(id: string, request: BranchTaskRequest): Promise<Task>
```
**4.2 Branch Button**
Add to `makima/frontend/src/components/mesh/TaskDetail.tsx`:
- "Branch" button in task actions
- Opens dialog to enter new instructions
- Checkboxes for "Include conversation" and "Include file changes"
- Contract selector (defaults to current contract, allows choosing another)
**4.3 Tree Visualization (Optional)**
Show `branched_from_task_id` relationships in task list to visualize the branch tree.
**4.4 Contract Tasks View**
Update `makima/frontend/src/components/contracts/ContractDetail.tsx`:
- Show branched tasks in the Tasks tab with visual indicators
- Display branch relationships (e.g., "Branched from: Task X")
## Files to Modify
### Backend (Server)
- `makima/src/db/models.rs` - Add `BranchTaskRequest`, extend `Task`
- `makima/src/db/repository.rs` - Add conversation CRUD, branch query
- `makima/src/server/handlers/mesh.rs` - Add `branch_task` handler
- `makima/src/server/handlers/mesh_daemon.rs` - Store conversation turns
- `makima/src/server/protocol.rs` - Add `ConversationTurn` message
### Backend (Daemon)
- `makima/daemon/src/ws/protocol.rs` - Add `ConversationTurn` message
- `makima/daemon/src/task/manager.rs` - Emit user messages as conversation turns
### Migrations
- `makima/migrations/20250111000000_add_task_conversations.sql`
- `makima/migrations/20250111000001_add_branching_fields.sql`
### Frontend
- `makima/frontend/src/lib/api.ts` - Add `branchTask()` method and types
- `makima/frontend/src/components/mesh/TaskDetail.tsx` - Add Branch button/dialog
- `makima/frontend/src/components/contracts/ContractDetail.tsx` - Show branch relationships in Tasks tab
## Key Design Decisions
1. **Conversation as context, not replay** - We prepend a transcript to the plan rather than trying to inject messages into Claude Code (which only accepts user messages)
2. **Separate from parent-child hierarchy** - Using `branched_from_task_id` instead of `parent_task_id` to distinguish from orchestrator/subtask relationships
3. **Reuse existing worktree mechanism** - Set `continue_from_task_id` to copy files from source task
4. **Opt-in conversation/worktree** - Both are configurable per-branch request
5. **Contract inheritance** - Branched tasks inherit the source task's contract by default, but can be placed in a different contract if needed (e.g., branching research findings into a new execute-phase contract)
