Skip to content
Back to search

repo-task-proof-loop

Repo-local workflow skill for large coding tasks. Initializes .agent/tasks/TASK_ID artifacts, installs project-scoped Codex and Claude subagents, updates AGENTS.md plus the repo's Claude guide file with the workflow, and runs a spec-freeze → build → evidence → verify → fix loop with fresh-session verification.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/denissergeevitch--repo-task-proof-loop/badge.svg)](/listings/denissergeevitch--repo-task-proof-loop)

HTML

<a href="/listings/denissergeevitch--repo-task-proof-loop"><img src="/api/listings/denissergeevitch--repo-task-proof-loop/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install the skill as a project skill.

Codex

.agents/skills/repo-task-proof-loop/

Claude Code

.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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 255 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: repo-task-proof-loop
  3. description: Repo-local workflow skill for large coding tasks. Initializes .agent/tasks/TASK_ID artifacts, installs project-scoped Codex and Claude subagents, updates AGENTS.md plus the repo's Claude guide file with the workflow, and runs a spec-freeze → build → evidence → verify → fix loop with fresh-session verification.
  4. license: Apache-2.0
  5. compatibility: Skills-compatible coding agents. Integrates with Codex and Claude Code project-scoped subagents. Bundled scripts require Python 3.10+.
  6. metadata:
  7. author: OpenAI
  8. version: "1.0.0"
  9. ---
  10. # Repo Task Proof Loop
  11. Use this skill when the user wants a repeatable, auditable implementation workflow for a non-trivial coding task, especially a feature, refactor, migration, or bug fix that should leave repo-local proof in `.agent/tasks/<TASK_ID>/`.
  12. All task artifacts created by this workflow must stay inside the repository.
  13. When the examples below mention `scripts/task_loop.py`, that path is relative to this skill root. Run it while your shell working directory is inside the target repository.
  14. ## What this skill does
  15. 1. Initializes a strict repo-local task folder under `.agent/tasks/<TASK_ID>/`
  16. 2. Seeds or updates the required artifact files
  17. 3. Installs project-scoped Codex and Claude subagent templates into `.codex/agents/` and `.claude/agents/`
  18. 4. Updates the repo-root `AGENTS.md` Codex baseline plus the repo's Claude guide file (`CLAUDE.md` or `.claude/CLAUDE.md`) with a managed block that explains the workflow
  19. 5. Guides the agent through a strict loop:
  20. - spec freeze
  21. - builder implementation
  22. - evidence packing
  23. - fresh verification
  24. - minimal fix
  25. - fresh verification again until `PASS`
  26. See:
  27. - `references/REFERENCE.md`
  28. - `references/COMMANDS.md`
  29. - `references/SUBAGENTS.md`
  30. - `references/SCHEMAS.md`
  31. ## Commands this skill supports
  32. Treat the following words as commands when the user invokes this skill:
  33. - `init <TASK_ID>`: create `.agent/tasks/<TASK_ID>/`, install or refresh subagent templates, and update `AGENTS.md` plus the repo's Claude guide file
  34. - `freeze <TASK_ID>`: create or refine `spec.md` from the user task, task file, and repo guidance
  35. - `build <TASK_ID>`: implement the task against the frozen spec
  36. - `evidence <TASK_ID>`: create or refresh `evidence.md`, `evidence.json`, and raw artifacts without changing production code
  37. - `verify <TASK_ID>`: run a fresh verifier pass and write `verdict.json`, plus `problems.md` when needed
  38. - `fix <TASK_ID>`: apply the smallest safe fix set from `problems.md`, then refresh the evidence bundle
  39. - `run <TASK_ID>`: execute the full loop from spec freeze through verification
  40. - `status <TASK_ID>`: summarize current artifact status
  41. If the user does not supply a command, infer the next step from repo state:
  42. - If the task folder does not exist, run `init` first. If the user clearly wants initialization only, stop there. Otherwise, after `init` succeeds and `.agent/tasks/<TASK_ID>/spec.md` exists, continue by re-evaluating repo state in the same turn. Do not overlap `init` with `freeze`, `build`, `evidence`, `verify`, `fix`, `validate`, `status`, or subagent work.
  43. - If `spec.md` is missing or placeholder-only, do `freeze`
  44. - If implementation is not yet complete, do `build`
  45. - If evidence is stale or missing, do `evidence`
  46. - If no fresh verdict exists, do `verify`
  47. - If verdict is not `PASS`, do `fix`
  48. ## Initialization step
  49. Run the bundled initializer from the repository root or current working directory inside the repo:
  50. ```bash
  51. scripts/task_loop.py init --task-id <TASK_ID>
  52. ```
  53. Optional task seeding:
  54. ```bash
  55. scripts/task_loop.py init --task-id <TASK_ID> --task-file path/to/task.md
  56. scripts/task_loop.py init --task-id <TASK_ID> --task-text "User task text"
  57. ```
  58. The initializer will:
  59. - resolve the repo root
  60. - create `.agent/tasks/<TASK_ID>/`
  61. - create all required artifacts, including placeholders under `raw/`
  62. - install project-scoped subagent files
  63. - insert or refresh managed workflow blocks in `AGENTS.md` and the repo's Claude guide file
  64. For Codex, the initializer keeps its managed workflow block in the repo-root `AGENTS.md`. Codex also supports `AGENTS.override.md` and configured fallback guide filenames; nested files closer to the code still take precedence, and this skill intentionally does not overwrite them.
  65. If `init` creates or rewrites `AGENTS.md` during a running Codex session, start a new Codex session before relying on the updated instructions. Codex snapshots project-doc guidance at session start.
  66. For Claude Code, the initializer keeps its managed workflow block in the repo-root `CLAUDE.md`. Claude Code also supports `.claude/CLAUDE.md`, `.claude/rules/*.md`, and `CLAUDE.local.md`, but this skill treats root `CLAUDE.md` as the primary project guide because Claude surfaces it directly.
  67. In Claude Code, if `init` just wrote or refreshed `.claude/agents/*` during the current session, do not assume those updated agents are already available mid-session.
  68. Treat `init` as a serial prerequisite. Never overlap it with `freeze`, `build`, `evidence`, `verify`, `fix`, `validate`, `status`, or child-agent spawning.
  69. ## Heavy-task default workflow
  70. For large tasks, keep the user-facing request simple. In Codex, continue serially unless the user explicitly asks for delegation or parallel agent work; after that authorization, the skill can choose the internal child setup automatically when the current product surface supports delegation and the task shape warrants it.
  71. ### Preferred delegated sequence
  72. 1. Run `init <TASK_ID>` if needed. Wait for it to finish, then confirm `.agent/tasks/<TASK_ID>/spec.md` and the repo-local task structure exist before continuing.
  73. 2. Only after `init` completes, spawn exactly one spec-freezer subagent and wait for it
  74. 3. Spawn exactly one builder subagent and let it implement
  75. 4. Continue with the same builder session for evidence packing
  76. 5. Spawn exactly one fresh verifier subagent and wait for it
  77. 6. If verdict is not `PASS`, spawn exactly one fixer subagent
  78. 7. Spawn one fresh verifier subagent again
  79. 8. Repeat steps 6-7 until the verifier returns `PASS` or the user stops the loop
  80. ### Codex adaptive fan-out
  81. Use this only after the user has explicitly authorized Codex delegation and the task is broad enough to benefit from bounded parallel work. Use the simpler serial sequence above for narrow tasks.
  82. Good fits:
  83. - multiple independent codebase questions must be answered before the spec is stable
  84. - implementation can be split into disjoint write scopes
  85. - proof requires several independent read-only checks across different surfaces
  86. Codex pattern:
  87. 1. `init` stays serial.
  88. 2. If the task is still ambiguous, fan out up to 3 built-in `explorer` children in parallel. Give each one a single question, subsystem, or path scope. Wait for them, then freeze the spec.
  89. 3. Spawn one spec-freezer child and wait for it.
  90. 4. Spawn one `task-builder` child as the integration owner.
  91. 5. If implementation splits cleanly, the parent may also spawn bounded built-in `worker` children in parallel. Each worker must have explicit file or module ownership and must not write `evidence.md`, `evidence.json`, `verdict.json`, or `problems.md`.
  92. 6. Use `send_input` or the equivalent follow-up surface to keep the integration builder alive for evidence packing. The builder remains the single owner of the evidence bundle.
  93. 7. If extra proof is needed, the parent may fan out a small bounded set of read-only `explorer` children to rerun disjoint checks or inspect separate proof gaps in parallel. Those children may report commands, outputs, and findings, but they do not write `verdict.json`.
  94. 8. Run exactly one fresh verifier child for each verify pass.
  95. ### Platform behavior
  96. - In Codex, keep the normal path serial and auto-mode-first after `init`. Avoid surfacing delegation internals unless they materially affect the work.
  97. - In Codex, spawn bounded subagents only when the user explicitly asks for sub-agents, delegation, or parallel agent work.
  98. - In Codex, once delegation is authorized, the skill may choose the matching child roles and whether to stay one-child-at-a-time or use bounded fan-out. The user should not need to name specific child roles or slash commands.
  99. - In Codex, child spawning is still an explicit parent-orchestrator action. If the current Codex surface blocks delegation, say so briefly only when it materially affects the work, then continue serially.
  100. - In Codex, keep the task tree shallow. The parent session should spawn research, builder, fixer, and verifier children directly instead of asking one custom task child to orchestrate more children.
  101. - In Codex, once delegation is authorized, choose between one-child-at-a-time delegation and bounded fan-out from the frozen spec, repo shape, and current delegation surface. Keep `init`, evidence ownership, and every verifier pass serialized either way.
  102. - In Codex, keep helper fan-out modest and wave-based. Prefer up to 3 parallel helper children at once, wait for that wave to finish, then decide the next phase.
  103. - In Codex, built-in `explorer` is the first choice for read-only repo discovery and proof probes. Built-in `worker` is appropriate for bounded disjoint implementation or check reruns when you can assign explicit ownership.
  104. - In Codex, reuse the live builder child for evidence packing by sending it a follow-up instruction. Verifier passes must use a fresh child or fresh session; do not satisfy verifier freshness by resuming an earlier verifier. Builder and fixer children can be reused or resumed when you intentionally want that context back.
  105. - In Codex, inspect the current child-thread list before reusing or resuming a child. Use `/agent` in Codex CLI or any equivalent child-thread inventory surface available in the current Codex product surface.
  106. - In Codex, the plan/todo checklist UI from `update_plan` is optional session guidance only. It is useful for live progress display, but it is not the source of truth for this workflow.
  107. - In Claude Code, the skill should decide whether to stay on the main thread or let the main Claude session auto-delegate the current phase to a matching built-in or project subagent after `init`. The user should not need to request a specific Claude subagent or delegation mode separately.
  108. - In Claude Code, TodoWrite or the visible task/todo UI is optional session-scoped progress display only. It can help with live tracking in the current session, but it is not the source of truth for this workflow.
  109. - In Claude Code, prefer the installed project subagents from `.claude/agents/`, with descriptions written as proactive trigger conditions for the matching proof-loop phase. Claude's main session routes by the task request, subagent descriptions, and current context, so keep each phase prompt clear in natural language. Reuse the same builder child for the evidence step by default. Only run a fresh builder in evidence-only mode if the original builder session is unavailable or you intentionally discarded it. If `init` just refreshed `.claude/agents/*` during the current Claude session, fall back to the main thread or already-visible agents instead of assuming the refreshed ones are available immediately.
  110. - In Claude Code, keep the orchestration flat: main-session auto-delegation is fine, but the proof-loop workflow agents themselves are leaf roles. The parent session should own the proof-loop phase transitions instead of asking one custom task agent to spawn another.
  111. - In Claude Code, the canonical durable state is always the repo-local artifact set under `.agent/tasks/<TASK_ID>/`, especially `spec.md`, `evidence.md`, `evidence.json`, `verdict.json`, and `problems.md`.
  112. - If subagents are unavailable, preserve the same role separation across separate sessions or clear mode changes in the current session.
  113. Use the exact role prompts from `references/COMMANDS.md`.
  114. ## Spec freeze requirements
  115. `spec.md` must contain at least:
  116. - original task statement
  117. - explicit acceptance criteria labeled `AC1`, `AC2`, ...
  118. - constraints
  119. - non-goals
  120. It may also include:
  121. - repo guidance sources
  122. - verification plan
  123. - assumptions resolved narrowly from the user request
  124. Do not edit production code during spec freeze.
  125. ## Evidence packing requirements
  126. `evidence.md` and `evidence.json` must judge each acceptance criterion independently with one of:
  127. - `PASS`
  128. - `FAIL`
  129. - `UNKNOWN`
  130. Evidence packing may run missing checks, but it must not keep changing production code.
  131. Every `PASS` must cite concrete proof such as:
  132. - file paths
  133. - commands run
  134. - exit codes
  135. - output summaries
  136. - artifact paths under `raw/`
  137. Do not claim overall `PASS` in the evidence bundle unless every acceptance criterion is `PASS`.
  138. ## Fresh verification requirements
  139. The verifier must be a fresh session or fresh subagent.
  140. In Codex, do not satisfy this requirement by resuming a prior verifier child.
  141. The verifier must judge the current repository state and current rerun results, not the builder narrative.
  142. The verifier writes:
  143. - `.agent/tasks/<TASK_ID>/verdict.json`
  144. - `.agent/tasks/<TASK_ID>/problems.md` only when overall verdict is not `PASS`
  145. `problems.md` must include, for each non-`PASS` criterion:
  146. - criterion id and text
  147. - status
  148. - why it is not proven
  149. - minimal reproduction steps
  150. - expected vs actual
  151. - affected files
  152. - smallest safe fix
  153. - corrective hint in 1-3 sentences
  154. The verifier must not modify production code or backfill the evidence bundle.
  155. ## Fixer requirements
  156. The fixer reads only:
  157. - `spec.md`
  158. - `verdict.json`
  159. - `problems.md`
  160. The fixer must:
  161. - reconfirm each listed problem in the codebase before editing
  162. - make the smallest safe change set
  163. - avoid regressing already-passing criteria
  164. - regenerate `evidence.md`, `evidence.json`, and raw artifacts
  165. - stop without writing final sign-off
  166. ## Validation
  167. Before claiming the workflow is correctly initialized or the artifact set is complete, run:
  168. ```bash
  169. scripts/task_loop.py validate --task-id <TASK_ID>
  170. ```
  171. Run `validate` only after `init` has fully finished. If it reports initialization in progress, wait and rerun it instead of treating that result as stable task failure.
  172. For a quick summary:
  173. ```bash
  174. scripts/task_loop.py status --task-id <TASK_ID>
  175. ```
  176. Run `status` only after `init` has fully finished when you need stable task state. If it reports `init_in_progress: true`, treat that as a retry-later condition.
  177. ## Guardrails
  178. - Keep `.agent/tasks/<TASK_ID>/` inside the repo
  179. - Treat the Codex todo/checklist UI as ephemeral progress only; the durable workflow state lives in `.agent/tasks/<TASK_ID>/`
  180. - Never claim task completion unless every acceptance criterion is `PASS`
  181. - Separate evaluator and fixer roles
  182. - Keep Codex fan-out shallow and bounded. Parallel helpers may inform the proof loop, but one builder still owns evidence and one fresh verifier still owns verdict.
  183. - Keep the verifier fresh
  184. - Prefer the smallest defensible diffs during fixes
  185. - Preserve existing user guidance outside the managed blocks in `AGENTS.md` and the repo's chosen Claude guide file
