# Supervisor
Supervisor is a Codex skill for running technical plans, SDD work, implementation, and review through visible role threads.
It stores runtime state outside target repositories, under `~/.supervisor` by default.
## What It Does
- Creates one visible Coder thread for each request.
- Creates one visible Reviewer thread by default.
- Supports `review_required=false` for Coder-only workflows.
- Supports configurable human approval gates: `per_step`, `final_only`, `on_failure_only`, and `none`.
- Supports active completion notification or polling.
- Keeps reusable role memory under `~/.supervisor/memory/`.
- Stores request state under `~/.supervisor/projects/<project-key>/<request-id>/`.
## Install
Copy this folder into a skills directory supported by your agent environment, for example:
```bash
$CODEX_HOME/skills/supervisor
```
When `CODEX_HOME` is not set, Codex commonly uses `~/.codex/skills/supervisor`. Other agents may use a different skill directory; install the folder wherever that agent loads skills or rules.
Then invoke the skill as:
```text
$supervisor
```
Other agents can use the same files by adapting `SKILL.md` into that agent's rule or skill format. Point all tools to the same runtime workspace if you want shared state and memory.
## Requirements
- Python 3.10+.
- A Codex or compatible agent environment that can read skill folders.
- Codex thread tools for visible Coder/Reviewer threads.
## Basic Usage
Start a supervised request by providing a target project and requirement document:
```text
Use $supervisor for this request.
project_path: /path/to/project
requirement document: /path/to/requirement.md
```
The supervisor first shows a startup confirmation view:
```text
supervisor_workspace: "~/.supervisor"
project_path: "/path/to/project"
project_key: "project"
project_dir: "~/.supervisor/projects/project"
request_title: "feature request"
human_gate_policy: "per_step" (Allowed: per_step, final_only, on_failure_only, none)
review_required: true
review_max_passes: 2
agent_completion_mode: "notify" (Allowed: notify, poll)
```
To skip the reviewer flow, set:
```text
review_required: false
```
## Runtime Files
Generated request files belong in the configured Supervisor workspace, not in this skill folder and not in the target repository:
```text
~/.supervisor/
โโโ config.json
โโโ registry.json
โโโ memory/
โ โโโ coder-memory.md
โ โโโ reviewer-memory.md
โโโ projects/
โโโ <project-key>/<request-id>/
โโโ config.json
โโโ supervisor-state.json
โโโ document-index.json
โโโ sdd.md
โโโ summary.md
```
## Thread Tool Requirement
The visible-thread workflow expects Codex thread tools such as `create_thread`, `send_message_to_thread`, and `read_thread`.
If thread tools are unavailable, the skill can fall back to keeping role transcripts in the supervisor thread, but visible independent histories will not be created.
## Scripts
Useful script entry points:
```bash
python3 scripts/init_request.py --help
python3 scripts/render_prompt.py --help
python3 scripts/update_status.py --help
python3 tests/smoke_test.py
```
## License
MIT. See `LICENSE`.