Codex Team Lead Mode

Languages: English | 简体中文 | 日本語 | Русский | Deutsch | Français | Español

Codex Team Lead Mode is a reusable orchestration protocol for running Codex as a lead engineer while delegating work through a pluggable worker contract. Bounded work defaults to Codex native subagents and large loop work defaults to a tmux-backed Codex automation factory; ZCode can be selected explicitly for either shape, while Claude remains an explicit legacy bridge.

The goal is simple: make the session mode explicit. Default Mode lets Codex work directly. Team Lead Mode keeps the lead responsible for scope, planning, review, validation, and user-facing synthesis while Codex workers do detailed code-affecting edits through a strict scope, escalation, and handoff contract. Factory Mode makes the Codex-native production-line path explicit: the main Codex performs intake, dispatch, monitoring, review, validation, and final reporting while the approved factory runner executes the backlog loop. Factory Mode supports Codex by default and ZCode when explicitly specified; record the choice as factory_runner: codex | zcode. ZCode factory lines are runner-homogeneous. No Codex worker or Codex subagent may execute concrete backlog work inside a ZCode factory line.

This repository is intentionally project-neutral. It contains no product architecture, ports, framework choices, backend/frontend paths, deploy steps, or business-specific validation rules. Those belong in the target repository's own project rules.

What This Extracts

The reusable core is:

• A three-mode Codex session model: default mode, team-lead mode, and factory production-line mode.
• A persistent per-user mode preference, ~/.codex/session-mode.json: the first non-temporary explicit choice is saved and automatically reused in later fresh sessions, without asking the user to choose again.
• An optional Team Lead worker-runner preference in that same global file: worker_runner_preference: codex | zcode | claude resolves an unspecified Team Lead worker without changing the other dispatch dimensions.
• A lower-precedence repository marker, .codex/session-mode.json, that can auto-activate a selected mode on fresh sessions without auto-starting work.
• A hard gate for code-affecting work: in team-lead mode, the lead delegates implementation instead of quietly editing files directly.
• A Factory Mode route for approved worker-run production-line work with intake, factory ledger, WorkGraph, progress notes, heartbeat/status digest, stop boundary, and escalation rules.
• Factory runner selection for production-line goals: Codex is the default runner, while ZCode is allowed only when the user or approved intake/charter explicitly sets factory_runner: zcode.
• ZCode production-line homogeneity: once factory_runner: zcode is selected, implementation, revision, verification, subagent, and handoff-scribe lanes must all be ZCode-run.
• A worker routing rule: generic "worker", "subagent", "parallel agent", and similar phrasing uses a four-dimensional runner/profile/model/execution contract, with Codex as the auto default.
• Independent worker_runner, worker_profile, model_policy, and execution_mode fields so runtime, role, model, and transport are not conflated.
• A Codex-subagent-first path for bounded work. Small bounded work defaults to Codex subagents.
• A tmux-backed Codex automation factory path for large, enumerable, loop-oriented work. Large loop work defaults to a tmux-backed Codex automation factory.
• Optional legacy Claude Code worker backends only when explicitly requested by the user in the current turn.
• An autonomous goal loop: after the user approves a plan, the lead keeps deciding routine execution choices and looping until Done, truly Blocked, or the stop limit instead of repeatedly asking the user.
• Optional Superpowers integration inside Codex workers, including lead-selected superpowers_skills for large approved plans, systematic debugging, TDD, code review, and subagent execution.
• A runner-neutral worker envelope with task, scope, acceptance, validation, escalation, handoff, and commit policy.
• A versioned [TEAM_LEAD_WORKER_V1] activation marker retained only for the explicit legacy Claude bridge.
• A worker-side partnership contract: workers may push back, but may not silently expand scope.
• A three-tier durable memory ladder: inline summaries for tiny work, a Persistent Active Plan Ledger under docs/active-plans/<work_id>.md for multi-turn initiatives, and full epic docs under docs/epics/<epic_id>/ for long-running scope.
• Append-only escalation files under .tmp/team-lead/.
• Full Markdown handoff reports before the lead accepts work.
• Lead-owned review, focused validation, final reporting, and shared-log serialization.
• Completion safeguards: scope ledger, validation evidence, no false Done.

