dev-loop

---

name: dev-loop description: Autonomous dev loop that plans, implements, and iteratively reviews code with Codex and Claude review agents until clean. Use when asked to run a dev loop, build a feature autonomously, or implement something with review cycles. argument-hint: [max_iterations=N]

You are running an autonomous dev loop. You MUST NOT stop until the phase is "done". Follow this workflow exactly.

CRITICAL: First Action

YOUR VERY FIRST ACTION must be to check if .claude/dev-loop-state.json exists:

• If it exists: read it, then resume from the recorded phase (see Workflow).
• If it does NOT exist: this is a fresh start. Run the Bootstrap step below.

Do NOT skip this. Do NOT do anything else first.

Bootstrap (fresh start only)

Run these steps in order. Do NOT proceed to the Workflow until all are done:

1. Create a new branch: git checkout -b dev-loop/<short-slug> (2-3 word kebab-case summary of the prompt).
2. Ensure .claude/dev-loop-state.json, .claude/dev-loop.log.md, and .claude/dev-loop-plan.md are gitignored.
3. Write .claude/dev-loop-state.json NOW with this exact content (fill in the values):

   {
     "phase": "plan",
     "prompt": "<the user prompt>",
     "pr_url": null,
     "iteration": 0,
     "max_iterations": <4 or parsed from args>,
     "last_codex_thread": null,
     "last_review_source": null,
     "last_review_summary": null,
     "branch": "<the branch you just created>",
     "ref_files": [],
     "codex_lgtm": false,
     "next_phase": null,
     "slack_channel": null,
     "slack_thread_ts": null
   }
   

   If this was triggered from a Slack thread, populate slack_channel and slack_thread_ts from the trigger context so that progress updates can be posted back to the thread.
4. Initialize .claude/dev-loop.log.md with the header.
5. Scan the prompt for file paths. If found, read them and update ref_files in state.
6. Now proceed to Phase: plan.

State File Schema

{
  "phase": "plan|improve|implement|commit|codex-review|codex-fix|claude-review|claude-fix|done",
  "prompt": "the original work prompt",
  "pr_url": "url if PR is created",
  "iteration": 0,
  "max_iterations": 4,
  "last_codex_thread": "thread id if resuming codex",
  "last_review_source": "codex|claude",
  "last_review_summary": "summary of last review findings",
  "branch": "branch name",
  "ref_files": ["optional list of files referenced in the prompt"],
  "codex_lgtm": false,
  "next_phase": null,
  "slack_channel": "channel ID if triggered from Slack, else null",
  "slack_thread_ts": "thread timestamp if triggered from Slack, else null"
}

iteration tracks full loops (each loop = codex-review + claude-review). Default max_iterations is 4 (so up to 8 total review cycles: 4 codex + 4 claude). The user can override this by passing e.g. /dev-loop:go max_iterations=2 <prompt>.

Workflow

IMPORTANT: After completing ANY phase, immediately continue to the next phase. NEVER stop between phases. The only phase where you may stop is "done".

Phase: plan

1. Create a thorough implementation plan. Write it to .claude/dev-loop-plan.md.
2. Append plan summary to log, update state to phase "improve".
3. Continue immediately to phase "improve". Do NOT use EnterPlanMode or ExitPlanMode — just write the plan to the file and move on.

Phase: improve

1. Review your own plan and ask yourself: "anything to improve?"
2. Refine the plan with improvements. Update .claude/dev-loop-plan.md.
3. Append improvements to log. Update state to phase "implement". Do NOT wait for user approval. Do NOT use ExitPlanMode. Just keep going.

Phase: implement

1. Use the Task tool to spawn an implementation subagent. This gives it a clean context without all the planning back-and-forth. The subagent prompt should be:

   Read .claude/dev-loop-plan.md and .claude/dev-loop-state.json.
   If ref_files are listed in state, read those too.
   Implement the plan fully. Follow all instructions in the plan.
   Do not create commits — just make the code changes.
   When done, list all files you created or modified.
   

   Use subagent_type: "general-purpose".
2. After the subagent finishes, verify the changes look correct (quick scan).
3. Update state to phase "commit".

Phase: commit

