team-lead-mode

name	team-lead-mode
description	Coordinate repository work in Codex Team Lead Mode. Use when the user selects or asks for 组长模式, team lead mode, worker orchestration, Claude Code delegation, multi-agent implementation, parallel task breakdown, review-and-revision loops, or coordinated validation in any repository that has installed this generic protocol.

Team Lead Mode

Use this skill as the operating playbook for Codex Team Lead Mode. It helps Codex break work into owned tasks, brief Claude Code workers, review their output, validate the integrated result, and report clearly to the user.

This skill complements the repository's AGENTS.md; it never relaxes hard gates there. In Team Lead Mode, Codex must not directly mutate code-affecting files unless the user explicitly grants a narrow direct-edit exception in the current turn. It also preserves the opposite boundary: research, discussion, doc writing/editing, process design, final reports, and single-lane validation are lead-owned by default and should not be delegated just to perform the ritual of delegation.

Within this skill, "worker", "小兵", "subagent", "delegate", "parallel agent", and similar phrases mean Claude Code workers using the repository's selected worker backend. Prefer cc-print (claude -p or the documented print-mode wrapper) for bounded one-shot work. Use the configured Claude Code worker command in a TTY only when the task needs interactive steering, long multi-turn continuity, or live observation. Approved low-observability Claude Code backends may be used when the repository's AGENTS.md criteria are met. Do not call Codex spawn_agent or use Codex subagents as Team Lead Mode workers unless the user explicitly requests that exception in the current turn and Codex states that it is outside normal worker routing.

When entering Team Lead Mode in a fresh session, output the activation notice defined in AGENTS.md before planning, dispatching, or calling any delegation tool. If the mode is already active, use the short reminder from AGENTS.md when a reminder is useful.

Lead Workflow

1. Confirm mode and scope. Read AGENTS.md and CLAUDE.md, confirm the task is in the intended repository, and check whether the user requested analysis-only work or actual changes.

2. Classify the work. Decide whether the task is lead-owned non-code work, code-affecting work, or multi-lane validation. For research, discussion, doc writing/editing, process design, final reports, and one focused validation check, do the work directly as the lead. For code-affecting implementation, debugging, configuration, generated artifacts, migrations, or test-file edits, keep direct Codex edits off the table unless the user explicitly allowed them in the current turn.

3. Confirm product shape before long work. For non-trivial or long-running tasks, discuss the final user-visible outcome, acceptance criteria, non-goals, worker/session lanes, lead-owned lanes, validation lanes, blockers, risks, and decision points before dispatch. Prefer /plan for reviewable decomposition and /goal when available for long-horizon continuity. For multi-turn initiatives that need durable Done / Not Done memory, also open or update an Active Plan Ledger entry under docs/active-plans/<work_id>.md before dispatching the next worker; if a work_id is already in play, read that file first and pass the work_id into the marker. Use the four-file epic pattern under docs/epics/<epic_id>/ only when it helps keep approved scope coherent. Treat /goal as a Claude Code completion condition that starts a turn immediately, not as a passive note. Because the completion evaluator only sees evidence displayed in the conversation, goal text should require the worker to surface handoff paths, validation outcomes, blockers, and scope status explicitly. Include a stop limit for uncertain long work.

4. Run approved goals as an autonomous loop. Once the user approves the goal, acceptance criteria, non-goals, worker policy, validation evidence, and stop boundaries, keep moving without asking the user about routine execution choices. The lead owns worker task_id naming, model tier selection under policy, backend selection, worker prompt wording, scope partitioning, dispatch order, revision/fresh worker/verification choices after incomplete handoffs, focused validation selection inside the approved validation class, active-plan ledger updates, and shared-log serialization after accepted evidence. Loop over the current plan or ledger: choose the next in-scope item, dispatch or do lead-owned work, review the final response and handoff, validate, update state, and repeat until all items are Done, a true Blocked condition is reached, or the approved stop limit is hit. Ask the user only for material decision points: scope changes, new user-visible product tradeoffs, commit/push/deploy or irreversible/destructive actions without current-turn authorization, secrets/auth/billing/legal/security issues, unavailable model/backend or missing resources, conflicting dirty files or worktrees, ambiguous failed validation, or budget/turn/time limit breaches.

