subagentspy

Mandatory sub-agent tracking skill for Codex.

What it does

• Tracks sub-agent tasks and lifecycle state
• Logs execution events (decisions, risks, artifacts, waits, errors)
• Enforces compliance gates (evidence, outcomes, follow-up, closure)
• Generates human-readable execution reports

Core commands

python3 scripts/subagent_spy.py init --run-file .codex-artifacts/subagent-run.json --goal "Your goal"
python3 scripts/subagent_spy.py add --run-file .codex-artifacts/subagent-run.json --agent agent-a --task "Task" --spawn-event
python3 scripts/subagent_spy.py event --run-file .codex-artifacts/subagent-run.json --type decision --summary "Reasoning"
python3 scripts/subagent_spy.py close --run-file .codex-artifacts/subagent-run.json --id T001 --status completed --quality good --outcome "Done" --evidence "path:line"
python3 scripts/subagent_spy.py check --run-file .codex-artifacts/subagent-run.json
python3 scripts/subagent_spy.py report --run-file .codex-artifacts/subagent-run.json --output .codex-artifacts/subagent-report.md --strict

Skill files

• SKILL.md
• scripts/subagent_spy.py
• references/mandatory-tracking-playbook.md
• references/rating-rubric.md
• agents/openai.yaml