1. Check if there are any staged/unstaged changes. If no changes, skip straight to the next review phase (codex-review or claude-review based on next_phase in state, default "codex-review").
2. Stage and create a commit with all changes.
3. If no PR exists yet, create a PR with gh pr create.
4. Push changes.
5. Post iteration summary PR comment. If this commit completes a full review cycle (i.e., last_review_source is set — meaning we're coming from codex-fix or claude-fix, not the initial implementation), add a PR comment via gh pr comment summarizing the iteration that just finished. The comment should include:
   • Iteration number (from state)
   • Codex review verdict and issues found/fixed (or LGTM)
   • Claude review verdict and issues found/fixed (or clean)
   • Brief list of what was changed in this cycle
   • Format: use a header like ## Dev Loop — Iteration N Review Summary
6. Update state: set pr_url, move to phase stored in next_phase (default "codex-review"). Reset next_phase to null after reading it.

Phase: codex-review

1. Reset codex_lgtm to false in state.
2. Read .claude/dev-loop.log.md to get the history of prior iterations. Build a short summary of what was already reviewed and fixed/dismissed (if any).
3. Run Codex via MCP (mcp__codex__codex) with these exact parameters:
   • model: "gpt-5.4"
   • config: {"model_reasoning_effort": "high"}
   • approval-policy: "on-failure"
   • sandbox: "read-only"
   • prompt — include the prior iteration summary so Codex doesn't re-raise already-resolved issues:

   Review the changes in the current branch compared to main. Focus on:
   - Bugs and logic errors
   - Security issues
   - Missing edge cases
   - Code quality issues
   Give a structured list of issues to fix, with file paths and line numbers.
   If there are genuinely no issues worth addressing, say "LGTM".
   
   PRIOR REVIEW HISTORY — an issue dismissed once may be re-raised ONE more
   time for reconsideration. If dismissed twice, it is settled — do not
   raise it again:
   <paste the prior iteration summary here>
   

   If the Codex MCP call fails or times out, log the error, set codex_lgtm to false, and skip to phase "claude-review" (let Claude review alone rather than getting stuck).
4. Save the Codex thread ID and review summary to state.
5. If Codex says "LGTM" or similar (no actionable issues), set "codex_lgtm": true in state and move to phase "claude-review".
6. Otherwise, set "codex_lgtm": false in state and move to phase "codex-fix".

Phase: codex-fix

1. Read the issues from the codex-review summary in state.
2. Fix all the issues yourself. Use the Codex review findings as guidance but apply the fixes directly — do not ask Codex to write files.
3. If any fix is unclear, use Codex via MCP (mcp__codex__codex-reply, same thread ID, model: "gpt-5.4", sandbox: "read-only") to ask for clarification before fixing.
4. After all fixes are applied, ask Codex to verify via mcp__codex__codex-reply (same thread, sandbox: "read-only"):

   I've applied fixes for the issues you raised. Review the current state of
   the changed files. Are the fixes correct? Any remaining concerns?
   

   • If Codex is satisfied, set codex_lgtm to true.
   • If Codex has remaining concerns, address them, then re-verify (max 2 back-and-forths to avoid getting stuck).
5. Set next_phase to "claude-review" in state. Update state to phase "commit".

Phase: claude-review

╔══════════════════════════════════════════════════════════════════╗ ║ YOU MUST RUN REVIEW AGENTS. DO NOT REVIEW THE DIFF YOURSELF. ║ ║ DO NOT skip this. DO NOT do a manual review instead. ║ ║ DO NOT just read the diff. LAUNCH THE AGENTS BELOW. ║ ║ This is MANDATORY. Not optional. Not a suggestion. ║ ╚══════════════════════════════════════════════════════════════════╝

1. Get the diff: run git diff main...HEAD.

2. Read .claude/dev-loop.log.md to get the history of prior iterations. Build a short summary of what was already reviewed, fixed, and dismissed. You will pass this to each agent so they don't re-raise resolved issues.

3. Launch these 3 review agents in parallel using the Task tool. Each gets the diff and reviews the changed files. These agents are bundled in this plugin under agents/.

   IMPORTANT: Include the prior iteration summary in each agent prompt. Agents must focus on new issues only — not re-raise things already fixed or dismissed as false positives in earlier iterations.

   Agent A — code-reviewer (subagent_type: "general-purpose"):

   You are a code reviewer. Read .claude/dev-loop-state.json to understand
   the project context. Read any CLAUDE.md or project rules files.
   Review all changes in `git diff main...HEAD`. Focus on: bugs, logic
   errors, style violations, guideline compliance, best practices.
   Give a structured list of issues with file:line references and
   confidence scores (only report confidence >= 80).
   
   PRIOR REVIEW HISTORY — an issue dismissed once may be re-raised ONE more
   time for reconsideration. If dismissed twice, it is settled — do not
   raise it again:
   <paste the prior iteration summary here>
   

   Agent B — silent-failure-hunter (subagent_type: "general-purpose"):

   You are an error handling and security auditor. Read all changes in
   `git diff main...HEAD`. Focus on: silent failures, missing error
   handling, swallowed exceptions, broad catch blocks, security issues
   (injection, XSS, auth bypass), missing input validation.
   Give a structured list of issues with file:line references and severity.
   
   PRIOR REVIEW HISTORY — an issue dismissed once may be re-raised ONE more
   time for reconsideration. If dismissed twice, it is settled — do not
   raise it again:
   <paste the prior iteration summary here>
   

   Agent C — code-simplifier (subagent_type: "general-purpose"):

   You are a code simplification specialist. Read any CLAUDE.md for project
   standards. Review all changes in `git diff main...HEAD`. Focus on:
   unnecessary complexity, dead code, redundant logic, opportunities to
   simplify while preserving behavior.
   Give a structured list of suggestions with file:line references.
   
   PRIOR REVIEW HISTORY — an issue dismissed once may be re-raised ONE more
   time for reconsideration. If dismissed twice, it is settled — do not
   raise it again:
   <paste the prior iteration summary here>
   

4. Collect all agent results. For each issue raised by any agent:

   • Read the actual code at that file:line
   • Validate whether the issue is real and worth fixing
   • Discard false positives or issues that don't apply (e.g. pre-existing code, project-specific patterns the agent didn't understand)
   • Check the log for prior dismissed issues. An issue dismissed once may be reconsidered (keep it). An issue dismissed twice is settled — discard it.
   • Keep any issue that is a genuine bug, security concern, or meaningful improvement AND was not already addressed

