Skip to main content
Before running any CLI commands, confirm that SKILL_PATH points to the installed skill directory. For Codex: SKILL_PATH=.agents/skills/repo-task-proof-loop. For Claude Code: SKILL_PATH=.claude/skills/repo-task-proof-loop. All script paths are relative to this skill root.
Claude Code loads project agents at session start. If init wrote or refreshed .claude/agents/* during a running session, those files will not appear until you start a new Claude Code session.Start a new session, then run /agents to confirm the updated agent list is available.
One or more required artifact files are absent from .agent/tasks/<TASK_ID>/. Re-run init with --force to recreate any missing artifacts:
python3 "$SKILL_PATH/scripts/task_loop.py" init \
  --task-id <TASK_ID> \
  --force
--force overwrites existing task artifact templates but does not affect production code.
Read problems.md. The verifier gives a per-criterion reason for each non-PASS criterion, including why the criterion is not proven, minimal reproduction steps, expected vs. actual behavior, affected files, and a corrective hint.The fixer reads only spec.md, verdict.json, and problems.md. It reconfirms each listed problem in the codebase before editing, then makes the smallest safe change set. Run the fix → verify cycle until the verifier returns PASS.
TASK_ID may only contain letters, numbers, dot (.), underscore (_), and hyphen (-). Path separators (/, \) and .. are not allowed.Examples of valid task IDs: feature-auth-hardening, fix_login_bug, v2.0-migrationExamples of invalid task IDs: feature/auth, ../escape, task id with spaces
validate checks that the task_id field inside evidence.json matches the --task-id argument you passed to the script. If they differ, the artifact was written for a different task or with a different ID.Re-run init with the correct --task-id to recreate a consistent artifact set:
python3 "$SKILL_PATH/scripts/task_loop.py" init \
  --task-id <CORRECT_TASK_ID> \
  --force
In Codex, subagents do not spawn automatically. You must explicitly ask for them in your prompt. Use the role prompts from references/COMMANDS.md when directing the spec-freezer, builder, verifier, and fixer subagents.
Use the Check Existing Task prompt first to confirm the task ID and its current state:
Use $repo-task-proof-loop to find the existing repo-local task that matches the task described below, inspect its artifacts, and report the matched task ID, current status, and next recommended step.
...
Then use the Continue Existing Task prompt to resume from where the workflow left off. The agent will infer the next step from the current repo state.

Build docs developers (and LLMs) love

Get started for freeTalk to us