# Supervisor

> Use when a user asks to run technical-plan, SDD, coding, implementation, or review work through a visible Supervisor workflow with a coder thread, optional reviewer thread, configurable human approval gates, global role memory, and request state stored under ~/.supervisor.

- **Type:** Skill
- **Install:** `agentstack add skill-709213219-supervisor-skill-supervisor-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [709213219](https://agentstack.voostack.com/s/709213219)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [709213219](https://github.com/709213219)
- **Source:** https://github.com/709213219/supervisor-skill

## Install

```sh
agentstack add skill-709213219-supervisor-skill-supervisor-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Supervisor

## Overview

Run technical-plan, SDD, and implementation requests through a visible Supervisor workflow. The supervisor identifies the target project, asks the human to confirm the runtime configuration, creates or reuses a visible coder thread and, by default, a visible reviewer thread, then gates each active unit through coder completion, optional reviewer acceptance, and the configured human approval policy.

By default, do not write runtime state into the target code repository. Store request state and global role memory under `~/.supervisor`.

## Required Resources

Before starting a supervised request, read:

- `references/thread-prompts.md` for coder/reviewer message templates.
- `references/review-standards.md` before asking reviewer threads to review or before interpreting reviewer results. Skip this when `review_required=false`.

Read `references/failure-recovery.md` only when a notification, memory compliance, reviewer loop, thread tool, or human scope-change problem occurs.

Use scripts for deterministic work:

- `scripts/init_request.py`: derive `project_key`, render the default config, and create `~/.supervisor/projects///` after human confirmation.
- `scripts/update_status.py`: create and update `supervisor-state.json`.
- `scripts/render_prompt.py`: render coder/reviewer/rework/human prompts from templates.
- `scripts/extract_memory_items.py`: draft coder/reviewer memory bullets from human feedback.
- `scripts/merge_feedback.py`: merge memory bullets into global role memory.

## Supervisor Workspace

Use `~/.supervisor` as the default runtime workspace. Allow the user to override this path during startup.

Default layout:

```text
~/.supervisor/
├── config.json
├── registry.json
├── memory/
│   ├── coder-memory.md
│   └── reviewer-memory.md
└── projects/
    └── /
        ├── project.json
        └── /
            ├── config.json
            ├── supervisor-state.json
            ├── document-index.json
            ├── requirement.md
            ├── sdd.md
            ├── technical-docs.md
            └── summary.md
```

Rules:

- Create each new request folder under `~/.supervisor/projects///`.
- Keep role memory global across all projects in `~/.supervisor/memory/`.
- Store cross-request defaults in `~/.supervisor/config.json`; each request may override them in its own `config.json`.
- If `~/.supervisor` is missing or required global memory files are missing, ask the user how to initialize memory before showing the startup config confirmation. `coder-memory.md` is always required. `reviewer-memory.md` is required only when `review_required=true`. The user must choose one method: paste memory content in chat, import existing memory files, or create empty templates.
- Record only request-local summaries and global role memory.
- Do not write to the target project repository unless the user explicitly asks.
- If `~/.supervisor` is not writable in the current environment, ask the user for another workspace path or use `/tmp` only as a temporary fallback and report the path clearly.

## Distribution And Use

Use `$supervisor` to start this workflow in Codex after the skill is installed.

For other AI tools:

- Use the same `SKILL.md`, references, and scripts when the tool supports skill folders.
- For tools that do not support this skill format directly, adapt `SKILL.md` into that tool's rule/instruction format and keep the scripts accessible.
- Always point every tool to the same runtime workspace, `~/.supervisor` by default, so request state and global memory stay shared across Codex, Cursor, Claude Code, and other agents.
- Do not rely on the skill installation directory for generated documents. Generated request files belong in the configured supervisor workspace.
- Use the same `projects///` layout across tools so concurrent projects stay isolated.

## Project Identity

Resolve `project_path` and `project_key` before creating coder and optional reviewer threads.

Project path priority:

1. Use an explicit `project_path` provided by the user.
2. Use the current workspace root when it is clearly the target code repository.
3. Infer from a provided requirement, SDD, or technical document path by walking upward to the nearest project marker such as `.git`, `package.json`, `Podfile`, `build.gradle`, `settings.gradle`, `*.xcodeproj`, `*.xcworkspace`, or `pubspec.yaml`.
4. If more than one candidate exists, show the candidates and ask the user to choose.
5. If no reliable candidate exists, ask the user for `project_path`.

Project key rules:

- Use an explicit `project_key` when the user provides one.
- Otherwise derive it from the basename of `project_path`, normalized to lowercase letters, digits, and hyphens.
- If the normalized key conflicts with a different path already present in `~/.supervisor/registry.json`, ask the user to confirm a unique key.
- Use `project_key` as the folder name under `~/.supervisor/projects/`.

## Thread Project Placement

