soia-dev-agent-cli-dispatch

soia-dev-agent-cli-dispatch

Hand coding, review, analysis, research, documentation, or content tasks toexternal AI Agent CLI processes, with unified constraints on working directory, permissions, actual model, usage, cost, and result quality. It does not dispatch host built-in subagents, nor does it replace ordinary one-off shell commands.

Customer-readable description

What this skill can do

Customer wants	Skill will do	Customer can see
Dispatch a task to a specified AI CLI	Check CLI, authentication, working directory, and permissions, then launch according to that executor's specification	Executor, requested/actual model, status, and verification result
Let the system automatically select a model tier	Select only from candidates that already have verification evidence; block when there are no candidates	Selection rationale, reasoning tier, price range, and evidence status
Batch or resumable execution	Run cases serially, atomically updating the redacted manifest item by item	Success, failure, degradation, timeout, remaining tasks, and recovery status
See which AI Agents are supported	Read references/supported-agents.yml	Support status, usage, automatic routing scope, and corresponding specifications

This skill does not treat "process exit code 0" directly as verified model or task quality, nor does it open new automatic routing without evidence.

How customers use it

Customers should at least specify:

1. The task to be completed and acceptance criteria;
2. The target project or working directory;
3. A specified executor/model/reasoning tier, or allow automatic selection;
4. Whether file modification, network access, worktree creation, commits, or other high-impact actions are allowed.

Example request:

把这个小范围修复派给 Pi，允许改当前项目，不允许提交；运行相关测试并回报实际模型和 Token。

Dependencies and installation

• Runtime dependencies: Python 3, plus the external AI CLI selected for this run. Stop when the target CLI is missing; do not silently switch to another executor.
• Optional dependencies:soia-meta-sync-skills, used only to sync installed skills to another host explicitly chosen by the customer.
• Each CLI's authentication, models, and plans are managed by its official login state or provider configuration; this skill does not manage credentials on its behalf.

Install the entire dev plugin:

claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-dev@soia

Install only this skill:

npx skills add soia-team/soia-open-dev-skills -g -a '*' -s soia-dev-agent-cli-dispatch -y

Do not maintain both a plugin copy and a ~/.agents/skills shared copy at the same time, to avoid drift of same-named skills.

WorkBuddy 's loading unit is role-based experts rather than plugins,npx skills add -a '*' cannot cover it, and it needs to be installed separately, see docs/install/workbuddy.md。

Configuration files

There are two types of YAML in this skill directory, with different responsibilities:

File	Nature	Purpose
references/supported-agents.yml	Public configuration shipped with the skill	Which AI Agents are supported, what work they suit, how to invoke them, and to what degree they are verified
assets/config.example.yml	Private configuration template	Configure host identity and state/temp root directories; after copying, it is held by the customer

Optional private configuration locations and override variables:

~/.config/soia-skills/soia-dev-agent-cli-dispatch/config.yml
SOIA_DEV_AGENT_CLI_DISPATCH_CONFIG_FILE=<custom-config-path>

Configuration priority: this run's CLI parameters → process environment → private config.yml → Cross-platform default. API keys, cookies, tokens, and sessions must not be written into this configuration; they remain in the provider login state or the system credential store.

Private information and intermediate data

• prompt: write to a directory isolated by task-id under the OS temporary directory; clean up after the task ends. Unless the customer explicitly requests it, do not retain the prompt long-term.
• run manifest: by default write to <state>/soia-skills/soia-dev-agent-cli-dispatch/runs/<run-id>/manifest.json。
• The manifest only stores redacted status, CLI version, requested/actual model, tokens, cost, time, and recovery information; it does not store prompts, response bodies, credentials, accounts, or private absolute paths.
• When the platform allows it, the state directory uses 0700, and the manifest uses 0600. By default, retain at most 50 runs; when the limit is reached, block new runs rather than deleting automatically. Before cleanup, first let the customer review the scope and confirm.
• The repository checkout must not be used as the runtime config, state, cache, or temporary directory.