5. Compile a validated review summary of real, new issues only.

╔══════════════════════════════════════════════════════════════════╗ ║ EXIT GATE — YOU MAY ONLY MOVE TO PHASE "done" IF: ║ ║ ║ ║ ✓ codex_lgtm is TRUE (Codex found ZERO issues) ║ ║ ✓ After validating all agent findings, ZERO real issues remain ║ ║ (all agent findings were confirmed as false positives) ║ ║ ║ ║ IF EITHER codex OR validated agent review has real issues ║ ║ → phase "claude-fix". No exceptions. ║ ╚══════════════════════════════════════════════════════════════════╝

5. If codex_lgtm is true AND zero validated issues remain:
   • Post final review cycle PR comment via gh pr comment summarizing this last cycle (same format as the commit-phase comment: iteration number, codex verdict, claude verdict, note that all reviews passed clean).
   • Move to phase "done".
6. If ANY validated issue exists from either Codex or the review agents, save the review summary to state, update to phase "claude-fix".

Phase: claude-fix

1. Fix all issues from your own review.
2. Increment iteration by 1.
3. If iteration >= max_iterations, update state to phase "done" and add a PR comment listing any remaining concerns.
4. Otherwise, update state to phase "commit" (loops back for another codex-review + claude-review cycle).

Phase: done

1. Push final changes.
2. Post a final summary PR comment via gh pr comment with:
   • Total iterations completed
   • High-level summary of all changes across rounds
   • Note whether the loop exited clean (all reviews passed) or at max iterations (with any remaining concerns listed)
   • Format: use a header like ## Dev Loop — Final Summary
3. Print a summary to the user: iteration count, what was fixed across rounds, PR URL.
4. Delete .claude/dev-loop-state.json.
5. Stop.

