• When 2 or more local Agents/Codex/Claude sessions need to work in parallel.
• When tasks require independent worktrees, independent branches, and independent PRs.
• When the PM session needs to start, monitor, correct, and wrap up multiple workers.
• When simple tasks need to be routed to Claude Code, Codex, OpenCode, or other CLI workers to control token consumption of the main session and quota consumption of different models.

• For single short tasks, single-file modifications, or one-time Q&A.
• For task status management, responsible person tracking, or dependency management: use

  cross-agent-coordination

  .
• For branch naming, commit formatting, PR merge, push, or conflict resolution: use

  git-workflow

  .
• For external Agent email triggers: use corresponding external collaboration/email Skills.

• User explicitly mentions

  tmux

  ,

  independent session

  ,

  start workers

  ,

  multi-agent parallelism

  ,

  you act as PM/orchestrator

  ,

  don't implement directly

  , or project rules require tmux/independent session.
• Tasks require independent quota, long context, continuous background operation, manual takeover, or simultaneous execution of 2 or more local workers.

1. Create or confirm the isolated worktree, semantic branch, and Session Context path.
2. Start the tmux session; Claude official

   --worktree --tmux

   can be used as a dedicated equivalent entry for Claude.
3. Use

   tmux has-session

   /

   tmux list-sessions

   /

   claude agents --json

   to verify session survival, and confirm that the pane cwd or agent cwd points to the target worktree.
4. Send a Bootstrap-only prompt or Full worker prompt to the worker, which must include Branch, Worktree, Session Context, Runtime Profile, Allowed files, Forbidden files, and verification commands.
5. Confirm that

   STATUS.json

   appears within 1-2 minutes; if not, only send checkpoint-only corrections or restart the worker, do not directly take over business implementation.

• When tmux is explicitly required, Agent Teams, Subagent, or PM Direct Processing are not equivalent substitutes; unless the user explicitly agrees to downgrade.
• When independent session is explicitly required but tmux is not specified, tmux is used by default; Claude official

  --worktree --tmux

  is available. Agent view/Agent Teams can only be substituted if they can prove independent background sessions, independent cwd/worktree, and inspectable status.
• When the gate fails, the PM must report the blockage and failure points; only orchestration layer files such as worker prompts, Skill documents, monitoring scripts, or local collaboration configurations can be directly modified.
• If the PM triggers an exception to directly process business code, the final report must state the exception reason, specific gate failure points for not using the session, and whether the user approved the downgrade.

• If the user explicitly requires the current session to act as PM/orchestrator/multi-agent orchestrator, the PM does not directly write business code by default; if §2.1 is triggered simultaneously, the startup gate must be passed first.
• The core value of PM lies in token efficiency, model/quota routing, multi-threaded execution, scope control, and acceptance wrap-up; task implementation is prioritized to be assigned to worktree workers, independent CLI sessions, Agent Teams, or Subagents.
• Exceptions where PM can directly modify code: extremely small tasks with no parallel value, user explicitly requires PM to do it directly, worker fails to correct continuously and only narrow-range wrap-up remains, or immediate repair of orchestration documents/configurations generated by PM itself. Under explicit tmux/independent session requirements, these exceptions must first obtain user confirmation or record gate failures.
• If the PM bypasses exceptions to directly modify code, the reason should be explained in the final report; regular implementation should be completed through worker outputs, PM corrections, and PR reviews.

• It doesn't matter what the current main session is; by default, "who starts the orchestration, who is the PM".
• When needing to start Claude Code via a third-party Anthropic-compatible API, select Claude Code as the worker backend; this is the default quota mode for Claude Code workers.
• Only when the user explicitly requires Claude subscription/OAuth, use

  claude-oauth-*

  profiles and clear third-party provider environment variables.
• When needing to consume Codex/OpenAI quota or use Codex configurations, select Codex as the worker backend.
• When needing to consume configured providers/models of OpenCode, or use OpenCode's

  opencode run

  /

  opencode acp

  capabilities, select OpenCode as the worker backend.
• When needing to consume quota from WorkBuddy/CodeBuddy or QoderWork platforms (reuse desktop login state, zero API Key, includes daily free models), select

  codebuddy

  /

  qoderwork-cn

  as the worker backend; this is a cross-tool exception (§2.3), suitable for quota diversion or evaluation fan-out. Both are uniformly generated by

  render-runtime-profile.sh

  (including Qoder's SDK variable clearing, CodeBuddy's

  -y

  ); external CLI backend worker spawn uses snapshot-copy-into-worktree (DEC-037) by default for self-containment.
• Other Agents can also serve as custom CLI workers as long as they can be started with one command and read/write files in the specified cwd.
• When stable process lifecycle and manual takeover are required, prioritize

  tmux + worktree

  ; when §2.1 is triggered,

  tmux + worktree

  is the default execution layer, not a suggestion that can be silently skipped.
• ACP is only enabled when the adapter is stable and can output structured status; do not add uncertainty for the protocol when there is no adapter.

main_force.task_routing

concurrency

config/claude-provider-registry.example.json

opencode:<provider>/<model>

qoderclicn

backend_model_routing.qoderclicn

codebuddy

backend_model_routing.codebuddy

-y

This table does not list specific models—model and framework selection is personal preference (each person has different available provider/platform quotas). Specific models are all in

config/orchestration-personal.json

(yours) +

.example.json

(general template); this table only lists backend capabilities + model configuration field locations, and if missing, PM reads according to §2.4 personal preferences.

• When starting workers, PM must explicitly write

  Runtime Profile

  , settings/profile path, model source, and key environment variable handling methods, do not assume that Claude Code, Codex, and OpenCode share the same shell environment.
