1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
---
name: makima-supervisor
description: Supervisor commands for makima contract orchestration. Use when spawning subtasks, waiting for tasks, managing branches, creating PRs, or coordinating work across multiple Claude instances.
---
# Makima Supervisor Commands
These commands are for supervisors coordinating work on a makima contract. Environment variables (`MAKIMA_API_URL`, `MAKIMA_API_KEY`, `MAKIMA_CONTRACT_ID`, `MAKIMA_TASK_ID`) are pre-configured by the daemon.
## Task Management
### Spawn a new subtask
```bash
makima supervisor spawn "<task_name>" "<task_plan>"
```
Creates and starts a new task. Returns JSON with `taskId`.
Options:
- `--parent <task_id>` - Branch from a parent task's worktree
- `--checkpoint <sha>` - Start from a specific checkpoint
- `--repo <url>` - Repository URL (detected from current directory if not provided)
### Wait for task completion
```bash
makima supervisor wait <task_id> [timeout_seconds]
```
Blocks until task completes. Default timeout: 300s. Returns task status JSON.
Options:
- `--poll-interval <seconds>` - How often to check status (default: 5)
### List all tasks
```bash
makima supervisor tasks
```
Returns JSON array of all tasks in the contract.
### Get task tree structure
```bash
makima supervisor tree
```
Returns hierarchical JSON of task relationships.
### Get individual task details
```bash
makima supervisor task <task_id>
```
### Get task output/log
```bash
makima supervisor output <task_id>
```
### View task diff
```bash
makima supervisor diff <task_id>
```
Shows uncommitted changes in the task's worktree.
### Read file from task worktree
```bash
makima supervisor read-file <task_id> <file_path>
```
## Git Operations
### Create a branch
```bash
makima supervisor branch "<branch_name>"
```
Options:
- `--from <task_id_or_sha>` - Branch from specific reference
### Merge task changes
```bash
makima supervisor merge <task_id>
```
Options:
- `--to <branch>` - Target branch (default: contract's target branch)
- `--squash` - Squash commits
### Create pull request
```bash
makima supervisor pr "<branch_name>" --title "<title>" --body "<body>"
```
## Checkpoints
### Create checkpoint
```bash
makima supervisor checkpoint "<message>"
```
Creates a checkpoint of current state.
### List task checkpoints
```bash
makima supervisor task-checkpoints <task_id>
```
Options:
- `--with-diff` - Include diff summary
## History and Recovery
### View task conversation history
```bash
makima supervisor task-history <task_id>
```
Options:
- `--tool-calls <true|false>` - Include tool calls (default: true)
- `--limit <n>` - Maximum messages to return
- `--format <table|json|chat>` - Output format (default: chat)
### Resume from checkpoint
```bash
makima supervisor task-resume-from <task_id> --checkpoint <n> --plan "<plan>"
```
Options:
- `--name "<name>"` - Name for the new task
### Fork task from checkpoint
```bash
makima supervisor task-fork <task_id> --checkpoint <n> --name "<name>" --plan "<plan>"
```
Options:
- `--include-conversation <true|false>` - Include conversation history (default: true)
### Rewind task to checkpoint
```bash
makima supervisor task-rewind <task_id> --checkpoint <n>
```
Options:
- `--preserve <discard|create_branch|stash>` - How to preserve current work (default: create_branch)
- `--branch-name "<name>"` - Branch name for create_branch mode
## Contract Lifecycle
### Get contract status
```bash
makima supervisor status
```
### Advance to next phase
```bash
makima supervisor advance-phase <phase>
```
Phases: specify, plan, execute, review.
Options:
- `-y` - Confirm the transition (without this, returns deliverables for review)
### Mark deliverable complete
```bash
makima supervisor mark-deliverable <deliverable_id>
```
Options:
- `--phase <phase>` - Phase the deliverable belongs to
### Ask user a question
```bash
makima supervisor ask "<question>"
```
Options:
- `--choices "opt1,opt2,opt3"` - Provide choices
- `--context "<context>"` - Additional context
- `--timeout <seconds>` - Wait timeout (default: 3600)
- `--phaseguard` - Block indefinitely until response
- `--multi-select` - Allow multiple choice selection
- `--non-blocking` - Return immediately without waiting
- `--question-type <general|phase_confirmation|contract_complete>` - Question type
### Mark contract complete
```bash
makima supervisor complete
```
### Resume a completed contract
```bash
makima supervisor resume-contract <contract_id>
```
## Output Format
All commands output JSON to stdout. Parse with `jq` or handle in code.
Example workflow:
```bash
# Spawn a subtask
task_id=$(makima supervisor spawn "Implement feature" "Add the new button to the header" | jq -r '.taskId')
# Wait for completion
makima supervisor wait "$task_id"
# Check the diff
makima supervisor diff "$task_id"
# Merge if satisfied
makima supervisor merge "$task_id"
```
|
