Use this skill when any host AI needs to dispatch coding, review, analysis, research, documentation, or content work to an external AI model/CLI — Codex, Antigravity CLI, Gemini CLI, Kimi CLI, OpenCode, Qwen Code, or a separately-launched Claude Code process — instead of continuing directly in the current agent session. This is about calling an external AI process; it is not about a host's built-in sub-agents.
Do not use it when the current agent can just finish the task itself with no external process involved, or when you only need a one-off local shell command with no orchestration, monitoring, or prompt-injection concerns.
Customer-readable description
What this skill can do
Dispatch external AI models/CLIs (codex/claude/agy/gemini/kimi/opencode/qwen, not the host's built-in subagents,qodercli command templates are also available but not included in the streamlined list below) for controlled dispatch, covering coding, review, analysis, research, documentation, and content tasks: task boundary decomposition, independent workdir, injection-resistant prompt writing, model tiering matrix, Worktree approval gate, Anti-Fake-Fix three-step verification. On top of this, you can explicitly specify executor + model + reasoning depth, or provide only the executor family and let task difficulty drive automatic selection (see "Automatic Routing"); after each call, output a Token/cost summary (see "Call Summary Receipt"), model integrity check (see "Model Integrity Gate"), quota pre-check (see "Quota Pre-check"), and resumable execution (see "Resumable Execution"). Detailed command templates for each executor are in the references/ subdirectory and loaded on demand.
| What the customer wants | What the skill will do | What the customer can see |
|---|---|---|
| Complete the work covered by this skill | Read the user request, necessary context, and this skill's main workflow, and execute the minimum reliable steps | The customer will see the execution plan, command output summary, code/document changes, verification results, and risk notes. |
| Missing dependencies, permissions, configuration, or keys | Stop actions that require external state and clearly state what is missing | Install commands, application addresses, configuration paths, or questions requiring customer confirmation |
| Execution complete | Summarize successes, skips, failures, file changes, and verification results | A completion receipt that can be copied into a ticket/log |
How the customer uses it
- Describe the goal in natural language and provide the necessary inputs: files, URLs, repo, workspace, proposal, vault, or platform account status.
- The Agent first determines whether this skill applies, then checks dependencies, configuration, permissions, and risky actions.
- For actions that can be dry-run or previewed, provide a preview first; for actions involving deletion, overwriting, sending, publishing, or writing remote state, ask the customer for confirmation first.
- After execution, verify the real output; do not substitute "looks successful" for evidence.
- The final reply must give the customer a visible summary: what was done, log summary, file changes, issues, and next steps.
Dependencies and installation
Install this skill (single skill):
npx skills add soia-team/soia-open-dev-coding-skills -g -a '*' -s soia-dev-agent-cli-dispatch -y
npx skills will update the ~/.agents/skills shared source, but does not manage all custom targets. In an environment with open-source soia-meta-sync-skills installed, a single-item sync can be performed after explicitly specifying the target:
python3 ~/.agents/skills/soia-meta-sync-skills/scripts/sync_soia_skills.py \
--source-dir ~/.agents/skills \
--targets soia,workbuddy \
--skills soia-dev-agent-cli-dispatch
Final acceptance should confirm that ~/.soia/skills/soia-dev-agent-cli-dispatch and ~/.workbuddy/skills/soia-dev-agent-cli-dispatch are both symlinks pointing to ~/.agents/skills/soia-dev-agent-cli-dispatch ; do not treat a local source checkout as the result of an npx installation.
Configuration conventions:
~/.config/soia-skills/soia-dev-agent-cli-dispatch/config.yml
SOIA_DEV_AGENT_CLI_DISPATCH_CONFIG_FILE=<custom-config-path>
- If this skill does not need private configuration, you may skip creating
config.yml。 - If API keys, cookies, sessions, provider home, or local paths are needed, they may only be placed in private
config.yml, the process environment, or the provider's own login state; they must not be written into the repository, vault body, or logs. - Hard dependencies, optional dependencies, and third-party skill relationships must be based on this
SKILL.mdsubsequent "dependencies / prerequisites / resources / boundaries" description; if it is not clearly written, add the description first or ask the client, do not guess. - Third-party skills may only declare dependencies and installation methods, and must not directly modify third-party skill files.
- This skill does not hard-bind to any specific orchestration system; "your orchestration layer" appearing in the text refers to the upper-level Agent/system that invokes this skill, not a specific product.
Logging and completion receipts
Every execution must let the client see the process and results. Minimum receipt format:
完成：<一句话说明本次完成了什么>。
日志摘要：
- started: <检查到的输入/配置/依赖，不打印秘密值>
- processed: <数量或范围>
- created/updated: <数量或路径>
- skipped/failed: <数量和原因>
文件变化：
- <绝对路径或“未改动文件”>
验证：
- <运行过的检查、命令或人工核对点>
问题与下一步：
- <缺 key / 缺依赖 / 需要客户确认 / 建议下一条命令；没有则写“无”>
⚡ Trigger conditions
Invoke this skill when any one is satisfied (common natural-language phrasings include but are not limited to "assign work to codex", "have claude analyze", "invoke an external AI", "multi-CLI dispatch", "run tasks in the background"):
| Condition | Description |
|---|---|
| A coding, review, analysis, research, documentation, or content subtask needs to be handed off to an external AI CLI for execution | The current host AI does not do it directly, but dispatches it to another external AI process |
| Generate a prompt for a sub-agent | Need injection-resistant temp file writing method |
| Start long tasks in the background | Need a controlled workdir + progress monitoring |
| Multiple agents in parallel | Need to formulate dependencies / allocation matrix / dispatch plan |
No need to invoke: execute the code task directly yourself (no dispatch action).
How to self-check your external AI CLI availability
Do not assume a CLI is certainly serviceable. Before dispatching, self-check in the following order, and record the results in your own availability records rather than copying any example status from this document (examples will become outdated):
- Whether the CLI is installed：
which <command>or<command> --version; the version number is based on the actual output. - Whether authentication / plan is valid: prefer using the official local status command. If the CLI does not have an auth-status command that does not invoke the model (currently
agyis like this), you must not treat<command> -p "ping"as a "zero-quota read-only check"; model invocation may consume quota, so client confirmation must be obtained first. When browser login is required, start it in a PTY and record the status asblocked_user_action, with the client themselves completing account selection and authorization. - Whether the last dispatch failed: if the most recent task of that executor returned an unexpected error or repeatedly timed out, first record it as temporarily unserviceable, and resume dispatching only after you have verified the fix.
- Maintain your own availability table: it is recommended to build your own table of "executor / CLI available / plan-key status / serviceable / remarks", and update it as your orchestration layer state changes.
Unserviceable executors must not be dispatched to; wait until the state recovers and you have verified it yourself, then update the record before dispatching again.
Google authentication channels must not be mixed: The Gemini CLI consumer Google OAuth service has been discontinued since
2026-06-18, and should be migrated to the separate command agy; Gemini Code Assist
Standard/Enterprise, Gemini API Key, and Vertex AI channels are still retained in the gemini
executor. Aliases, silent command substitution, copying OAuth files, or applying one channel's
plan/billing conclusion to another channel are prohibited. See references/antigravity-cli.md and
references/gemini-cli.md。
Full benchmark coverage closed loop
Before claiming "all models × all reasoning tiers have been tested", the following must be present simultaneously: the model discovery snapshot of the current CLI/account, discovery evidence for the supported tiers of each model, a complete Cartesian product case list, raw per-case manifest.json and aggregate reports. If any item is missing, uniformly mark partial_coverage, and do not report "full completion" based only on aggregate paraphrase or exit code. In the price catalog, availability only indicates that the pricing material lists that model; it does not mean the current account/CLI has been verified as callable; actual execution capability is subject to discovered_at、discovery_evidence and the raw manifest.
Applicable / Not applicable
Applicable：
- Split an engineering task to other coding agents for parallel execution
- Dispatch, in a controlled manner, simple tasks that require external AI execution, review, or record-keeping
- Start long-running coding tasks in a controlled working directory
- Collect, summarize, and review subtask execution results
Not applicable：
- Actions that do not involve external AI dispatch and are completed directly by the current host or local tools
- Results are needed immediately and asynchronous background execution is not tolerable
- There is not yet a clear subtask scope, working directory, and acceptance criteria
Task simplicity is not an exclusion condition: as long as execution by an external AI CLI is required, choose the minimal sufficient dispatch method according to risk, input scope, and acceptance requirements.
Core principles
- Define task boundaries first, then start the agent
- Each agent must have an independent
workdir - Long tasks run in the background by default, with regular progress reports
git worktreemust obtain explicit user approval in advance before starting(an irreversible-operation gate on the same level as commit/push/merge); without approval, do not executegit worktree add- Do not start coding agents directly in credential directories, user configuration directories, or unknown directories
- All source code files must carry a metadata header → see
references/metadata-header.md - Once an unapproved high-risk operation occurs, it must be recorded in your own governance/audit trail (tickets, change logs, violation record documents, etc.) — this recording step cannot be omitted
Executor dispatch decision tree
⚠️ The model names, version numbers, and tier naming below are for reference only. Please rely on the actual output of each CLI's
--version/models/--help; version numbers will become outdated over time.
任务类型判断
├── 简单且非破坏性任务（写配置/简单脚本；删除、覆盖等破坏性动作不得归入此类）
│ └── opencode run "..." 或 kimi -w <wt> --plan -p "..."（确认后改 --print）
│ 详见 references/opencode-qwen.md / references/kimi-cli.md / references/qodercli.md
│
├── 中等任务（rsync/build/verify/小范围重构）
│ └── opencode run "..." 或 kimi -w <wt> -m kimi-k2.6 --thinking --print -p "..."
│ 详见 references/opencode-qwen.md / references/kimi-cli.md / references/qodercli.md
│
├── 文档/内容写作
│ ├── 消费者 Google 账号：agy -p "..."（需先确认额度；显式派发）
│ ├── Gemini 企业/API Key/Vertex：gemini -p "..."
│ └── qwen "..." / qwen -m qwen-max "..."
│ 详见 references/antigravity-cli.md / references/gemini-cli.md / references/opencode-qwen.md
│
├── 中等复杂度编码 / 快速迭代
│ └── kimi -w <wt> -m kimi-k2.6 --thinking --skills-dir <your-skills-dir> --print -p "..."
│ 详见 references/kimi-cli.md
│
├── 复杂代码编辑（常见默认候选）
│ └── codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check
│ 详见 references/codex.md
│
├── 代码审核 / diff review / evidence 验证
│ └── codex exec ...
│ 详见 references/codex.md
│
├── 新增/难任务/高风险变更
│ └── codex exec -m <model> -c model_reasoning_effort="high" ...
│ 详见 references/codex.md
│
├── 调度 / 代码审查 / 计划拆分 / 复杂推理
│ └── Claude Code — 高阶推理档（thinking=high）
│ 适用：派发子 agent / 审 PR / 规划提案 / 复杂 bug 定位
│ 详见 references/claude-code.md
│
├── 代码编写 / 中等任务（高阶档节流替代）
│ └── Claude Code — 中阶档
│ 适用：UI 编辑 / 文档改写 / 中型重构
│ 详见 references/claude-code.md
│
├── 轻量 Edit / Read / Grep（超轻量）
│ └── Claude Code — 轻量档
│ 适用：一次性小改 / 快速查阅
│ 详见 references/claude-code.md
│
├── 大上下文分析 / 结构化输出
│ ├── 消费者 Google 账号：agy --model "<agy models 显示名>" -p "..."
│ ├── Gemini 非消费者通道：gemini -p "..." --output-format json
│ ├── Gemini 非消费者通道：gemini -p "..." --output-format stream-json
│ └── claude --permission-mode bypassPermissions --print --output-format json
│ 详见 references/antigravity-cli.md / references/gemini-cli.md / references/claude-code.md
│
├── 高隔离分析（沙箱）
│ ├── 消费者 Google 账号：agy --sandbox --mode plan -p "..."
│ └── Gemini 非消费者通道：gemini --sandbox -y -p "..."
│ 详见 references/antigravity-cli.md / references/gemini-cli.md
│
└── Qwen 生态编码/评审
└── qwen / qwen -i / qwen -m qwen-max
详见 references/opencode-qwen.md
Dispatch matrix (quick lookup table)
| Scenario | Executor | Mode | Detailed rules |
|---|---|---|---|
| Simple task | opencode / kimi | run / --plan after confirmation, --print |
references/opencode-qwen.md / references/kimi-cli.md |
| Simple task | qodercli | --yolo or --model auto |
references/qodercli.md |
| Medium task | opencode / kimi | run / kimi-k2.6 --thinking --print |
references/opencode-qwen.md / references/kimi-cli.md |
| Medium task | qodercli | --dangerously-skip-permissions |
references/qodercli.md |
| Medium-complexity coding / rapid iteration | kimi | --thinking |
references/kimi-cli.md |
| Antigravity consumer account | agy | Explicit dispatch; currently no automatic model selection | references/antigravity-cli.md |
| Documentation/content | agy (consumer) / gemini (non-consumer) / qwen | agy explicit runtime display name / gemini -p --yolo / qwen-max |
references/antigravity-cli.md / references/gemini-cli.md / references/opencode-qwen.md |
| Complex code (common default) | codex | high reasoning | references/codex.md |
| Code review | codex | high reasoning | references/codex.md |
| New/high-risk | codex | high reasoning | references/codex.md |
| Scheduling / review / planning / complex reasoning | Claude Code | High-order reasoning tier (thinking=high) | references/claude-code.md |
| Code writing / medium tasks | Claude Code | Mid-tier | references/claude-code.md |
| Lightweight Edit / Read / Grep | Claude Code | Lightweight tier | references/claude-code.md |
| Large-context analysis | agy (consumer) / gemini (non-consumer) / claude | agy explicit dispatch / Gemini JSON or stream-json | references/antigravity-cli.md / references/gemini-cli.md / references/claude-code.md |
| High-isolation sandbox | agy (consumer) / gemini (non-consumer) | agy --sandbox --mode plan -p / gemini --sandbox -y -p |
references/antigravity-cli.md / references/gemini-cli.md |
| headless agent | opencode | run / serve |
references/opencode-qwen.md |
| Qwen stack | qwen | qwen / qwen -i |
references/opencode-qwen.md |
Excluded：Ollama is not a coding-agent executor; it belongs to the local model runtime / OpenAI-compatible provider category and should be placed in your own provider/runtime layer, which is outside this skill's dispatch scope.
Automatic routing / Auto-routing
Covers the scenario where "the client or upstream orchestration layer only provided the executor family, not a specific model/reasoning depth".Explicit specification always has absolute priority—This section takes effect only when no specific model/reasoning depth is explicitly specified; as long as a specific model or reasoning depth is given, skip this section and use the given value directly.
Criteria (ten items, used to place the task into easy / medium / hard)
| # | Criterion | easy tendency | hard tendency |
|---|---|---|---|
| 1 | Number of files changed | 1-2 | Multiple files across modules |
| 2 | Whether concurrency / consistency / security boundaries are involved | No | Yes |
| 3 | Whether new architectural decisions are needed | No, copy existing patterns | Yes, design trade-offs are needed |
| 4 | Cost of failure | Reversible, easy to retry | Irreversible or externally visible |
| 5 | Context window requirement | Single file / local | Cross-repository / long history |
| 6 | Whether multiple rounds of tool calls that mutually verify are needed | One edit is enough | Need to repeatedly read results before editing again |
| 7 | Whether security / permissions / credentials code is involved | No | Yes |
| 8 | Whether the task description already gives precise before/after | Yes | No, exploratory reasoning is needed |
| 9 | Whether it is review / evidence verification type or writing type | Simple check | Complex diff review tends toward hard |
| 10 | Budget / time sensitivity | Need quick results | Can trade for longer runtime |
The ten items do not all need to be satisfied; place the task into one of the three tiers based on the overall tendency. If it lands on easy/medium but the execution result does not meet the bar, escalate and retry according to the handling rules of the "⚡ Anti-Fake-Fix Gate"; do not repeatedly retry at the same tier expecting different results.
Executable routing and fixed receipt
Do not just make an ad-hoc decision in natural language. After determining easy/medium/hard, call scripts/route_model.py; automatic routing only selects models that simultaneously have routing_profile、discovered_at、discovery_evidence and verified reasoning levels. Explicitly specified models/tiers always take priority, but unverified combinations must be marked explicit_unverified。
python3 scripts/route_model.py --executor codex --complexity hard
python3 scripts/route_model.py --executor claude --complexity medium --model claude-sonnet-5 --reasoning high
Each routing must output selected_model、selected_reasoning_effort、task_complexity、selection_reason、estimated_cost_range、catalog_version and selection_status, then write the result into the unified invocation contract; when there is no verified candidate, return a blocked status and do not silently pick one from pending_benchmark candidates.
Recommended combinations (P4 partially-empirical routing, 2026-07-10 smoke matrix)
The table below gives model/reasoning-depth combinations by executor family. The 35-case records for 6 Codex models and the 15-case records for 3 Claude models already have real smoke aggregate records, but the original manifests were not provided with the handoff, and they do not cover all models in the catalog, so they are uniformly marked as partial_coverage; the recommendations in the table are valid only for covered combinations. Gemini this round is blocked_auth, Antigravity has not been approved to run paid/quota model evaluations, and Kimi/OpenCode/Qwen are still pending_benchmark. Partial empirical evidence must not be packaged as full completion; see the evidence boundary in references/benchmark-2026-07-10.md。
| Executor family | easy candidate | medium candidate | hard candidate | Status |
|---|---|---|---|---|
| codex | gpt-5.6-luna @ low |
gpt-5.6-terra @ medium (most token-efficient, empirically validated within covered combinations) |
gpt-5.6-sol @ high, escalating to xhigh only when exhaustively needed (empirically validated within covered combinations) |
partial_coverage — 6 models have aggregate records, lacking full catalog coverage and original manifests |
| claude | claude-haiku-4-5(about 18x cheaper than opus; data not split by effort) |
claude-sonnet-5 @ medium |
(no empirical recommendation for the hard tier yet, see the anti-pattern warning below) | partial_coverage — 3 models have aggregate records, lacking full catalog coverage and original manifests |
| agy | — | — | — | availability_discovered（agy models no longer has prompt validation; for the account-level display name see references/antigravity-cli.md, but no real model benchmark has been done, automatic routing is prohibited) |
| gemini | gemini-2.5-flash-lite | gemini-2.5-flash | gemini-2.5-pro / gemini-3.1-pro-preview | blocked_auth(measured 2026-07-10: after the consumer OAuth browser callback succeeded, the server rejected it under a deprecation policy; Standard/Enterprise, API Key, and Vertex AI remain supported independent channels, not tested this round) |
| kimi | kimi-k2.6 (default tier) | kimi-k2.6 --thinking | kimi-k2.6 --thinking (longer context/more turns) | pending_benchmark(not tested) |
| opencode / qwen | default model | qwen-max or an equivalent mid-tier model | the strongest available model already configured for the project | pending_benchmark(not tested) |
Large remote file / cloud drive semantic routing (operational policy, not a benchmark)
The table below selects easy / medium / hard paths based on operational semantics, for large data sets such as remote files, object storage, shared drives, or cloud drives. It is not a benchmark of model capability, price, speed, or correctness, nor does it replace executor availability checks, user authorization, permission validation, dry-run, backup, and recovery plans. The actual executor, storage service, account, and runtime environment are all determined by the current task context and are not hard-coded here.
| Path | Typical task | Allowed core actions | Required evidence to deliver | Escalation conditions |
|---|---|---|---|---|
| Luna / easy | read-only enumeration, directory/metadata inventory, format and naming verification | read-only listing, sampling reads, format detection, generating an inventory or difference report; does not modify remote state | scope, enumeration time, counts, sampling rules, anomalous items, and unread items | escalate to Terra when encountering cross-directory associations, or when rewriting categorization or migration design is needed |
| Terra / medium | cross-file implementation, category consolidation, migration plan | analyze association relationships, generate or execute reversible batched plans; preview target mapping and conflict handling first | source/target mapping, conflict list, batch plan, dry-run or equivalent preview, rollback path | escalate to Sol when involving deletion, overwriting, irreversible replacement, or when final state must be confirmed |
| Sol / hard | pre-deletion red team, final-state acceptance | First falsify the deletion scope, dependencies, and recovery path; after authorization, re-verify the actual final state, and do not substitute the task exit code for acceptance | Pre-deletion scope reconciliation, counterexample/dependency checks, authorization records, post-deletion enumeration reconciliation, sampling readability and residual/erroneous-deletion checks | If any reconciliation is inconsistent, the recovery path is unproven, or the permission boundary is unclear, stop and report back |
For remote writes, moves, overwrites, deletions, or publications, first comply with this skill's confirmation gate and unified invocation contract; Luna must not write beyond its authority, Terra must not treat a migration plan as a completed migration, and Sol must not declare completion when final-state evidence is lacking.
Anti-pattern warning (empirical, basis: 2026-07-10 smoke matrix)
claude-opus-4-8No response to effort on simple tasks: on the same fixture, the output token count and cost are exactly the same across five effort levels (low/medium/high/xhigh/max) (22 tokens / $0.0677) — all five levels were accepted by the CLI (not unsupported), it is just that no difference was measured.This holds only for this simple fixed arithmetic task, difficult tasks were not tested, do not generalize this into "opus's effort parameter is entirely useless". Therefore this table's hard tier gives no recommendation for the claude side. Basis: 2026-07-10 smoke matrix.gpt-5.6-luna'sxhightier burns money without producing output: in the older "same question, 8 runs deep research" comparison,xhightier burned up to 933k tokens (about 4.6 times that of terra), yet the output volume did not grow correspondingly, so luna only recommends the easy tier + low effort, and does not recommend upgrading to a high tier. Basis: 2026-07-10 same question, 8 runs deep research (see the "codex 5.6 series measured grading" section below).- Conclusion: whether high effort pays off depends on the combined effect of two variables, "this model" and "this task difficulty", not just task difficulty. On the same simple task,
claude-sonnet-5's output grows monotonically with effort (low 22 tokens → max 410 tokens), showing that it really is trading effort for more thinking;claude-opus-4-8is completely unmoved — two models' responses to the same effort knob can be utterly different. Do not blindly turn on the highest tier for all models; first confirm whether that model already has empirical evidence that "effort is effective" on similar tasks. Basis: 2026-07-10 smoke matrix.
Relationship with model-catalog.yml
references/model-catalog.yml Each model entry reserves the routing_profile、discovered_at、discovery_evidence three fields. P4 (2026-07-10) only backfills the real callable models that participated in the smoke matrix:gpt-5.6-sol/gpt-5.6-terra/gpt-5.6-luna/claude-sonnet-5/claude-opus-4-8/claude-haiku-4-5; future pricing periods serve only as the same model's future_pricing, and must not be disguised as a second model ID.gpt-5.5/gpt-5.4/gpt-5.4-mini has run records but still lacks evidence that reasoning takes effect,routing_profile remains []. Models that did not participate in the matrix remain unknown, and must not be packaged as verified recommendations.
codex 5.6 series measured grading (2026-07-10, same question comparison, 8 runs)
Status of this section (P4 update, 2026-07-10): the 35+15 case smoke matrix ispartial coverage empirical evidencefor Codex/Claude, and cannot replace a full-catalog matrix; Gemini/Kimi/OpenCode/Qwen are still blocked/pending. This section includes another, earlier batch of "same question, 8 runs deep research" data, answering "which model/tier is worth the money on deep research tasks", and complements the smoke matrix's callability/echo dimensions; they do not replace each other.
The following is a same-question comparison test of the codex 5.6 series models (
sol/terra/luna) andgpt-5.5A same-task comparative live test (same task, same day, 8 runs), used to supplement the model/tier selection experience for the codex column in the "dispatch matrix" above.This is a comparative conclusion for a single task on a single date, with a limited sample, not a long-term benchmark—before actual dispatch, still rely on each--versionand the actual performance at that time; do not mechanically apply the table below.
| Model | Positioning | Key live-test data | Recommended scenarios |
|---|---|---|---|
gpt-5.6-sol |
Deep audit king | xhigh tier produces the deepest output (line-number-level anchors, unique cross-check actions);low tier has extremely high cost-effectiveness (43 evidence annotations + caught real drift, taking 43% of the time) |
Architecture review / deep research; for daily use, use medium, and only bring out xhigh（996s / 246k tokens） |
gpt-5.6-terra |
for heavy work | Evidence and cost kingmedium Most token-efficient throughout (xhigh tier's "seen : inferred = 38 : 1" is the most restrained |
Fact-checking / status inventory / verification-type tasks |
gpt-5.6-luna |
No unique advantage obtained in this round | No unique findings on the same task;xhigh tier burned 933k tokens (4.6 times terra's), yet the output volume did not grow correspondingly |
Not recommended for heavy reasoning tasks for now; positioning remains to be evaluated later on creative/divergent tasks |
gpt-5.5 |
Speed first | Fastest (190s); structurally complete but weak in depth of findings | Lightweight summaries / quick checks / image generation (soia-pkm-cover-image backend) |
Reasoning effort experience：
xhighonly produces a qualitative change forsol(deeper line-number-level anchors + unique cross-check actions); forterra/lunait is merely more expensive, with no corresponding qualitative change in output.- For the default tier, use
medium。 - For quick checks:
sol@low(extremely high cost-effectiveness) orterra@medium(most token-efficient, most restrained) are both fine.
Note: The above is a comparative conclusion for a single task on a single date, with a limited sample (8 runs on the same task), and does not constitute a long-term benchmark; please rely on each --version and the actual performance at that time, review regularly, and do not stop updating after configuring once.
Minimum workflow
- Define subtask title, goal, input, and acceptance criteria
- Output dependency analysis table (Step 1)
- Output allocation matrix (Step 2)
- Output dispatch plan (Step 3)
- Start tasks sequentially/in parallel, record task IDs
- Wait for notifications, read output, and on failure analyze the cause before retrying
- After each task is completed, confirm in your task tracking system that the status has been updated before starting the next batch
Prompt injection protection (general)
Prompts containing single quotes, special characters, or YAML frontmatter must notbe directly embedded into bash -c "...", nor passed as positional arguments without a parameter terminator. When a prompt starts with - / --- , the CLI may mistake the body for command options.mustFirst write a separate file, and preferentially pass it via stdin:
# 1. 把 prompt 写入临时文件（按任务 ID 隔离）
# 这是一次性运行产物（SKILL_SPEC.md「脚本写盘决策规则」A 类），用完即可清理
mkdir -p "${TMPDIR:-/tmp}/soia-dev-agent-cli-dispatch/<task-id>/"
cat > "${TMPDIR:-/tmp}/soia-dev-agent-cli-dispatch/<task-id>/prompt.txt" << 'PROMPT_EOF'
你的 prompt 内容，可以包含任意引号和特殊字符...
PROMPT_EOF
# 2a. Codex：用 `-` 明确从 stdin 读取
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check - \
< "${TMPDIR:-/tmp}/soia-dev-agent-cli-dispatch/<task-id>/prompt.txt"
# 2b. Claude：用本技能脚本从 stdin 读取，prompt 不进入 argv / ps 输出
python3 scripts/run_claude_prompt.py \
--prompt-file "${TMPDIR:-/tmp}/soia-dev-agent-cli-dispatch/<task-id>/prompt.txt" \
--model <model-id> --effort high --permission-mode dontAsk \
--tools Read,Grep,Glob --output-format json
If a CLI does not support stdin and can only accept positional arguments, it must be written as command [options] -- "$(< "$PROMPT_FILE")"; among these, -- must not be omitted. Long prompts still take priority via stdin, avoiding the command-line length limit and exposing the body in the process list.
Prompt file naming convention：${TMPDIR:-/tmp}/soia-dev-agent-cli-dispatch/<task-id>/prompt.txt
- Put different tasks in different subdirectories (isolated by task-id) to avoid parallel dispatches overwriting each other
- Must first
mkdir -ptarget directory - If your orchestration layer needs to trace these prompts across sessions (audit scenarios), switch to
${XDG_STATE_HOME:-~/.local/state}/soia-dev-agent-cli-dispatch/or a similar persistent location (SKILL_SPEC.md category B); do not default to writing to a temporary directory
⛔ Worktree approval gate
git worktree add belongs toirreversible operations, and before execution you must:
- Show the user: target path / branch name / purpose description
- Wait for the user's explicit reply("go" / "approve" / "okay")
- Execute only after receiving approval
Creating a worktree on your own without approval is a violation; write the violation record into your own governance/audit trail (ticket, changelog, violation record document, etc.); do not skip this step and rely only on after-the-fact remediation.
Output contract
When dispatching, output at least:
- Subtask title
- Executor
- Working directory
- Startup mode (foreground / background)
- Current status (RUNNING / BLOCKED / DONE)
- Next checkpoint
Unified invocation contract
The unified invocation's fields, statuses, prechecks, model integrity, checkpoint recovery, receipt, dangerous directories, and anti-fake-fix gates are centralized in references/dispatch-contract.md。
Before invocation, keep only this main flow:
- First do the CLI version and auth/quota precheck; if the result is
holdorskip, stop and explain the reason. - Fix the two fields
requested_modelandactual_model; when it cannot be verified from the executor output, writeunknown, and do not use the requested value to impersonate the actual value. For codex, actual_model is uniquely authoritative based on the session headermodel:line (when the models cache is corrupted, its self-reported identity is untrustworthy; seereferences/codex.md"Practical Control Procedures"). - Batch tasks use a recoverable manifest; after each case completes, write the status atomically; failures, degradations, timeouts, and untested must not be disguised as passes.
- The completion receipt must simultaneously give the executor, model, usage status, anomalies/degradations, issues, and next steps; unknown values remain unknown.
- When dangerous directories, external writes, or code agent tasks are involved, first execute the safety gates and real output verification in the reference files.
🔴 Codex Prompt Hygiene Rules (prevent the CLI from reading governance files instead of writing code)
Most coding CLIs scan the working directory at startup. Unrelated governance/skill files will consume context, but the target repo's applicable rules and target files must not be deleted because of this.
The following unrelated content is prohibited in code-fix prompts：
- Product workspaces, boards, proposals,
AGENTS.mdor other skill paths unrelated to the target task - Skill/sub-agent invocation instructions unrelated to the target (such as
@xxx-skill, internal skill prefix names) - Product governance process descriptions that do not apply to the target repo (phase numbers, gate names, and other internal terminology)
- Write-back instruction (optional: simplify to a single-line command when write-back is needed)
If the target itself is a skill package or AGENTS configuration, the prompt mustinclude the AGENTS.md rules applicable to the target repository and the exact skills/<skill-name>/... / configuration file paths; only exclude irrelevant SOIA product board/proposal context, and do not delete task-necessary inputs just because a path name contains skills/ or AGENTS.md .
A code fix prompt should contain only：
- working directory
- the file paths + line numbers to modify
- the edit operations to perform (exact before/after)
- verification commands (e.g.
cargo check/npm test/ the corresponding project's test command) - Simple write-back (optional, one-line command)
Working directory selection：
- When dispatching a code fix task, specify as narrow a subdirectory as possible (e.g. a specific module directory rather than the repository root), to avoid the CLI scanning governance/skill directories
- If the target is repository-level rules, cross-skill tests, or the catalog, the repository root is the necessary workdir; use a target-file allowlist and explicit forbidden zones to control scope, and do not fake a narrower directory
🔴 CLI stop-processing protocol (uncommitted changes scenario)
Some coding CLIs have governance-check behavior: upon finding uncommitted changes in the working directory, they may stop and request confirmation.
Trigger scenario: the working directory has staged/unstaged changes (e.g. uncommitted fixes left by another parallel task or session)
Handling options(state one of them at the end of the prompt):
选项 A — 明确授权继续：
"以下未提交改动是已知用户/上游工作：[列表]。全部保留；只修改本任务 allowlist。若发生文件重叠或基线不符，停止并回报。"
选项 B — 提前 commit 再派：
只有用户在当前任务明确授权 commit，且逐项确认已有改动均属于该提交时，才能在派发前精确 git add + git commit。禁止为了“清理工作目录”打包未知或他人的改动。
选项 C — 在 prompt 里列出改动文件并说明：
"以下文件有未提交改动：[列表]。它们属于其他任务，请保留不动，继续执行本任务。"
Recommended: prefer a user-approved isolated worktree/temporary clone; when isolation is not possible, use option C or A with an allowlist. Option B is not a default cleanup measure; use it only when the commit has been explicitly authorized and the commit boundary has been verified.
Pricing reference note / Pricing reference
references/model-pricing-2026-07-10.mdincludes verbatim the original 2026-07-10 model pricing research text (numbers not rewritten), with the source noted at the top and the statement that "official budget is subject to the official pricing page".references/model-catalog.ymlis extracted in normalized form from the above original text as thesingle source of truth at runtime：scripts/estimate_cost.py、scripts/run_matrix.pyonly this YAML file is read; Markdown is not parsed. When manually checking prices, defer to the Markdown original text; for script computation, defer to the YAML; if the numbers in the two disagree, fix the YAML first and then verify the source, rather than each acting independently.- When updating prices: first modify
model-pricing-2026-07-10.md(or add a new dated snapshot file), then updatemodel-catalog.ymlaccordingly, and after the changes runpython3 scripts/catalog_lib.py --selftestto confirm the structure is still valid. - The "codex 5.6 series measured grading" section (see above) is apreliminary single-day sample, and is different in nature from the official/semi-official pricing reference in this section; do not mix them: the grading section is about "which model/tier performed better in this test", whereas this section is about "how much this model is officially priced per 1M tokens". The grading section needs updating after full matrix coverage (P3
scripts/run_matrix.pybatch results).
References (load on demand)
| Topic | File | When to load |
|---|---|---|
| Codex execution specification (common coding mainstay) | references/codex.md |
When dispatching to codex |
| Claude Code execution specification | references/claude-code.md |
When dispatching to claude |
| Antigravity CLI Execution Specification | references/antigravity-cli.md |
When dispatching to agy or migrating consumer Google accounts |
| Gemini CLI Execution Specification | references/gemini-cli.md |
When dispatching to gemini |
| Kimi CLI Execution Specification | references/kimi-cli.md |
When dispatching to kimi |
| qodercli Execution Specification | references/qodercli.md |
When dispatching to qodercli |
| OpenCode + Qwen Execution Specification | references/opencode-qwen.md |
When dispatching to opencode/qwen |
| Code File Metadata Header Specification | references/metadata-header.md |
Before any code is written |
| Original model pricing reference material (2026-07-10 snapshot) | references/model-pricing-2026-07-10.md |
When official pricing needs manual verification, or when pricing reference material is updated |
| Model pricing/reasoning tier runtime directory | references/model-catalog.yml |
scripts/estimate_cost.py / scripts/run_matrix.py Read at runtime; run once before and after manual modification scripts/catalog_lib.py --selftest |
| P4 partial coverage routing evidence (2026-07-10 smoke matrix aggregated results) | references/benchmark-2026-07-10.md |
When you need to check covered combinations, aggregated numbers, original manifest gaps, or the next round's scope |
Loading principle: After the dispatch decision determines the executor, load only the reference for the corresponding executor, do not load all of them.
Scripts (invoked on demand)
| Script | Purpose | Self-test command |
|---|---|---|
scripts/catalog_lib.py |
Restricted YAML subset parser + model-catalog.yml schema validation (duplicate model_id / missing fields / negative price rejected, unknown reasoning level marked as WARN) |
python3 scripts/catalog_lib.py --selftest |
scripts/estimate_cost.py |
Given model + token count, output API-equivalent cost estimate (itemized + total + confidence), unknown models give approximate candidates and exit with exit code 2 |
python3 scripts/estimate_cost.py --selftest |
scripts/run_matrix.py |
Resumable serial dispatch matrix executor (used for P3; in this document's stage only mock commands are used for self-test, no real model is called) | python3 scripts/run_matrix.py --selftest |
scripts/route_model.py |
Mechanically select model/reasoning tier from verified catalog records and output a fixed routing receipt; explicit specification takes priority | python3 scripts/route_model.py --selftest |
scripts/run_claude_prompt.py |
Invoke Claude Code via stdin from a UTF-8 prompt file, preventing YAML --- from being misinterpreted as an option, and preserving structured stdout |
python3 scripts/run_claude_prompt.py --selftest |
All scripts are implemented purely with the Python standard library, with no third-party dependencies. After modifying any one of them, first run the corresponding --selftest, then run the self-tests of the remaining scripts to confirm there is no collateral breakage (estimate_cost.py and run_matrix.py both import parsing/validation logic from catalog_lib.py ).