Loop

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

• Do only the control actions this skill explicitly requires.
• Do NOT implement, review, fix issues, run checks, inspect repository.

1. Prepare handoff

Build a concise initial_prompt for the next LLM. Include user's request and context from previous 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 previous conversation, if user's request is not self-contained.>

## Critical Data, Examples, and References

<Supplied from previous conversation, if user's request is not self-contained.>

Keep it concise, structured, and focused on helping the next LLM seamlessly continue the work.

$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. Create handoff file

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

3. Run the Rounds

Run at most 6 rounds by default (user can change via --rounds N). In each round, do the following:

1. Start one subagent using the potter_worker agent.

2. Prompt the subagent with handoff file path only:

   Work according to this handoff file: <path to handoff md file>
   

3. Wait for the subagent to finish.

4. Report last subagent message, keep it unchanged.

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

4. Final Report

After the loop stops, report these to user (using bullet points):

• Total rounds run.
• State (one of):
  • round limit reached
  • finished (when finite_incantatem==true)
• git hash change (if available) (xxxxxx -> xxxxxx).
• Last subagent messages of each round, which is the work summary. Keep it unchanged.
• Overall summary (according to last subagent messages in all rounds).

Do not add implementation analysis, code review, extra verification, or recommendations beyond the loop outcome.

How to resume

If what user passed in is an existing handoff file to resume (iterate more rounds), you should:

1. Reset handoff file status to open, finite_incantatem to false.
2. Follow the same steps in "3. Run the Rounds" section.

How to continue

If current loop was paused / interrupted and user wants to continue, you could simply send continue prompt to the subagent.

Feedback Principles

• Keep concise and structured way.
• Before start the loop, tell user: how many rounds to run, handoff file path (using bullet points).
• Do not mention this control flow details like "finite_incantatem", etc. User only know "rounds", "handoff file".
• Feedback using the same language as user request.