{"id":"5680cbf2-7389-4d2e-ae33-4330652a2977","slug":"codex-team-lead-mode","kind":"skill","name":"codex-team-lead-mode","summary":"","owner":"Leehow","repoUrl":"https://github.com/Leehow/codex-team-lead-mode","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":3,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-05-14T08:48:27.000Z","addedAt":"2026-10-21T23:08:00.989Z","logoUrl":"https://avatars.githubusercontent.com/u/8022275?u=3fe759602636e777bdb3e174fd11d6422cb42710&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["writing"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-22T13:37:04.851Z","sample":false,"url":"https://conduits.dev/tools/codex-team-lead-mode","language":"","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Codex Team Lead Mode\n\nLanguages: English | [简体中文](README.zh-CN.md) |\n[日本語](README.ja.md) | [Русский](README.ru.md) |\n[Deutsch](README.de.md) | [Français](README.fr.md) |\n[Español](README.es.md)\n\nCodex Team Lead Mode is a reusable orchestration protocol for running Codex as\na lead engineer while delegating work through a pluggable worker contract.\nBounded work defaults to Codex native subagents and large loop work defaults to\na tmux-backed Codex automation factory; ZCode can be selected explicitly for\neither shape, while Claude remains an explicit legacy bridge.\n\nThe goal is simple: make the session mode explicit. Default Mode lets Codex\nwork directly. Team Lead Mode keeps the lead responsible for scope, planning,\nreview, validation, and user-facing synthesis while Codex workers do detailed\ncode-affecting edits through a strict scope, escalation, and handoff contract.\nFactory Mode makes the Codex-native production-line path explicit: the main\nCodex performs intake, dispatch, monitoring, review, validation, and final\nreporting while the approved factory runner executes the backlog loop. Factory Mode supports Codex by default and ZCode when explicitly specified; record the\nchoice as `factory_runner: codex | zcode`.\nZCode factory lines are runner-homogeneous. No Codex worker or Codex subagent may execute concrete backlog work inside a ZCode factory line.\n\nThis repository is intentionally project-neutral. It contains no product\narchitecture, ports, framework choices, backend/frontend paths, deploy steps,\nor business-specific validation rules. Those belong in the target repository's\nown project rules.\n\n## What This Extracts\n\nThe reusable core is:\n\n- A three-mode Codex session model: default mode, team-lead mode, and factory\n  production-line mode.\n- A persistent per-user mode preference, `~/.codex/session-mode.json`: the\n  first non-temporary explicit choice is saved and automatically reused in later\n  fresh sessions, without asking the user to choose again.\n- An optional Team Lead worker-runner preference in that same global file:\n  `worker_runner_preference: codex | zcode | claude` resolves an unspecified\n  Team Lead worker without changing the other dispatch dimensions.\n- A lower-precedence repository marker, `.codex/session-mode.json`, that can\n  auto-activate a selected mode on fresh sessions without auto-starting work.\n- A hard gate for code-affecting work: in team-lead mode, the lead delegates\n  implementation instead of quietly editing files directly.\n- A Factory Mode route for approved worker-run production-line work with intake,\n  factory ledger, WorkGraph, progress notes, heartbeat/status digest, stop\n  boundary, and escalation rules.\n- Factory runner selection for production-line goals: Codex is the default\n  runner, while ZCode is allowed only when the user or approved intake/charter\n  explicitly sets `factory_runner: zcode`.\n- ZCode production-line homogeneity: once `factory_runner: zcode` is selected,\n  implementation, revision, verification, subagent, and handoff-scribe lanes\n  must all be ZCode-run.\n- A worker routing rule: generic \"worker\", \"subagent\", \"parallel agent\", and\n  similar phrasing uses a four-dimensional runner/profile/model/execution\n  contract, with Codex as the `auto` default.\n- Independent `worker_runner`, `worker_profile`, `model_policy`, and\n  `execution_mode` fields so runtime, role, model, and transport are not\n  conflated.\n- A Codex-subagent-first path for bounded work. Small bounded work defaults to\n  Codex subagents.\n- A tmux-backed Codex automation factory path for large, enumerable,\n  loop-oriented work. Large loop work defaults to a tmux-backed Codex\n  automation factory.\n- Optional legacy Claude Code worker backends only when explicitly requested by\n  the user in the current turn.\n- An autonomous goal loop: after the user approves a plan, the lead keeps\n  deciding routine execution choices and looping until Done, truly Blocked, or\n  the stop limit instead of repeatedly asking the user.\n- Optional Superpowers integration inside Codex workers, including\n  lead-selected `superpowers_skills` for large approved plans, systematic\n  debugging, TDD, code review, and subagent execution.\n- A runner-neutral worker envelope with task, scope, acceptance, validation,\n  escalation, handoff, and commit policy.\n- A versioned `[TEAM_LEAD_WORKER_V1]` activation marker retained only for the\n  explicit legacy Claude bridge.\n- A worker-side partnership contract: workers may push back, but may not\n  silently expand scope.\n- A three-tier durable memory ladder: inline summaries for tiny work, a\n  Persistent Active Plan Ledger under `docs/active-plans/<work_id>.md` for\n  multi-turn initiatives, and full epic docs under\n  `docs/epics/<epic_id>/` for long-running scope.\n- Append-only escalation files under `.tmp/team-lead/`.\n- Full Markdown handoff reports before the lead accepts work.\n- Lead-owned review, focused validation, final reporting, and shared-log\n  serialization.\n- Completion safeguards: scope ledger, validation evidence, no false Done.\n\n## File Map\n\n```text\n.\n├── .codex/\n│   └── agents/\n│       ├── team-lead-fast-explorer.toml\n│       └── team-lead-deep-implementer.toml\n├── README.md\n├── README.zh-CN.md\n├── README.ja.md\n├── README.ru.md\n├── README.de.md\n├── README.fr.md\n├── README.es.md\n├── AGENTS.md\n├── CLAUDE.md\n├── docs/\n│   ├── global-installation.md\n│   ├── team-lead-mode-extraction.zh.md\n│   └── superpowers/\n│       ├── plans/\n│       └── specs/\n└── .agents/\n    └── skills/\n        ├── team-lead-mode/\n        │   ├── SKILL.md\n        │   ├── agents/openai.yaml\n        │   └── references/\n        │       ├── active-plan-template.md\n        │       ├── active-plans-readme-template.md\n        │       ├── epic-docs-template.md\n        │       ├── validation-matrix.md\n        │       ├── worker-runners.md\n        │       ├── worker-improvement-log-template.md\n        │       └── worker-prompts.md\n        └── team-lead-worker/\n            ├── SKILL.md\n            ├── agents/openai.yaml\n            └── references/\n                ├── escalation-template.md\n                ├── handoff-template.md\n                └── marker-spec.md\n```\n\nFor the longer Chinese design and extraction report, read\n`docs/team-lead-mode-extraction.zh.md`.\n\n## Installation\n\nThere are two supported install shapes. The **global install** is recommended\nbecause the orchestration protocol stays in one place and per-project setup\nshrinks to a small adapter. The **per-project install** still works for repos\nthat prefer to vendor everything locally.\n\n### Global Install (recommended)\n\nThe generic protocol — the Team Lead Mode skills, Factory Mode rules, and\nproject-neutral hard gates — lives once under your global Codex home. New\nprojects only add a thin adapter file with project-specific variables (worker\ncommand, default model policy, validation recipes, optional tmux session,\noptional shared-log path).\n\n1. Copy the Team Lead Mode skills and optional named Codex agent profiles into\n   your global Codex directories. The skill commands are the idempotent skill\n   upgrade path; the profile command is a non-clobbering first install that\n   also admits newly added profile names. Factory Mode uses Codex factory\n   workers by default and can use ZCode when explicitly selected. The\n   `team-lead-worker` copy below is only for users who want to retain the\n   explicit legacy Claude bridge:\n\n   ```bash\n   mkdir -p ~/.codex/skills/team-lead-mode ~/.codex/skills/team-lead-worker ~/.codex/agents\n   rsync -a --delete .agents/skills/team-lead-mode/  ~/.codex/skills/team-lead-mode/\n   rsync -a --delete .agents/skills/team-lead-worker/ ~/.codex/skills/team-lead-worker/\n   rsync -a --ignore-existing .codex/agents/ ~/.codex/agents/\n   ```\n\n   The trailing slashes copy directory *contents*, and `--delete` clears\n   files removed upstream, so re-runs do not create nested directories or\n   leave stale files. Plain `cp -R src existing_dest` is unsafe on macOS/BSD\n   because it nests the source inside the destination instead of replacing\n   it. See [`docs/global-installation.md`](docs/global-installation.md) for\n   the no-`rsync` fallback and the upgrade procedure. The profile command\n   neither deletes unrelated agents nor overwrites an existing same-named\n   personal profile. It therefore does not upgrade an existing profile: first\n   diff upstream against the installed file, make a backup, then explicitly\n   merge or approve replacement.\n\n2. Merge a project-neutral collaboration-mode section into your global\n   `~/.codex/AGENTS.md`. It should persist the first non-temporary explicit\n   mode choice (`默认模式`, `组长模式`, `工厂模式`) to the global\n   `~/.codex/session-mode.json`, optionally persist the Team Lead default\n   runner (`codex`, `zcode`, or `claude`) there too, document the\n   lower-precedence optional\n   `.codex/session-mode.json` marker, point the Team Lead role at\n   `~/.codex/skills/team-lead-mode/SKILL.md`, declare\n   that `小兵/worker/subagent` resolves through the unified selection protocol,\n   with Codex as the default only when no runner is explicitly selected;\n   document that small bounded work defaults to Codex subagents and large loop\n   work defaults to a tmux-backed Codex automation factory; state the\n   lead-discipline hard gates; and add Factory Mode intake, ledger, heartbeat,\n   and stop-boundary rules. See\n   this repo's own [`AGENTS.md`](AGENTS.md) for the long-form text and\n   [`docs/global-installation.md`](docs/global-installation.md) for a ready\n   section to paste.\n\n3. For each target repository, add a thin adapter to its own `AGENTS.md`.\n   Add the `CLAUDE.md` bridge only when legacy Claude routing is desired. The\n   adapter defines project-specific variables and validation recipes; it does\n   not duplicate the global protocol. See\n   [`docs/global-installation.md`](docs/global-installation.md) for templates.\n\n4. Start a fresh Codex session in the target repo. The first non-temporary\n   explicit mode choice becomes the global default for later sessions; users\n   can use `仅本次` / `only this session` for a one-session override. For Team\n   Lead Mode, Codex loads the global skill, the global hard gates, and the\n   project adapter as overrides. For Factory Mode, the main Codex dispatches\n   the approved production line through the selected factory runner, with\n   runner, model policy, permission, command, and transport recorded\n   separately. ZCode requires explicit `factory_runner: zcode`\n   in the approved intake/charter. If ZCode is selected, Codex remains the lead\n   only; no Codex worker or Codex subagent executes concrete backlog work inside\n   that production line.\n\nProject-local skills win over global ones when present. If a repo ships\n`.agents/skills/team-lead-mode/` of its own, Codex prefers that copy so the\nproject can pin an older or extended protocol version. Project-local\n`AGENTS.md` and `CLAUDE.md` always win on stricter requirements; they cannot\nrelax a global hard gate.\n\n### Per-Project Install (alternative)\n\nUse this when you want the protocol fully vendored into the target repo (for\nexample to pin a specific version, ship the package to teammates who do not\nkeep `~/.codex/skills/` populated, or distribute the protocol with the repo\nitself).\n\n1. Copy `.agents/skills/team-lead-mode/` into the target repository.\n2. Copy `.agents/skills/team-lead-worker/` into the target repository if the\n   explicit legacy Claude bridge is needed.\n3. Copy only missing `.codex/agents/*.toml` profiles into the target repository,\n   reviewing model ids for that account/client before relying on them. If a\n   same-named target profile already exists, diff and back it up, then merge or\n   replace only with explicit approval; do not blindly overwrite it.\n4. Merge `AGENTS.md` into the target repository's `AGENTS.md`.\n5. Merge `CLAUDE.md` only when the legacy Claude bridge is needed.\n6. Replace every placeholder listed in the next section.\n7. Add project-specific coding rules, validation recipes, and task splitting\n   guidance outside this generic package.\n8. Start a fresh Codex session. A non-temporary explicit mode choice is saved\n   globally; use the repository marker only when that lower-precedence default\n   is desired.\n\nTo make a repo auto-enter Factory Mode when no valid global preference exists,\nadd:\n\n```json\n{\n  \"version\": 1,\n  \"mode\": \"factory\",\n  \"scope\": \"repository\",\n  \"auto_activate\": true,\n  \"auto_start_goal\": false\n}\n```\n\nat `.codex/session-mode.json`. The marker only activates the role and cannot\noverride a valid global user preference. A concrete factory goal still requires\n`工厂：<目标>`, `factory: <goal>`, or an approved factory intake.\n\nThe target repository decides whether this package is copied directly,\nvendored as a subtree, or imported through its own plugin/skill mechanism.\nThe protocol does not require a build step.\n\n## Required Placeholders\n\nReplace these values in copied files:\n\n| Placeholder | Meaning | Example |\n|---|---|---|\n| `<PROJECT_NAME>` | Human-readable project name | `Acme CRM` |\n| `<PROJECT_SLUG>` | Filesystem/session-safe project slug | `acme-crm` |\n| `<REPO_ROOT>` | Absolute path to the target repo | `/path/to/acme-crm` |\n| `<TEAM_LEAD_SKILL>` | Lead skill directory name | `team-lead-mode` |\n| `<CODEX_FACTORY_COMMAND>` | Documented Codex factory command/tool surface | project-specific |\n| `<ZCODE_COMMAND>` | ZCode PATH command or documented app-bundled CLI invocation | `zcode` |\n| `<WORKER_SKILL>` | Legacy Claude worker skill directory | `team-lead-worker` |\n| `<WORKER_MARKER>` | Legacy Claude activation marker | `[TEAM_LEAD_WORKER_V1]` |\n| `<WORKER_COMMAND>` | Legacy Claude launch command | `runclaude` |\n| `<PREFERRED_MODEL_TIER>` | Legacy Claude model bias, not a lock | `opus` |\n| `<TMUX_SESSION>` | Persistent tmux session name | `acme-crm-lead` |\n| `<SHARED_LOG_PATH>` | Optional lead-owned shared log/changelog path | `docs/changelog/YYYY-MM-DD.md` |\n\nIf the target project does not maintain a shared changelog or release log, keep\nthe shared-log rule but set it to \"not applicable\" in worker handoffs.\n\n## Pluggable Worker Selection\n\nEvery dispatch keeps four decisions separate:\n\n```text\nworker_runner:  auto | codex | zcode | claude\nworker_profile: explorer | implementer | reviewer | verifier | custom:<name>\nmodel_policy:   inherit | auto | profile:<name> | pinned:<model-id>\nexecution_mode: oneshot | factory\n```\n\n| Selection | Result |\n|---|---|\n| `auto + oneshot` | Codex native subagent |\n| `auto + factory` | Codex factory runner |\n| explicit `zcode + oneshot` | bounded ZCode CLI worker |\n| explicit `zcode + factory` | homogeneous tmux-backed ZCode production line |\n| explicit `claude` | legacy Claude bridge only |\n\nPermission/sandbox, command, and transport are adapter details, not aliases\nfor these fields. A valid global Team Lead `worker_runner_preference` resolves\nan otherwise-unspecified runner before `auto`; it is a saved explicit choice,\nnot a fallback. ZCode and Claude still block on unavailable login/config, named\nprofile, pinned model, permission mode, or launch surface; they never silently\nfall back to Codex. The preference has no effect on top-level Factory Mode.\n\n`<ZCODE_COMMAND>` may be a PATH command or a documented app-bundled CLI. The\nobserved CLI supports `--prompt`/`-p`, `--cwd`,\n`--mode build|edit|plan|yolo`, `--json`, and interactive `/model`; no generic\n`--model` launch flag is assumed. A pinned model that cannot be confirmed is a\nblocker.\n\nTop-level Factory Mode remains narrower than Team Lead Mode and accepts only\n`factory_runner: codex | zcode`. See\n`.agents/skills/team-lead-mode/references/worker-runners.md` for the complete\nCodex, ZCode, and legacy Claude adapter contracts.\n\n## Operating Model\n\nTeam Lead Mode separates responsibility into two roles.\n\n**Codex lead**\n\n- Confirms product shape, scope, acceptance criteria, and non-goals.\n- After plan approval, runs the autonomous goal loop without asking the user\n  about routine execution choices such as task IDs, worker runner/profile/\n  model/execution choices,\n  revision dispatches, validation ordering, or ledger updates.\n- Decides what is lead-owned versus worker-owned.\n- For a large or unfamiliar information corpus, first dispatches read-only,\n  disjoint reconnaissance workers to return ranked sources with exact\n  path/URL and line/section anchors; it then reads only the cited originals and\n  synthesizes them rather than searching the corpus serially.\n- Dispatches workers with precise scope and risk boundaries.\n- Uses Codex subagents for small bounded work.\n- Uses a tmux-backed Codex automation factory for large loop work.\n- Verifies dispatch before waiting: unconfirmed submission is not worker\n  slowness.\n- Monitors running workers without interrupting slow-but-valid reading.\n- For a tmux lane, uses a 5-minute read-only quiet probe, then at 10 minutes\n  compares two or three snapshots 60–90 seconds apart. PID or connection alone\n  is only `RUNNING_QUIET`; recovery requires a progress-aware state\n  classification, cited snapshot deltas, one relaunch lock, and no overlap with\n  a blocked or possibly live editor. External wakeups remain required.\n- Reads the complete worker final response and full handoff report.\n- Reviews changed files and asks for revision when needed.\n- Runs focused validation directly when there is only one validation lane.\n- Writes the final user-facing synthesis.\n- Serializes shared files such as changelogs after accepting worker output.\n- Owns the Active Plan Ledger under `docs/active-plans/<work_id>.md` for\n  multi-turn initiatives, applying worker handoff notes after review and\n  comparing requested scope to ledger items before declaring complete.\n\n**Selected worker**\n\n- Runs in the target repo through the resolved Codex, ZCode, or explicit\n  legacy Claude adapter.\n- Confirms repo root, four selection dimensions, actual runtime/model/\n  permission context, scope, and handoff path.\n- Reads the project rules.\n- Restates the task before editing.\n- Edits only inside `scope_own`, never inside `scope_off`.\n- Escalates ambiguity, scope conflicts, failed checks, and risky actions.\n- Validates with exact evidence.\n- Writes the handoff report to `.tmp/team-lead/` or `.codex/factory/`.\n- Does not stage, commit, deploy, or summarize directly for the human user.\n\n**Codex Factory Mode**\n\n- Runs only after `工厂模式`, `factory mode`, a valid global or repository\n  session-mode marker, or another explicit Factory Mode selector.\n- Separates role activation from goal activation: the marker can enter the\n  role, but a concrete factory goal needs `工厂：<目标>`, `factory: <goal>`, or\n  an approved intake.\n- Makes the main Codex the factory lead, not the primary executor. Concrete\n  backlog work runs through the selected factory runner.\n- Starts code-affecting factory work only after intake records objective,\n  acceptance criteria, non-goals, source of truth, T0-T3 complexity, validation\n  evidence, editable/off-limits scope, `factory_runner: codex | zcode`, launch\n  command, stop boundary, escalation triggers, and continuation path.\n- Uses Codex by default and ZCode only when explicitly selected; missing ZCode\n  CLI/login/config is a blocker rather than a reason to fall back.\n- Treats ZCode factory lines as runner-homogeneous: implementation, revision,\n  verification, subagent, and scribe lanes all use ZCode.\n- Uses operational state under `.codex/factory/`, including the active goal,\n  acceptance ledger, WorkGraph, progress notes, heartbeat, status digest,\n  worker handoffs, and optional `STOP`.\n- Lets the factory worker continue routine T0-T2 execution inside the approved\n  boundary, but stops or asks for T3 items, scope changes, secrets, deploys,\n  destructive git, irreversible migrations, ambiguous validation, missing\n  resources, and stop boundary breaches.\n\n## Autonomous Goal Loop\n\nFor non-trivial work, the lead first confirms the plan with the user: goal,\nacceptance criteria, non-goals, worker lanes, validation evidence, budget or\nturn limits, and actions that require fresh permission. After that approval,\nTeam Lead Mode becomes escalation-only for routine execution. The lead decides\ntask IDs, Codex subagent versus tmux-backed Codex automation factory routing,\nprompt wording, worker fan-out, revision or verification dispatches, validation\norder, active plan ledger updates, and shared-log serialization without asking\nthe user each time.\n\nThe lead loops over the approved plan: choose the next in-scope item, dispatch\nor do lead-owned work, read the final response and handoff, review diffs,\nvalidate, update state, and repeat until everything is Done, a real Blocked\ncondition appears, or the stop limit is reached.\n\nThe lead comes back to the user only for material decisions: scope changes,\nnew user-visible product tradeoffs, commit/push/deploy or destructive actions\nwithout current-turn authorization, secrets/auth/billing/legal/security\nquestions, unavailable runners/profiles/models/permission contexts/transports,\nconflicting dirty worktrees, failed validation with no safe next step, or\nbudget/turn/time limit breaches.\n\n## Runner-Neutral Worker Envelope\n\nCodex and ZCode prompts start with a runner-neutral envelope:\n\n```text\ntask_id:        <slug>\nmode:           implementation | investigation | review | revision | verification | test_design | adversarial_review | browser_verification | factory_pipeline\nworker_runner:  auto | codex | zcode\nworker_profile: explorer | implementer | reviewer | verifier | custom:<name>\nmodel_policy:   inherit | auto | profile:<name> | pinned:<model-id>\nexecution_mode: oneshot | factory\nscope_own:      <owned paths; none for read-only work>\nscope_off:      <off-limits paths and unrelated existing changes>\npermission_policy: inherit | read-only | workspace-write | <approved runner mode>\ncommit_policy: no_commit | scoped_commit\nsubagent_policy: none | research_only | implementation_allowed\nsuperpowers:    off | optional | required\nsuperpowers_skills: none | worker-selected | <comma-separated skills>\nescalation:     .tmp/team-lead/questions-<task_id>.md\nhandoff:        .tmp/team-lead/worker-<task_id>-<timestamp>.md\n```\n\nFactory envelopes add the resolved `factory_runner: codex | zcode`, runtime\ncommand/tool surface, transport, charter, operational ledger, heartbeat,\nstatus digest, wakeup policy, gates, and stop boundary. The complete templates\nlive in `worker-prompts.md`.\n\nThe lane is `submitted-unconfirmed` after dispatch and becomes `running` only\nafter activation output, repo-root confirmation, or a blocking activation\nerror. Codex acceptance requires the complete subagent response and handoff;\nZCode additionally requires the CLI/JSON result and confirmed login/model/\npermission context.\n\n## Codex Subagent Model Selection\n\nLocal Codex custom agents can use models different from the main agent. Define\nthem under `~/.codex/agents/` or project `.codex/agents/` with `model` and\n`model_reasoning_effort`. Omitted values inherit from the parent session, and\nwhen neither is pinned Codex can choose a task-appropriate setup.\n\nA named Codex agent is a complete configuration layer, not a model-only alias:\nit also carries `description`, `developer_instructions`, sandbox, and other\neffective settings. The four dispatch dimensions are still recorded\nseparately, but arbitrary combinations are not valid. Before activation,\nresolve `name`, description/instructions, model/effort, and sandbox (including\ninheritance) and require them to match the requested worker profile, mode, risk\nbudget, and permission policy; otherwise fail closed.\n\nThe current `spawn_agent` callable surface does not expose a per-call `model`\nargument. Do not document or call fictitious syntax such as\n`spawn_agent(model=...)`. For deterministic selection, use\n`model_policy: profile:<name>` with a named custom agent. If the active client\ncannot select that profile, fail closed.\n\nThis repository ships `team_lead_fast_explorer` (`gpt-5.6-terra`, medium,\nread-only) and `team_lead_deep_implementer` (`gpt-5.6`, high,\nworkspace-write), following the current official\n[Codex Subagents guidance](https://learn.chatgpt.com/docs/agent-configuration/subagents).\nAvailability varies by account/client; replace an unavailable model with an\nexplicitly approved supported model or block the lane, never silently\ndowngrade.\n\nThe bundled mappings are strict: the fast explorer is only for\n`worker_profile: explorer` + read-only `mode: investigation`; the deep\nimplementer is only for `worker_profile: implementer` + workspace-write\n`mode: implementation | revision`. Do not use the deep implementer as a\nread-only reviewer/verifier or the fast explorer for a writing lane.\n\n## Legacy Claude Worker Marker\n\nOnly an explicitly selected legacy Claude worker uses\n`[TEAM_LEAD_WORKER_V1]`, `model_tier`, and `backend: cc-print | tty |\ncc-background | cc-agent-view | cc-internal-subagents | cc-factory`. Its first\nvisible response must be `ACK_TEAM_LEAD_WORKER <task_id>`, and it must read the\n`team-lead-worker` skill. These Claude-only fields are isolated in the legacy\nappendix of `worker-prompts.md`; they are not generic Codex/ZCode requirements.\n\n## Legacy Claude Model Selection\n\nThis section applies only when the user explicitly asks for the legacy Claude\nworker route. Default Team Lead routing uses Codex subagents for bounded work\nand tmux-backed Codex automation factories for large loop work.\n\n`<PREFERRED_MODEL_TIER>` is a decision bias, not a hard lock and not an\nimplicit fallback. The lead must choose `model_tier` for each worker dispatch:\n\n- Use `opus` for implementation, bug fixing, debugging, architecture, broad\n  integration, planning/design/spec work that will shape later implementation,\n  ambiguous requirements, high-risk review, and expensive-to-be-wrong work.\n- Use `sonnet` as the normal choice for narrow read-only investigation,\n  documentation or process edits, mechanical validation, log summaries, simple\n  handoff synthesis, translation/localization cleanup, and other low-risk work\n  with clear acceptance criteria.\n- Do not spend Opus as a blanket default just because the repository bias is\n  Opus. For code, architecture, planning/design/spec, and high-risk review,\n  choose Opus when unsure; for bounded non-code low-risk work, choose Sonnet\n  when unsure.\n\nThe worker must confirm it is on the selected tier. If the selected model is\nunavailable, the worker stops and reports a blocker instead of silently\ndowngrading.\n\nMissing, vague, or placeholder model fields such as `default` are activation\nblockers. A lead should never dispatch a worker while unsure which model the\ntask should use.\n\nThe project adapter should document how to launch each tier: for example\n`<WORKER_COMMAND> --model opus`, `<WORKER_COMMAND> --model sonnet`, direct\n`claude --model <tier>` commands, or separate wrappers. A wrapper that ignores\narguments is a setup blocker for non-default model dispatch.\n\n## Legacy Claude Worker Backend Selection\n\nThis section applies only when the user explicitly asks for the legacy Claude\nworker route. Default Team Lead routing uses Codex subagents for bounded work\nand tmux-backed Codex automation factories for large loop work.\n\nThe legacy default backend is `cc-print`: launch Claude Code from the target repo with\n`claude -p` or the project's print-mode wrapper. This is the legacy path for most\nbounded investigations, reviews, revisions, validations, documentation tasks,\nand small-to-medium implementations where final stdout, handoff, diff, and\nvalidation evidence are enough.\n\nTypical launch shape:\n\n```bash\nmkdir -p .tmp/team-lead\nclaude -p \\\n  --model <tier> \\\n  --permission-mode <mode> \\\n  --no-session-persistence \\\n  --output-format json \\\n  --allowedTools '<tool allowlist>' \\\n  < .tmp/team-lead/prompts/<task_id>.md\n```\n\nPrefer stdin or a prompt file. If passing the prompt as an argument after\nvariadic flags such as `--allowedTools`, insert `--` before the prompt so the\nCLI does not consume it as another option value. Do not rely on `--bare` unless\nthe project documents API-key auth for it.\n\nUse `tty` through the configured worker command, usually `runclaude`, when a\ntask needs live steering, long multi-turn `/plan` or `/goal` continuity, prompt\nrecovery, permission prompts, fragile UI/browser observation, auth flows,\ninteractive CLIs, or production-risk supervision. Other documented Claude Code\nbackends are:\n\n- `cc-background`: a documented Claude Code background session route.\n- `cc-agent-view`: a documented Claude Code Agent View session route.\n- `cc-internal-subagents`: a parent Claude Code worker remains accountable and\n  may use Claude Code subagents internally.\n\nThese are legacy Claude worker routes, not default Codex subagents. The worker must\nstill confirm repo root, selected model tier, permission/settings context where\nvisible, scope, and handoff path. For `cc-print`, acceptance also requires a\nsuccessful JSON result (`is_error: false`, `terminal_reason: completed`) and no\nunexplained permission denials. Final acceptance still requires the worker\nresponse, Markdown handoff, diff review, and validation evidence.\n\nUse `subagent_policy: implementation_allowed` only when the lead explicitly\nallows Claude Code subagents to perform bounded implementation subtasks inside\n`scope_own`. The parent worker remains responsible for review, integration,\nvalidation, and the final handoff.\n\nFor long or context-heavy handoffs, the parent worker may use one internal\nhandoff-scribe subagent under `subagent_policy: research_only` or\n`implementation_allowed`. The scribe may draft only from the parent's notes,\ndiff summary, validation evidence, blocker list, shared-log note, and\nplan-ledger note. The parent worker must read, correct, and explicitly sign off\nthe final handoff before claiming completion.\n\n## Legacy Claude Superpowers Integration\n\nIf Claude Code has the Superpowers plugin installed and enabled, the lead can\nopt a worker into it with `superpowers: optional` or require it with\n`superpowers: required`. This is useful for large approved plans, TDD,\nsystematic debugging, code review, and Superpowers' own subagent-driven\ndevelopment loop.\n\nThe lead should normally name the expected skills with\n`superpowers_skills:` instead of relying on Claude Code to infer the workflow.\nUse `worker-selected` only when the worker has better local context and must\nreport its selection before implementation or final conclusions. A practical\nrouting table:\n\n- Unclear feature: `brainstorming`, then `writing-plans`.\n- Approved single-lane plan: `executing-plans`,\n  `verification-before-completion`.\n- Approved plan with independent subtasks: `subagent-driven-development`,\n  `requesting-code-review`, `verification-before-completion`.\n- Bug, failed test, or CI failure: `systematic-debugging`, then\n  `test-driven-development` for behavior changes.\n- High-risk handoff: `requesting-code-review`.\n- Review feedback: `receiving-code-review`.\n- Team Lead Mode or Factory Mode protocol edits: `writing-skills`,\n  `verification-before-completion`.\n\nSuperpowers runs inside the Claude Code worker. It is not a Codex subagent, not\na new backend, and not permission to widen scope. It must still obey\n`model_tier`, `scope_own`, `scope_off`, `risk_budget`, validation, and the\n`.tmp/team-lead/` handoff. If Superpowers performs implementation with internal\nsubagents, the marker must set `subagent_policy: implementation_allowed`, and\nthe parent worker must report skill usage, subagent count, review loops, and\nvalidation evidence.\n\n`using-git-worktrees` requires lead approval for the workspace strategy.\n`finishing-a-development-branch` does not authorize staging, committing,\npushing, merging, or PR creation unless the user explicitly approved that\ncurrent-turn action.\n\n## Legacy Claude tmux Layer\n\n`tmux` is optional and only manages terminals for the `tty` backend. It does\nnot replace the worker command, relax model requirements, change repo root,\nwiden scope, or count as acceptance evidence.\n\nThe tmux session is persistent; worker windows are not. Treat each\n`worker-<task_id>` window as a disposable execution slot. After the worker's\nfinal response and handoff have been reviewed, close the window unless there is\nan explicit follow-up reason and short time-to-live.\n\nBefore opening another worker window, list existing `worker-*` windows, close\naccepted/rejected/stale workers, and make sure the session will stay under\neight worker windows. If a session already has eight worker windows, clean up\nor consolidate before dispatching more work.\n\nFor many small independent subtasks, prefer `cc-print` fan-out or one\naccountable Claude Code parent worker using internal subagents\n(`backend: cc-internal-subagents`, `subagent_policy: implementation_allowed`)\ninstead of opening many tmux TTY windows. Reserve multiple worker windows for\ntruly independent lanes that need separate live observation, model/runtime\nisolation, or separate handoffs.\n\nAfter sending a worker prompt, verify the dispatch submission gate before\nwaiting on the worker. Seeing `ACK_TEAM_LEAD_WORKER <task_id>`, activation\noutput, or a blocking activation error is required. For tmux workers, use\ndeterministic send mechanics such as tmux buffer paste followed by\n`tmux send-keys C-m`, then still verify the ACK gate. If the first short ACK\nwindow is quiet, send `Enter` at most once more when the prompt appears\nunsubmitted; if the second window is also quiet, report dispatch failure instead\nof treating the worker as slow.\n\nRecommended tmux launch shape:\n\n```bash\ntmux new-session -d -s <TMUX_SESSION> -n lead-shell -c <REPO_ROOT>\ntmux new-window -t <TMUX_SESSION> -n worker-<task_id> -c <REPO_ROOT>\ntmux attach -t <TMUX_SESSION>\n```\n\nUse `tmux capture-pane` for liveness and recovery context, not for accepting\nwork. It is read-only observation, not permission to send status pings to a slow\nbut safe running worker. Acceptance still requires the full worker response and\nhandoff report.\n\nClaude Code itself is interactive in a tmux pane. Commands launched from\ninside Claude Code's Bash tool may still not have an interactive TTY, so\narrow-key menus, auth prompts, curses tools, `psql`, and similar CLIs should\nuse non-interactive flags/config/stdin or be run manually in a dedicated tmux\npane.\n\n## Legacy Claude `/goal` Layer\n\nClaude Code `/goal` is optional and only keeps a long worker session pointed at\na completion condition. It is not a planner and not acceptance evidence.\n\nDo not set `/goal` before the worker marker. First send the\n`[TEAM_LEAD_WORKER_V1]` prompt, let the worker confirm repo root, backend,\nselected model tier, scope, and handoff path, then send `/goal <condition>` as a\nseparate follow-up when useful. A good condition names the handoff path,\nvalidation evidence, scope boundaries, risks, shared-log notes when relevant,\nand a stop bound such as `or stop after 8 turns`.\n\n## Active Plan Ledger\n\nMulti-turn initiatives that need durable Done / Not Done memory live in\n`docs/active-plans/<work_id>.md`, with an index in\n`docs/active-plans/README.md`. This is the middle tier between an inline\nchat summary and a full epic-docs charter:\n\n- Inline summary — fine for tiny one-turn work.\n- Active plan — used when work spans turns or has deferrable items.\n- Epic docs — used for non-trivial long-running scope with formal milestones.\n\nThe ledger is memory and accountability only. It does not authorize direct\ncode edits, does not replace worker handoffs, and does not weaken validation.\nThe Codex lead owns updates by default; workers contribute a concise \"Plan\nledger note for lead\" in their handoff, and the lead serializes the change\nafter review. See `AGENTS.md` §\"Persistent Active Plan Ledger\" for the full\nrule body and `.agents/skills/team-lead-mode/references/active-plan-template.md`\nplus `active-plans-readme-template.md` for reusable seeds.\n\n## Shared Log And Changelog Policy\n\nIf several workers edit a shared changelog, release note, migration log, or\nstatus ledger, they will conflict. The generic rule is:\n\n- Workers do not edit shared logs directly in marker mode.\n- Workers write a concise \"Shared log note for lead\" in the handoff.\n- The lead updates the shared log after review and validation.\n\nThis keeps concurrent worker lanes independent and preserves final narrative\nquality.\n\n## What You Must Add Per Project\n\nThis package deliberately omits:\n\n- Repository architecture.\n- Dev commands.\n- Ports and service URLs.\n- Language/framework rules.\n- Product safety rules.\n- Generated contract rules.\n- Database and migration rules.\n- Deployment policy.\n- Authentication or test credentials.\n- Domain-specific validation recipes.\n- Project-specific task splitting.\n\nPut those in the target repo's own `AGENTS.md`, `CLAUDE.md`, and optional\nproject-specific reference files. The team-lead protocol should coordinate\nthose rules, not own them.\n\n## Publishing Checklist\n\nBefore making this repository public:\n\n- Confirm the repository license remains Apache License 2.0.\n- Decide whether `runclaude` is a documented dependency or a local wrapper\n  users must replace with their Claude Code command.\n- Remove any local paths, project names, ports, credentials, and private\n  references from examples.\n- Run the residual-coupling scan in the validation section below.\n- Add a short quick-start section for your intended audience if needed.\n\n## License\n\nThis project is licensed under the Apache License 2.0. You may use, modify,\ndistribute, and use it commercially under the terms of the license.\n\n## Validation\n\nUseful local checks:\n\n```bash\nfind . -type f | sort\nrg -n 'Chat''RPG|Chat''Lab|chat''rpg|chat''lab|/User''s/|80''10|80''13|30''10|30''13|S''NT|R''NE|T''RPG|Fast''API|Nu''xt|Re''act'\nrg -n '<PROJECT_NAME>|<REPO_ROOT>|<WORKER_MARKER>|<WORKER_COMMAND>|<TMUX_SESSION>'\n```\n\nThe first `rg` should return nothing in the standalone package. The second\nshould return the template placeholders that a downstream project must replace.\n"}