---
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"
```
