/threads

name: threads
description: Use when the user explicitly asks for $threads, Codex-native subagents, 开几个子 agent, or a GitHub issue/PR queue needing parallel lanes, worktrees, review/merge gates, and closure audit. Do not use for OS/language threads, chat/email/forum threads, or Assistants product threads unless Codex workflow orchestration is explicit.
compatibility: Requires Codex with native subagent support.
metadata:
  spellbook-runtimes: "codex"

Threads

Use this skill to turn a broad request into controlled Codex-native subthreads with explicit lanes, file ownership, review gates, and verifiable closure.

Native Codex threads are short-lived parallel work lines inside the Codex workflow. They are not the same as OMX/tmux workers. If native subagent tools are not visible, discover them with tool search. If no native subagent capability is available, produce the thread prompt pack and execution plan instead of pretending threads were launched.

Quick Path

1. Classify the request: `single_agent`, `plan_only`, `execute_direct`, `review_only`, `research_spec`, or `clarify_first`. 2. If the user explicitly asked for threads, record `intent_contract` and `thread_dispatch_gate`, write a `run_phase: preflight` record, and pass `append_run_log.py --validate-only` before spawning. 3. For GitHub queues, fetch remote state in the coordinator lane, then write `queue_gate`, `queue_ledger`, `issue_to_pr_map`, and the validated `queue_bounds`. 4. Write a lane map with file ownership, verification owner, stop conditions, context budget, and output firewall. 5. Route large command output to artifacts before dispatch; the parent reads only summaries, short tails, targeted greps, and evidence paths. 6. Dispatch only bounded native lanes with disjoint writable scopes or read-only roles. 7. Collect, wait, and close spawned agents; do not count the coordinator as a spawned thread. 8. Run fresh verification tied to the current head or artifact. 9. End with a compact final report and `threads_run_log`; write durable JSONL for queue, multi-lane, push, comment, or merge-capable runs.

Do Not Use For

Do not use this skill for generic uses of "thread" unless the user explicitly means Codex workflow orchestration:

• operating-system threads, language concurrency, or async programming models
• chat, email, forum, Slack, GitHub discussion, or comment threads
• OpenAI Assistants API threads or other product APIs
• ordinary single-agent repo work where there are no independent lanes

Decision

Choose one mode:

• **single_agent**: handle a small, well-scoped task locally with the same evidence gates.
• **plan_only**: map issues, PRs, risks, and parallelization without edits.
• **execute_direct**: run one or more bounded implementation lanes after planning.
• **review_only**: launch independent reviewers for PRs, diffs, or risky code.
• **research_spec**: split exploration by angle, then synthesize docs/spec/issues.
• **clarify_first**: ask only when repo, target queue, permission, or done-when is missing.

Use `single_agent` only for one-file fixes, simple questions, or tasks where the next step depends on one immediate result. If the user explicitly asks for threads, subagents, or a GitHub issue/PR queue and native subagents are available, do not silently choose `single_agent`; record a concrete `no_spawn_reason` before implementation work begins.

For any implementation mode, start with a lane map before spawning workers. For GitHub issue/PR queues, complete the Capability Gate and Queue Gate first; do not create worker lanes until `capability_gate`, `queue_gate`, `queue_ledger`, and `issue_to_pr_map` are written.

Explicit Thread Dispatch Gate

When the user explicitly asks for threads, subagents, "开几个子 agent", or a GitHub issue/PR queue that the skill classifies as `plan_only`, `execute_direct`, `review_only`, or `research_spec`, native dispatch is required whenever native subagent tools are available.

Record this gate before implementation, review, or merge work:

thread_dispatch_gate:
- explicit_thread_request: yes | no
- native_subagents: available | unavailable
- spawn_requirement: required | optional | unavailable
- fallback_mode: single_agent | prompt_pack_only | none
- planned_native_threads:
  - id:
    role:
    target:
    write_scope: read_only | disjoint_writable | none
    spawn_status: planned | spawned | skipped
    no_spawn_reason:
- native_thread_evidence:
    user_requested_native_threads: yes | no
    spawned_agents:
      - lane_id:
        spawn_tool:
        agent_id_or_thread_id:
        wait_evidence:
        close_evidence:
        result_collected: yes | no
    fallback_reason:
- no_spawn_reason:

Rules:

• If `explicit_thread_request: yes`, `native_subagents: available`, and `spawn_requirement: required`, spawn at least one bounded native subagent before claiming the run is using threads.
• `native_subagents: available` plus `fallback_mode: none` is valid only when `native_thread_evidence.spawned_agents` contains at least one real agent/thread ID.
• Every `planned_native_threads` lane must have a matching `native_thread_evidence.spawned_agents[].lane_id` or a lane-level `no_spawn_reason`; spawning one native thread does not justify running the remaining planned lanes serially.
• A main-thread lane is a coordinator lane, not a native thread. Do not count the coordinator as `native_thread_evidence.spawned_agents`.
• If no native thread is spawned, set `fallback_mode: single_agent` and write `no_spawn_reason` before editing files, commenting on GitHub, or merging. Valid reasons are narrow: task is tiny and truly sequential, all possible writable lanes overlap, native tools are unavailable, or the user explicitly asks not to spawn.
• For GitHub PR merge work, at least one read-only reviewer or merge-reviewer native thread is required when native subagents are available. A self-review by the coordinator does not satisfy the independent review lane.
• If