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.

Prefer `single_agent` for one-file fixes, simple questions, or tasks where the next step depends on one immediate result. Use parallel lanes only when the work can be split by independent targets or disjoint writable files.

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.

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

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, spawn bounded native subagents when useful, 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/tmux/OMX orchestration.

Evidence-backed pushback: choose `single_agent` when parallelism adds coordination risk without independent work; challenge vague worker output, stale remote state, or unverified completion claims.

Feedback loop: record notable failures in `threads_run_log`, classify the failure mode, tighten the lane prompt or split, then retry only after the hypothesis changes.

If the user asks for issue/PR queue handling, `remote_truth_required` is `yes` and `queue_ledger` is `required_for_queue`.

Broad queue requests such as "all issues and PRs" are bounded by default. If the user did not give an explicit long-run budget, choose one smallest mergeable tranche, record `max_items` / `time_budget` / `queue_tranche`, and leave the remaining queue for the next run with exact next actions.

## Capability Gate

Before dispatching lanes, record whether native Codex subagents are actually available:

```text
capability_gate:
- native_subagents: available | unavailable
- tools_seen:
- fallback_mode: single_agent | prompt_pack_only | none
- manual_orchestration_allowed: yes | no
```

Rules:

- If native subagents are unavailable, do not claim threads were launched.
- Do not switch to shell, tmux, OMX, Harness, or other manual orchestration unless the user explicitly asks for that fallback.
- If `fallback_mode` is `single_agent`, explain why parallelism was rejected.
- If `fallback_mode` is `prompt_pack_only`, output exact lane prompts and stop before implementation.

## Queue Gate

For GitHub issue/PR queue handling, write a `queue_gate` block before the lane map and before any implementation worker is launched. This is mandatory even when all open PRs look `MERGEABLE` or `CLEAN`.

The gate must use live state from the current session:

```text
queue_gate:
- fetched_remote:
- truth_level:
- remote_refresh:
    base_ref:
    origin_main_sha:
    local_base_sha:
    stale_base:
    policy:
- current_branch:
- dirty_files:
- unpushed_commits:
- worktrees:
- open_prs:
- open_issues:
- pr_classification:
  - PR:
    head_sha:
    merge_state:
    check_rollup:
    review_threads:
    classification:
    reason:
- issue_to_pr_map:
  - issue:
    covering_pr:
    status: covered | uncovered | stale_or_superseded | needs_human_decision
    reason:
- recommended_order:
- stop_conditions:
```

Classify every open PR as exactly one of:

- `merge_ready`
- `review_thread_blocked`
- `ci_failed`
- `conflict_blocked`
- `stale_or_superseded`
- `needs_human_decision`

Rules:

- `MERGEABLE` or `CLEAN` is never sufficient by itself. A PR is `merge_ready` only when the current head SHA, check rollup, merge state, and GraphQL review-thread state are all fresh and clean.
- Query review