Skip to content

SKILL.md

Latest commit

 

History

History
156 lines (113 loc) · 6.01 KB

SKILL.md

File metadata and controls

156 lines (113 loc) · 6.01 KB
Raw
name command-code-subagent
description Use when a main agent delegates research, analysis, review, or implementation through Command Code cmd CLI shards and needs a controller subagent, project-specific model routing, validation, or fallback handling.

Command Code Subagent

Delegate bounded cmd -p work through one controller subagent. Keep the controller responsible for planning, validation, and synthesis; use cmd only for narrow shards that add value.

Required Main-Agent Setup

Before dispatching the controller, the main agent must create and read a project-local routing file:

WORKSPACE="<absolute workspace path>"
ROUTING_FILE="$WORKSPACE/.commandcode-subagent/model-routing.md"
SKILL_DIR="${CLAUDE_SKILL_DIR:-<path-to-this-skill>}"

if [ ! -f "$ROUTING_FILE" ]; then
  mkdir -p "$(dirname "$ROUTING_FILE")"
  cp "$SKILL_DIR/references/project-model-routing.template.md" "$ROUTING_FILE"
fi
  • Never overwrite an existing routing file: it belongs to the project user.
  • Tell the user that they may edit this Markdown file to select available model IDs, fallbacks, and project constraints.
  • Read the project file before choosing the controller or any shard model.
  • Treat references/model-routing.md only as a fallback when the project file leaves a role unspecified.

The main agent must dispatch the controller on a medium-capability model. Do not use the smallest, cheapest, lite, or flash tier for controller work merely to save cost. Choose the lowest-cost model that the active runtime classifies as medium capability; use high reasoning effort when supported. The project routing file is authoritative if it names a compatible medium model.

Main-Agent Dispatch

Pass only the focused task, relevant paths, and routing-file path—not broad session history:

Use command-code-subagent from <path-to-this-skill>.

You are the Command Code controller subagent. You are running on the project-selected medium-capability controller model.

Task:
<focused user task or path to task brief>

Workspace:
<absolute workspace path>

Project model routing:
<workspace>/.commandcode-subagent/model-routing.md

Constraints:
- Read the project model-routing file before planning or selecting cmd models.
- Shard only independent, bounded work; use cmd -p only when it adds value.
- Validate each accepted shard before an edit shard begins.
- If cmd reports auth, rate-limit, token/context-limit, or repeated max-turn failures, finish remaining work directly.
- Return one composed report with status, cmd runs, validation, and risks.

Controller Workflow

  1. Read the project routing file. Preserve its choices unless a model is unavailable; then use its fallback or the bundled reference.

  2. Check Command Code availability and current models:

    command -v cmd && cmd --version && cmd --list-models | sed -n '1,120p'

  3. Create narrow shards: one question, subsystem, file group, or failing-test domain each. Run read-only shards first; run edit shards sequentially.

  4. For large handoffs, use .commandcode-subagent/shards/ and .commandcode-subagent/results/ instead of pasting large artifacts.

  5. Validate every accepted shard:

    • Research/analysis: verify claims against repo files or cited docs.
    • Edits: inspect git diff and run the smallest meaningful tests.
    • Reviews: cite files and line numbers where possible.

  6. Compose one concise report. Do not expose raw shard transcripts unless asked.

Run Cmd Shards

Use the project routing file's model for the shard role. If it omits a usable model, choose the least powerful available fallback that can finish in one or two turns.

python3 "$SKILL_DIR/scripts/cmd_shard.py" \
  --cwd "$WORKSPACE" \
  --model deepseek/deepseek-v4-flash \
  --max-turns 10 \
  --prompt-file .commandcode-subagent/shards/task-1.md

For a trusted implementation shard only:

python3 "$SKILL_DIR/scripts/cmd_shard.py" \
  --cwd "$WORKSPACE" \
  --model gpt-5.3-codex \
  --mode edit \
  --max-turns 20 \
  --prompt-file .commandcode-subagent/shards/task-2.md

Use --mode edit or direct --yolo only in trusted workspaces and only for shards that must edit files or run shell commands. Default headless mode blocks writes and shell commands.

Shard Prompt Contract

You are a bounded Command Code shard worker.

Goal:
<one narrow objective>

Context:
<repo paths, failing tests, docs URLs, or artifact paths>

Constraints:
- Stay within this shard scope.
- Prefer existing project patterns.
- If editing, make the smallest coherent change.
- Report commands/tests run and exact failures.

Return:
- RESULT
- FILES READ OR CHANGED
- VALIDATION
- RISKS OR UNRESOLVED QUESTIONS

Do not build on a vague, unverified, or out-of-scope result. Re-run once with a clearer prompt or stronger routed model; then complete it directly.

Failure And Fallback

  • 0: accept only after validation.
  • 3: unauthenticated—do not loop; complete directly or request login when required.
  • 4: permission/model denied—if MODEL_NOT_IN_PLAN, use an available routed fallback or omit --model. Use edit mode only for trusted tasks that need it.
  • 5: rate-limited—stop creating cmd shards and complete directly.
  • 6 or 7: network/server error—retry one important shard once, then fallback.
  • 8, max turns, context, or token limit—split once; on repetition, fallback for that and similar shards.
  • Missing cmd or unavailable model—use cmd --list-models when possible, then complete directly if needed.

Mark direct completion as FALLBACK_USED; fallback is a control decision, not a failed result.

Final Controller Report

STATUS: DONE | DONE_WITH_CONCERNS | FALLBACK_DONE | BLOCKED

CMD RUNS:
- task-1: model, mode, exit code, accepted/retried/fallback

RESULT:
<composed answer or implementation summary>

VALIDATION:
- <commands run, files checked, tests passed/failed>

RISKS:
- <remaining uncertainty, skipped cmd shards, or manual follow-up>

Include changed paths and tests run, or explicitly state that no files changed.