Repo Task Proof Loop

Repo Task Proof Loop

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

All task artifacts created by this workflow must stay inside the repository.

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.

What this skill does

1. Initializes a strict repo-local task folder under .agent/tasks/<TASK_ID>/ 2. Seeds or updates the required artifact files 3. Installs project-scoped Codex and Claude subagent templates into .codex/agents/ and .claude/agents/ 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 5. Guides the agent through a strict loop:

• spec freeze
• builder implementation
• evidence packing
• fresh verification
• minimal fix
• fresh verification again until PASS

See:

• references/REFERENCE.md
• references/COMMANDS.md
• references/SUBAGENTS.md
• references/SCHEMAS.md

Commands this skill supports

Treat the following words as commands when the user invokes this skill:

• init <TASK_ID>: create .agent/tasks/<TASK_ID>/, install or refresh subagent templates, and update AGENTS.md plus the repo's Claude guide file
• freeze <TASK_ID>: create or refine spec.md from the user task, task file, and repo guidance
• build <TASK_ID>: implement the task against the frozen spec
• evidence <TASK_ID>: create or refresh evidence.md, evidence.json, and raw artifacts without changing production code
• verify <TASK_ID>: run a fresh verifier pass and write verdict.json, plus problems.md when needed
• fix <TASK_ID>: apply the smallest safe fix set from problems.md, then refresh the evidence bundle
• run <TASK_ID>: execute the full loop from spec freeze through verification
• status <TASK_ID>: summarize current artifact status

If the user does not supply a command, infer the next step from repo state:

• 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.
• If spec.md is missing or placeholder-only, do freeze
• If implementation is not yet complete, do build
• If evidence is stale or missing, do evidence
• If no fresh verdict exists, do verify
• If verdict is not PASS, do fix

Initialization step

Run the bundled initializer from the repository root or current working directory inside the repo:

scripts/task_loop.py init --task-id <TASK_ID>

Optional task seeding:

scripts/task_loop.py init --task-id <TASK_ID> --task-file path/to/task.md
scripts/task_loop.py init --task-id <TASK_ID> --task-text "User task text"

The initializer will:

• resolve the repo root
• create .agent/tasks/<TASK_ID>/
• create all required artifacts, including placeholders under raw/
• install project-scoped subagent files
• insert or refresh managed workflow blocks in AGENTS.md and the repo's Claude guide file

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

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.

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.

Treat init as a serial prerequisite. Never overlap it with freeze, build, evidence, verify, fix, validate, status, or child-agent spawning.

Heavy-task default workflow

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.

Preferred delegated sequence

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. 2. Only after init completes, spawn exactly one spec-freezer subagent and wait for it 3. Spawn exactly one builder subagent and let it implement 4. Continue with the same builder session for evidence packing 5. Spawn exactly one fresh verifier subagent and wait for it 6. If verdict is not PASS, spawn exactly one fixer subagent 7. Spawn one fresh verifier subagent again 8. Repeat steps 6-7 until the verifier returns PASS or the user stops the loop

Codex adaptive fan-out

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.

Good fits:

• multiple independent codebase questions must be answered before the spec is stable
• implementation can be split into disjoint write scopes
• proof requires several independent read-only checks across different surfaces

Codex pattern:

1. init stays serial. 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. 3. Spawn one spec-freezer child and wait for it. 4. Spawn one task-builder child as the integration owner. 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. 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. 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. 8. Run exactly one fresh verifier child for each verify pass.

Platform behavior

• In Codex, keep the normal path serial and auto-mode-first after init. Avoid surfacing delegation internals unless they materially affect the work.
• In Codex, spawn bounded subagents only when the user explicitly asks for sub-agents, delegation, or parallel agent work.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• If subagents are unavailable, preserve the same role separation across separate sessions or clear mode changes in the current session.

Use the exact role prompts from references/COMMANDS.md.

Spec freeze requirements

spec.md must contain at least:

• original task statement
• explicit acceptance criteria labeled AC1, AC2, ...
• constraints
• non-goals

It may also include:

• repo guidance sources
• verification plan
• assumptions resolved narrowly from the user request

Do not edit production code during spec freeze.

Evidence packing requirements

evidence.md and evidence.json must judge each acceptance criterion independently with one of:

• PASS
• FAIL
• UNKNOWN

Evidence packing may run missing checks, but it must not keep changing production code.

Every PASS must cite concrete proof such as:

• file paths
• commands run
• exit codes
• output summaries
• artifact paths under raw/

Do not claim overall PASS in the evidence bundle unless every acceptance criterion is PASS.

Fresh verification requirements

The verifier must be a fresh session or fresh subagent. In Codex, do not satisfy this requirement by resuming a prior verifier child.

The verifier must judge the current repository state and current rerun results, not the builder narrative.

The verifier writes:

• .agent/tasks/<TASK_ID>/verdict.json
• .agent/tasks/<TASK_ID>/problems.md only when overall verdict is not PASS

problems.md must include, for each non-PASS criterion:

• criterion id and text
• status
• why it is not proven
• minimal reproduction steps
• expected vs actual
• affected files
• smallest safe fix
• corrective hint in 1-3 sentences

The verifier must not modify production code or backfill the evidence bundle.

Fixer requirements

The fixer reads only:

• spec.md
• verdict.json
• problems.md

The fixer must:

• reconfirm each listed problem in the codebase before editing
• make the smallest safe change set
• avoid regressing already-passing criteria
• regenerate evidence.md, evidence.json, and raw artifacts
• stop without writing final sign-off

Validation

Before claiming the workflow is correctly initialized or the artifact set is complete, run:

scripts/task_loop.py validate --task-id <TASK_ID>

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.

For a quick summary:

scripts/task_loop.py status --task-id <TASK_ID>

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.

Guardrails

• Keep .agent/tasks/<TASK_ID>/ inside the repo
• Treat the Codex todo/checklist UI as ephemeral progress only; the durable workflow state lives in .agent/tasks/<TASK_ID>/
• Never claim task completion unless every acceptance criterion is PASS
• Separate evaluator and fixer roles
• 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.
• Keep the verifier fresh
• Prefer the smallest defensible diffs during fixes
• Preserve existing user guidance outside the managed blocks in AGENTS.md and the repo's chosen Claude guide file

<!-- repo-task-proof-loop:start -->

Repo task proof loop

For substantial features, refactors, and bug fixes, use the repo-task-proof-loop workflow.

Required artifact path:

• Keep all task artifacts in .agent/tasks/<TASK_ID>/ inside this repository.

Required sequence: 1. Freeze .agent/tasks/<TASK_ID>/spec.md before implementation. 2. Implement against explicit acceptance criteria (AC1, AC2, ...). 3. Create evidence.md, evidence.json, and raw artifacts. 4. Run a fresh verification pass against the current codebase and rerun checks. 5. If verification is not PASS, write problems.md, apply the smallest safe fix, and reverify.

Hard rules:

• Do not claim completion unless every acceptance criterion is PASS.
• Verifiers judge current code and current command results, not prior chat claims.
• Fixers should make the smallest defensible diff.
• For broad Codex tasks, bounded fan-out is allowed only after init, only when the user has explicitly asked for delegation or parallel agent work, and only when task shape warrants it: use bounded explorer children before or after spec freeze, use bounded worker children only after the spec is frozen, keep the task tree shallow, keep evidence ownership with one builder, and keep verdict ownership with one fresh verifier.
• This root AGENTS.md block is the repo-wide Codex baseline. More-specific nested AGENTS.override.md or AGENTS.md files still take precedence for their directory trees.
• Keep this block lean. If the workflow needs more Codex guidance, prefer nested AGENTS.md / AGENTS.override.md files or configured fallback guide docs instead of expanding this root block indefinitely.

Installed workflow agents:

• .codex/agents/task-spec-freezer.toml
• .codex/agents/task-builder.toml
• .codex/agents/task-verifier.toml
• .codex/agents/task-fixer.toml

<!-- repo-task-proof-loop:end -->

<!-- repo-task-proof-loop:start -->

Repo task proof loop

For substantial features, refactors, and bug fixes, use the repo-task-proof-loop workflow.

Required artifact path:

• Keep all task artifacts in .agent/tasks/<TASK_ID>/ inside this repository.

Required sequence: 1. Freeze .agent/tasks/<TASK_ID>/spec.md before implementation. 2. Implement against explicit acceptance criteria (AC1, AC2, ...). 3. Create evidence.md, evidence.json, and raw artifacts. 4. Run a fresh verification pass against the current codebase and rerun checks. 5. If verification is not PASS, write problems.md, apply the smallest safe fix, and reverify.

Hard rules:

• Do not claim completion unless every acceptance criterion is PASS.
• Verifiers judge current code and current command results, not prior chat claims.
• Fixers should make the smallest defensible diff.

Installed workflow agents:

• .claude/agents/task-spec-freezer.md
• .claude/agents/task-builder.md
• .claude/agents/task-verifier.md
• .claude/agents/task-fixer.md

Claude Code note:

• If init just created or refreshed these files during the current Claude Code session, do not assume the refreshed workflow agents are already available.
• The main Claude session may auto-delegate to these workflow agents when the current proof-loop phase matches their descriptions. If automatic delegation is not precise enough, make the current proof-loop phase more explicit in natural language.
• TodoWrite or the visible task/todo UI is optional session-scoped progress display only. The canonical durable proof-loop state is the repo-local artifact set under .agent/tasks/<TASK_ID>/.
• Keep this workflow flat. These generated workflow agents are role endpoints, not recursive orchestrators.
• Keep this block in the root CLAUDE.md. If the workflow needs longer repo guidance, prefer @path imports or .claude/rules/*.md instead of expanding this block.

<!-- repo-task-proof-loop:end -->

!Banner

Repo Task Proof Loop

This skill was built from OpenClaw-RL: Train Any Agent Simply by Talking 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.

!Repo Task Proof Loop Diagram

What It Creates

Inside the target repository:

.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

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

Quick Prompts

Use this prompt for the normal flow:

Do Task

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

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

Claude Code example

SKILL_PATH=.claude/skills/repo-task-proof-loop

Initialize a task:

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:

python3 "$SKILL_PATH/scripts/task_loop.py" init \
  --task-id feature-auth-hardening \
  --task-text "Implement auth hardening for session refresh and logout."

Validate:

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:

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:

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

Commands and role prompts

Use these prompts as the parent-orchestrator language when running the workflow manually or through product-specific subagents.

Replace <TASK_ID> and any placeholder text.

Codex orchestration mapping:

• spawn_agent: spawn one child with agent_type set to the role name from .codex/agents/
• built-in explorer: preferred Codex role for bounded read-only discovery and proof probes
• built-in worker: appropriate for bounded disjoint implementation or check shards when explicit ownership is possible
• send_input: preferred way to reuse a live builder child for evidence packing
• resume_agent: available when you intentionally want an older builder or fixer child back; do not use it to satisfy verifier freshness
• child-thread inventory: inspect the current child list before reusing or resuming a child. In Codex CLI, use /agent; in other Codex surfaces, use the exposed thread inventory if available.
• update_plan: optional way to mirror the current proof-loop step in Codex's todo/checklist UI; do not treat it as the durable workflow record
• CLI surfaces: /agent inspects or switches child threads, /status shows session config, /review reviews the working tree, and /init scaffolds a generic AGENTS.md if you are not using this skill's managed block

Claude Code note:

• Claude can automatically delegate from the main session based on the request, subagent descriptions, and current context. Write Claude-facing proof-loop prompts so the current phase is obvious.
• Claude may use TodoWrite or show a task/todo list UI for multi-step work. Treat that as optional session-scoped progress display only, not as the durable workflow record.
• The canonical proof-loop state always lives in .agent/tasks/<TASK_ID>/....
• Keep the Claude workflow flat. These custom workflow agents are role endpoints, not recursive orchestrators.

init

Parent action:

scripts/task_loop.py init --task-id <TASK_ID> [--task-file path/to/task.md | --task-text "task text"]

init is a serial prerequisite. Never overlap it with freeze, build, evidence, verify, fix, validate, status, or child-agent spawning.

After init, inspect .agent/tasks/<TASK_ID>/spec.md and confirm the repo-local structure is present. In Codex, /init is optional and separate; this skill's initializer already manages the workflow block in AGENTS.md. In Claude Code, if init just created or refreshed .claude/agents/* during the current session, do not assume those refreshed agents are already available mid-session. In Claude Code, a TodoWrite list or visible task UI after init is optional session progress only. Do not treat it as a substitute for the repo-local task files. In Claude Code, after init, normal phase prompts should stay task-focused and let Claude auto-delegate. If delegation is not specific enough, restate the phase more explicitly in natural language rather than relying on out-of-band controls.

freeze

Parent prompt for a spec-freezer subagent

Codex note:

• The child already receives in-scope AGENTS.override.md / AGENTS.md instructions automatically.
• If the child moves into a deeper directory or a path outside the parent's current scope, it should check for any more-specific Codex guide files that apply there.
• CLAUDE.md is not a Codex project instruction file. Only treat it as source material when the parent explicitly wants cross-tool alignment.
• If the parent previously fanned out explorer children, treat their reports as inputs to reconcile, not as final proof.

You are in SPEC FREEZE mode for TASK_ID <TASK_ID>.

Read:
- .agent/tasks/<TASK_ID>/spec.md
- any user-provided task file or inline task text
- only the minimum relevant code needed to freeze the spec

Write or update:
- .agent/tasks/<TASK_ID>/spec.md

Requirements:
- Preserve the original task statement
- Produce explicit acceptance criteria labeled AC1, AC2, ...
- Include constraints
- Include non-goals
- Add a concise verification plan
- Resolve ambiguity narrowly and list assumptions
- Do not change production code
- Do not write evidence, verdict, or problems files

build

Parent prompt for a builder subagent

Codex note:

• The child already receives in-scope AGENTS.override.md / AGENTS.md instructions automatically.
• If the child moves into a deeper directory or a path outside the parent's current scope, it should check for any more-specific Codex guide files that apply there.
• If the parent used parallel helper children, treat their findings or diffs as scoped inputs to validate before claiming a criterion is satisfied.

You are in BUILD mode for TASK_ID <TASK_ID>.

Read:
- .agent/tasks/<TASK_ID>/spec.md

Your job:
- Implement the task against the frozen spec
- Make the smallest safe change set that satisfies the acceptance criteria
- Run focused checks as needed
- Keep unrelated files untouched
- Do not write verdict.json or problems.md
- Do not claim final completion yet

Return to the parent with:
- files changed
- checks run
- open risks

Codex adaptive helpers

Use these only after Codex delegation is explicitly authorized by the user and the task clearly splits into bounded scopes. Otherwise stay on the simpler serial proof loop.

Parent prompt for parallel explorer children

Spawn up to 3 built-in `explorer` children for TASK_ID <TASK_ID>.

Before spawning, inspect the current child-thread list and reuse an already-live scoped explorer only if it is still the right fit.

Each explorer must get exactly one scope:
- path prefix or subsystem
- question to answer
- read-only boundary

Each explorer returns only:
- scope inspected
- findings
- risks
- recommended next checks

Wait for all explorers. Then fold their findings into one spec-freezer, builder, or verifier step.

Parent prompt for parallel worker children

Spawn a bounded set of built-in `worker` children for TASK_ID <TASK_ID>.

Before spawning, inspect the current child-thread list and avoid duplicating an existing scoped worker unless you intentionally want a fresh child.

For each worker, define:
- exact file or module ownership
- acceptance criteria subset or check shard
- no-touch boundaries

Rules:
- do not write .agent/tasks/<TASK_ID>/evidence.md
- do not write .agent/tasks/<TASK_ID>/evidence.json
- do not write .agent/tasks/<TASK_ID>/verdict.json
- do not write .agent/tasks/<TASK_ID>/problems.md
- report files changed and checks run back to the parent

After the workers finish, continue the primary task-builder child so it can integrate the current repo state and own evidence packing.

Parent prompts for built-in helper children in Codex adaptive fan-out

Use these when the task clearly benefits from bounded parallel work and the user has already explicitly asked for delegation or parallel agent work. Once delegation is authorized, choose them from task shape and current delegation availability, keep the task tree shallow, and keep proof-loop artifact ownership with the custom task-* roles. Keep helper fan-out modest and wave-based. Prefer up to 3 parallel helper children at once, then wait before the next phase.

Built-in explorer

Spawn one built-in `explorer` child for TASK_ID <TASK_ID>.

Scope:
- <one bounded question, subsystem, or path prefix>

Rules:
- Read relevant code, tests, and guides
- Do not edit production code
- Do not write proof-loop artifacts
- Do not spawn child agents

Return only:
- paths inspected
- constraints, risks, and existing patterns
- proof or verification gaps worth folding into the spec or evidence plan

Built-in worker

Spawn one built-in `worker` child for TASK_ID <TASK_ID>.

Scope:
- <one bounded implementation or check shard>

Allowed paths:
- <explicit paths or modules>

Rules:
- Edit only the allowed paths
- Do not write .agent/tasks/<TASK_ID>/evidence.md
- Do not write .agent/tasks/<TASK_ID>/evidence.json
- Do not write .agent/tasks/<TASK_ID>/verdict.json
- Do not write .agent/tasks/<TASK_ID>/problems.md
- Do not spawn child agents

Return only:
- files changed
- checks run
- residual integration risks

evidence

Follow-up prompt to the same builder session

Codex note:

• In Codex, keep the builder child alive and send this as a follow-up instruction to that same child so it can reuse its own command results.

PACK EVIDENCE for TASK_ID <TASK_ID>.

Do not change production code.

Read:
- .agent/tasks/<TASK_ID>/spec.md
- the current repository state
- any prior command results from this builder session

Write or update:
- .agent/tasks/<TASK_ID>/evidence.md
- .agent/tasks/<TASK_ID>/evidence.json
- .agent/tasks/<TASK_ID>/raw/build.txt
- .agent/tasks/<TASK_ID>/raw/test-unit.txt
- .agent/tasks/<TASK_ID>/raw/test-integration.txt
- .agent/tasks/<TASK_ID>/raw/lint.txt
- .agent/tasks/<TASK_ID>/raw/screenshot-1.png when a screenshot is useful

Rules:
- For each AC, assign PASS, FAIL, or UNKNOWN
- Every PASS must cite concrete proof
- FAIL and UNKNOWN must explain the gap
- Overall PASS only if every AC is PASS
- If sibling `explorer` or `worker` children gathered raw outputs, fold them into the evidence bundle here instead of letting each child write its own parallel evidence file
- Prefer raw artifacts over narrative prose

Return only:
- overall_status
- created or updated files
- commands a fresh verifier should rerun

In Claude Code, this follow-up is the default path. Use the fallback below only if the original builder session is unavailable or you intentionally want a fresh evidence-only run.

Fallback prompt when the original builder session is unavailable

You are in EVIDENCE-ONLY mode for TASK_ID <TASK_ID>.

Read:
- .agent/tasks/<TASK_ID>/spec.md
- the current repository state

Write the same evidence bundle as above.

Do not change production code.

verify

Parent prompt for a fresh verifier subagent

Codex note:

• Spawn a brand-new verifier child or a fresh standalone session for this step.
• Do not satisfy verifier freshness by resuming an older verifier child.
• If earlier helper children gathered raw outputs, treat them as hints only. The verifier still judges the current repository state and reruns whatever it needs.

You are a strict fresh-session verifier for TASK_ID <TASK_ID>. You are not the implementer.

Read in this order:
1. .agent/tasks/<TASK_ID>/spec.md
2. .agent/tasks/<TASK_ID>/evidence.md
3. .agent/tasks/<TASK_ID>/evidence.json

Then independently inspect the current codebase and rerun verification.
Source of truth is the current repository state and current command results, not prior chat claims.
Use the currently available verification surface directly. If browser or MCP tools are available and relevant, use them rather than narrowing yourself to code reading alone.

Write:
- .agent/tasks/<TASK_ID>/verdict.json

If overall verdict is not PASS, also write:
- .agent/tasks/<TASK_ID>/problems.md

Rules:
- PASS an AC only if it is proven in the current codebase now
- FAIL if contradicted, broken, or incomplete
- UNKNOWN if it cannot be verified locally
- Overall PASS only if every AC PASS
- Do not modify production code
- Do not edit the evidence bundle

`problems.md` requirements for each non-PASS AC:
- criterion id and text
- status
- why it is not proven
- minimal reproduction steps
- expected vs actual
- affected files
- smallest safe fix
- corrective hint in 1-3 sentences

Return only:
- overall_verdict
- created files
- one-line reason for each non-PASS AC

fix

Parent prompt for a fixer subagent

Codex note:

• A fresh fixer is preferred for clean role separation, but Codex does not require fixer freshness.
• Reusing or resuming a fixer child is acceptable when you intentionally want that context back.
• If the parent hands the fixer narrowed findings from prior helper children, reconfirm them in the current repository before editing.

You are a repair agent for TASK_ID <TASK_ID>.

Read only:
- .agent/tasks/<TASK_ID>/spec.md
- .agent/tasks/<TASK_ID>/verdict.json
- .agent/tasks/<TASK_ID>/problems.md

Your job:
- Reconfirm each listed FAIL or UNKNOWN condition before editing
- Make the smallest safe change set
- Avoid regressing already-passing criteria
- Rerun only the relevant checks
- Regenerate:
  - .agent/tasks/<TASK_ID>/evidence.md
  - .agent/tasks/<TASK_ID>/evidence.json
  - updated raw artifacts

Do not:
- write verdict.json
- claim final PASS without a fresh verifier
- make broad refactors unless required to satisfy a criterion

Return only:
- files changed
- checks rerun
- remaining risks

run

Default serial order

Run this sequence strictly in order.
1. init <TASK_ID>
2. wait for init to finish, then confirm .agent/tasks/<TASK_ID>/spec.md exists
3. freeze <TASK_ID> using one spec-freezer child
4. build <TASK_ID> using one builder child
5. evidence <TASK_ID> in the same builder child by default, otherwise in evidence-only mode
6. verify <TASK_ID> using one fresh verifier child
7. if verdict is PASS, stop
8. if verdict is FAIL or UNKNOWN, run fix <TASK_ID> using one fixer child, fresh by default
9. run verify <TASK_ID> again using one fresh verifier child
10. repeat 7-9 until PASS or user stops the loop

Codex adaptive fan-out path

Choose between this path and the simpler serial order automatically from the frozen spec, repo shape, and current delegation surface. Keep init, evidence ownership, and each verifier pass serialized either way.

1. init <TASK_ID>
2. wait for init to finish, then confirm .agent/tasks/<TASK_ID>/spec.md exists
3. inspect the current child-thread list with /agent in the CLI or the current product's exposed child-thread inventory surface
4. if the spec is not stable yet, fan out up to 3 built-in `explorer` children in parallel with disjoint questions or path scopes
5. wait for those explorers, then freeze <TASK_ID> using one spec-freezer child
6. spawn one task-builder child as the integration owner
7. if implementation splits cleanly, fan out bounded built-in `worker` children in parallel with explicit file or module ownership
8. continue the live builder with send_input so it integrates the current repo state, reruns focused checks, and evidence <TASK_ID>
9. if proof still needs extra read-only probes, fan out bounded built-in `explorer` children in parallel to rerun disjoint checks or inspect separate proof gaps
10. wait for those proof explorers, then run verify <TASK_ID> using one fresh verifier child
11. if verdict is PASS, stop
12. if verdict is FAIL or UNKNOWN, run fix <TASK_ID> using one fixer child, then run verify <TASK_ID> again using one fresh verifier child
13. repeat 11-12 until PASS or user stops the loop

status

Parent action:

scripts/task_loop.py status --task-id <TASK_ID>

If the repo is not yet initialized, run init first. Do not run status or validate in parallel with init; wait for init to finish first. If status reports init_in_progress: true, retry later.

Reference

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.

This skill is designed to be portable, but the repository-local artifacts and subagent files it creates must stay in the target repository.

Recommended install locations

Codex

Project skill:

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

Personal skill:

• $HOME/.agents/skills/repo-task-proof-loop/

Claude Code

Project skill:

• .claude/skills/repo-task-proof-loop/

Personal skill:

• ~/.claude/skills/repo-task-proof-loop/

The same skill directory can be reused in either product. The initialization script writes repo-local workflow files into the current repository, not into the skill directory.

Claude Code note:

• This skill manages its workflow block in the project-root CLAUDE.md.
• Claude Code also loads .claude/CLAUDE.md, .claude/rules/*.md, and CLAUDE.local.md, but those remain compatible add-ons outside this skill's managed block.

Repo files created by init

.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

The initializer also creates or refreshes these project-level integration files:

.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

And it inserts a managed workflow block into:

• repo-root AGENTS.md
• one Claude guide file: CLAUDE.md or .claude/CLAUDE.md

If both Claude guide locations exist, the initializer updates the repo-root CLAUDE.md and leaves .claude/CLAUDE.md untouched. The managed block is replaced in place on re-run, so user-authored content outside the managed markers is preserved. For Codex, the managed block always lives in repo-root AGENTS.md. That file acts as the repo-wide baseline. More-specific nested AGENTS.override.md, AGENTS.md, or configured fallback filenames still take precedence in their directory trees, and the initializer does not rewrite them. If init creates or rewrites AGENTS.md during a running Codex session, start a new Codex session before relying on the updated instructions. In Claude Code, CLAUDE.md is the project guide file Claude checks during onboarding. When --guides auto is used together with --install-subagents claude or --install-subagents both, the initializer ensures CLAUDE.md exists even if the repo previously only had AGENTS.md.

Commands

Initialize workflow files

scripts/task_loop.py init --task-id my-task

Codex CLI also has /init to scaffold a generic AGENTS.md, but this skill's initializer already manages the workflow block and does not require /init.

In Claude Code, if init just created or refreshed .claude/agents/* during the current session, do not assume those refreshed agents are already available mid-session.

Seed the task from a task file:

scripts/task_loop.py init --task-id my-task --task-file docs/task.md

Seed the task from inline text:

scripts/task_loop.py init --task-id my-task --task-text "Implement feature X"

Control which guide files are created or updated:

scripts/task_loop.py init --task-id my-task --guides auto
scripts/task_loop.py init --task-id my-task --guides both
scripts/task_loop.py init --task-id my-task --guides agents
scripts/task_loop.py init --task-id my-task --guides claude
scripts/task_loop.py init --task-id my-task --guides none

For Claude Code, --guides auto updates an existing CLAUDE.md or .claude/CLAUDE.md. If neither exists and Claude subagents are being installed, it creates CLAUDE.md.

--guides auto keeps existing guide files up to date, creates both guides when none exist yet, and also creates the product-native guide when you install that product's agents (CLAUDE.md for Claude, AGENTS.md for Codex).

Control which project subagent sets are installed:

scripts/task_loop.py init --task-id my-task --install-subagents both
scripts/task_loop.py init --task-id my-task --install-subagents codex
scripts/task_loop.py init --task-id my-task --install-subagents claude
scripts/task_loop.py init --task-id my-task --install-subagents none

Validate the artifact set

scripts/task_loop.py validate --task-id my-task

Run validate only after init has finished. If it reports initialization in progress, wait and rerun instead of treating that output as the durable workflow state.

Summarize current status

scripts/task_loop.py status --task-id my-task

Run status only after init has finished when you need stable task state. If it returns init_in_progress: true, treat that as a retry-later signal.

Expected working pattern

1. Initialize the task folder 2. Freeze the spec 3. Implement 4. Pack evidence 5. Fresh verify 6. Fix if needed 7. Fresh verify again

Codex adaptive orchestration:

• Keep normal Codex usage auto-mode-first and serial by default. Users do not need child-management details unless they explicitly want delegated or parallel agent work.
• Only after the user has explicitly asked for sub-agents, delegation, or parallel agent work may the parent choose between the serial path above and bounded fan-out from the frozen spec, repo shape, and current delegation surface.
• Once delegation is authorized, the parent may fan out bounded built-in explorer or worker children in parallel when a large Codex task has independent research questions, disjoint write scopes, or several read-only proof probes.
• Keep helper fan-out modest and wave-based. Prefer up to 3 parallel helper children at once, then wait before the next phase.
• Keep the task tree shallow. The parent session should orchestrate children directly instead of asking one custom task child to spawn more children.
• One integration builder still owns evidence.md and evidence.json.
• One fresh verifier still owns verdict.json and problems.md.

For exact prompts to use with child agents, see references/COMMANDS.md.

Claude adaptive delegation:

• Let the main Claude Code session decide whether to auto-delegate the current proof-loop phase to a matching project subagent. Users should not need to name a specific Claude subagent for normal operation.
• Keep prompts phase-focused so the current need is obvious, for example “freeze the spec”, “run a fresh verification pass”, or “repair the non-PASS criteria”.
• If automatic delegation is not specific enough, tighten the natural-language prompt for the current proof-loop phase rather than relying on out-of-band controls.
• Keep the proof loop flat even when delegation is automatic. The parent session still owns phase transitions, the evidence bundle stays with one builder, and each verify pass stays fresh.

Notes

• The initializer does not write the final spec.md content for you. It creates the strict file structure and seeds the task statement when provided. The actual spec freeze is an agent step.
• evidence.json and verdict.json are created with valid placeholder content so validation can run immediately after init.
• raw/screenshot-1.png is created as a tiny placeholder PNG so the required path exists from the start.
• Guidance discovery for seeded task specs includes repo-visible AGENTS.override.md, AGENTS.md, root CLAUDE.md, .claude/CLAUDE.md, and .claude/rules/**/*.md when present.
• That seeded guidance list is a workflow artifact, not a literal dump of Codex's automatic project-doc context.
• Codex can also load extra fallback filenames configured via project_doc_fallback_filenames. The initializer does not try to infer every user's Codex config layer, so treat the seeded guidance list as best-effort when custom fallback filenames matter.
• Codex may also render an update_plan checklist or todo list in the UI. Treat that as ephemeral session progress, not as durable proof-loop state.
• Codex CLI surfaces most relevant to this workflow are /agent, /status, /review, and /init (generic scaffold only).
• Before reusing or resuming a Codex child, inspect the current child-thread list in /agent in the CLI or the equivalent child-thread inventory surface exposed by the current Codex product surface.
• Built-in explorer is the preferred Codex role for read-only repo discovery and proof probes. Built-in worker is appropriate for bounded disjoint implementation or check shards when explicit ownership is possible.
• Claude Code also loads .claude/rules/*.md and .claude/CLAUDE.md as project guidance. The initializer discovers those files when seeding guidance sources for the task.
• After installing or refreshing .claude/agents/ in the current Claude Code session, do not assume the new agent list is already available.
• Claude Code uses the subagent description field to decide when the main session should delegate automatically. Phrase project agent descriptions as proactive trigger conditions when you want Claude to pick them on its own.
• For this workflow, treat the generated Claude agents as flat role endpoints. Do not expect one workflow agent to recursively spawn another.
• Claude Code may also render TodoWrite or a task/todo UI for multi-step work. Treat that as optional session-scoped progress display only. The canonical durable workflow state is the repo-local artifact set under .agent/tasks/<TASK_ID>/.

Artifact schemas

These are the required files for each task folder:

.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

evidence.json

Required top-level keys:

• task_id
• overall_status
• acceptance_criteria
• changed_files
• commands_for_fresh_verifier
• known_gaps

Allowed status values:

• PASS
• FAIL
• UNKNOWN

Recommended shape:

{
  "task_id": "my-task",
  "overall_status": "UNKNOWN",
  "acceptance_criteria": [
    {
      "id": "AC1",
      "text": "Describe the criterion",
      "status": "UNKNOWN",
      "proof": [
        {
          "type": "command",
          "path": ".agent/tasks/my-task/raw/test-unit.txt",
          "command": "npm test -- --runInBand",
          "exit_code": 0,
          "summary": "Targeted unit tests passed."
        }
      ],
      "gaps": []
    }
  ],
  "changed_files": [],
  "commands_for_fresh_verifier": [],
  "known_gaps": []
}

verdict.json

Required top-level keys:

• task_id
• overall_verdict
• criteria
• commands_run
• artifacts_used

Allowed status values:

• PASS
• FAIL
• UNKNOWN

Recommended shape:

{
  "task_id": "my-task",
  "overall_verdict": "UNKNOWN",
  "criteria": [
    {
      "id": "AC1",
      "status": "UNKNOWN",
      "reason": "Not yet verified."
    }
  ],
  "commands_run": [],
  "artifacts_used": []
}

problems.md

Required sections for each non-PASS criterion:

• criterion id and text
• status
• why it is not proven
• minimal reproduction steps
• expected vs actual
• affected files
• smallest safe fix
• corrective hint in 1-3 sentences

Validation script

Run:

scripts/task_loop.py validate --task-id <TASK_ID>

This checks:

• required file presence
• JSON parseability
• top-level key presence
• allowed status values
• task id consistency

Subagent integration

This skill installs project-scoped subagent templates for both Codex and Claude Code.

On the Codex side, these are custom agent TOML config layers, not a separate manifest format.

Installed files

Codex

.codex/agents/task-spec-freezer.toml
.codex/agents/task-builder.toml
.codex/agents/task-verifier.toml
.codex/agents/task-fixer.toml

Claude Code

.claude/agents/task-spec-freezer.md
.claude/agents/task-builder.md
.claude/agents/task-verifier.md
.claude/agents/task-fixer.md

The agent files are intentionally narrow and role-specific.

Codex file shape

Codex custom agents under .codex/agents/ are standalone TOML config layers.

Each file in this skill defines:

• name
• description
• developer_instructions

The Codex templates also use nickname_candidates for cleaner UI labels when several spawned children are visible at once.

Other config.toml keys could be added later if needed, but this skill mostly inherits the parent session's model, sandbox, tools, and MCP configuration.

Codex also ships built-in default, worker, and explorer roles. This skill adds task-specific roles alongside those built-ins rather than replacing the general-purpose ones.

Built-in Codex roles in this workflow

• Use built-in explorer for bounded read-only discovery before spec freeze and for read-only proof probes after build.
• Use built-in worker only when the task cleanly splits into disjoint implementation or check shards with explicit ownership.
• Keep task-builder as the integration owner. Even in broader-task Codex fan-out runs, that role remains the single writer for evidence.md and evidence.json.
• Keep task-verifier as the single fresh judge. Parallel helper children may gather inputs, but they do not write verdict.json.

Role definitions

task-spec-freezer

Purpose:

• Freeze the task into .agent/tasks/<TASK_ID>/spec.md

Hard boundaries:

• May read repo guidance and relevant code
• Must not change production code
• Must not write verdict or problems files

task-builder

Purpose:

• Implement the task and later pack evidence

Modes:

• BUILD
• EVIDENCE

Hard boundaries:

• In BUILD, implement against the spec
• In EVIDENCE, do not change production code

task-verifier

Purpose:

• Fresh-session verification against the current codebase

Hard boundaries:

• Must not edit production code
• Must not patch the evidence bundle to make it look complete
• Must write verdict.json
• Must write problems.md only when the verdict is not PASS

task-fixer

Purpose:

• Repair only what the verifier identified

Hard boundaries:

• Must reread the spec and verifier output
• Must reconfirm the problem before editing
• Must regenerate evidence after the fix
• Must not write final sign-off

Codex invocation pattern

Use explicit delegation language at the parent-orchestrator layer. The skill should spawn one named child, wait for it, and then continue when delegation is the right internal choice. Do not spawn any child until init <TASK_ID> has finished and .agent/tasks/<TASK_ID>/spec.md exists. Do not batch init with other commands or tool calls.

Codex-native expectations that matter here:

• The parent-orchestrator must explicitly spawn a new child, and in Codex it may do so only after the user has explicitly asked for sub-agents, delegation, or parallel agent work.
• Once delegation is authorized, the parent chooses the specific child roles. The user does not need to name the exact role or slash-command flow.
• Keep the task tree shallow. The parent session should orchestrate children directly instead of asking one custom task child to spawn more children.
• Inspect the current child-thread list with /agent in the CLI or the equivalent child-thread inventory surface exposed by the current Codex product surface before respawning or resuming a child.
• Use send_input to continue a live child.
• Use resume_agent only when you intentionally want an older builder or fixer child back. Do not reuse or resume a verifier when freshness matters.
• Before reusing or resuming a child, inspect the current child-thread list rather than assuming the needed child is gone.

Default Codex path for narrower tasks:

• One child per workflow role.
• Same builder child for evidence.
• Fresh verifier child for every verify pass.

Adaptive Codex fan-out path for broader tasks after delegation is explicitly authorized:

• Fan out up to 3 explorer children in parallel when the task needs parallel discovery before the spec is stable.
• Keep one task-builder child as the integration owner.
• If implementation splits cleanly, add bounded worker children in parallel with explicit file or module ownership.
• If proof needs multiple read-only probes, add bounded explorer children in parallel, but keep verdict writing with one fresh verifier child.

Suggested shape:

Spawn one `task-spec-freezer` agent for TASK_ID <TASK_ID>. Wait for it. Tell it to freeze the spec in .agent/tasks/<TASK_ID>/spec.md using the repo guidance and the task source.

Repeat the same pattern for task-builder, task-verifier, and task-fixer.

Keep delegation depth flat. The narrower-task path uses one child per role at a time; the broader-task path may fan out multiple bounded explorer or worker children in parallel.

Fan-out variant:

Spawn two `explorer` children in parallel for TASK_ID <TASK_ID>.

Explorer A scope:
- path prefix: <PATH_A>
- question: <QUESTION_A>

Explorer B scope:
- path prefix: <PATH_B>
- question: <QUESTION_B>

Wait for both. Then fold their findings into one spec-freezer or builder step.

Claude Code invocation pattern

Use the installed project subagents from .claude/agents/. Claude Code can automatically delegate from the main session to a matching subagent based on the task request, the subagent description, and current context, so normal proof-loop prompts do not need to name an agent explicitly. Because this skill writes agent files directly on disk, if init just created or refreshed .claude/agents/* during the current Claude Code session, do not assume those refreshed agents are already available. Treat these agents as preferred workflow roles whose descriptions should encourage automatic delegation from the main session. If automatic delegation is not precise enough, make the current proof-loop phase more explicit in the prompt. Keep verifier freshness and same-builder evidence reuse as hard workflow constraints.

TodoWrite or the visible task/todo list UI is optional session-scoped progress tracking only.

Suggested automatic shape:

Freeze the repo-local spec for TASK_ID <TASK_ID> in `.agent/tasks/<TASK_ID>/spec.md` before any implementation. Use explicit acceptance criteria and constraints.

For Claude Code, keep this distinction explicit:

• TodoWrite or the visible task/todo UI is optional live progress display for the current session.
• .agent/tasks/<TASK_ID>/... is the canonical durable proof-loop state.

When you need a specific role outcome, prefer an explicit natural-language phase prompt:

Run a fresh verifier pass for TASK_ID <TASK_ID> against the current codebase and write `verdict.json`, plus `problems.md` if needed.

For large tasks, prefer one workflow owner per role rather than handing the entire proof loop to one general-purpose child. Descriptions in the Claude agent templates should read as proactive trigger conditions so Claude can delegate more reliably. Prefer wording that starts with Use proactively when.... Keep the delegation flat. Main-session auto-delegation is the intended Claude path here; the workflow agents themselves are leaf roles, so the parent should orchestrate each role directly instead of asking one custom task agent to spawn another.

Same-session evidence packing

The preferred pattern is:

1. Spawn task-builder 2. Let it implement 3. Continue with the same child in EVIDENCE mode

In Codex, this same-session follow-up is the preferred path. Keep the builder child alive and send it a follow-up instruction for evidence packing so it can reuse its own command results and local context. If the parent used parallel explorers or workers earlier, the builder should still stay the single owner of evidence.md and evidence.json and cite those sibling results only after validating they still apply.

In Claude Code, this same-session follow-up is the default path. Only run a second task-builder child with an explicit EVIDENCE-ONLY prompt if the original builder session is unavailable or you intentionally want a fresh evidence-only run.

Verifier freshness is different. In Codex, each verification pass should use a fresh verifier child or a fresh standalone session, not a resumed verifier.

Why the roles stay separate

The workflow is designed to keep:

• implementation
• judgment
• correction

as separate roles. This reduces self-justification and makes failures easier to localize.

Verification

This package was smoke-tested before packaging.

Command run

python scripts/verify_package.py

What the smoke test checks

• SKILL.md frontmatter exists and the name matches the parent directory
• the skill body is non-empty
• scripts/task_loop.py init --task-id demo-task --task-text "Implement a demo task." succeeds inside a fresh temporary git repository
• scripts/task_loop.py validate --task-id demo-task returns valid: true
• a task-local init sentinel makes validate report initialization-in-progress instead of only a misleading missing-files failure when init is still active
• scripts/task_loop.py status --task-id demo-task reports init_in_progress: true when the init sentinel is present
• the expected repo-local artifacts are created under .agent/tasks/demo-task/
• project-scoped subagent files are created under .codex/agents/ and .claude/agents/
• AGENTS.md and CLAUDE.md are created with managed workflow blocks
• generated Codex agent files stay Codex-specific and do not tell Codex to read CLAUDE.md
• generated Codex AGENTS guidance mentions the bounded explorer / worker fan-out path
• generated Codex AGENTS guidance allows explorer fan-out before or after spec freeze and keeps worker fan-out post-freeze only
• generated Codex task-builder template still defines a single integration owner for evidence
• the Codex-facing skill metadata prompt mentions the explorer / worker adaptive fan-out path
• references/COMMANDS.md documents the Codex adaptive fan-out orchestration path, includes first-class built-in explorer / worker helper prompts, and mentions public child-thread inspection surfaces
• seeded guidance discovery includes AGENTS.override.md before AGENTS.md
• seeded guidance discovery includes nested .claude/rules/**/*.md files
• --guides auto --install-subagents claude creates CLAUDE.md even if the repo previously only had AGENTS.md
• --guides auto --install-subagents codex creates AGENTS.md even if the repo previously only had CLAUDE.md

Last local result

PASS