agent-plan-act-reflect · diff
git:20260904.4e8a7fd to git:20261016.a802ce4
12 added, 117 removed. Audit A to A.
---
name: agent-plan-act-reflect
- description: Use when one agent must iteratively plan, act, evaluate evidence, and revise under a readable policy until acceptance, checkpoint, stop, or human escalation.
+ description: Use when a plan, prompt, or doc still names agent-plan-act-reflect. Deprecated in 0.6.0; ordinary iterate-until-it-passes work needs no skill, and an unattended policy-driven loop follows agent-context-budget's harness loop reference. This stub is removed in 0.7.0.
---
- # agent-plan-act-reflect
-
- Run a single-agent correction loop under the public policy/checkpoint contract.
- This differs from agent-debate: plan-act-reflect revises one candidate against
- evidence; debate compares genuinely consequential alternatives.
-
- ## Use this skill for
-
- - A task with a runnable or otherwise deterministic acceptance contract.
- - A candidate likely to need more than one evidence-producing cycle.
- - A bounded optimization, refactor, or draft correction.
-
- Do not use it for open-ended ideation, an unbounded “until perfect” request, or
- semantic acceptance that belongs to a human.
-
- ## Preconditions
-
- Require:
-
- - one concrete goal
- - acceptance criteria
- - a readable policy_ref
- - a valid checkpoint_ref
- - an identified critique source
-
- The policy is the only source for cycle, retry, context, and child limits. This
- skill does not define fallback numeric limits.
-
- If agent-collab-harness is unavailable, perform at most the currently authorized
- single action and return to the human. Do not emulate an autonomous loop with
- copied limits.
-
- ## Cycle
-
- 1. Validate the policy and checkpoint.
- 2. Evaluate policy before any delegated-executor or reviewer spawn.
- 3. Plan the smallest action that could add acceptance evidence.
- 4. Act within the declared scope.
- 5. Run the critique source.
- 6. Add evidence references and observed metrics to the checkpoint.
- 7. Classify progress:
- - acceptance satisfied: stop with PASS.
- - same failure: increment same_failure_retries.
- - no new artifact, test, source, decision, or blocker: increment
- no_evidence_cycles.
- - new evidence: reset the relevant no-progress counter.
- 8. Run `agent-collab policy evaluate` after the cycle.
- 9. Obey PolicyDecision:
- - continue: revise the plan using the new evidence.
- - checkpoint: save resumable state. For v2 scope=slice with auto_continue,
- use `agent-collab checkpoint advance` and continue the same authorized goal.
- No human override is needed for an ordinary eligible slice transition.
- For a v2 action checkpoint requiring context compaction, preserve evidence
- and authorization in a smaller linked packet, record measured active sizes,
- then re-evaluate before execution. Maintenance is not a human approval gate.
- - stop: obey its scope. An action stop prohibits repeating that action;
- the primary-agent may diagnose read-only or prepare an evidence-backed
- correction. A goal stop preserves the hard limit or human gate.
- - v1 decisions retain their original checkpoint/stop semantics until explicit
- migration; do not silently reinterpret an old record.
-
- An infrastructure error is evidence of an error, not permission to retry. A
- retry requires the next policy evaluation to permit it.
-
- ## State
-
- Write .coord/par_<topic>.yml:
-
- schema_version: 2
- goal: "..."
- policy_ref: "${AGENT_COLLAB_POLICY}"
- checkpoint_ref: ".coord/task-checkpoint.json"
- acceptance_criteria:
- - "..."
- critique_source: "..."
- cycles:
- - cycle: 1
- plan_summary: "..."
- artifact_refs: ["..."]
- evidence_refs: ["..."]
- verdict: "pass | fail | error | needs-human"
- next_action: "..."
- final_status: "pass | checkpoint | stop | error | needs-human"
-
- Write .coord/par_<topic>_final.md with:
-
- - final status
- - last PolicyDecision
- - acceptance evidence
- - unsuccessful attempts
- - unresolved risks
- - human decision required, if any
-
- Both files are scratch by default. Promote only explicit shipping or acceptance
- evidence.
-
- ## Memory
+ # agent-plan-act-reflect (deprecated)
- Never write a lesson directly to canonical memory. Create a proposal under
- .coord/memory-proposals/ with evidence references. Applying it requires a
- recorded human approval and appends a new event; it never edits an older event.
+ Deprecated in 0.6.0 and removed in 0.7.0.
- ## Invariants
+ - Iterating with the user present (edit, run the check, fix, repeat) needs no
+ skill. Keep the acceptance check runnable and report its real result.
+ - An unattended multi-cycle loop under a configured `agent-collab` policy
+ follows [harness-loop.md](../agent-context-budget/references/harness-loop.md),
+ the former body of this skill. It still runs `agent-collab policy evaluate`
+ after every cycle and before every spawn.
+ - Comparing two consequential alternatives is
+ [agent-debate](../agent-debate/SKILL.md), not a loop.
- - Evaluate after every cycle and before every spawn.
- - Preserve cumulative usage and failure history across slices, sessions, and
- executors. Unknown tokens/cost remain unknown, never zero. Explicit goal
- limits and native platform limits remain hard; absent limits are not invented.
- - Use stable failure identities based on operation, target, relevant inputs,
- and error class. Renaming a task or switching executors is not a correction.
- - A waiting external service is not a failed retry. Continue only with new
- evidence, a safe next step, and the required acceptance checks.
- - Diagnose recoverable action failures and perform safe context maintenance
- before escalating. Do not ask the user to renew unchanged authorization.
- Count actual human intervention separately from automatic recovery or waiting;
- fewer pauses never justify bypassing a real gate or claiming unmeasured success.
- - Agent self-critique is not independent acceptance.
- - Human semantic gates cannot be replaced by an aggregate agent score.
- - PASS requires cited acceptance evidence, not “looks good”.
+ See [migration 0.6](../../docs/migration-0.6.md).