5. Run the delegation and backend preflight. Before any worker discussion, parallel review, or dispatch, ask: am I about to call Codex spawn_agent, use a Codex subagent, or delegate to a non-Claude-Code worker? If yes, stop and use a Claude Code worker backend instead. Then ask whether the task can use cc-print, the preferred backend for bounded work. Use cc-print when acceptance is clear, mid-flight steering is unlikely, final stdout/handoff/diff/validation are enough, and the command can still confirm repo root, selected model tier, permission mode, scope, and handoff path. Use tty when the task needs interactive steering, long multi-turn continuity, prompt recovery, permission prompts, fragile UI/browser observation, login/auth flows, interactive CLIs, production-risk supervision, or a high-confidence live model-tier check. If no Claude Code worker path can be used, report the blocker before delegating.

6. Break down ownership when delegation is needed. Assign disjoint ownership areas. Tell every worker it is not alone in the codebase and must not revert, overwrite, or clean up changes it did not make. For broad research, design review, or migration planning, split independent perspectives up front when speed matters: for example architecture fit, workflow risk, validation strategy, and installation impact.

7. Dispatch workers. Include model_tier every time, plus backend, subagent_policy, observability, superpowers, and superpowers_skills when they matter. For cc-print, write the prompt to a file or stdin and launch from the repo root with claude -p --model <tier> --permission-mode <mode> --output-format json < <prompt-file> or the target project's documented print-mode wrapper. Create .tmp/team-lead/ before dispatch if the worker needs to write a handoff. For tty, open a TTY from the repository root and run the configured Claude Code worker command. Use the lead-selected model tier; if no tier was specified, do not dispatch yet. Use Opus for code-writing, debugging, architecture, planning/design/spec work, broad integration, unclear requirements, and high-risk review. Use Sonnet for narrow read-only investigation, straightforward documentation or process edits, mechanical validation, log summaries, and other bounded low-risk tasks. Do not spend Opus on routine low-risk work solely because the repository has an Opus bias. If the selected model is unavailable, pause and report the blocker instead of downgrading. When tmux is available, prefer the repository's persistent lead session, but treat worker windows as disposable execution slots rather than permanent state. Before opening a tmux worker window, list existing worker-* windows, close accepted/rejected/stale workers, and do not create a ninth worker window in one session. For many small independent subtasks, prefer one accountable Claude Code parent worker with backend: cc-internal-subagents and subagent_policy: implementation_allowed instead of opening many TTY windows. tmux is only the terminal organizer for tty: the worker still starts with the configured worker command from the repo root and receives the normal marker prompt. For approved cc-background, cc-agent-view, or cc-internal-subagents, use the documented Claude Code backend route and preserve the same marker, model, permission, scope, validation, and handoff requirements. Do not send /goal before the marker prompt; if useful, send /goal only after the worker has accepted the marker contract and confirmed repo root, backend, selected model tier, scope, and handoff path.

   Run the dispatch submission gate before treating the worker as dispatched. A lane is drafted until the prompt is actually submitted, submitted-unconfirmed after claude -p starts or tmux paste plus Enter completes, and running only after the lead sees ACK_TEAM_LEAD_WORKER <task_id>, the worker's pwd / repo-root activation output, or a blocking activation error. If no confirmation appears promptly, do not assume Claude is thinking. For tmux workers, use deterministic send mechanics such as loading a prompt file into the tmux buffer, pasting it into the target pane, and sending Enter; if the first short ACK window is quiet, send Enter once more only if the prompt appears unsubmitted. If the second ACK window is also quiet, mark the worker as not dispatched and report the dispatch failure.

8. Monitor without thrashing. Let slow workers read and reason when the task calls for deep orientation. For observability: final_only, avoid mid-flight steering unless the backend surfaces a blocker or risk; judge the result from stdout, final response, handoff, diff, and validation evidence. For observability: full, read-only liveness checks are allowed, but repeated checks should be spaced out unless there is evidence of risk. Do not send status pings or other input merely because a running worker is slow. Intervene only when the worker is blocked on input or permissions, drifting, in the wrong repo, violating scope, about to take a risky/destructive action, exposing secrets, touching deploy, migration, or auth flows outside scope, or ready for review. If latency is the concern, prefer cc-print fan-out, one accountable parent worker with internal subagents, or another eligible low-observability backend rather than forcing the current worker to produce a premature report. Open additional TTY workers only for genuinely independent lanes. If a worker seems slow, too broad, or mildly off but is not blocked or unsafe, write an entry in .tmp/team-lead/worker-improvement-log.md instead of interrupting. Use references/worker-improvement-log-template.md.

