command-code-subagent

Codex and Claude Code skill for delegating bounded work to the Command Code (cmd) CLI from inside Codex, Claude Code, or Superpowers-style subagents.

The intended flow is:

1. A main agent writes a focused task brief.
2. The main agent dispatches a lightweight controller subagent.
3. The controller subagent shards the task into small units.
4. Each useful shard runs through cmd -p.
5. The controller validates shard outputs and returns one composed report.

If cmd is unavailable, unauthenticated, rate-limited, model-limited, or repeatedly hits max-turn/context limits, the controller falls back to completing the remaining shards directly.

Contents

• SKILL.md - Runtime skill instructions for the controller subagent workflow.
• scripts/cmd_shard.py - Wrapper for consistent bounded cmd -p shard execution.
• references/model-routing.md - Model selection guidance by shard role.
• agents/openai.yaml - Codex UI metadata for the skill.
• .claude/skills/command-code-subagent/ - Claude Code project-skill symlinks.
• quick_validate.py - Local skill structure validator.

Prerequisites

• Codex or Claude Code with skill support.
• Command Code CLI installed and authenticated.
• A workspace where cmd -p can run.

Check the CLI:

command -v cmd
cmd --version
cmd --list-models

Use The Skill

Codex can use this repository as the skill directory directly.

Claude Code discovers this skill through .claude/skills/command-code-subagent/, which symlinks back to the project-local skill files.

From a main agent or controller prompt:

Use $command-code-subagent at .

Task:
<focused task or path to task brief>

Workspace:
<absolute workspace path>

The controller should use the workflow in SKILL.md: shard narrowly, run read-only shards first, run edit shards sequentially, validate each result, and return the final controller report shape.

Run A Shard Directly

Read-only shard:

python3 scripts/cmd_shard.py \
  --cwd "$PWD" \
  --max-turns 10 \
  --prompt "Summarize this repository in five bullets."

Specific model:

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

Trusted edit shard:

python3 scripts/cmd_shard.py \
  --cwd "$PWD" \
  --mode edit \
  --max-turns 20 \
  --prompt-file .commandcode-subagent/shards/task-2.md

Use edit mode only in trusted workspaces where the shard is expected to modify files or run shell commands.

Model Routing

Start with references/model-routing.md. In general:

• Use deepseek/deepseek-v4-flash or the account default for cheap read-only shards.
• Use stronger coding models for implementation and review shards.
• Omit --model when the account default is good enough.
• If cmd returns MODEL_NOT_IN_PLAN, run cmd --list-models, choose an available model, or omit --model.

Validate

Validate the skill structure:

python3 quick_validate.py .
python3 quick_validate.py .claude/skills/command-code-subagent

Check the wrapper:

python3 -m py_compile scripts/cmd_shard.py quick_validate.py

Smoke test:

scripts/cmd_shard.py \
  --cwd "$PWD" \
  --max-turns 1 \
  --prompt "Return exactly: OK"