File Map

.
├── .codex/
│   └── agents/
│       ├── team-lead-fast-explorer.toml
│       └── team-lead-deep-implementer.toml
├── README.md
├── README.zh-CN.md
├── README.ja.md
├── README.ru.md
├── README.de.md
├── README.fr.md
├── README.es.md
├── AGENTS.md
├── CLAUDE.md
├── docs/
│   ├── global-installation.md
│   ├── team-lead-mode-extraction.zh.md
│   └── superpowers/
│       ├── plans/
│       └── specs/
└── .agents/
    └── skills/
        ├── team-lead-mode/
        │   ├── SKILL.md
        │   ├── agents/openai.yaml
        │   └── references/
        │       ├── active-plan-template.md
        │       ├── active-plans-readme-template.md
        │       ├── epic-docs-template.md
        │       ├── validation-matrix.md
        │       ├── worker-runners.md
        │       ├── worker-improvement-log-template.md
        │       └── worker-prompts.md
        └── team-lead-worker/
            ├── SKILL.md
            ├── agents/openai.yaml
            └── references/
                ├── escalation-template.md
                ├── handoff-template.md
                └── marker-spec.md

For the longer Chinese design and extraction report, read docs/team-lead-mode-extraction.zh.md.

Installation

There are two supported install shapes. The global install is recommended because the orchestration protocol stays in one place and per-project setup shrinks to a small adapter. The per-project install still works for repos that prefer to vendor everything locally.

Global Install (recommended)

The generic protocol — the Team Lead Mode skills, Factory Mode rules, and project-neutral hard gates — lives once under your global Codex home. New projects only add a thin adapter file with project-specific variables (worker command, default model policy, validation recipes, optional tmux session, optional shared-log path).

1. Copy the Team Lead Mode skills and optional named Codex agent profiles into your global Codex directories. The skill commands are the idempotent skill upgrade path; the profile command is a non-clobbering first install that also admits newly added profile names. Factory Mode uses Codex factory workers by default and can use ZCode when explicitly selected. The team-lead-worker copy below is only for users who want to retain the explicit legacy Claude bridge:

   mkdir -p ~/.codex/skills/team-lead-mode ~/.codex/skills/team-lead-worker ~/.codex/agents
   rsync -a --delete .agents/skills/team-lead-mode/  ~/.codex/skills/team-lead-mode/
   rsync -a --delete .agents/skills/team-lead-worker/ ~/.codex/skills/team-lead-worker/
   rsync -a --ignore-existing .codex/agents/ ~/.codex/agents/

   The trailing slashes copy directory contents, and --delete clears files removed upstream, so re-runs do not create nested directories or leave stale files. Plain cp -R src existing_dest is unsafe on macOS/BSD because it nests the source inside the destination instead of replacing it. See docs/global-installation.md for the no-rsync fallback and the upgrade procedure. The profile command neither deletes unrelated agents nor overwrites an existing same-named personal profile. It therefore does not upgrade an existing profile: first diff upstream against the installed file, make a backup, then explicitly merge or approve replacement.

2. Merge a project-neutral collaboration-mode section into your global ~/.codex/AGENTS.md. It should persist the first non-temporary explicit mode choice (默认模式, 组长模式, 工厂模式) to the global ~/.codex/session-mode.json, optionally persist the Team Lead default runner (codex, zcode, or claude) there too, document the lower-precedence optional .codex/session-mode.json marker, point the Team Lead role at ~/.codex/skills/team-lead-mode/SKILL.md, declare that 小兵/worker/subagent resolves through the unified selection protocol, with Codex as the default only when no runner is explicitly selected; document that small bounded work defaults to Codex subagents and large loop work defaults to a tmux-backed Codex automation factory; state the lead-discipline hard gates; and add Factory Mode intake, ledger, heartbeat, and stop-boundary rules. See this repo's own AGENTS.md for the long-form text and docs/global-installation.md for a ready section to paste.