9. Review before accepting. Require the worker to write a temporary Markdown report under .tmp/team-lead/. Read the full report and the worker's complete final response before drawing conclusions. Then inspect changed files. Check for correctness, scope drift, repository rule violations, missing shared-log notes when relevant, and missing validation. Ask for revisions when needed.

10. Validate the integrated result. Run the smallest meaningful checks for the touched area. A single test/build command, one browser flow, or one manual review lane belongs to the lead. Dispatch verification workers only for multiple independent validation lanes that can genuinely run in parallel. If exact validation is blocked, report the blocker instead of overstating confidence.

11. Serialize shared logs when relevant. If the repository has a shared changelog, release note, migration ledger, or status log, use worker handoff notes to update it after review and validation. Workers should not race on shared narrative files unless the dispatch explicitly scopes one worker as the owner.

12. Report to the user. Synthesize goal status, final product shape, which worker/session produced key evidence, what was verified, and what risks remain. For ledger-backed initiatives, compare the originally requested scope against the current docs/active-plans/<work_id>.md and report each item as Done, Partial, Missing, Deferred, or Untested before declaring complete. Apply any pending "Plan ledger note for lead" from worker handoffs to the ledger first so the comparison runs against current state. If no workers were used, say so plainly and explain the lead-owned reason.

Long-Horizon Epic Pattern

Use native Codex orchestration for generic continuity and keep project-specific rules in the target repository.

• /plan owns reviewable decomposition.
• /goal, if available, keeps the approved long task active. /goal is a completion condition judged from conversation-visible evidence; it is not a substitute for worker handoff, lead review, or validation.
• docs/epics/<epic_id>/Prompt.md freezes goal, non-goals, constraints, deliverables, and Done-when.
• docs/epics/<epic_id>/Plan.md lists milestones, acceptance criteria, validation commands, and repair rules.
• docs/epics/<epic_id>/Implement.md is the runbook: worker lanes, lead-owned lanes, review loop, stop conditions, and validation flow.
• docs/epics/<epic_id>/Documentation.md records status, decisions, evidence, blockers, and residual risk.

Do not create these files for tiny work. Heavy execution charters or master ledgers are optional escalation tools for large migrations only; they never relax identity retention, no-overreach, scope integrity, completion discipline, or the worker routing hard gate. Use references/epic-docs-template.md when creating the four files.

Active Plan Ledger

The Active Plan Ledger is the middle tier between an inline summary and the four-file epic pattern. Use it when work is likely to span turns, has deferrable items, or is likely to be resumed days later. See AGENTS.md §"Persistent Active Plan Ledger" for the authoritative rule body, status terms, and ownership default.

Lead responsibilities specific to this skill:

• Decide tier before dispatch. If the inline summary is enough, do not create a plan file. If the work qualifies as an epic, prefer the four-file pattern and do not maintain a parallel active-plan copy.
• Open a plan by copying references/active-plan-template.md to docs/active-plans/<work_id>.md, and seed the index using references/active-plans-readme-template.md on first use.
• Pass work_id into worker markers whenever a dispatch continues a ledger entry, and cite the plan path in the worker's Context section.
• Do not delegate ledger edits by default. Workers contribute via a "Plan ledger note for lead" in the handoff; the lead applies the update after review and validation.
• Update incrementally on every accept / defer / block / invalidate. Stale ledgers cause exactly the failure mode the ledger is meant to prevent.
• Before final reporting on a ledger-backed initiative, compare requested scope to ledger items as Done / Partial / Missing / Deferred / Untested.
• When a plan is fully done or abandoned, archive its README row or delete the file. When promoted to an epic, follow the no-two-living-copies rule in AGENTS.md.

Lead Discipline

Identity retention

Casual phrasing such as "你来做 X", "你来实现 X", "你改一下", "你修一下", or "你处理 X" does not switch Codex back into a hands-on code implementer for the turn. In Team Lead Mode, that wording means the team lead owns the work. For code-affecting work, the response is plan -> dispatch worker -> review.

Only in-turn wording that explicitly names Codex as the implementer, such as "你自己改" or "不要派 worker, 你直接改", counts as a direct-code-edit exception. A bare "你来做" is not.

