threads

# 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.

## 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:

```text
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 native tools are unavailable, produce a prompt pack or continue as `single_agent` only after saying that no native threads were launched.

## Operating Contract

Before dispatch, record this block as `intent_contract`:

```text
intent_contract:
  goal:
  non_goals:
  done_when:
  merge_policy: no_merge | merge_after_gate | user_confirm_before_merge
  remote_truth_required: yes | no
  truth_level: A | B | C | D
  queue_ledger: required_for_queue | optional | none
  ci_truth_source: discovered_workflow | user_supplied | language_default | none
  data_collection: final_report | local_jsonl | none
  queue_bounds:
    max_items:
    time_budget:
    queue_tranche:
  remote_refresh:
    cadence:
    last_fetch:
    stale_base_policy:
  thread_dispatch:
    explicit_thread_request:
    spawn_requirement:
    no_spawn_reason:
```

Defaults:

- `merge_policy` is `no_merge` unless the user explicitly authorizes merging in the current conversation.
- `data_collection` is `final_report` unless the user requests durable logging, debug data collection, or an issue/PR queue run explicitly sets `local_jsonl`.
- If merge permission is ambiguous, stop after merge review and report the exact recommendation or merge command instead of merging.

Direct actions: inspect repo instructions, fetch remote state, map lanes, apply the Explicit Thread Dispatch Gate, spawn required bounded native subagents, integrate results, verify, and report closure.

Escalate before: modifying high-context files, merging without fresh CI/review-thread truth, sharing writable files across workers, or switching to shell