3. For each target repository, add a thin adapter to its own AGENTS.md. Add the CLAUDE.md bridge only when legacy Claude routing is desired. The adapter defines project-specific variables and validation recipes; it does not duplicate the global protocol. See docs/global-installation.md for templates.

4. Start a fresh Codex session in the target repo. The first non-temporary explicit mode choice becomes the global default for later sessions; users can use 仅本次 / only this session for a one-session override. For Team Lead Mode, Codex loads the global skill, the global hard gates, and the project adapter as overrides. For Factory Mode, the main Codex dispatches the approved production line through the selected factory runner, with runner, model policy, permission, command, and transport recorded separately. ZCode requires explicit factory_runner: zcode in the approved intake/charter. If ZCode is selected, Codex remains the lead only; no Codex worker or Codex subagent executes concrete backlog work inside that production line.

Project-local skills win over global ones when present. If a repo ships .agents/skills/team-lead-mode/ of its own, Codex prefers that copy so the project can pin an older or extended protocol version. Project-local AGENTS.md and CLAUDE.md always win on stricter requirements; they cannot relax a global hard gate.

Per-Project Install (alternative)

Use this when you want the protocol fully vendored into the target repo (for example to pin a specific version, ship the package to teammates who do not keep ~/.codex/skills/ populated, or distribute the protocol with the repo itself).

