Supervisor

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:

~/.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:

{
  "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:

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

Example confirmation view:

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
• Source: 709213219/supervisor-skill
• License: MIT

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