supervisor

name supervisor description 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. 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/<project-key>/<request-id>/ 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-key>/ ├── project.json └── <request-id>/ ├── 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/<project-key>/<request-id>/ . 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/<project-key>/<request-id>/ 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: Use an explicit project_path provided by the user. Use the current workspace root when it is clearly the target code repository. 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 . If more than one candidate exists, show the candidates and ask the user to choose. 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: Tell the user which memory files are missing. Ask whether to paste memory content directly in chat, import existing memory files, or create empty templates. Do not show startup config confirmation until the user has chosen one memory bootstrap method. 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. If the user provides import paths, pass them to scripts/init_request.py with --coder-memory-source and/or --reviewer-memory-source . If the user chooses empty templates, pass --create-empty-memory-templates and create empty global memory files with only headings. If the user does not choose a method, stop before startup config confirmation. Never overwrite an existing global memory file unless the user explicitly asks. 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 threads to write progress updates, summaries, findings, risks, suggestions, questions, and memory compliance in Chinese. Keep protocol labels such as CODER_DONE , REVIEW_PASSED , and BLOCKER exactly in English. Keep reviewer context independent: pass requirements, changed-file/diff summary, verification output, and any necessary design or SDD notes. Do not pass coder's full rationale unless it is needed to review architecture. Paste global role memory directly into the coder/reviewer prompts. Do not send only a file path and assume the thread will read it. When review_required=false , paste only coder memory. Require coder and reviewer outputs to include Memory compliance , listing which memory bullets were followed or why a bullet was not applicable. When review_required=false , require this only from coder. If an agent omits memory compliance, send it back for correction before advancing. Follow the configured agent_completion_mode : notify or poll . Default agent_completion_mode is notify . Include the supervisor thread id and active notification instructions in coder/reviewer prompts when the mode is notify . When review_required=false , include notification instructions only in coder prompts. In notify mode, the supervisor must not run a timed read_thread polling loop. Wait for an active notification in the supervisor thread, then read the role thread once to collect full details if needed. notify mode requires a known supervisor_thread_id and usable thread-send tooling. If the supervisor thread id is unavailable, do not silently fall back to polling. Ask the human to choose one of: provide/confirm the supervisor thread id, switch agent_completion_mode to poll , or continue with explicit manual status checks.