1. Copy .agents/skills/team-lead-mode/ into the target repository.
2. Copy .agents/skills/team-lead-worker/ into the target repository if the explicit legacy Claude bridge is needed.
3. Copy only missing .codex/agents/*.toml profiles into the target repository, reviewing model ids for that account/client before relying on them. If a same-named target profile already exists, diff and back it up, then merge or replace only with explicit approval; do not blindly overwrite it.
4. Merge AGENTS.md into the target repository's AGENTS.md.
5. Merge CLAUDE.md only when the legacy Claude bridge is needed.
6. Replace every placeholder listed in the next section.
7. Add project-specific coding rules, validation recipes, and task splitting guidance outside this generic package.
8. Start a fresh Codex session. A non-temporary explicit mode choice is saved globally; use the repository marker only when that lower-precedence default is desired.

To make a repo auto-enter Factory Mode when no valid global preference exists, add:

{
  "version": 1,
  "mode": "factory",
  "scope": "repository",
  "auto_activate": true,
  "auto_start_goal": false
}

at .codex/session-mode.json. The marker only activates the role and cannot override a valid global user preference. A concrete factory goal still requires 工厂：<目标>, factory: <goal>, or an approved factory intake.

The target repository decides whether this package is copied directly, vendored as a subtree, or imported through its own plugin/skill mechanism. The protocol does not require a build step.

Required Placeholders

Replace these values in copied files:

Placeholder	Meaning	Example
<PROJECT_NAME>	Human-readable project name	Acme CRM
<PROJECT_SLUG>	Filesystem/session-safe project slug	acme-crm
<REPO_ROOT>	Absolute path to the target repo	/path/to/acme-crm
<TEAM_LEAD_SKILL>	Lead skill directory name	team-lead-mode
<CODEX_FACTORY_COMMAND>	Documented Codex factory command/tool surface	project-specific
<ZCODE_COMMAND>	ZCode PATH command or documented app-bundled CLI invocation	zcode
<WORKER_SKILL>	Legacy Claude worker skill directory	team-lead-worker
<WORKER_MARKER>	Legacy Claude activation marker	[TEAM_LEAD_WORKER_V1]
<WORKER_COMMAND>	Legacy Claude launch command	runclaude
<PREFERRED_MODEL_TIER>	Legacy Claude model bias, not a lock	opus
<TMUX_SESSION>	Persistent tmux session name	acme-crm-lead
<SHARED_LOG_PATH>	Optional lead-owned shared log/changelog path	docs/changelog/YYYY-MM-DD.md

If the target project does not maintain a shared changelog or release log, keep the shared-log rule but set it to "not applicable" in worker handoffs.

Pluggable Worker Selection

Every dispatch keeps four decisions separate:

worker_runner:  auto | codex | zcode | claude
worker_profile: explorer | implementer | reviewer | verifier | custom:<name>
model_policy:   inherit | auto | profile:<name> | pinned:<model-id>
execution_mode: oneshot | factory

Selection	Result
auto + oneshot	Codex native subagent
auto + factory	Codex factory runner
explicit zcode + oneshot	bounded ZCode CLI worker
explicit zcode + factory	homogeneous tmux-backed ZCode production line
explicit claude	legacy Claude bridge only

Permission/sandbox, command, and transport are adapter details, not aliases for these fields. A valid global Team Lead worker_runner_preference resolves an otherwise-unspecified runner before auto; it is a saved explicit choice, not a fallback. ZCode and Claude still block on unavailable login/config, named profile, pinned model, permission mode, or launch surface; they never silently fall back to Codex. The preference has no effect on top-level Factory Mode.

<ZCODE_COMMAND> may be a PATH command or a documented app-bundled CLI. The observed CLI supports --prompt/-p, --cwd, --mode build|edit|plan|yolo, --json, and interactive /model; no generic --model launch flag is assumed. A pinned model that cannot be confirmed is a blocker.

Top-level Factory Mode remains narrower than Team Lead Mode and accepts only factory_runner: codex | zcode. See .agents/skills/team-lead-mode/references/worker-runners.md for the complete Codex, ZCode, and legacy Claude adapter contracts.

Operating Model

Team Lead Mode separates responsibility into two roles.

Codex lead

• Confirms product shape, scope, acceptance criteria, and non-goals.
• After plan approval, runs the autonomous goal loop without asking the user about routine execution choices such as task IDs, worker runner/profile/ model/execution choices, revision dispatches, validation ordering, or ledger updates.
• Decides what is lead-owned versus worker-owned.
• For a large or unfamiliar information corpus, first dispatches read-only, disjoint reconnaissance workers to return ranked sources with exact path/URL and line/section anchors; it then reads only the cited originals and synthesizes them rather than searching the corpus serially.
• Dispatches workers with precise scope and risk boundaries.
• Uses Codex subagents for small bounded work.
• Uses a tmux-backed Codex automation factory for large loop work.
• Verifies dispatch before waiting: unconfirmed submission is not worker slowness.
• Monitors running workers without interrupting slow-but-valid reading.
• For a tmux lane, uses a 5-minute read-only quiet probe, then at 10 minutes compares two or three snapshots 60–90 seconds apart. PID or connection alone is only RUNNING_QUIET; recovery requires a progress-aware state classification, cited snapshot deltas, one relaunch lock, and no overlap with a blocked or possibly live editor. External wakeups remain required.
• Reads the complete worker final response and full handoff report.
• Reviews changed files and asks for revision when needed.
• Runs focused validation directly when there is only one validation lane.
• Writes the final user-facing synthesis.
• Serializes shared files such as changelogs after accepting worker output.
• Owns the Active Plan Ledger under docs/active-plans/<work_id>.md for multi-turn initiatives, applying worker handoff notes after review and comparing requested scope to ledger items before declaring complete.

Selected worker

• Runs in the target repo through the resolved Codex, ZCode, or explicit legacy Claude adapter.
• Confirms repo root, four selection dimensions, actual runtime/model/ permission context, scope, and handoff path.
• Reads the project rules.
• Restates the task before editing.
• Edits only inside scope_own, never inside scope_off.
• Escalates ambiguity, scope conflicts, failed checks, and risky actions.
• Validates with exact evidence.
• Writes the handoff report to .tmp/team-lead/ or .codex/factory/.
• Does not stage, commit, deploy, or summarize directly for the human user.

Codex Factory Mode

• Runs only after 工厂模式, factory mode, a valid global or repository session-mode marker, or another explicit Factory Mode selector.
• Separates role activation from goal activation: the marker can enter the role, but a concrete factory goal needs 工厂：<目标>, factory: <goal>, or an approved intake.
• Makes the main Codex the factory lead, not the primary executor. Concrete backlog work runs through the selected factory runner.
• Starts code-affecting factory work only after intake records objective, acceptance criteria, non-goals, source of truth, T0-T3 complexity, validation evidence, editable/off-limits scope, factory_runner: codex | zcode, launch command, stop boundary, escalation triggers, and continuation path.
• Uses Codex by default and ZCode only when explicitly selected; missing ZCode CLI/login/config is a blocker rather than a reason to fall back.
• Treats ZCode factory lines as runner-homogeneous: implementation, revision, verification, subagent, and scribe lanes all use ZCode.
• Uses operational state under .codex/factory/, including the active goal, acceptance ledger, WorkGraph, progress notes, heartbeat, status digest, worker handoffs, and optional STOP.
• Lets the factory worker continue routine T0-T2 execution inside the approved boundary, but stops or asks for T3 items, scope changes, secrets, deploys, destructive git, irreversible migrations, ambiguous validation, missing resources, and stop boundary breaches.

Autonomous Goal Loop

For non-trivial work, the lead first confirms the plan with the user: goal, acceptance criteria, non-goals, worker lanes, validation evidence, budget or turn limits, and actions that require fresh permission. After that approval, Team Lead Mode becomes escalation-only for routine execution. The lead decides task IDs, Codex subagent versus tmux-backed Codex automation factory routing, prompt wording, worker fan-out, revision or verification dispatches, validation order, active plan ledger updates, and shared-log serialization without asking the user each time.

The lead loops over the approved plan: choose the next in-scope item, dispatch or do lead-owned work, read the final response and handoff, review diffs, validate, update state, and repeat until everything is Done, a real Blocked condition appears, or the stop limit is reached.

The lead comes back to the user only for material decisions: scope changes, new user-visible product tradeoffs, commit/push/deploy or destructive actions without current-turn authorization, secrets/auth/billing/legal/security questions, unavailable runners/profiles/models/permission contexts/transports, conflicting dirty worktrees, failed validation with no safe next step, or budget/turn/time limit breaches.

Runner-Neutral Worker Envelope

Codex and ZCode prompts start with a runner-neutral envelope:

task_id:        <slug>
mode:           implementation | investigation | review | revision | verification | test_design | adversarial_review | browser_verification | factory_pipeline
worker_runner:  auto | codex | zcode
worker_profile: explorer | implementer | reviewer | verifier | custom:<name>
model_policy:   inherit | auto | profile:<name> | pinned:<model-id>
execution_mode: oneshot | factory
scope_own:      <owned paths; none for read-only work>
scope_off:      <off-limits paths and unrelated existing changes>
permission_policy: inherit | read-only | workspace-write | <approved runner mode>
commit_policy: no_commit | scoped_commit
subagent_policy: none | research_only | implementation_allowed
superpowers:    off | optional | required
superpowers_skills: none | worker-selected | <comma-separated skills>
escalation:     .tmp/team-lead/questions-<task_id>.md
handoff:        .tmp/team-lead/worker-<task_id>-<timestamp>.md

Factory envelopes add the resolved factory_runner: codex | zcode, runtime command/tool surface, transport, charter, operational ledger, heartbeat, status digest, wakeup policy, gates, and stop boundary. The complete templates live in worker-prompts.md.

The lane is submitted-unconfirmed after dispatch and becomes running only after activation output, repo-root confirmation, or a blocking activation error. Codex acceptance requires the complete subagent response and handoff; ZCode additionally requires the CLI/JSON result and confirmed login/model/ permission context.

Codex Subagent Model Selection

Local Codex custom agents can use models different from the main agent. Define them under ~/.codex/agents/ or project .codex/agents/ with model and model_reasoning_effort. Omitted values inherit from the parent session, and when neither is pinned Codex can choose a task-appropriate setup.

A named Codex agent is a complete configuration layer, not a model-only alias: it also carries description, developer_instructions, sandbox, and other effective settings. The four dispatch dimensions are still recorded separately, but arbitrary combinations are not valid. Before activation, resolve name, description/instructions, model/effort, and sandbox (including inheritance) and require them to match the requested worker profile, mode, risk budget, and permission policy; otherwise fail closed.

The current spawn_agent callable surface does not expose a per-call model argument. Do not document or call fictitious syntax such as spawn_agent(model=...). For deterministic selection, use model_policy: profile:<name> with a named custom agent. If the active client cannot select that profile, fail closed.

This repository ships team_lead_fast_explorer (gpt-5.6-terra, medium, read-only) and team_lead_deep_implementer (gpt-5.6, high, workspace-write), following the current official Codex Subagents guidance. Availability varies by account/client; replace an unavailable model with an explicitly approved supported model or block the lane, never silently downgrade.

The bundled mappings are strict: the fast explorer is only for worker_profile: explorer + read-only mode: investigation; the deep implementer is only for worker_profile: implementer + workspace-write mode: implementation | revision. Do not use the deep implementer as a read-only reviewer/verifier or the fast explorer for a writing lane.

Legacy Claude Worker Marker

Only an explicitly selected legacy Claude worker uses [TEAM_LEAD_WORKER_V1], model_tier, and backend: cc-print | tty | cc-background | cc-agent-view | cc-internal-subagents | cc-factory. Its first visible response must be ACK_TEAM_LEAD_WORKER <task_id>, and it must read the team-lead-worker skill. These Claude-only fields are isolated in the legacy appendix of worker-prompts.md; they are not generic Codex/ZCode requirements.

Legacy Claude Model Selection

This section applies only when the user explicitly asks for the legacy Claude worker route. Default Team Lead routing uses Codex subagents for bounded work and tmux-backed Codex automation factories for large loop work.

<PREFERRED_MODEL_TIER> is a decision bias, not a hard lock and not an implicit fallback. The lead must choose model_tier for each worker dispatch:

• 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 investigation, documentation or process edits, mechanical validation, log summaries, simple handoff synthesis, translation/localization cleanup, and other low-risk work with clear acceptance criteria.
• Do not spend Opus as a blanket default just because the repository bias is Opus. For code, architecture, planning/design/spec, and high-risk review, choose Opus when unsure; for bounded non-code low-risk work, choose Sonnet when unsure.

The worker must confirm it is on the selected tier. If the selected model is unavailable, the worker stops and reports a blocker instead of silently downgrading.

Missing, vague, or placeholder model fields such as default are activation blockers. A lead should never dispatch a worker while unsure which model the task should use.

The project adapter should document how to launch each tier: for example <WORKER_COMMAND> --model opus, <WORKER_COMMAND> --model sonnet, direct claude --model <tier> commands, or separate wrappers. A wrapper that ignores arguments is a setup blocker for non-default model dispatch.

Legacy Claude Worker Backend Selection

This section applies only when the user explicitly asks for the legacy Claude worker route. Default Team Lead routing uses Codex subagents for bounded work and tmux-backed Codex automation factories for large loop work.

The legacy default backend is cc-print: launch Claude Code from the target repo with claude -p or the project's print-mode wrapper. This is the legacy path for most bounded investigations, reviews, revisions, validations, documentation tasks, and small-to-medium implementations where final stdout, handoff, diff, and validation evidence are enough.

Typical launch shape:

mkdir -p .tmp/team-lead
claude -p \
  --model <tier> \
  --permission-mode <mode> \
  --no-session-persistence \
  --output-format json \
  --allowedTools '<tool allowlist>' \
  < .tmp/team-lead/prompts/<task_id>.md

Prefer stdin or a prompt file. If passing the prompt as an argument after variadic flags such as --allowedTools, insert -- before the prompt so the CLI does not consume it as another option value. Do not rely on --bare unless the project documents API-key auth for it.

Use tty through the configured worker command, usually runclaude, when a task needs live steering, long multi-turn /plan or /goal continuity, prompt recovery, permission prompts, fragile UI/browser observation, auth flows, interactive CLIs, or production-risk supervision. Other documented Claude Code backends are:

• cc-background: a documented Claude Code background session route.
• cc-agent-view: a documented Claude Code Agent View session route.
• cc-internal-subagents: a parent Claude Code worker remains accountable and may use Claude Code subagents internally.

These are legacy Claude worker routes, not default Codex subagents. The worker must still confirm repo root, selected model tier, permission/settings context where visible, scope, and handoff path. For cc-print, acceptance also requires a successful JSON result (is_error: false, terminal_reason: completed) and no unexplained permission denials. Final acceptance still requires the worker response, Markdown handoff, diff review, and validation evidence.

Use subagent_policy: implementation_allowed only when the lead explicitly allows Claude Code subagents to perform bounded implementation subtasks inside scope_own. The parent worker remains responsible for review, integration, validation, and the final handoff.

For long or context-heavy handoffs, the parent worker may use one internal handoff-scribe subagent under subagent_policy: research_only or implementation_allowed. The scribe may draft only from the parent's notes, diff summary, validation evidence, blocker list, shared-log note, and plan-ledger note. The parent worker must read, correct, and explicitly sign off the final handoff before claiming completion.

Legacy Claude Superpowers Integration

If Claude Code has the Superpowers plugin installed and enabled, the lead can opt a worker into it with superpowers: optional or require it with superpowers: required. This is useful for large approved plans, TDD, systematic debugging, code review, and Superpowers' own subagent-driven development loop.

The lead should normally name the expected skills with superpowers_skills: instead of relying on Claude Code to infer the workflow. Use worker-selected only when the worker has better local context and must report its selection before implementation or final conclusions. A practical routing table:

• Unclear feature: brainstorming, then writing-plans.
• Approved single-lane plan: executing-plans, verification-before-completion.
• Approved plan with independent subtasks: subagent-driven-development, requesting-code-review, verification-before-completion.
• Bug, failed test, or CI failure: systematic-debugging, then test-driven-development for behavior changes.
• High-risk handoff: requesting-code-review.
• Review feedback: receiving-code-review.
• Team Lead Mode or Factory Mode protocol edits: writing-skills, verification-before-completion.

Superpowers runs inside the Claude Code worker. It is not a Codex subagent, not a new backend, and not permission to widen scope. It must still obey model_tier, scope_own, scope_off, risk_budget, validation, and the .tmp/team-lead/ handoff. If Superpowers performs implementation with internal subagents, the marker must set subagent_policy: implementation_allowed, and the parent worker must report skill usage, subagent count, review loops, and validation evidence.

using-git-worktrees requires lead approval for the workspace strategy. finishing-a-development-branch does not authorize staging, committing, pushing, merging, or PR creation unless the user explicitly approved that current-turn action.

Legacy Claude tmux Layer

tmux is optional and only manages terminals for the tty backend. It does not replace the worker command, relax model requirements, change repo root, widen scope, or count as acceptance evidence.

The tmux session is persistent; worker windows are not. Treat each worker-<task_id> window as a disposable execution slot. After the worker's final response and handoff have been reviewed, close the window unless there is an explicit follow-up reason and short time-to-live.

Before opening another worker window, list existing worker-* windows, close accepted/rejected/stale workers, and make sure the session will stay under eight worker windows. If a session already has eight worker windows, clean up or consolidate before dispatching more work.

For many small independent subtasks, prefer cc-print fan-out or one accountable Claude Code parent worker using internal subagents (backend: cc-internal-subagents, subagent_policy: implementation_allowed) instead of opening many tmux TTY windows. Reserve multiple worker windows for truly independent lanes that need separate live observation, model/runtime isolation, or separate handoffs.

After sending a worker prompt, verify the dispatch submission gate before waiting on the worker. Seeing ACK_TEAM_LEAD_WORKER <task_id>, activation output, or a blocking activation error is required. For tmux workers, use deterministic send mechanics such as tmux buffer paste followed by tmux send-keys C-m, then still verify the ACK gate. If the first short ACK window is quiet, send Enter at most once more when the prompt appears unsubmitted; if the second window is also quiet, report dispatch failure instead of treating the worker as slow.

Recommended tmux launch shape:

tmux new-session -d -s <TMUX_SESSION> -n lead-shell -c <REPO_ROOT>
tmux new-window -t <TMUX_SESSION> -n worker-<task_id> -c <REPO_ROOT>
tmux attach -t <TMUX_SESSION>

Use tmux capture-pane for liveness and recovery context, not for accepting work. It is read-only observation, not permission to send status pings to a slow but safe running worker. Acceptance still requires the full worker response and handoff report.

Claude Code itself is interactive in a tmux pane. Commands launched from inside Claude Code's Bash tool may still not have an interactive TTY, so arrow-key menus, auth prompts, curses tools, psql, and similar CLIs should use non-interactive flags/config/stdin or be run manually in a dedicated tmux pane.

Legacy Claude /goal Layer

Claude Code /goal is optional and only keeps a long worker session pointed at a completion condition. It is not a planner and not acceptance evidence.

Do not set /goal before the worker marker. First send the [TEAM_LEAD_WORKER_V1] prompt, let the worker confirm repo root, backend, selected model tier, scope, and handoff path, then send /goal <condition> as a separate follow-up when useful. A good condition names the handoff path, validation evidence, scope boundaries, risks, shared-log notes when relevant, and a stop bound such as or stop after 8 turns.

Active Plan Ledger

Multi-turn initiatives that need durable Done / Not Done memory live in docs/active-plans/<work_id>.md, with an index in docs/active-plans/README.md. This is the middle tier between an inline chat summary and a full epic-docs charter:

• Inline summary — fine for tiny one-turn work.
• Active plan — used when work spans turns or has deferrable items.
• Epic docs — used for non-trivial long-running scope with formal milestones.

The ledger is memory and accountability only. It does not authorize direct code edits, does not replace worker handoffs, and does not weaken validation. The Codex lead owns updates by default; workers contribute a concise "Plan ledger note for lead" in their handoff, and the lead serializes the change after review. See AGENTS.md §"Persistent Active Plan Ledger" for the full rule body and .agents/skills/team-lead-mode/references/active-plan-template.md plus active-plans-readme-template.md for reusable seeds.

Shared Log And Changelog Policy

If several workers edit a shared changelog, release note, migration log, or status ledger, they will conflict. The generic rule is:

• Workers do not edit shared logs directly in marker mode.
• Workers write a concise "Shared log note for lead" in the handoff.
• The lead updates the shared log after review and validation.

This keeps concurrent worker lanes independent and preserves final narrative quality.

What You Must Add Per Project

This package deliberately omits:

• Repository architecture.
• Dev commands.
• Ports and service URLs.
• Language/framework rules.
• Product safety rules.
• Generated contract rules.
• Database and migration rules.
• Deployment policy.
• Authentication or test credentials.
• Domain-specific validation recipes.
• Project-specific task splitting.

Put those in the target repo's own AGENTS.md, CLAUDE.md, and optional project-specific reference files. The team-lead protocol should coordinate those rules, not own them.

Publishing Checklist

Before making this repository public:

• Confirm the repository license remains Apache License 2.0.
• Decide whether runclaude is a documented dependency or a local wrapper users must replace with their Claude Code command.
• Remove any local paths, project names, ports, credentials, and private references from examples.
• Run the residual-coupling scan in the validation section below.
• Add a short quick-start section for your intended audience if needed.

License

This project is licensed under the Apache License 2.0. You may use, modify, distribute, and use it commercially under the terms of the license.

Validation

Useful local checks:

find . -type f | sort
rg -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'
rg -n '<PROJECT_NAME>|<REPO_ROOT>|<WORKER_MARKER>|<WORKER_COMMAND>|<TMUX_SESSION>'

The first rg should return nothing in the standalone package. The second should return the template placeholders that a downstream project must replace.