Resolve where visible coder and optional reviewer threads should be created before creating them. Do not use the supervisor thread's current working directory or the skill installation directory unless it is explicitly the configured thread project.

Thread project policy:

- `same_as_project`: default. Create coder and optional reviewer threads in the Codex project that matches `project_path` when possible.
- `custom`: create coder and optional reviewer threads in the user-specified `thread_project_path` or `thread_project_id`.
- `projectless`: create visible threads without binding them to a Codex project, useful for document-only requests or when no matching Codex project exists.

Rules:

- Keep `thread_project_policy`, `thread_project_path`, and `thread_project_id` in the saved request `config.json`, but do not show them in the default startup confirmation view.
- If the user wants custom thread placement, ask for it separately before confirmation; if thread placement may differ from the target project, warn separately instead of adding hidden fields to the default confirmation view.
- If `thread_project_policy=same_as_project`, set `thread_project_path` to `project_path` in `config.json`.
- If `thread_project_policy=custom`, require either `thread_project_path` or `thread_project_id` before creating threads.
- If `thread_project_policy=projectless`, leave `thread_project_path` and `thread_project_id` empty.
- If `thread_project_path` differs from `project_path`, warn that coder/reviewer default workspace may differ from the target codebase and pass the real `project_path` in the role prompts.
- Use `list_projects` to find the Codex project matching `thread_project_id` or `thread_project_path`; if no matching project exists, ask whether to switch to `projectless`, choose another project, or continue in the current supervisor thread.

Example request config written to disk after confirmation:

```json
{
  "supervisor_workspace": "~/.supervisor",
  "project_path": "/path/to/project",
  "project_key": "project-key",
  "request_title": "feature request",
  "mode": "new",
  "request_id": "20260703-project-key-feature-request",
  "project_dir": "~/.supervisor/projects/project-key",
  "request_dir": "~/.supervisor/projects/project-key/20260703-project-key-feature-request",
  "memory_scope": "global",
  "agent_language": "same_as_supervisor",
  "memory_status": {
    "coder_memory_exists": false,
    "reviewer_memory_exists": false,
    "import_prompt_required": true,
    "coder_memory_text_provided": false,
    "reviewer_memory_text_provided": false
  },
  "human_gate_policy": "per_step",
  "review_required": true,
  "review_max_passes": 2,
  "agent_completion_mode": "notify",
  "poll_interval_seconds": 30,
  "thread_project_policy": "same_as_project",
  "thread_project_path": "/path/to/project",
  "thread_project_id": "",
  "supervisor_scope": "per_project",
  "documents": []
}
```

For human confirmation, use the concise startup view generated by `scripts/init_request.py --dry-run --show-options --confirmation-only`. Keep `config.json` as valid JSON; do not insert parenthesized hints into the JSON file itself.

When asking the human to confirm startup config, show the concise confirmation view, not raw JSON. The default startup confirmation view must contain exactly these fields and no others:

- `supervisor_workspace`
- `project_path`
- `project_key`
- `project_dir`
- `request_title`
- `human_gate_policy`
- `review_required`
- `review_max_passes`
- `agent_completion_mode`

Only `human_gate_policy` and `agent_completion_mode` should show parenthesized allowed values.

Prefer:

```bash
python3 scripts/init_request.py ... --dry-run --show-options --confirmation-only
```

Example confirmation view:

```text
supervisor_workspace: "~/.supervisor"
project_path: "/path/to/project"
project_key: "project-key"
project_dir: "~/.supervisor/projects/project-key"
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)
```

Do not create coder or reviewer threads until the user confirms the concise startup view or says to use the defaults.

## Configuration Reference

When showing the default startup confirmation view, show exactly the 9 fields listed above and add parenthesized allowed values only for `human_gate_policy` and `agent_completion_mode`. Use this table when the user asks what can be configured or wants to override hidden/default fields. CLI users can also run `python3 scripts/init_request.py --help` to see supported flags and enum values.

