Agent Plan Act Reflect

agent-plan-act-reflect

Single-agent iterative self-correction loop. Composes existing building blocks (task-splitter / shared-memory / acceptance-gate) into one closed cycle.

This is the agent equivalent of test-driven development: write spec, build, test, fail, revise, build again, until pass. Where agent-debate is "2 agents disagree", PAR is "1 agent revises".

When to use

Good for:

• A single agent owns the task end-to-end, but the first attempt

rarely lands clean (refactors, papers, optimizations, anything with > 3 quality dimensions to balance)

• The success criterion is automatically checkable (tests, eval, linter)
• Budget allows 2-5 iterations
• You want a paper trail of what was tried + why it failed

Not for:

• Single-shot tasks (overkill)
• Tasks where two agents should argue opposing designs (use agent-debate)
• Multi-agent coordination (use agent-task-splitter)
• Pure exploration / ideation (no test criterion to drive iteration)
• Tasks where a human is the final adjudicator (PAR can't replace human review for high-stakes decisions; run PAR, then present result to human)

Inputs

User must provide:

1. Goal — single sentence, with concrete acceptance criterion

• Good: "Stage 6 §RAG section reads at .yml

│ ▼ ┌──────────────────────────────────────┐ │ Iteration loop (cap = maxiterations): │ │ │ │ Act ─► delegate executes │ │ writes result.md │ │ │ │ Reflect ─► run critique source │ │ (test / subagent / │ │ eval / self) │ │ │ │ Pass? ─► YES → exit loop with PASS │ │ NO → continue if N .yml with │ │ learned-from-failure │ └──────────────────────────────────────┘ │ ▼ write final summary → .coord/par_final.md

• promote learned principles → .coord/memory.yml

**Exit conditions (be explicit, prevents runaway loops)**:
- Verdict PASS at any iteration → exit immediately with status `PASS`
- N reaches `max_iterations` without PASS → exit with status `EXHAUSTED`, surface to user with summary of all failed attempts
- Any iteration fails with status `error` (test infrastructure crash, delegate timeout, etc.) → exit with status `ERROR`, do NOT continue

The loop NEVER continues past `max_iterations`. The anti-pattern says
"don't go past 5"; the workflow enforces this by failing closed.

## Outputs

- `.coord/par_.yml` — running state (plan + iteration history)
- `.coord/par__final.md` — final summary + lessons (≤ 500 words)
- Promoted principles → `.coord/memory.yml` (via `agent-shared-memory`)

## par_.yml schema

```yaml
goal: "Stage 6 §RAG passes plain-language test"
acceptance_criterion: "subagent code-reviewer scores >= 8/10 on clarity"
max_iterations: 3
critique_source: subagent
delegate: claude-inline

iterations:
  - n: 1
    plan_summary: "Drop encyclopedic table; replace with prose + 3 concrete examples"
    artifact: ".coord/par_rag_iter1.md"
    critique:
      score: 6
      issues:
        - "Examples still too abstract (no specific Yelp/database)"
        - "DSPy reference confuses scope"
      verdict: FAIL
    revise: "Add concrete Yelp example; drop DSPy until next iteration"

  - n: 2
    plan_summary: "Apply iter-1 revisions"
    artifact: ".coord/par_rag_iter2.md"
    critique:
      score: 8
      issues:
        - "Heading hierarchy still inconsistent"
      verdict: CONDITIONAL PASS
    revise: "Fix heading levels; minor polish"

  - n: 3
    plan_summary: "Final polish"
    artifact: ".coord/par_rag_iter3.md"
    critique:
      score: 9
      issues: []
      verdict: PASS

final_status: PASS
total_cost_usd: 0.45
elapsed_minutes: 22

Anti-patterns

• Don't loop more than 5 times. If after 5 the agent hasn't

converged, the goal is probably mis-specified or the critique source is inconsistent. Surface to user, don't keep burning $.

• Don't use self-critique as the only critique source. The agent

that wrote the code will mostly approve its own code. Bias is real and well-documented. Use external test / subagent / eval.

• Don't promote raw iteration content to memory. Only PROMOTE

the learned principle (e.g., "DSPy belongs in §進階 RAG, not in intro") to .coord/memory.yml. Iteration artifacts stay in .coord/par_*.md and get archived after 14 days like other .ai/ files.

• Don't run PAR for trivial tasks. Single-shot is fine for

typo fixes, sweep rules, single-file edits. PAR is for tasks where 1 iteration is reliably insufficient.

Subagent review (keep main session lean)

When: PAR loop enters iteration 3+, OR .coord/par_*.yml exceeds 8 KB.

Why: Main session that wrote the original plan + observed iteration 1+2 results doesn't need to re-read all artifacts in later iterations. A subagent can read the par_*.yml + recent iteration artifact + return a structured "should we iterate again or stop?" verdict.

Pattern:

Spawn `code-reviewer` subagent:
  - Read .coord/par_.yml in full
  - Read latest iteration artifact (.coord/par__iterN.md)
  - Apply critique source (test results / preset / etc.)
  - Return: { verdict: PASS/CONDITIONAL/FAIL,
              top 3 issues: [...],
              recommend: continue/stop/escalate,
              estimated_iterations_remaining: N }

Main session reads only the verdict.

Commit Boundary

Every agent boundary is a commit boundary (see global rule: ~/.claude/CLAUDE.md → "Commit Discipline for Multi-Agent Work").

Specific to this skill: each iteration is its own commit with message par(iter-N): . The final PASS iteration commit can be followed by a par(final): merge to main commit that includes the principle promotion to .coord/memory.yml.

This makes the PAR loop a commit-by-commit replay: a future maintainer can git log --grep "par(iter" to see the full self-correction history.

Composes with

• agent-task-splitter — write the initial plan
• agent-shared-memory — promote learned principles after PAR converges
• agent-acceptance-gate — can be the critique source for an iteration
• agent-debate — different tool (multi-agent disagreement). Use PAR

for single-agent self-correction; use debate for adjudicating between two equally-valid options.

Output to user (final message format)

[agent-plan-act-reflect]
  Goal: 
  Status: PASS after N iterations
  Final artifact: 
  Cost: ~$X.XX total
  Promoted to memory: 

  Iteration summary:
    iter 1: FAIL (score 6/10) → revised plan
    iter 2: CONDITIONAL (score 8/10) → minor polish
    iter 3: PASS (score 9/10)

  Time: ~N min wall-clock

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: WenyuChiou
• Source: WenyuChiou/agent-collab-skills
• License: MIT
• Homepage: https://github.com/WenyuChiou/agent-collab-skills

Install and usage instructions live in the source repository linked above.