Path resolution:

python3 scripts/resolve_storage.py --json

Logs and completion receipts

The final receipt always includes:

完成：<本次派发结果>。

调用：
- executor: <外部 AI CLI>
- requested/actual model: <值或 unknown>
- requested/actual reasoning: <值或 unknown>
- status: <passed / failed / blocked / fallback_or_downgrade / actual_model_unverified>

用量与费用：
- input/cache/output/total tokens: <分项值或 unavailable>
- provider-reported / API-equivalent cost: <值、口径或 unavailable>

验证：<实际运行的检查及结果>
状态记录：<泛化 state 位置或“纯 stdout”>
问题与下一步：<阻塞、未验证边界或“无”>

Do not print credentials, accounts, full response bodies, or local private absolute paths in customer receipts.

Triggers and boundaries

Use when any of the following scenarios applies:

• Explicitly requesting to "dispatch to Codex / Claude / Pi / DeepCode / agy / other external AI CLIs";
• Needing multi-CLI division of labor, external model routing, quota pre-checks, or unified usage receipts;
• Needing to place long tasks into an independent external process and track them recoverably.

Do not use:

• The current host completes the task directly, with no external AI process;
• Only ordinary shell commands are needed;
• The task boundaries, target working directory, or acceptance criteria are still unclear.

Input contract

Before execution, normalize the request into:

task:
  title: <short-title>
  objective: <observable-result>
  acceptance: [<evidence>]
executor: <agent-id-or-auto>
model: <model-id-or-auto>
reasoning: <level-or-auto>
workdir: <project-path>
permissions:
  file_write: false
  network: false
  worktree: false
  commit: false
  remote_write: false

Permissions not explicitly authorized remain false. Explicitly specified executors, models, and reasoning tiers take precedence; however, unverified combinations must be marked explicit_unverified, and must not be packaged as automatic recommendations. The specific model division of labor among Coordinator, Executor, Verifier, Reviewer, and Advisor belongs to the caller's project/user policy and is not hardcoded by this general skill; the dispatcher must provide that policy as part of this input, and only when it is not provided should candidates be given based on task complexity and existing verification evidence.

Core workflow

1. Define the task and evidence

Clearly write the goal, inputs, allowed modification scope, forbidden areas, and acceptance commands. Split tasks along independently verifiable boundaries; assign a unique task ID to each subtask.

First read the applicable AGENTS.md, contribution guidelines, and testing conventions of the target repository. Target repository rules take precedence; do not stuff this skill's own historical governance terminology or irrelevant files into the dispatch prompt.

2. Select the executor

1. Read references/supported-agents.yml, confirm dispatch_supported, verification status, and the corresponding reference.
2. When the user explicitly specifies a value, execute according to the specified value without silent substitution.
3. When the user allows automatic routing, first determine easy/medium/hard, then run:

python3 scripts/route_model.py --executor <agent-id> --complexity <easy|medium|hard>

1. Stop when there is no verified candidate; do not automatically select a model from pending_benchmark or command_help_verified entries.
2. After determining the executor, load only its reference; load references/executor-routing.md。

again when routing criteria are needed.

• Run command -v <cli> and <cli> --version, and record the actual versions.
• Use the official read-only status check to verify authentication/plan; if the check itself calls a paid model, obtain customer confirmation first.
• Check whether the workdir exists, whether it is a credentials/config directory, whether there are uncommitted changes, and whether it overlaps with other tasks.
• Stop and give a clear status when the service is unavailable, authentication is blocked, quota is insufficient, or the directory is unsafe.
• The Antigravity consumer channel and the Gemini enterprise/API Key/Vertex channels must be kept separate; copying authentication state or silently aliasing is prohibited.

4. Establish isolation and permission gates