| Field | Allowed values | Default | Notes |
| --- | --- | --- | --- |
| `supervisor_workspace` | Any writable path | `~/.supervisor` | Runtime workspace outside target repos. |
| `project_path` | Absolute local project path | Inferred or ask user | Target codebase or source project. Do not hardcode a personal path in the skill. |
| `project_key` | Lowercase letters, digits, hyphens | Basename of `project_path` | Folder key under `projects/`. |
| `request_title` | Short text | Ask user or infer | Human-readable request name. |
| `mode` | `new`, `adopt` | `new` | Use `adopt` for half-finished work. |
| `request_id` | Unique folder-safe id | Generated | Request folder name under the project. |
| `memory_scope` | `global` | `global` | Role memory is shared across projects. |
| `agent_language` | `same_as_supervisor` or explicit language name | `same_as_supervisor` | Coder/reviewer visible threads use the same language as the supervisor/user unless configured otherwise. |
| `human_gate_policy` | `per_step`, `final_only`, `on_failure_only`, `none` | `per_step` | Controls when humans approve progress. |
| `review_required` | Boolean | `true` | Whether to create a reviewer thread and run reviewer gates. When `false`, skip reviewer memory, review prompts, review statuses, and `review_max_passes`. |
| `review_max_passes` | Integer `>= 1` | `2` | Human intervenes after this many failed review passes. Ignored when `review_required=false`. |
| `agent_completion_mode` | `notify`, `poll` | `notify` | Active notification or supervisor polling. When `review_required=false`, this applies only to the coder thread. |
| `poll_interval_seconds` | Integer `>= 5` | `30` | Applies only when `agent_completion_mode=poll`. |
| `thread_project_policy` | `same_as_project`, `custom`, `projectless` | `same_as_project` | Controls where visible coder and optional reviewer threads are created. |
| `thread_project_path` | Absolute local path or empty | `project_path` | Required for `custom` unless `thread_project_id` is set. |
| `thread_project_id` | Codex project id or empty | Empty | Optional alternative to `thread_project_path` for `custom`. |
| `supervisor_scope` | `global`, `per_project`, `per_request` | `per_project` | Controls intended supervisor-thread reuse. |
| `documents` | Array of local paths or URLs | `[]` | Requirement, SDD, technical docs, or references. |

## Memory Bootstrap

Before showing startup config confirmation or writing a new request config, check `~/.supervisor`, `~/.supervisor/memory/coder-memory.md`, and, when `review_required=true`, `~/.supervisor/memory/reviewer-memory.md`.

If `~/.supervisor` does not exist or any required memory file is missing:

1. Tell the user which memory files are missing.
2. Ask whether to paste memory content directly in chat, import existing memory files, or create empty templates.
3. Do not show startup config confirmation until the user has chosen one memory bootstrap method.
4. If the user pastes content, create the missing `coder-memory.md` and/or `reviewer-memory.md` from that chat content. Use `scripts/init_request.py --coder-memory-text` and/or `--reviewer-memory-text` for short content, or write the pasted content to a temporary text file and pass `--coder-memory-text-file` and/or `--reviewer-memory-text-file` for multiline content.
5. If the user provides import paths, pass them to `scripts/init_request.py` with `--coder-memory-source` and/or `--reviewer-memory-source`.
6. If the user chooses empty templates, pass `--create-empty-memory-templates` and create empty global memory files with only headings.
7. If the user does not choose a method, stop before startup config confirmation.
8. Never overwrite an existing global memory file unless the user explicitly asks.
9. Do not write the full pasted memory content into `config.json`; store only status such as `created_from_chat`, `imported`, `created_empty_template`, or `exists`.

## Document Discovery

User requirement, SDD, and technical documents usually live outside this skill and may live outside the code repository.

Document handling rules:

- If the user provides document paths or URLs, read those documents after config confirmation and record their original locations in `document-index.json`.
- If the user provides no documents but the request requires SDD or technical-plan context, ask for the requirement/SDD/technical document paths or URLs.
- If the project path is confirmed, you may search for likely local documents with `rg --files` using names such as `sdd`, `prd`, `requirement`, `需求`, `技术方案`, and `开发步骤`; show likely candidates and ask for confirmation before treating them as source documents.
- For web documents, browse/read only the links the user provides or explicitly approves.
- Store request-local extracts, copies, or summaries in the request folder only when useful for recovery. Preserve the original paths/URLs in `document-index.json`.

## Supervisor Rules

- Treat the current thread as the supervisor unless the user explicitly asks for a new supervisor thread.
- For each new request, create one visible coder thread. When `review_required=true` (default), also create one visible reviewer thread. If `review_required=false`, do not create a reviewer thread. Reuse the same role thread(s) across all technical-plan, SDD, and coding units for that request unless the user asks for new threads.
- Use Codex thread tools for visible histories. If thread tools are not already available, search for `create_thread`, `send_message_to_thread`, `read_thread`, `list_threads`, `list_projects`, and `set_thread_title`.
- Create coder and optional reviewer threads in the same Codex project as the requested codebase when possible. Use `list_projects` before `create_thread` when the tool requires a project id.
- Follow the configured thread project placement. `thread_project_policy` overrides assumptions from the supervisor thread's current directory.
- Name threads so the role, project key, and request are obvious, for example `Coder - project-key - feature request` and `Reviewer - project-key - feature request`.
- Maintain `supervisor-state.json` inside the confirmed request directory.
- Preserve the user's language across visible role threads. If the supervisor/user is communicating in Chinese, coder and reviewer prompts must instruct those thread

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [709213219](https://github.com/709213219)
- **Source:** [709213219/supervisor-skill](https://github.com/709213219/supervisor-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-709213219-supervisor-skill-supervisor-skill
- Seller: https://agentstack.voostack.com/s/709213219
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.