Subagent Worker

subagent-worker: A Codex subagent that uses Caveman to reduce reporting tokens for code review, testing, and debugging.

一個使用 Caveman 壓縮回報、降低輸出 token 的 Codex 子代理。

Configuration:

• Agents: subagent_worker (review/tests), subagent_worker_debug (root-cause debugging)
• Model: gpt-5.6-luna (both agents)
• Reasoning effort: high for subagent_worker, max for subagent_worker_debug
• Default sandbox: workspace-write
• Reporting style: Caveman full

Caveman Reporting

Subagent Worker uses the project Caveman skill at full intensity for status updates and final reports. See .agents/skills/caveman/README.md for what it does, the intensity levels, and examples.

Note: Caveman reduces visible output only — it does not guarantee lower total task-token use, since delegating work to subagents can still add reasoning and context tokens. The biggest token lever for Subagent Worker is model_reasoning_effort, tiered across .codex/agents/subagent-worker.toml (high) and .codex/agents/subagent-worker-debug.toml (max) — not report formatting.

Project Structure

.
├── .codex/
│   └── agents/
│       ├── subagent-worker.toml
│       └── subagent-worker-debug.toml
├── .agents/
│   └── skills/
│       ├── subagent-worker/
│       │   ├── SKILL.md
│       │   └── agents/openai.yaml
│       └── caveman/
│           ├── SKILL.md
│           └── README.md
├── .gitignore
├── LICENSE
└── README.md

Installation

Keep .codex and .agents in the repository root so Codex can discover the project agent and skills.

Enable project agents in ~/.codex/config.toml:

[agents]
enabled = true

Restart Codex after changing the configuration if the agent or skills do not appear.

⚠️ Check your Codex multi-agent surface. On the v2 spawn surface (default for gpt-5.6-sol / gpt-5.6-terra, or when features.multi_agent_v2 is enabled), hide_spawn_agent_metadata defaults to true. That hides the model/model_reasoning_effort fields from the spawning agent, so a spawned subagent_worker or subagent_worker_debug may silently inherit your current session's model/effort instead of the values pinned in their .toml files. Verify by asking Codex which model/effort a spawned agent actually used. If it's not gpt-5.6-luna at the expected effort, add this to ~/.codex/config.toml and restart:

[features.multi_agent_v2]
enabled = true
hide_spawn_agent_metadata = false

Some newer Codex builds stabilize this automatically — check your build's release notes if the flag above doesn't apply.

Use

Request Subagent Worker through the $subagent-worker skill.

Code review:

$subagent-worker Review current branch against main. Return severity-ranked findings with precise file and line references, plus missing test coverage.

Unit testing:

$subagent-worker Add focused deterministic unit tests for the payment service. Run the narrowest relevant test command and report exact results.

Debugging:

$subagent-worker Reproduce the intermittent checkout failure, gather evidence, identify root cause, make the smallest authorized fix, and rerun relevant verification.

You can also find and invoke the skill through /skills by selecting subagent-worker.

Permissions

• Use read-only access for review-only tasks.
• Use workspace-write access when authorized work requires tests or code changes.
• Preserve unrelated user changes.
• Do not broaden scope or rewrite working code without evidence.
• Use clear normal language for security warnings and destructive confirmations.

Limits

• Subagent Worker handles one bounded software-quality task at a time.
• It should not claim success without fresh verification.
• It should avoid style-only review comments unless they conceal a real defect.
• If blocked, it must state the missing evidence or permission and provide actionable next steps.

Validation

Validate the bundled skills with:

Windows (PowerShell):

python "$HOME\.codex\skills\.system\skill-creator\scripts\quick_validate.py" .agents\skills\subagent-worker
python "$HOME\.codex\skills\.system\skill-creator\scripts\quick_validate.py" .agents\skills\caveman

macOS/Linux:

python "$HOME/.codex/skills/.system/skill-creator/scripts/quick_validate.py" .agents/skills/subagent-worker
python "$HOME/.codex/skills/.system/skill-creator/scripts/quick_validate.py" .agents/skills/caveman

Paste-Ready Codex Action

Use the `$subagent-worker` skill to delegate one bounded software-quality task — the skill selects `subagent_worker` for review/tests or `subagent_worker_debug` for root-cause debugging.

Requirements:
1. Use the project Caveman skill at `full` intensity for status and final responses.
2. Stay within the assigned scope and preserve unrelated user changes.
3. For code review, return severity-ranked findings with precise file and line references and missing test coverage. For unit testing, add or improve focused deterministic tests, run the narrowest relevant test command first, and report exact results. For debugging, reproduce the failure, gather evidence, identify root cause, make the smallest authorized fix, and rerun relevant verification — capped at 3 reproduce-fix-verify cycles before reporting blockers.
4. Return a verdict or root cause, findings or changes, verification evidence, and remaining risks or blockers.
5. Do not claim success without fresh verification.

Task: Replace this line with the concrete task for Subagent Worker.

License

MIT

If u like, get me the star.

Credits

Caveman reporting method and skill: caveman. It favors terse, technically accurate output to reduce report/output tokens where clarity remains intact.