• Each write task uses an independent workdir; multiple tasks must not write to the same file at the same time.
• Before creating git worktree , show the target path, branch and purpose, and wait for explicit customer approval.
• Deletion, overwriting, committing, pushing, publishing, sending, authorization changes, and other remote writes must each obtain authorization for the current task.
• When the workspace already has unknown changes, do not commit, clean up, or overwrite; report the scope of the conflict to the customer.

5. Pass the prompt securely

The prompt must first be written to a UTF-8 temporary file isolated by task-id. Do not splice untrusted body text directly into the shell; prefer stdin or the executor's native file argument. For specific commands, argument terminators, and structured output methods, refer to the selected executor's reference.

The prompt contains only: task objective, necessary context, target files/scope, permission boundaries, acceptance commands, and receipt requirements. Exclude unrelated repositories, private paths, credentials, and other task context.

6. Dispatch and monitoring

• Run short tasks in the foreground; for long tasks use an observable background method and periodically check exit status, log summaries, and resource signals.
• Use multiple cases with scripts/run_matrix.py; atomically update the manifest after each case completes.
• After a failure, classify the cause first before deciding whether to retry; the same command or the same assumption must not be run repeatedly without changes.
• An external Agent's self-reported "complete" is only input pending verification and cannot be directly used as the main control's conclusion.

7. Verification and closure

1. Compare requested_model with the actual_model。
2. in structured or trusted echo output. When actual model evidence is missing, write actual_model_unverified; do not fill in actual values with requested values.
3. Record input, cache read/write, output, and total Tokens separately; when itemized values are missing, keep unavailable。
4. Keep provider-reported costs separate from API-equivalent estimates; subscription plans must not be disguised as real per-Token billing.
5. Run acceptance commands in the target workdir and inspect the actual diff/artifacts; exit codes and model echo output cannot replace task quality verification.
6. Check for similar issues, unauthorized changes, and residual risks, then output the completion receipt.

For unified fields, state machine, recovery, and the Model Integrity Gate, see references/dispatch-contract.md。

Evidence and status rules

• In the manifest, passed: The executor succeeded and the model evidence satisfies that executor's gate; it does not mean the task artifact quality has been accepted.
• "Complete" in the customer receipt: in addition to the above invocation status, the task artifacts must also be independently verified by the main control.
• fallback_or_downgrade: The actual model does not match the request.
• actual_model_unverified: The task may have output, but trusted actual model evidence is missing.
• blocked_*: Authentication, quota, permissions, or paid confirmation were not satisfied, and the corresponding call was not executed.
• partial_coverage: Only partial models/tiers or aggregate reports are available, so full-matrix completion cannot be claimed.

To claim "all models × all reasoning levels verified", you must retain the discovery snapshot, the complete case list, the per-case manifest, the model echo, and the aggregation report.

On-demand resources

Required	Resources
Which AI Agents are supported, their usage, and verification status	references/supported-agents.yml
Routing criteria and recommended combinations	references/executor-routing.md
Unified invocation fields, states, dispatch discipline, and recovery rules	references/dispatch-contract.md
Single executor command	references/supported-agents.yml for that agent in the reference
Model and price runtime source of truth	references/model-catalog.yml
Date-stamped source snapshot of the price catalog	reports/model-pricing-2026-07-10.md
Historical evidence boundaries	reports/benchmark-2026-07-10.md
Pi + DeepSeek V4 Flash example	examples/pi-deepseek-v4-flash-easy.md
Private run configuration template	assets/config.example.yml

Loading principle: main file → selected executor reference, at most one hop; do not load all references at once.

Verification

After modifying this skill, at minimum run:

python3 scripts/resolve_storage.py --selftest
python3 scripts/validate_supported_agents.py --selftest
python3 scripts/catalog_lib.py --selftest
python3 scripts/estimate_cost.py --selftest
python3 scripts/route_model.py --selftest
python3 scripts/run_claude_prompt.py --selftest
python3 scripts/run_matrix.py --selftest

For complex behavior, also run a real sanitized forward instance and verify the artifact or manifest contents, not just the exit code.