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 host built-in sub-agents,qodercli there are also command templates but they are not included in the streamlined list below) for controlled dispatch, covering coding, review, analysis, research, documentation, and content tasks: task boundary decomposition, independent workdir, anti-injection 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 automatically select the model (see "Automatic Routing"); after each call, output Token/cost summary (see "Call Summary Receipt"), model integrity check (see "Model Integrity Gate"), quota precheck (see "Quota Precheck"), and resumable execution (see "Resumable Execution"). Detailed command templates for each executor are in references/ subdirectory and loaded on demand.
| Customer wants | Skill will do | 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/documentation changes, verification results, and risk notes. |
| Missing dependencies, permissions, configuration, or key | Stop actions that require external state, and clearly state what is missing | Installation commands, application addresses, configuration paths, or questions requiring customer confirmation |
| Execution completed | 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, URL, 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 for customer 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-skills -g -a '*' -s soia-dev-agent-cli-dispatch -y
npx skills will update ~/.agents/skills shared source, but does not manage all custom targets. In an environment where the open-source soia-dev-sync-skills is installed, a single sync can be performed after explicitly specifying the target:
python3 ~/.agents/skills/soia-dev-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-open-skills/soia-dev/soia-dev-agent-cli-dispatch/config.yml
SOIA_DEV_AGENT_CLI_DISPATCH_CONFIG_FILE=<custom-config-path>
- If this skill does not require private configuration, you may skip creating
config.yml。 - If an API key, cookie, session, provider home, or local path is required, it can only be placed in private
config.yml, the process environment, or the provider's own login state, and must not be written into the repository, vault body, or logs. - Hard dependencies, optional dependencies, and third-party skill relationships must be governed by this
SKILL.mdby the subsequent "dependencies / prerequisites / resources / boundaries" description; if it is not clearly written, first supplement the description 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 is not hard-bound to any specific orchestration system; "your orchestration layer" mentioned in the text refers to the upper-layer 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 |
|---|---|
| Coding, review, analysis, research, documentation, or content subtasks need to be handed 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 an injection-resistant temp file writing method |
| Start a long-running task in the background | Need a controlled workdir + progress monitoring |
| Multi-agent parallelism | Need to define dependencies / allocation matrix / dispatch plan |
No invocation needed: execute the coding task directly yourself (no dispatch action).
How to Self-Check Your External AI CLI Availability
Do not assume that a certain CLI must be serviceable. Before dispatching, self-check in the following order, and record the results in your own availability record rather than copying any example status in this document (examples will become outdated):
- Whether the CLI is installed：
which <command>or<command> --version; the version number is subject to the actual output. - Whether authentication / plan is valid: prefer the official local status command. If the CLI does not have an auth-status command that does not invoke the model (currently
agyis the case), you must not disguise<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, record the status asblocked_user_action, and have the client themselves complete account selection and authorization. - Whether the last dispatch failed: if the most recent task for that executor returned an unexpected error or repeatedly timed out, first record it as temporarily unserviceable, and resume dispatch only after you have verified the fix.
- Maintain your own availability table: it is recommended to build a 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 status recovers and you have verified it yourself, then update the record and dispatch again.
Google authentication channels must not be mixed: Gemini CLI's consumer Google OAuth has been discontinued since
2026-06-18, and you should migrate to the independent 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 the plan/billing conclusion of one channel 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 all be present at the same time: a model discovery snapshot for the current CLI/account, discovery evidence for the tiers supported by each model, a complete Cartesian product case list, per-case raw manifest.json and an aggregated report. If any item is missing, uniformly mark it as partial_coverage, and do not report "full completion" based only on an aggregated paraphrase or exit code. In the price catalog, availability only indicates that the price data lists that model; it does not mean that the current account/CLI has been verified as able to invoke it. Actual execution capability is subject to discovered_at、discovery_evidence and the raw manifest.
Applicable / Not applicable
Applicable：
- Split an engineering task among other coding agents for parallel execution
- Dispatch simple tasks that require external AI execution, review, or an audit trail in a controlled manner
- Start long-running coding tasks in a controlled working directory
- Collect, aggregate, and review the execution results of subtasks
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 cannot be tolerated
- There is not yet a clear subtask scope, working directory, and acceptance criteria
Simplicity is not an exclusion condition: as long as execution by an external AI CLI is required, choose the minimal sufficient dispatch method based on risk, input scope, and acceptance requirements.
Core principles
- Define the task boundary first, then start the agent
- Each agent must have an independent
workdir - Long tasks run in the background by default and report progress periodically
git worktreemust obtain explicit user approval in advance before starting(the same irreversible-operation gate 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 log, violation record document, etc.) — this recording step cannot be omitted
Executor dispatch decision tree
⚠️ The model names, version numbers, and tier names 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 | Medium 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 and should be placed in your own provider/runtime layer, outside the dispatch scope of this skill.
Automatic routing / Auto-routing
Covers the scenario where "the client or upstream orchestration layer only provides the executor family, not the specific model/reasoning depth".Explicit specification always takes absolute priority—This section only takes effect when no 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 a task into easy / medium / hard)
| # | Criterion | easy tendency | hard tendency |
|---|---|---|---|
| 1 | Number of files changed | 1-2 | Cross-module, multiple files |
| 2 | Whether concurrency / consistency / security boundaries are involved | No | Yes |
| 3 | Whether new architectural decisions are needed | No, copy the existing pattern | 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 are needed to cross-verify each other | One edit is enough | Need to repeatedly read results and then modify |
| 7 | Whether security / permissions / credential 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 or authoring | Simple check | Complex diff review tends toward hard |
| 10 | Budget / time sensitivity | Need results quickly | 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 is placed into easy/medium but the execution result does not meet the standard, 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 the pending_benchmark candidates.
Recommended combinations (P4 partially empirically verified routing, 2026-07-10 smoke matrix)
The table below gives model/reasoning-depth combinations by executor family. Real smoke aggregate records exist for the 35-case set of 6 Codex models and the 15-case set of 3 Claude models, but the original manifests were not provided with the handover, and they do not cover all models in the catalog, so they are uniformly marked partial_coverage; the recommendations in the table are valid only for the covered combinations. Gemini in this round is blocked_auth, Antigravity was not 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; for the evidence boundary see 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, escalate to xhigh only when exhaustive (empirically validated within covered combinations) |
partial_coverage — 6 models have aggregate records; full catalog coverage and original manifests are missing |
| claude | claude-haiku-4-5(about 18 times cheaper than opus; data not broken down 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; full catalog coverage and original manifests are missing |
| 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, so 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 on 2026-07-10: after a successful consumer OAuth browser callback, the server rejected it under a deprecation policy; Standard/Enterprise, API Key, and Vertex AI remain supported independent channels and were not tested in 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 accuracy, 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 | Evidence that must be delivered | Escalation condition |
|---|---|---|---|---|
| Luna / easy | Read-only enumeration, directory/metadata inventory, format and naming verification | Read-only listing, sampled reads, format detection, generating inventories or difference reports; do not change remote state | Scope, enumeration time, counts, sampling rules, anomalies, and unread items | Escalate to Terra when cross-directory associations arise, or when rewriting classification or migration design is required |
| Terra / medium | Cross-file implementation, classification consolidation, migration plan | Analyze associations, generate or execute a reversible batched plan; preview the target mapping and conflict handling first | Source/target mapping, conflict list, batch plan, dry-run or equivalent preview, rollback path | Escalate to Sol when deletion, overwriting, irreversible replacement is involved, or when the final state must be confirmed |
| Sol / hard | Pre-deletion red team, final-state acceptance | First disprove 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, sampled readability and residual/erroneous deletion checks | Stop and report back if any reconciliation is inconsistent, the recovery path is unproven, or the permission boundary is unclear |
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 warnings (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, hard 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 of 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 suggest upgrading to a high tier. Basis: 2026-07-10 same question, 8 runs of 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 on task difficulty alone. 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 can react utterly differently to the same effort knob. 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 price 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 keep []. 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 of deep research" data, answering "which model/tier is worth the money on deep research tasks", and complements the smoke matrix's callability/echo dimensions; the two do not replace each other.
The following are codex 5.6 series models (
sol/terra/luna) andgpt-5.5A same-task controlled 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 controlled conclusion for a single task on a single date, with a limited sample, not a long-term benchmark—before actual dispatch, still rely on the respective--versionand the real performance of that run; 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 mediumfor heavy work xhigh（996s / 246k tokens） |
gpt-5.6-terra |
Evidence and cost king | Most token-efficient throughout (medium tier 87k tokens);xhigh tier "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 that of terra), yet the output volume did not grow correspondingly |
Not recommended for heavy reasoning tasks for now; positioning to be evaluated later with 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 only 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 controlled 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 the respective --version and the actual performance of that run, review regularly, and do not configure once and never update again.
Minimum workflow
- Define subtask title, goal, input, 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 ID
- Wait for notification, 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, then start the next batch
Prompt injection protection (general)
Prompts containing single quotes, special characters, or YAML frontmatter cannotbe 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 be written to a separate file, and preferably passed 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")"; where -- must not be omitted. Long prompts still prioritize stdin, to avoid command-line length limits and exposing the body in the process list.
Prompt file naming conventions：${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
- You must first
mkdir -pthe target 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), and 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" / "approved" / "okay")
- Only execute after receiving approval
Creating a worktree on your own without approval is a violation; write the violation record into your own governance/audit trail (tickets, change log, violation record documents, etc.), and 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 fields, statuses, prechecks, model integrity, checkpoint recovery, receipts, dangerous directories, and anti-fake-fix gates for unified invocation are centralized in references/dispatch-contract.md。
Before invocation, keep only this main flow:
- First perform CLI version and authentication/quota prechecks; when 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 pass off requested values as actual values. 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" for details). - Batch tasks use a resumable manifest; after each case completes, atomically write the status, and failures, degradations, timeouts, and untested cases must not be disguised as passed.
- 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 file.
🔴 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 applicable rules of the target repo and the 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/subagent 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 (internal terminology such as phase numbers and gate names)
- 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 repo and the exact skills/<skill-name>/... / configuration file paths; only exclude irrelevant SOIA product board/proposal context, and do not delete task-necessary input just because a path name contains skills/ or AGENTS.md .
A code fix prompt should only include：
- Working directory
- File paths to modify + line numbers
- 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 code fix tasks, specify as narrow a subdirectory as possible (e.g. a specific module directory rather than the repo root), to avoid the CLI scanning governance/skill directories
- If the target is repo-level rules, cross-skill tests, or the catalog, the repo root is the necessary workdir; use a target file allowlist and explicit forbidden zones to control scope, and do not fabricate a narrower directory
🔴 CLI stop-handling procedure (uncommitted changes scenario)
Some coding CLIs have governance check behavior: when they find 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 option A with an allowlist. Option B is not a default cleanup method; use it only when the commit has been explicitly authorized and the commit boundary has been verified.
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 a statement that "the official budget is subject to the official pricing page".references/model-catalog.ymlis theruntime single source of truth：scripts/estimate_cost.py、scripts/run_matrix.pyextracted and normalized from the above original text; only this YAML file is read, Markdown is not parsed. When manually checking prices, refer to the original Markdown; script calculations use the YAML; if the numbers in the two are inconsistent, fix the YAML first and then verify the source, do not act independently.- When updating prices: first modify
model-pricing-2026-07-10.md(or add a new dated snapshot file), then synchronously modifymodel-catalog.yml, and after the changes runpython3 scripts/catalog_lib.py --selftestto confirm the structure is still valid. - The "codex 5.6 series measured tiering" 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 tiering section is "which model/tier performed better in this test", while this section is "how much this model is officially priced per 1M tokens". The tiering section needs to be updated after full matrix coverage (P3
scripts/run_matrix.pybatch results).
References (load on demand)
| Topic | File | When to load |
|---|---|---|
| Codex execution spec (common coding mainstay) | references/codex.md |
When dispatching to codex |
| Claude Code execution spec | 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 the pricing reference material is updated |
| Model Pricing/Reasoning Tier Runtime Catalog | references/model-catalog.yml |
scripts/estimate_cost.py / scripts/run_matrix.py Read at runtime; run once both before and after manual modifications 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, gaps in the original manifest, or the scope of the next round |
Loading Principles: 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-check 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 flagged as WARN) |
python3 scripts/catalog_lib.py --selftest |
scripts/estimate_cost.py |
Given a model + token count, output an API-equivalent cost estimate (line items + total + confidence), for 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 by P3; in this document stage only self-check with mock commands, do not actually call any model) | python3 scripts/run_matrix.py --selftest |
scripts/route_model.py |
Mechanically select a 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 from a UTF-8 prompt file via stdin, preventing YAML --- from being misinterpreted as an option, and preserve 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-checks of the remaining scripts to confirm there is no collateral breakage (estimate_cost.py and run_matrix.py both import the parsing/validation logic from catalog_lib.py ).