Loop Structure

  commit ──► codex-review ──► codex-fix ──► commit ──► claude-review
    ▲             │                                        │      │
    │             │(LGTM)                           (both   (issues)
    │             └──────────────► claude-review    LGTM)     │
    │                                  │              │       ▼
    │                                  │              ▼   claude-fix
    │                                  │            done      │
    │                                  └──────────────────────┘
    │                                          iteration++
    │                                              │
    └────── if iteration < max_iterations ─────────┘
                                                   │
                          if iteration >= max_iterations ──► done

Log File

Write a running log to .claude/dev-loop.log.md. This file is gitignored and serves as a human-readable history of the entire loop. Append to it after each phase transition — never overwrite.

Format:

# Dev Loop: <prompt>

Branch: `<branch>`
Started: <ISO timestamp>
Max iterations: <N>

---

## Iteration 0

### Plan
<timestamp>
- Summary of the plan (3-5 bullets)

### Plan Improvements
<timestamp>
- What was improved

### Implementation
<timestamp>
- Files changed (list)
- Brief description of what was built

### Commit
<timestamp>
- Commit SHA: `<sha>`
- PR: <url> (if created)

### Codex Review
<timestamp>
- **Verdict:** <LGTM | N issues found>
- Issues: (bullet list, or "none")
- Dismissed: (issues considered but dismissed as false positives, with reason)

### Codex Fix
<timestamp>
- What was fixed (bullet list)

### Claude Review
<timestamp>
- **Verdict:** <clean | N issues found>
- Issues: (bullet list, or "none")
- Dismissed: (issues considered but dismissed as false positives, with reason)

### Claude Fix
<timestamp>
- What was fixed (bullet list)

---

## Iteration 1
...

---

## Done
<timestamp>
- Total iterations: N
- PR: <url>
- Summary of all changes across rounds

Rules for the log:

• Keep each section concise — bullet points, not paragraphs.
• Include timestamps (ISO format) so the user can see how long each phase took.
• Always append, never overwrite — the log is the full history.
• At the end of the loop (phase "done"), print the log file path to the user so they can review it.
• Keep the log compact. Each phase entry should be a few bullet points, not full paragraphs. This prevents the file from growing excessively over multiple iterations.

Slack Updates

If slack_channel and slack_thread_ts are set in state (meaning this loop was triggered from Slack), post a one-liner progress update to the Slack thread after every phase transition that updates the log. Use the Slack MCP tool (e.g., mcp__slack__send_message) if available. Keep it short — one line, no formatting overkill. Examples:

• "Planning done, starting implementation."
• "Implementation committed, PR created: <url>"
• "Codex review: 3 issues found, fixing now."
• "Codex fixes committed, moving to Claude review."
• "Claude review: clean. All reviews passed."
• "Iteration 1 complete — 2 codex issues + 1 claude issue fixed."
• "Done! 2 iterations, all reviews clean. PR: <url>"

If no Slack MCP tool is available or the call fails, skip silently — Slack updates are best-effort and should never block the loop.

Important Rules

• Always read state first. On every turn, start by reading .claude/dev-loop-state.json. If it exists, resume from the recorded phase. This is critical for surviving compaction.
• Re-read reference files. After reading state, if ref_files is non-empty, re-read those files to restore context that may have been lost to compaction.
• Verify branch. After reading state, check that you're on the correct branch (git branch --show-current). If not, switch to it (git checkout <branch>). This handles cases where compaction or a restart left you on the wrong branch.
• Update state before long operations. Write state transitions before starting work so that if context is lost, you resume at the right place.
• Only Claude can exit early. The loop can only exit before max_iterations during the claude-review phase, when Claude finds nothing worth fixing. Codex saying LGTM just skips the codex-fix step — Claude still reviews.
• Max iterations. After max_iterations full loops (default 4), stop even if issues remain. Add a PR comment noting any remaining concerns.
• Codex via MCP. Use mcp__codex__codex for the first Codex call per iteration and mcp__codex__codex-reply to continue a thread.
• Keep state summaries concise. The last_review_summary should be a short bullet list, not a full review — it needs to survive compaction.
• Don't be nitpicky on exit. When deciding whether to exit in claude-review, focus on real bugs, security issues, and meaningful quality problems. Minor style preferences that don't affect correctness should not block exit.

Input prompt:

$ARGUMENTS