| name | loop |
| description | Use only when user explicitly invokes $loop. |
This is a control protocol for running subagents in a loop pattern to "reconcile" repo to fulfill the user request, which may be a complex task or target state.
When working in this pattern, subagents own all task execution, you are the orchestrator, you must:
Control parameters:
Build a concise initial_prompt for the subagent. Include user's request and context from current conversation; do not inspect the repository to enrich it.
Structure initial_prompt with these sections:
## Original User Request
<The user's original request, unchanged.>
## Important Context, Constraints, and User Preferences
<Supplied from current conversation, if user's request is not self-contained.>
## Critical Data, Examples, and References
<Supplied from current conversation, if user's request is not self-contained.>
Next agent knows nothing about the current conversation - not even what user said or you previously said. Thus, make sure initial_prompt is self-contained, including all necessary context, including what you have previously replied and what user previously talked, related to working on the task.
Keep it concise, structured, and focused on helping the next agent seamlessly continue the work. Do not make up context or details. Do not enhance the initial_prompt with your own analysis, assumptions or deductions.
$loop control flow instructions MUST BE EXCLUDED in initial_prompt, otherwise subagent will loop again.
Other skills like $xxx should be kept as is if they are part of the user request.
2.1. Resolve the current git commit with git rev-parse HEAD, skip if not in a git repository.
2.2. Create handoff file:
.codexpotter/projects_v2/{yyyy}_{mm}_{dd}_{slug}.md
where:
{yyyy} {mm} {dd} is current local date{slug} is a short descriptive name generated from the user request (e.g., "add_login_feature", "fix_bug_123").Do not overwrite an existing project directory.
2.3. Write handoff file in this shape:
---
status: initial
finite_incantatem: false
git_commit: <current_git_commit> <-- leave empty if not in a git repository
---
# Overall Goal
<initial_prompt>
## In Progress
## Todo
## Done
Run at most 6 rounds by default (user can change via --rounds N). In each round, do the following:
Start one subagent using the potter_worker agent.
Prompt the subagent with handoff file path only:
Work according to [this handoff file](<path to handoff md file>)
Wait for the subagent to finish. Subagent may take long time (e.g. 3 hours). Wait patiently, do not timeout or interrupt it.
Close the subagent after it finishes.
Report last subagent message, keep it unchanged.
Read handoff file, stop if the frontmatter contains the literal value finite_incantatem: true
If potter_worker agent is not available: This is a critical issue. Fail fast, do not use other alternative agents. Ask user to follow https://github.com/breezewish/CodexPotter to setup.
If handoff file cannot be read: Stop immediately and report the control-state problem. Do not repair it in the parent agent.
If finite_incantatem is not true after a round and there are more rounds left:
Start the next round (even if subagent reports all tasks done).
After the loop stops, report these info to user:
Do not add implementation analysis, code review, extra verification, or recommendations beyond the loop outcome.
If what user passed in is an existing handoff file to resume (iterate more rounds), you should:
open, finite_incantatem to false.If current loop was paused / interrupted and user wants to continue, you could simply send continue prompt to the subagent.
When subagent fails or encounters an error, resume it by simply sending a continue prompt. Retry several times if it keeps failing.
This resumes the subagent with same working knowledge, ensures maximum continuity.
As the last resort, close the subagent and start a new one.