• For Claude Code third-party API providers, it is recommended to use the provider registry:

  config/claude-provider-registry.example.json

  describes

  base_url

  ,

  auth_token_env

  /

  api_key_env

  ,

  auth_type

  , and

  models

  for multiple providers; the real registry is placed in ignored local files, and real keys are prioritized in environment variables. The old single provider

  --settings <*.settings.json>

  path is retained for compatibility.
• Claude Code third-party API provider profiles must retain

  ANTHROPIC_BASE_URL

  /

  ANTHROPIC_AUTH_TOKEN

  /default model mapping; do not apply OAuth clearing commands. The registry mode dynamically generates these env via wrapper, eliminating the need to maintain a settings file for each model.
• Claude Code third-party API providers must explicitly pass

  --model <provider-model>

  , and the settings file should also include

  ANTHROPIC_MODEL

  /

  ANTHROPIC_MODEL_NAME

  . Only passing

  --settings

  is not enough to isolate the user-level

  ~/.claude/settings.json

  or inherit

  ANTHROPIC_MODEL

  in the environment; actual tests show mixed states where settings point to GLM, but the interface and actual default model still display MiniMax.
• By default, Claude Code third-party API providers generate the

  scripts/claude-provider-env.sh

  wrapper command via

  scripts/render-runtime-profile.sh

  . The wrapper first clears inherited Claude/Anthropic provider routing variables, then imports env from the target settings JSON, or parses env from the provider/model intent in the registry; supplements

  ANTHROPIC_AUTH_TOKEN

  /

  ANTHROPIC_API_KEY

  , sets

  CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST=1

  , and injects

  --setting-sources project,local

  into

  claude

  to avoid provider/model pollution from user-level

  ~/.claude/settings.json

  for this worker.
• Only use

  --no-provider-env-isolation

  to bypass the wrapper during troubleshooting; PM must record this exception in the Wave plan and

  runtime.env_isolation

  of

  METADATA.json

  , and check the banner/STATUS provider after startup.
• Only Claude Code subscription/OAuth profiles clear third-party provider environment variables to avoid mistakenly using external APIs.
• Codex/OpenAI workers, OpenCode workers, and custom CLI workers use their respective profiles; do not treat Anthropic provider environment variables as general worker environments.
• Worker bootstrap must write

  which claude/codex/opencode

  , version number, cwd, key profile name, and runtime information such as

  node/npm/python/cargo

  into

  STATUS.json

  , making it easier for PM to judge whether "different environments" affect the task.

• Same-host workers share a set of auth/settings/context conventions, with the lowest startup and troubleshooting costs; cross-tool introduces different profiles, different env, different CLI behaviors, increasing orchestration layer uncertainty.
• The core benefits of multi-agent are parallelism + scope isolation (independent worktree/session) + PM wrap-up, not "cross-tool". Parallel value comes from independent worktree/session/quota lane, regardless of whether tools are changed.
• Cross-tool is only used when there are clear reasons (see below), not by default.

