Supervisor

Creating a New Task (Recommended Path)

Before starting supervision you need a task directory. The easiest way is the CLI:

# Interactive wizard — creates ~/.supervisor/tasks/<task_id>/ for you
supervisor init --task <task_id> --working-dir /path/to/project --executor kimi

Or manually:

mkdir -p ~/.supervisor/tasks/<task_id>
cp <skills_dir>/supervisor/state-templates/task.json ~/.supervisor/tasks/<task_id>/
cp <skills_dir>/supervisor/state-templates/progress.json ~/.supervisor/tasks/<task_id>/
touch ~/.supervisor/tasks/<task_id>/{sessions,review_log,handoffs}.jsonl
# Edit task.json with your task definition

Once the directory exists, run the Startup Sequence below.

Monitoring During Supervision (Independent of Agent Context)

You can monitor task progress in a separate terminal without consuming your agent's context:

# TUI snapshot (one-shot)
supervisor status --task <task_id>

# Auto-refreshing TUI (every 5 s)
supervisor status --task <task_id> --watch

# Self-contained web status page (opens browser, zero extra deps)
supervisor status --task <task_id> --web

# Raw JSON for scripting
supervisor status --task <task_id> --json

# List all tasks
supervisor list

The scripts live in <skills_dir>/../scripts/supervisor and require only Python 3 — no additional packages.

Startup Sequence

When you begin (or resume) a supervision session:

Finding the task directory: The task state lives in ~/.supervisor/tasks/{task_id}/.

• If the user provides a task ID, use it directly.
• If no ID is given, list ~/.supervisor/tasks/ and ask the user to select, or use the most recently modified directory.

Skill directory path: This SKILL.md file lives inside the skills directory (e.g. skills/supervisor/). When invoking executor-profile scripts, resolve the path relative to this file. In practice, instruct yourself: "run the script at {directory containing this SKILL.md}/executor-profiles/{executor_type}/check_health.py".

1. Read ~/.supervisor/tasks/{task_id}/task.json → understand the original goal, plan items, and constraints
2. Read ~/.supervisor/tasks/{task_id}/progress.json → understand current state
3. Read executor-profiles/{executor_type}/ profile from this skill directory → load monitoring method and thresholds
4. Read the last 10 lines of ~/.supervisor/tasks/{task_id}/review_log.jsonl → recall recent issues
5. Confirm with the user what the next action is before proceeding

Per-Turn Loop

After each executor turn completes:

Step 1 — Health Check

Run the executor health check as described in executor-profiles/{executor_type}.md. Record ctx_usage, compactions, last_turn_steps in memory.

Step 2 — Lightweight Review

2a. Read executor status block (if executor-report-format skill is active)

If the executor is running with the executor-report-format skill, its last response contains a structured block:

<!-- supervisor:status --> ... <!-- /supervisor:status -->

Parse this block to get: plan_item, status, completed_this_turn, blockers, next_step, files_changed. This is the fastest signal — read it before running any shell commands.

2b. Git diff review

git -C {working_dir} diff --stat HEAD~1
git -C {working_dir} log --oneline -3

Read the output. Identify:

• Which files changed and by how much
• Whether the change scope matches the plan item
• Any sign of regression (unexpected file changes, deletions)

Step 3 — Update Progress

Write updated progress.json:

• Mark plan items as done / in_progress / blocked
• Update current_executor.ctx_usage and current_executor.compactions
• Append any new known_failures or key_decisions

Step 4 — Append Review Record

Append one line to review_log.jsonl:

{"ts": "{ISO timestamp}", "turn": {n}, "review_type": "lightweight",
 "ctx_usage": 0.0, "compactions": 0, "issues_found": 0,
 "issue_descriptions": [], "action": "continue|warn|handoff"}

Step 5 — Decide Action

• continue → ctx and quality are acceptable, send next prompt to executor
• warn → approaching threshold, inform executor to wrap up current subtask cleanly
• handoff → threshold exceeded, initiate handoff (see below)

Handoff Protocol

Trigger handoff when the executor profile's thresholds are exceeded.

Generate Handoff Prompt

<handoff>
## Task Background
{original_request from task.json}

## Completed Work
{list each done plan item with one-line summary}

## In Progress
{current plan item and its current state}

## Current Focus
{exact next step — be as specific as possible}

## Architecture Decisions (Do Not Revisit)
{key_decisions from progress.json}

## Known Failures (Do Not Repeat)
{known_failures from progress.json}

## Open Issues
{any unresolved blockers}

## Mandatory Execution Rules
You MUST read and rigidly follow the rules in `skills/executor-report-format/SKILL.md`. Every response you provide must end with the `<!-- supervisor:status -->` block as specified in that skill.

</handoff>

Continue from "Current Focus". Do not re-analyse completed work.

After Generating Handoff

1. Append to handoffs.jsonl:

   {"ts": "...", "from_session": "...", "trigger": "...", "handoff_tokens": N}
   

2. Start new executor session with the handoff prompt
3. Append new session to sessions.jsonl
4. Update progress.json with new session info

Supervisor Handoff (Switching Supervisor Instance)

If you need to hand off supervision to another LLM instance:

1. Write the latest state to progress.json (do not leave stale data)
2. The new Supervisor should be instructed:

   "Read ~/.supervisor/tasks/{task_id}/ and skills/supervisor/SKILL.md, then resume supervision."

3. The new Supervisor runs the Startup Sequence above

What You Must Not Do

• Do not modify project source files directly
• Do not run executor commands (compilation, tests) yourself
• Do not skip writing review_log.jsonl — it is required for continuity
• Do not make architectural decisions without recording them in progress.json