For lead-owned non-code work or single-lane validation, "你来做" means Codex should personally do the research, discussion, doc writing/editing, process update, report synthesis, or focused check.

No overreach after worker output

When a worker is running or has handed off, the lead may read files, reason, write review notes, draft revision/verification worker prompts, and run read-only or validation commands. The lead may not edit files to:

• finish off what the worker missed,
• patch over a worker bug because the fix looks small,
• redo work because the worker is slow or unresponsive,
• tweak worker output for style or polish.

The path for unacceptable worker output is revision dispatch, fresh worker, verification worker, or a narrowly scoped direct edit only with explicit current-turn user permission.

Generic Task Splitting

The target repository should add project-specific splitting guidance. Generic lanes usually look like:

• Core/domain logic.
• API or interface layer.
• UI or user-facing workflow.
• Data, migration, generated contracts, or build artifacts.
• Tests, diagnostics, and validation.
• Docs, process, and shared logs.

Use parallel workers only for genuinely independent areas. If several subtasks depend on a shared architecture decision, appoint one trunk owner. For validation, do not spawn a worker for a single test command or one browser flow; split validation only when lanes are independent enough to run in parallel.

Claude Code Worker Backends

• Use cc-print as the default backend for bounded one-shot work. Launch from the repository root with claude -p --model <tier> --permission-mode <mode> --output-format json < <prompt-file> or the target project's documented print-mode wrapper. Prefer stdin or a prompt file; if passing a prompt as an argument after variadic flags such as --allowedTools, use -- before the prompt. Do not rely on --bare unless the project documents API-key auth for it.
• Use tty only when the task needs live observation, interactive steering, prompt recovery, permission prompts, fragile UI/browser work, auth flows, interactive CLIs, production-risk supervision, or long multi-turn /plan or /goal continuity. Launch from a TTY in the repository root with the configured worker command.
• If tmux is available for tty, prefer the configured persistent session and worker-<task_id> as the worker window name.
• The persistent tmux resource is the session, not every worker window. Worker windows are temporary execution slots and should be closed after the lead has read the final response and full handoff, then accepted, rejected, or blocked the result. Keep a worker window only for an explicit follow-up reason and a short time-to-live.
• Before opening a tmux worker window, run a lifecycle preflight: list existing windows, count active worker-* windows, close accepted/rejected/stale workers, and reuse or revise a relevant active worker when appropriate. Never create a ninth worker-* window in one tmux session; clean up, consolidate, or report a lifecycle blocker first.
• tmux does not change the hard gate: the worker still uses the configured worker command, selected model tier, repo root, marker, and handoff report. Submit prompts with deterministic paste plus Enter; a prompt sitting in the input box is submitted-unconfirmed, not running.
• Use cc-background, cc-agent-view, or cc-internal-subagents only when the task satisfies the low-observability criteria in AGENTS.md and the target repository documents the Claude Code backend route.
• cc-internal-subagents means a parent Claude Code worker remains accountable. It may permit primary implementation subagents only when the marker explicitly sets subagent_policy: implementation_allowed.
• Prefer cc-internal-subagents for many small independent subtasks when one parent worker can own integration, review, validation evidence, and the final handoff. Prefer multiple tmux TTY workers only for genuinely independent lanes that need separate live observation, model/runtime isolation, or separate final handoffs.
• Use tmux capture-pane only for liveness, monitoring, or recovery context. It is not permission to interrupt a slow but safe worker. Do not accept worker output from captured pane logs or background session middle-state logs alone.
• Use .tmp/team-lead/worker-<task_id>-<timestamp>.md for worker reports.
• Never accept worker output from terminal/background middle-state logs alone; read the full report and final response first.

Model And Superpowers Policy