• When Claude Code PM starts Claude Code workers, the worker

  claude

  process inherits the PM's provider env (third-party API's

  ANTHROPIC_AUTH_TOKEN

  /

  ANTHROPIC_BASE_URL

  , or OAuth session). Even if the

  .claude/settings.json

  in the target worktree is empty or default, the worker can run using the PM's provider, no additional

  config/*.settings.json

  required.
• Only when multiple Claude Code workers need to be assigned to different providers (e.g., some use minimax, some use glm), use different settings files to distinguish slots; at this time, all are still Claude Code workers, no cross-tool.
• The standard for judging "whether the worker has obtained the provider env": worker bootstrap writes available

  claude

  version and provider source into

  STATUS.json

  ; PM decides whether to supplement settings or downgrade only when seeing empty provider source or 401/403 errors, instead of defaulting to cross-tool first.

• The current host provider's quota/rate limit/concurrency slots are insufficient to support this Wave, and cannot be solved by "reducing concurrency/splitting to next Wave".
• A certain worker task is obviously more suitable for the model capabilities of another tool (e.g., ultra-long context research, specific code stack).
• The user explicitly requires mixed workers (e.g., "Claude Code acts as PM, rewrite workers use Codex").

• Configuration Path:

  config/orchestration-personal.json

  (in the skill directory, but gitignore and not stored in the repository—each person places their actual preferences locally; do not commit to the repository to avoid solidifying personal models/frameworks into the general skill.

  .example.json

  is the general template stored in the repository).
• Template Path:

  config/orchestration-personal.example.json

  (schema documentation / clean template for fork users).
• Reading Timing: PM reads

  config/orchestration-personal.json

  before assigning workers; if missing, falls back to

  .example.json

  defaults.
• Scope: Only declares "preferences" (host, model rotation, codex policy, default model for cross-tool backends), not real tokens/keys/endpoints—those are still managed by

  config/claude-provider-registry.*.json

  .

main_force.host

claude-code

codex

opencode

claude-code

main_force.task_routing.high_end

main_force.task_routing.simple_multimodal

main_force.task_routing.default

concurrency.max_per_provider

concurrency.overflow_strategy

codex_policy.policy

explicit_only

allowed

allowed

backend_model_routing.<backend>.default_models

<backend>

• When

  codex_policy.policy = "explicit_only"

  , PM does not actively route any workers to Codex; only when the user explicitly says "use Codex" in the current round is it unlocked, and written into the Wave plan.
• This is independent of §2.3 same-host priority: even if §2.3 same-host tool is Codex host, PM still judges whether to assign workers to Codex according to this policy.
• To restore Codex availability by default, change

  policy = "allowed"

  .

• §2.2 backend table → §2.4 personal preferences → §3.3 project-level provider slot defaults → final backend/model selection. Priority: §2.3 (do not actively cross-tool) overrides §2.2 (multi-backend), §2.4 personal preferences override §2.2 default model table, §3.3 project-level provider slot plan overrides §2.4 general host.
• §2.4 field naming is deliberately not conflicting with §3.3 project-level provider slots: project-level slots write "which slot to use for which worker in this Wave" (including model, max_concurrency); §2.4 writes "my personal preference for default host/which backend for which model". The former is implemented in the Wave plan, the latter in PM's task assignment decisions.

scripts/render-runtime-profile.sh

main_force.task_routing

--model

codex_policy.policy

backend_model_routing.<backend>.default_models

1. Read Task Sources and Project Configurations: If the project provides

   .claude/orchestration.config.json

   or equivalent configuration, first read trunk, task sources, verification commands, copyable configurations, and hook boundaries; then use

   cross-agent-coordination

   to judge executable items, dependencies, and ownership.
2. Group Tasks First: Do not default to one worker per Issue. Tasks with overlapping file scopes, belonging to the same chapter/module, or having dependency chains should be grouped and executed sequentially.
3. Judge Parallel Safety: Only split into multiple worktrees for parallel execution when file scopes are clear, no shared migration/lock files/schema, and acceptance criteria are independent.
4. Judge Whether to Trigger Anti-Escape Gate: As long as the user or project explicitly requires tmux/independent session/starting workers, execute according to §2.1; do not write business code before the gate is passed.
5. Select Worker Backend and Runtime Profile: Select Claude Code/Codex/OpenCode/custom CLI/shell/ACP according to task complexity, current quota, model preferences, and whether independent processes are needed.
6. PM Creates Isolated Environment: By default, PM creates worktree, branch, and session context directory, then passes the path to the worker; only when Claude Code official Agent Teams/agent view explicitly uses its own

   --worktree

   capability is Claude Code allowed to create, but PM still needs to verify the branch, path, and isolation status.
7. Start Worker and Verify Gate: Give each worker clear target files, allowed modification scope, verification commands, session context directory, commit and PR requirements; confirm session survival, correct cwd/branch,

   STATUS.json

   appears, or bootstrap correction has been sent.
8. PM Inspection: Prioritize viewing

   .claude/agent-sessions/<session-id>/STATUS.json

   ,

   RESULT.md

   ,

   PATCH_SUMMARY.md

   , git status, commit/PR status; for Claude official Agent Teams, prioritize reading

   ~/.claude/teams/<team>/

   and

   ~/.claude/tasks/<team>/

   , with

   claude agents --json

   , tmux pane, or agent view as fallback observation. Intervene when off-topic, blocked, scope expanded, or no phased commits.
9. PM Accepts Instead of Writing: PM performs scope check, test review, and review on worker results; when problems are found, prioritize sending correction instructions or assigning to reviewer/another worker, do not default to modifying business code by yourself.
10. Wrap-Up: After the worker commits and opens a PR, PM performs scope check, triggers review, merges and cleans up according to

    git-workflow

    .
11. PM Must Perform Practical Verification: Before the worker claims "completion" for any software function modification (regardless of L1/L2/L3), PM must actually start the dev server (Vite dev/Tauri dev/corresponding entry), use Playwright MCP or screenshots to actually open the application, click buttons, switch tabs, adjust windows, input text, and write verification evidence (DOM measurement, key assertions, screenshots) into

    goal-contract.md

    or corresponding

    RESULT.md

    . Claiming "completion" only because typecheck/unit test/lint/build all pass is insufficient—these only prove "code can compile", not "function really works".

• wave_id

  , base ref, goal, worker list, branch/worktree/session for each worker.
• Type of each worker:

  ui-wiring

  (low-risk UI wiring),

  contract-extension

  (shared contract/dependency change),

  tauri-command

  (Rust/Tauri/native dependency),

  docs/research

  ,

  custom

  .
• Runtime profile/provider/model/registry or settings/profile path/quota source/concurrency slot. When there are more than 3-4 workers, do not press them on a single API provider or the same provider key; should divert across Claude providers, Codex/OpenAI, OpenCode, local/OSS profiles.
• Shared risks:

  package.json

  , lock files,

  src-tauri/

  ,

  src/shared/

  , global layout, DEC number, or the same module entry.
• Expected number of PRs, wrap-up order, entry conditions for next Wave.

• A slot represents a concurrent quota lane:

  backend + settings/profile path + provider + model + max_concurrency

  .
• For Claude Code third-party providers, it is recommended to distinguish by registry + provider id + model alias, e.g.,

  config/claude-providers.local.json

  +

  <provider>/<model-alias>

  ; old paths can also be distinguished by specific settings files, e.g.,

  config/<your-provider>.settings.json

  . Real registry/settings files remain locally ignored and not submitted; specific provider/model used see personal config.
• Codex is distinguished by Codex profile/model; OpenCode is distinguished by

  provider/model

  profile; custom workers specify the actual command source.
• By default, a maximum of 3 workers are placed in the same provider/settings file; only when tasks are low-risk and the previous Wave performed stably can it be increased to 4. When 5-6 workers are needed, prioritize splitting to the second provider or Codex/OpenCode/local profile.
• High-risk tasks (shared contracts, Tauri/Rust, native dependencies, lock files) are prioritized to profiles with the best instruction compliance and verification performance in the previous Wave, and usually only 1 worker is opened per high-risk shared domain.
• If there is only one available settings/profile locally, do not start 5-6 workers to凑 numbers; reduce the concurrency cap to 3-4, and remaining tasks enter the next Wave.

config/<provider-a>.settings.json

<provider-a>-1

config/<provider-a>.settings.json

<provider-a>-2

config/<provider-b>.settings.json

<provider-b>-1

config/<provider-b>.settings.json

<provider-b>-2

codex:<profile>

codex-1

<provider/model or command label>

opencode-1

merged

done-unmerged

blocked

deferred

restarted

templates/orchestration-goal.md

• Task source: e.g.,

  docs/TASKS.md

  , GitHub Issues, issue file in project configuration.
• Success criteria: e.g., no executable pending tasks within the target scope, all started workers enter

  merged

  /

  done-unmerged

  /

  blocked

  /

  deferred

  , trunk verification passes, documents are synchronized.
• Autonomy level:

  plan-only

  (only plan the next Wave),

  auto-launch

  (can automatically start the next Wave),

  auto-review

  (can automatically review worker results),

  auto-merge

  (merge according to

  git-workflow

  when project rules allow).
• Upper limits: maximum number of waves, maximum workers per round, total workers, budget/time, provider concurrency slots.
• Continue conditions and stop conditions.

/goal

/goal

1. Read the task source, close completed items, identify executable pending tasks, dependencies, file scopes, and shared risks.
2. Confirm that the current Wave has no unprocessed failed/blocked workers, unaccepted PRs, base drift, conflicts, trunk verification failures, or sensitive/destructive operations.
3. Adjust concurrency based on the provider/model evaluation of the previous Wave: maintain or slightly increase if cleanly passed, reduce concurrency if conflicts, scope overstepping, verification failures, or rate limits occur.
4. If there are still safely parallelizable tasks, create the next Wave; if only high-conflict/high-risk tasks remain, reduce to 1-2 workers or stop to request user confirmation.
5. If success criteria are met, write final goal summary and stop.

• All workers in the previous Wave are

  merged

  ,

  done-unmerged

  ,

  deferred

  , or clearly

  blocked

  and will not affect the next Wave.
• All merge actions have been processed according to

  git-workflow

  , base ref, local trunk, and remote trunk are consistent or differences have been clearly recorded.
• Required verifications pass; skipped verifications have clear reasons and do not affect the next Wave.
• Allowed/forbidden files for the next batch of tasks are clear, and there are no unresolved shared lock files, schema, global layout, or DEC number race.
• Provider concurrency slots are sufficient, and there is no continuous rate limit, long delay, or degradation of worker instruction compliance.

• Any worker is

  failed

  ,

  blocked

  and affects the next Wave, or continuous correction fails twice.
• PR conflicts, base drift, trunk verification failure, unstable tests, insufficient merge permissions, or unclear GitHub/CI status.
• The next batch of tasks requires user product judgment, destructive file operations, sensitive network processing, key/privacy processing, or automatic merge not authorized by project rules.
• Task source is ambiguous, dependencies are not met, file scopes are highly overlapping, or only high-risk tasks such as shared contracts/lock files/Tauri command remain.
• Reach the wave, worker, time, budget, or provider upper limits in the Goal Contract.

.claude/orchestration.config.json

templates/project-config.json

• Trunk/base ref, task source, default worktree/session context path.
• Verification commands split by worker type.
• Default provider slot plan, referenced by Goal/Wave startup list.
• Non-sensitive configuration files that can be copied to worktree, e.g.,

  .npmrc.example

  or read-only templates.
• Post-create/pre-merge hook commands.

config/orchestration-personal.json

.claude/orchestration.config.json

Example: Personal preference host=claude-code + model=<your model>; project-level provider slot plan writes "W3/W4 of this Wave use <a certain provider>"—then W3/W4 use this provider, other workers still follow personal preferences. The two do not conflict and should not copy each other; project-level does not write personal preference fields (avoid dotfile into repository).

• Never copy

  .env

  , real settings, tokens, keys, cookies, certificates, or account credentials by default.

• allowed_config_copy

  only allows non-sensitive files; must stop and report when

  forbidden_config_copy

  is hit.
• Hooks are only declarations by default. PM only runs them when authorized by project rules or user explicitly; should display the command before running, and dry-run if necessary.

• spawn-worker.sh

  does not automatically read project configuration, copy configuration, or execute hooks, avoiding upgrading optional conventions into implicit side effects.
• If configuration is missing or fields are unclear, PM returns to Skill defaults: trunk=

  main

  , no configuration copied, no hooks run, only use verification commands explicitly listed in worker prompts.

spawn-worker.sh

runs/<variant>/

wr-

wr-v0107-<model-id>-ch08

pwd

git branch --show-current

STATUS.json

git diff

• PM writes the

  {branch, worktree, session, run-dir}

  quadruple once in the Wave plan, and all subsequent

  tmux send-keys

  /correction/wrap-up commands are copied from this quadruple, not re-typed or simplified midway.

• scripts/spawn-worker.sh

  internally derives from a single source:

  BRANCH

  →

  safe_branch

  (worktree-safe) → default

  WORKTREE=.claude/worktrees/tmux-<safe_branch>

  →

  SESSION_CONTEXT=<worktree>/.claude/agent-sessions/<session>

  . PM only needs to ensure that the passed

  --branch

  and

  --session

  are consistent and complete, and the helper will not decouple worktree from branch.
• The naming quadruple for cross-model/evaluation scenarios includes model identification (see model-aware naming convention of

  agent-eval-lab

  ), and the entire link uses the same

  variant_slug

  , avoiding PM using different abbreviations in different links.

docs/ch01-agent-intro
research/issue-13-ch08-materials
fix/agent-session-shell

.claude/worktrees/tmux-ch01-agent-intro
.claude/worktrees/team-agent-session-shell
.claude/worktrees/subagent-copyedit-ch02

tmux-

subagent-

team-

agentteam-

git-workflow

git worktree add .claude/worktrees/tmux-ch01-agent-intro -b docs/ch01-agent-intro
git worktree add .claude/worktrees/team-agent-shell -b fix/agent-session-shell

templates/worker-prompt.md

• Bootstrap-only prompt: only creates

  STATUS.json

  , suitable for the first message of high-latency providers or high-effort models.
• Full worker prompt: organized by Context/Background/Mission/Scope/Deliverables/Process/Verification/Autonomy/Out of Scope/PM Correction, close to the writing style when assigning subagents.

Session Context/STATUS.json

templates/worker-prompt.md

.task-issueN.md

.task

.task

• Isolation Gate: Worker first confirms

  pwd

  /

  git branch

  , otherwise may modify by mistake in main or wrong worktree.
• Heartbeat cadence (force update STATUS every 10 minutes, even write

  phase=thinking-deep

  if no progress): PM relies on

  STATUS.updated_at

  to detect silent workers. Omitting it causes workers to write initial STATUS once and never update again, distorting PM inspection signals and making it impossible to judge stuck points.
• Commit Cadence + "commit is a mandatory wrap-up step": Even if the task requires "no push/no PR", workers must first

  git add

  +

  git commit

  their outputs. Omitting it causes workers to modify files without committing, and PM verifies empty diff when wrapping up with

  git diff --check main...HEAD

  (HEAD is still at base, false pass), and PM has to commit for workers. Especially after rebase/reset, reconfirm that changes have been committed.
• Canonical terminal status (literal

  status="done"

  ): The sentinel state machine matches literal

  done

  . Omitting it causes workers to write synonyms like

  completed

  /

  finished

  , sentinel does not exit, PM is not woken up by harness, and worker becomes orphan until

  --max-wait

  timeout.

.task-issueN.md

templates/worker-prompt.md

• check-dependencies.sh

  : Perform preflight once before starting Wave on a new machine.

• claude-provider-env.sh

  : Registry/settings-derived env isolation wrapper for Claude Code third-party provider workers.

• render-runtime-profile.sh

  : Render backend/settings/profile/model/slot and startup command for each worker.

• spawn-worker.sh

  : Create worktree, Session Context, and tmux session.

• sentinel.sh

  : One per worker, PM starts with

  run_in_background=true

  , wakes up PM when worker reaches terminal state (see §7.2).

• pm-monitor.sh

  : Inspection for multiple workers/Waves; use

  wait-worker.sh

  only for single worker or host wake-up.

templates/project-config.json

worktree-status.sh

clean-worktree.sh

smoke-tmux-worker.sh

lint-wait-script.sh

terminal-split.sh

scripts/spawn-worker.sh

templates/worker-prompt.md

STATUS.json

scripts/render-runtime-profile.sh

eval "$(bash scripts/render-runtime-profile.sh \
  --backend claude-code \
  --runtime-profile minimax \
  --api-provider minimax \
  --model m3 \
  --provider-slot minimax-1 \
  --provider-registry config/claude-providers.local.json)"

bash scripts/spawn-worker.sh \
  --project /path/to/repo \
  --branch docs/ch01-agent-intro \
  --session legal-ch01 \
  --worker-backend "$WORKER_BACKEND" \
  --runtime-profile "$RUNTIME_PROFILE" \
  --api-provider "$API_PROVIDER" \
  --model "$MODEL" \
  --provider-slot "$PROVIDER_SLOT" \
  --env-isolation "$PROVIDER_ENV_ISOLATION" \
  --verify-cmd 'npm run typecheck' \
  --command "$WORKER_COMMAND"

tmux has-session

git branch --show-current

Session Context/METADATA.json

Session Context/STATUS.json

• Claude Code third-party provider (recommended registry): Use

  render-runtime-profile.sh --backend claude-code --provider-registry <local-registry.json> --api-provider <provider-id> --model <model-alias>

  to generate command; by default wraps

  scripts/claude-provider-env.sh

  , and parses model alias into real

  claude --model <provider-model>

  . Real registry is not submitted; template see

  config/claude-provider-registry.example.json

  .
• Claude Code third-party provider (compatible settings): Can also use

  render-runtime-profile.sh --backend claude-code --settings <local-provider.settings.json> --model <provider-model>

  to generate command; real settings are not submitted; template see

  config/claude-provider-settings.example.json

  . After startup, must check banner model name; if still displays user default provider, stop worker first to troubleshoot registry/settings/wrapper/environment inheritance.
• Claude Code subscription/OAuth:

  env -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN -u ANTHROPIC_BASE_URL claude --permission-mode auto

  .
• Claude Code batch processing: Use

  render-runtime-profile.sh --backend claude-code --mode batch --settings <settings> --model <provider-model> --prompt-file /tmp/task.prompt.md

  to generate; third-party providers also wrap

  claude-provider-env.sh

  by default, and batch output is automatically wrapped with

  bash -lc

  to handle redirection.
• Codex:

  codex exec -a never -s danger-full-access - < /tmp/task.prompt.md

  .
• OpenCode:

  opencode run --format json --model <provider/model> "$(cat /tmp/task.prompt.md)"

  , or interactive

  opencode --model <provider/model>

  .
• WorkBuddy/CodeBuddy (

  codebuddy

  ): Use

  render-runtime-profile.sh --backend codebuddy --model <platform model> [--no-mcp] [--dangerously-skip-permissions]

  to generate; uses WorkBuddy desktop login state and platform quota, no API Key required. See

  references/08-workbuddy-cli-worker.md

  for details.
• QoderWork CN (

  qoderclicn

  ): Use

  render-runtime-profile.sh --backend qoderwork-cn --model <platform model> [--no-mcp] [--dangerously-skip-permissions]

  to generate; script automatically prepends

  env -u

  to clear SDK variables and handles binary paths with spaces. See

  references/07-qoderwork-cli-worker.md

  for details.
• Custom CLI: Any command that can run in specified cwd, receive prompt, and save checkpoint to disk.

<

bash -lc

spawn-worker.sh:305

tmux new-session -d -s "$SESSION" -c "$WORKTREE" "$COMMAND"

<

>

|

&&

--command

<

bash -lc 'real-command < /tmp/prompt.md'

--max-wait

--command 'claude -p < /tmp/x.md'

--command "bash -lc 'claude -p < /tmp/x.md'"

-p

-p

Autocompact is thrashing

--max-wait

claude

tmux send-keys

--max-turns

STATUS.json.updated_at

pm-monitor.sh

claude agents

claude agents --json

--worktree --tmux

--bg

/bg

claude --help

claude agents --help

workdir

• Whether worktree has files saved to disk, commits, PRs.
• Whether

  .claude/agent-sessions/<session-id>/METADATA.json

  records base ref, runtime profile, provider slot, verification commands, and PR placeholder.
• Whether

  .claude/agent-sessions/<session-id>/STATUS.json

  is updated, whether it reports blocked/needs_input/done.
• Whether

  .claude/agent-sessions/<session-id>/RESULT.md

  and

  PATCH_SUMMARY.md

  exist, whether the summary is sufficient for PM to accept without reading full logs.
• Whether tmux pane reads materials for a long time, waits for confirmation, goes off-topic online, repeatedly plans without execution.
• Whether workers expand modification scope or touch shared files.
• Whether PR diff only covers declared scope.

• Continue waiting when there is continuous output, checkpoint update, or file growth.
• When

  Session Context/STATUS.json

  still does not appear 1-2 minutes after startup, first send checkpoint-only correction; if still no response, interrupt current thinking and resend bootstrap instruction, do not directly take over implementation.
• When no files are saved for a long time but still planning, first send a narrower command "write target file first".
• When workers skip 10-15 minutes STATUS heartbeat or 30-60 minutes phased commit, PM actively sends correction, requiring immediate STATUS update or submission of current verified phase; if no STATUS/commit/file progress change within 5 minutes, upgrade to restart worker, assign reviewer, or PM narrow-range wrap-up.
• When mild off-topic, scope expansion, starting to fix environment/dependencies, waiting for confirmation, or verification method deviation is found, prioritize sending correction instructions via tmux/agent view/inbox, let workers return to scope execution by themselves.
• Only stop the session and take over by PM when continuous correction fails twice, workers continue to touch forbidden scope, prepare to execute destructive Git/file operations, leak sensitive information, or cannot recover in the original session.
• Retain worktree and

  Session Context

  before failure, restart, or stop, avoid losing saved outputs.

tmux send-keys -t legal-ch01 -l -- "PM correction: stop dependency/runtime changes now. Return to ISS-017 only. Do not modify package files or environment config. Update .claude/agent-sessions/legal-ch01/STATUS.json with needs_input=false and continue with the OCR quality report scope."
sleep 0.1
tmux send-keys -t legal-ch01 Enter

references/03-checkpoint-files.md

templates/checkpoint-status.json

templates/checkpoint-result.md

templates/checkpoint-patch-summary.md

bash scripts/pm-monitor.sh \
  --project /path/to/repo \
  --team-dir ~/.claude/teams/team-name \
  --tasks-dir ~/.claude/tasks/tasks-uuid \
  --claude-agents-cwd /path/to/repo \
  --wave-id wave-5 \
  --commit-stale-threshold 1800 \
  --progress-stale-threshold 1800 \
  --interval 60 \
  --log-file .claude/agent-sessions/pm-monitor/events.log \
  --branch docs/ch01-agent-intro:legal-ch01

• Do not let PM main session manually read worker logs every few minutes; this will offset token efficiency of multi-agent.
• Use

  pm-monitor.sh --once

  for lightweight check, run once by PM when needing to judge whether to intervene, only read event lines.
• For long tasks, run

  pm-monitor.sh --log-file ...

  in independent shell/tmux/background job, script continuously writes event logs; PM only reads a small amount of logs when status changes, user asks, PR wraps up, or logs show

  AGENT_NEEDS_INPUT

  /

  CHECKPOINT_STALE

  /

  CHECKPOINT_TEST_FAILURE

  .
• Current script only responsible for outputting events and writing logs; whether to automatically wake up PM depends on whether the host environment provides automation/monitor/webhook. When no host wake-up capability, default to

  --once

  or low-frequency reading of log tail, still saves context compared to repeated foreground inspection.

• STATUS.json

  only records structured signals necessary for PM decision-making, detailed implementation instructions continue to be written in

  RESULT.md

  and

  PATCH_SUMMARY.md

  .
• Use

  scripts/worktree-status.sh

  for read-only overview of single worker; use

  scripts/clean-worktree.sh

  for cleanup, default dry-run, explicit

  --execute

  required for real deletion.

scripts/wait-worker.sh

pm-monitor.sh

STATUS.json

RESULT.md

PATCH_SUMMARY.md

done

failed

blocked

stopped

• METADATA.json

  is static context written by PM at startup, records base/runtime/provider/verification, not used as completion judgment.

• STATUS.json

  /

  RESULT.md

  /

  PATCH_SUMMARY.md

  are main protocols for completion, blockage, verification, and wrap-up.

• tmux capture-pane

  is diagnostic window, only read tail output when checkpoint is missing, expired, terminal, or explicitly requested.
• Do not use tmux pane text to judge task completion; completion criteria are still checkpoint, git diff, verification, and PR status.

• Bash background/run-in-background can only let the waiter run in the background, does not guarantee triggering or waking up current PM/agent session; especially when multiple workers are waiting simultaneously, no completion message may be returned.
• Do not treat background Bash as a reliable completion notification mechanism. At most, it serves as a log writer or manually viewable background job; PM still must rely on

  STATUS.json

  ,

  pm-monitor.sh --log-file

  ,

  wait-worker.sh --once

  , tmux/agent view explicit inspection to wrap up.
• Single worker can temporarily use background Bash to run

  wait-worker.sh

  , but must record log file or retain queryable command when starting; default to

  pm-monitor.sh --log-file

  for multiple workers/Waves, do not start a background wait for each worker and expect host to callback one by one.
• Limited Condition Exception: The Sentinel mode described in §7.2 is a "limited condition working variant" of this rule—single worker single sentinel, started with

  run_in_background=true

  , harness 100% re-invoke works. Before Wave 6 enables sentinel, still follow the above conservative judgment.
  bash

  bash scripts/wait-worker.sh \
    --worktree .claude/worktrees/tmux-ch01-agent-intro \
    --session legal-ch01 \
    --tmux-session legal-ch01 \
    --interval 30

• Codex CLI's background shell will not automatically push completion events back to current conversation; do not assume it is equivalent to Claude Code

  run_in_background

  .
• In Codex App, prioritize connecting

  wait-worker.sh --once

  to heartbeat automation of current thread; complete prompt see

  templates/codex-heartbeat-wait.md

  . Must use

  automation_update

  tool first when creating, modifying, or deleting automation, do not write raw RRULE manually.
• When no heartbeat/automation capability, Codex PM uses

  pm-monitor.sh --once

  or

  wait-worker.sh --once

  for low-frequency manual inspection; still use

  pm-monitor.sh --log-file

  for long tasks to continuously record events.

wait-worker.sh

pm-monitor.sh

Applicable: After Wave 6, each worker is matched with a sentinel, PM is woken up by harness task-notification event-driven, zero idle token consumption, retains multi-round correction capability. Design basis see

references/04-sentinel-design.md

; DEC-031 supersede DEC-030 limited condition judgment.

scripts/sentinel.sh

STATUS.json

done | failed | blocked | stopped

tmux kill-session

exit

run_in_background=true

undefined

done

--max-wait

STATUS.json

issue-XXX-status.json

cat

grep

• Short Tasks (single worker, expected <1h): ~22 minutes
• Long Pipelines (multiple workers/Wave/expected 1-4h): 10-15 minutes
• Avoid

  :00

  /

  :30

  on the hour: All users crowding on the hour will cause API congestion + trigger rate limits; use off-peak expressions such as

  3,13,23,33,43,53 * * * *

  (off-peak every 10 minutes) or

  7,29,51 * * * *

  (off-peak every 22 minutes).
• Do not be less than 10 minutes: cron re-invokes PM every time it fires (reads STATUS + git + pane), too frequent will offset token efficiency of multi-agent.

1. STATUS Signal: Both

   STATUS.json.updated_at

   and file mtime have not changed for > threshold (20min for long pipelines, 15min for short tasks).
2. Pane Signal:

   tmux capture-pane

   tail shows evidence of infinite loop (continuous repeated lines / "Levitating… Nmin" keeps rising but no new tool calls / error stack does not exit).

tmux send-keys

templates/cron-monitor-prompt.md

CronDelete

• §7.1

  pm-monitor.sh

  /

  wait-worker.sh

  : Read-only inspection tools actively called by PM (one-time or low-frequency log).
• §7.2 sentinel: Event-driven wake-up when worker reaches terminal state (captures done in seconds), main monitoring.
• §7.3 cron: Time-driven fallback (captures sentinel blind spots + freeze dual signals + sentinel failure).
• The three superimpose, not replace. After PM assigns workers, must hang two layers (sentinel + cron); sentinel is main, cron is fallback, if cron triggers and finds worker still advancing, only return one sentence, no big actions.

1. Immediately run mergeable check after raising PR:
   bash

   gh pr view <N> --json state,mergeable,mergeStateStatus,baseRefName,headRefName

   • mergeable=CONFLICTING

     /

     mergeStateStatus=DIRTY

     /

     baseRefName

     is behind: base has been preempted by doc-curator or other PRs. Immediately handle according to

     git-workflow

     's "base behind/conflict handling" decision table (update branch vs rebase vs close-and-reopen).

   • mergeable=MERGEABLE

     and base is latest: enter review process.
2. PM local main push immediately:
   • After PM commits docs/DEC in main directory, immediately

     git push origin main

     , avoid drift between local and origin/main.
   • After drift, push reports non-fast-forward, "same content but different history" introduced by squash merge will make git misjudge conflict, high recovery cost.
   • When seeing origin/main is ahead of local, first

     git fetch origin

     +

     git switch -C main origin/main

     (not

     git pull

     , squash commit will not automatically ff), then continue PM work.

1. Check

   git status --short

   ,

   git diff --check main...HEAD

   , PR diff scope.
2. When review is needed, cross-review, branch author does not review their own PR. Select review tool according to project type, do not default to code-review: use code-review subagent for code projects; use

   writing-reviewer

   (or project-specific review skill) for manuscripts/docs/writing projects; use corresponding content review for research/configuration PRs. Projects should specify which review skill to use in their

   AGENTS.md

   ; if not written, PM judges according to project nature, do not assume code-review.
3. Merge, push, write PR number into commit, close Issue, etc., follow

   git-workflow

   .
4. If PM review finds problems, prioritize sending review correction to original worker via tmux/agent view/inbox; worker should add fix commit, re-run verification, and update PR, do not default to PM writing instead.
5. After PM reviews correction commit, verification results, and PR diff, decide whether to enter merge.
6. After merging, clean up worktree/session, dry-run first then execute explicitly:

bash scripts/clean-worktree.sh --project /path/to/repo --branch docs/ch01-agent-intro --session legal-ch01
bash scripts/clean-worktree.sh --project /path/to/repo --branch docs/ch01-agent-intro --session legal-ch01 --execute

• references/01-model-selection-matrix.md

  : Model and execution mode selection.

• references/02-runtime-dependencies.md

  : Local dependency matrix split by mode and installation suggestions.

• references/03-checkpoint-files.md

  : Fields and templates of

  STATUS.json

  ,

  RESULT.md

  ,

  PATCH_SUMMARY.md

  .

• references/04-sentinel-design.md

  : Design and signals of PM inspection (sentinel) bash mode.

• references/05-legal-domain-patterns.md

  : Legal project decomposition examples (litigation/non-litigation phase models, task fields, Agent routing).

• config/claude-provider-registry.example.json

  : Claude Code third-party API provider/model registry template.

• config/claude-provider-settings.example.json

  : Claude Code third-party API provider settings compatibility template.

• references/06-agent-cli-reference.md

  : Complete reference manual for all local Agent CLIs (Claude Code/Codex/OpenCode/Hermes/Kimi/Gemini/QoderWork), including parameter quick reference, tmux worker template, cross-CLI comparison matrix, and selection suggestions.

• references/07-qoderwork-cli-worker.md

  : Feasibility study of QoderWork CLI (

  qoderclicn

  ) as worker backend, including CLI parameters, model list, SDK environment conflicts, tmux startup examples, and applicable scenarios.

• references/08-workbuddy-cli-worker.md

  : Feasibility study of WorkBuddy/CodeBuddy CLI (

  codebuddy

  ) as worker backend, including Kimi K2.6 manuscript worker actual test, permission mode, checkpoint/path deviation, and wrap-up rules.

• references/09-parallel-lessons.md

  : Practical pitfalls of tmux/Agent Teams.

• references/10-agent-teams-troubleshooting.md

  : Troubleshooting for Agent Teams/agent view/Claude native

  --worktree --tmux

  backend.

• Claude Code agent view:

  https://code.claude.com/docs/en/agent-view

• Claude Code worktrees:

  https://code.claude.com/docs/en/worktrees

• Claude Code CLI usage:

  https://code.claude.com/docs/en/cli-usage

• Claude Code checkpointing:

  https://code.claude.com/docs/en/checkpointing

• scripts/check-dependencies.sh

  : Checks core dependencies, backend CLI, GitHub CLI, and terminal split tools.

• scripts/claude-provider-env.sh

  : Constructs isolated env for this worker from Claude provider registry or settings JSON, shields user-level provider/model pollution.

• scripts/render-runtime-profile.sh

  : Generates worker command, prompt context, and spawn metadata according to backend/profile.

• scripts/spawn-worker.sh

  : Creates isolated worktree, Session Context, and tmux session, and outputs startup gate.

• scripts/pm-monitor.sh

  : Automatic PM inspection script, retains checkpoint files, Agent Teams inbox, tasks, Git SHA, PR status, tmux session, Wave, and multi-signal progress monitoring.

• scripts/wait-worker.sh

  : Single worker waiter, can connect to Claude Code background Bash or Codex heartbeat automation.

• scripts/worktree-status.sh

  : Single worker read-only overview, displays metadata, checkpoint, tmux, and git status.

• scripts/clean-worktree.sh

  : Safe cleanup of worker session/worktree, default dry-run, displays metadata summary before cleanup.

• scripts/smoke-tmux-worker.sh

  : Temporary repo end-to-end smoke test; only run after modifying Skill scripts.

• scripts/smoke-provider-settings.sh

  : Verifies one by one that

  config/*.settings.json

  can start Claude Code and return response; run after adding or modifying providers.

• scripts/lint-wait-script.sh

  : Lint for wait/monitor/custom wait scripts; only run after modifying wait/monitor scripts.

• scripts/terminal-split.sh

  : Optional visualization aid, retains support for iTerm2, Kitty, WezTerm, Warp, Ghostty, Zed, Terminal.app; default orchestration does not depend on it.

• templates/worker-prompt.md

  : Worker bootstrap and complete assignment prompt template.

• templates/orchestration-goal.md

  : PM-level continuous multi-Wave Goal Contract template.

• templates/project-config.json

  : Optional project-level orchestration configuration template, declares trunk, task source, verification commands, provider slot, non-sensitive configuration copy, and hook boundaries.

• templates/codex-heartbeat-wait.md

  : Codex App heartbeat inspection prompt.

• templates/wave-summary.md

  : Template for each Wave wrap-up and provider/model evaluation.

• templates/checkpoint-status.json

  :

  STATUS.json

  template.

• templates/checkpoint-result.md

  : Completion/failure result summary template.

• templates/checkpoint-patch-summary.md

  : Diff summary template for PR review.

1. Anti-escape gate not passed (§2.1), PM directly writes business code.
2. After spawn-worker.sh starts, pane cwd ≠ worktree or branch ≠ target branch (gate failure).
3. Worker writes STATUS synonyms (completed/finished) instead of literal

   done

   , sentinel does not exit.
4. Worker modifies files without committing, PM verifies empty diff when wrapping up.
5. Real settings (config/*.settings.json) enter git tracking or package.

• smoke-tmux-worker.sh

  : Temporary repo e2e (spawn 1 worker to complete, STATUS=done, diff non-empty, clean no residue).
• It is recommended to add

  smoke-e2e-wave.sh

  : spawn 2 workers to modify non-overlapping files in parallel, sentinel waits for terminal state, verify that two PR diff scopes are independent, STATUS are all done, clean no residue.

• Static:

  lint-wait-script.sh

  (lint for wait/monitor scripts) +

  check-dependencies.sh

  (preflight dependency check).
• Dynamic:

  smoke-tmux-worker.sh

  (e2e end-to-end) +

  smoke-provider-settings.sh

  (provider verification, requires real key, optional).