README.md · README · 181 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ![Banner](assets/images/banner.png)
  2. # Repo Task Proof Loop
  3. 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.
  4. > "next-state signals are universal, and policy can learn from all of them simultaneously."
  5. Repo Task Proof Loop is a repo-local workflow skill for non-trivial coding tasks.
  6. 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:
  7. `spec freeze -> build -> evidence -> fresh verify -> minimal fix -> fresh verify`
  8. For Codex, that loop also supports an adaptive bounded fan-out path for `explorer` or `worker` children when the task splits cleanly.
  9. The point is simple: keep proof inside the repository, separate implementation from verification, and make task state easy to resume or audit later.
  10. ![Repo Task Proof Loop Diagram](assets/images/proof-loop-diagram.png)
  11. ## What It Creates
  12. Inside the target repository:
  13. ```text
  14. .agent/tasks/<TASK_ID>/
  15. spec.md
  16. evidence.md
  17. evidence.json
  18. raw/
  19. build.txt
  20. test-unit.txt
  21. test-integration.txt
  22. lint.txt
  23. screenshot-1.png
  24. verdict.json
  25. problems.md
  26. .codex/agents/
  27. task-spec-freezer.toml
  28. task-builder.toml
  29. task-verifier.toml
  30. task-fixer.toml
  31. .claude/agents/
  32. task-spec-freezer.md
  33. task-builder.md
  34. task-verifier.md
  35. task-fixer.md
  36. ```
  37. It also inserts managed workflow blocks into:
  38. - the repo-root `AGENTS.md` Codex baseline
  39. - the repo's Claude guide file: `CLAUDE.md` or `.claude/CLAUDE.md`
  40. ## Install
  41. Install the skill as a project skill.
  42. ### Codex
  43. ```text
  44. .agents/skills/repo-task-proof-loop/
  45. ```
  46. ### Claude Code
  47. ```text
  48. .claude/skills/repo-task-proof-loop/
  49. ```
  50. If you use both tools on the same repository, install it in both locations or keep one canonical copy and sync it.
  51. ## Quick Prompts
  52. Use this prompt for the normal flow:
  53. ### Do Task
  54. ```text
  55. 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.
  56. ...
  57. ```
  58. 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.
  59. This skill is intentionally proof-first, so `init` always comes before build.
  60. For users, the intended interaction stays simple: run Codex, mention `$repo-task-proof-loop`, and describe the task.
  61. ## Quick Start
  62. 1. Install the skill in the repository.
  63. 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.
  64. 3. That's it.
  65. ## Helper Script
  66. The bundled helper script currently ships three CLI commands:
  67. - `init` - create the repo-local task folder, artifacts, guides, and subagents
  68. - `validate`
  69. - `status` - inspect an existing initialized task
  70. The workflow phases `freeze`, `build`, `evidence`, `verify`, `fix`, and `run` are skill-level commands for the agent, not direct CLI subcommands in this package.
  71. Set `SKILL_PATH` to the installed skill directory:
  72. ### Codex example
  73. ```bash
  74. SKILL_PATH=.agents/skills/repo-task-proof-loop
  75. ```
  76. ### Claude Code example
  77. ```bash
  78. SKILL_PATH=.claude/skills/repo-task-proof-loop
  79. ```
  80. Initialize a task:
  81. ```bash
  82. python3 "$SKILL_PATH/scripts/task_loop.py" init \
  83. --task-id feature-auth-hardening \
  84. --task-file docs/tasks/auth-hardening.md
  85. ```
  86. Or seed from inline text:
  87. ```bash
  88. python3 "$SKILL_PATH/scripts/task_loop.py" init \
  89. --task-id feature-auth-hardening \
  90. --task-text "Implement auth hardening for session refresh and logout."
  91. ```
  92. Validate:
  93. ```bash
  94. python3 "$SKILL_PATH/scripts/task_loop.py" validate \
  95. --task-id feature-auth-hardening
  96. ```
  97. Run `validate` only after `init` completes. If it reports initialization in progress, wait and rerun.
  98. Status:
  99. ```bash
  100. python3 "$SKILL_PATH/scripts/task_loop.py" status \
  101. --task-id feature-auth-hardening
  102. ```
  103. Use `status` after `init` completes when you want stable task state. If it returns `init_in_progress: true`, retry after `init` finishes.
  104. Useful options:
  105. - `--guides auto|agents|claude|both|none`
  106. - `--install-subagents both|codex|claude|none`
  107. - `--force`
  108. 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.
  109. ## Validation
  110. The package includes a smoke test:
  111. ```bash
  112. python3 "$SKILL_PATH/scripts/verify_package.py"
  113. ```
  114. It checks the skill structure, initializes temporary repositories, installs the task artifacts and subagents, and verifies the generated task bundles and guide behavior.
  115. ## More Detail
  116. The exact role prompts and platform-specific guidance live in:
  117. - `references/COMMANDS.md`
  118. - `references/SUBAGENTS.md`
  119. - `references/REFERENCE.md`
  120. - `SKILL.md`

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.