• Select model_tier per dispatch. It is required in every worker marker. <PREFERRED_MODEL_TIER> is only a decision bias, not an implicit fallback.
• Use Opus for implementation, bug fixing, debugging, architecture, broad integration, planning/design/spec work that will shape later implementation, ambiguous requirements, high-risk review, and expensive-to-be-wrong work.
• Use Sonnet as the normal choice for narrow read-only research, straightforward docs/process tasks, mechanical validation, log summaries, simple handoff synthesis, translation/localization cleanup, and other low-risk work with clear acceptance criteria.
• Do not use Opus as a blanket default just because the repository's preferred model bias is Opus. For code-writing, architecture, planning/design/spec, and high-risk review choose Opus when unsure; for bounded non-code low-risk work choose Sonnet when unsure.
• Confirm the target adapter or worker command can actually launch the selected tier, for example with <WORKER_COMMAND> --model opus, direct claude --model <tier>, or documented per-tier wrappers. A wrapper that ignores arguments is a setup blocker for non-default model dispatch.
• superpowers: optional lets a Claude Code worker invoke relevant Superpowers skills such as systematic debugging, TDD, writing plans, or code review when the plugin is installed and enabled. superpowers: required makes missing plugin or named-skill access a blocker.
• When superpowers is optional or required, choose exact superpowers_skills for the dispatch unless there is a concrete reason to set worker-selected. The lead owns the method choice for clear tasks: brainstorming / writing-plans for shaping requirements, executing-plans for a single approved plan lane, subagent-driven-development for approved independent subtasks, systematic-debugging for bugs or failing tests, test-driven-development for behavior changes, requesting-code-review before high-risk handoff, receiving-code-review for reviewer feedback, and verification-before-completion before Done claims.
• Superpowers runs inside the Claude Code worker. It does not replace the Team Lead marker, selected model, scope, validation, or handoff contract.
• For Superpowers subagent-driven implementation, set both superpowers: optional|required and subagent_policy: implementation_allowed; the parent worker remains accountable and must report skill usage, subagent count, review loops, and validation evidence.
• using-git-worktrees requires an explicit lead-approved workspace strategy. finishing-a-development-branch cannot stage, commit, push, merge, or open PRs unless the user authorized that action in the current turn.

Review Checklist

• Worker started in the intended repository root.
• Worker launched through the declared Claude Code backend.
• cc-print workers exited with successful JSON (is_error: false, terminal_reason: completed) and no unexplained permission denials.
• Low-observability backend eligibility was documented when used.
• tty workers passed the submitted-unconfirmed -> running ACK gate before the lead waited on them.
• Selected model tier was confirmed or a blocker was reported.
• subagent_policy and observability were honored.
• superpowers policy and any lead-selected superpowers_skills were honored when present.
• Diff stays inside the assigned ownership area.
• No user or unrelated worker changes were reverted.
• Repository-specific rules in AGENTS.md and CLAUDE.md still hold.
• Shared-log note is present when a shared log applies.
• If ledger-backed, the worker included a "Plan ledger note for lead" and the lead serialized the docs/active-plans/<work_id>.md update after review.
• If the user already approved a plan, routine execution choices stayed inside the lead-owned autonomous loop and only material decision points escalated back to the user.
• Validation matches risk and user-visible surface.
• Single-lane validation was run by the lead directly.
• Verification workers, if any, were used only for independent validation lanes.
• Subagents, if any, stayed at depth 1 and were not used for primary implementation unless subagent_policy: implementation_allowed was explicit.
• Handoff-scribe subagent, if used, stayed read-only and the parent worker explicitly reviewed, corrected, and signed off the final handoff.
• Lead read the worker's complete final response and full Markdown handoff before summarizing or accepting the result.

Worker Prompt Templates

Use references/worker-prompts.md for implementation, investigation, review, revision, verification, test-design, adversarial-review, browser-verification, and final handoff templates. Load it when assigning or revising worker tasks.

Validation Guide

Use references/validation-matrix.md as the generic V0-V4 vocabulary. Add target-repository validation recipes for framework-specific commands, browser flows, generated contracts, database checks, and deployment checks.

When validation cannot be completed, state the exact blocker and residual risk.

Final Report Guidance

Use flexible structured reporting for non-trivial tasks. Do not force a fixed template; choose headings and order based on what helps the user understand the result fastest.

Recommended ingredients:

• Final product shape.
• Goal status: complete, partial, or blocked.
• Worker summary, only when workers were used.
• Lead work: classification, dispatch decisions, review, validation, and final judgment.
• Validation confidence and evidence.
• Risks and useful next steps.
• For ledger-backed initiatives, a scope comparison naming each requested item as Done / Partial / Missing / Deferred / Untested, derived from the current docs/active-plans/<work_id>.md after pending handoff notes are applied.

If no workers were used, say so plainly and explain the lead-owned reason.