# Repo Task Proof Loop
This skill was built from [OpenClaw-RL: Train Any Agent Simply by Talking](https://arxiv.org/html/2603.10165v1) and applies its proven approach to agentic flows in a repo-local workflow.
> "next-state signals are universal, and policy can learn from all of them simultaneously."
Repo Task Proof Loop is a repo-local workflow skill for non-trivial coding tasks.
It creates a durable task folder under `.agent/tasks/<TASK_ID>/`, installs project-scoped Codex and Claude subagents, updates repo guidance, and drives a strict loop:
`spec freeze -> build -> evidence -> fresh verify -> minimal fix -> fresh verify`
For Codex, that loop also supports an adaptive bounded fan-out path for `explorer` or `worker` children when the task splits cleanly.
The point is simple: keep proof inside the repository, separate implementation from verification, and make task state easy to resume or audit later.
## What It Creates
Inside the target repository:
```text
.agent/tasks/<TASK_ID>/
spec.md
evidence.md
evidence.json
raw/
build.txt
test-unit.txt
test-integration.txt
lint.txt
screenshot-1.png
verdict.json
problems.md
.codex/agents/
task-spec-freezer.toml
task-builder.toml
task-verifier.toml
task-fixer.toml
.claude/agents/
task-spec-freezer.md
task-builder.md
task-verifier.md
task-fixer.md
```
It also inserts managed workflow blocks into:
- the repo-root `AGENTS.md` Codex baseline
- the repo's Claude guide file: `CLAUDE.md` or `.claude/CLAUDE.md`
## Install
Install the skill as a project skill.
### Codex
```text
.agents/skills/repo-task-proof-loop/
```
### Claude Code
```text
.claude/skills/repo-task-proof-loop/
```
If you use both tools on the same repository, install it in both locations or keep one canonical copy and sync it.
## Quick Prompts
Use this prompt for the normal flow:
### Do Task
```text
Use $repo-task-proof-loop to do the task described below in this repository. Reuse the matching repo-local task if it already exists; if not, initialize it first and then continue automatically after init completes. You are explicitly authorized to use subagents and bounded parallel helper work when it materially helps. Choose the best internal orchestration automatically from the current task shape and tool surface. Keep the proof-loop phase explicit as you work so matching project agents can be picked automatically when the product supports that, otherwise continue on the main thread. Keep the task tree shallow, keep one integration builder responsible for evidence, and keep every verifier pass fresh.
...
```
For all prompts, replace `...` with either `Task file: <path/to/task-file.md>` on the next line or the task text pasted on following lines.
This skill is intentionally proof-first, so `init` always comes before build.
For users, the intended interaction stays simple: run Codex, mention `$repo-task-proof-loop`, and describe the task.
## Quick Start
1. Install the skill in the repository.
2. For the normal flow, use the [Do Task prompt](#do-task) or mention Repo Task Proof Loop (`$repo-task-proof-loop`) and describe the task.
3. That's it.
## Helper Script
The bundled helper script currently ships three CLI commands:
- `init` - create the repo-local task folder, artifacts, guides, and subagents
- `validate`
- `status` - inspect an existing initialized task
The workflow phases `freeze`, `build`, `evidence`, `verify`, `fix`, and `run` are skill-level commands for the agent, not direct CLI subcommands in this package.
Set `SKILL_PATH` to the installed skill directory:
### Codex example
```bash
SKILL_PATH=.agents/skills/repo-task-proof-loop
```
### Claude Code example
```bash
SKILL_PATH=.claude/skills/repo-task-proof-loop
```
Initialize a task:
```bash
python3 "$SKILL_PATH/scripts/task_loop.py" init \
--task-id feature-auth-hardening \
--task-file docs/tasks/auth-hardening.md
```
Or seed from inline text:
```bash
python3 "$SKILL_PATH/scripts/task_loop.py" init \
--task-id feature-auth-hardening \
--task-text "Implement auth hardening for session refresh and logout."
```
Validate:
```bash
python3 "$SKILL_PATH/scripts/task_loop.py" validate \
--task-id feature-auth-hardening
```
Run `validate` only after `init` completes. If it reports initialization in progress, wait and rerun.
Status:
```bash
python3 "$SKILL_PATH/scripts/task_loop.py" status \
--task-id feature-auth-hardening
```
Use `status` after `init` completes when you want stable task state. If it returns `init_in_progress: true`, retry after `init` finishes.
Useful options:
- `--guides auto|agents|claude|both|none`
- `--install-subagents both|codex|claude|none`
- `--force`
With `--guides auto`, the initializer preserves existing guide files, but it also ensures `CLAUDE.md` exists whenever Claude agents are being installed and `AGENTS.md` exists whenever Codex agents are being installed.
## Validation
The package includes a smoke test:
```bash
python3 "$SKILL_PATH/scripts/verify_package.py"
```
It checks the skill structure, initializes temporary repositories, installs the task artifacts and subagents, and verifies the generated task bundles and guide behavior.
## More Detail
The exact role prompts and platform-specific guidance live in:
- `references/COMMANDS.md`
- `references/SUBAGENTS.md`
- `references/REFERENCE.md`
- `SKILL.md`