agent-plan-act-reflect

Name: agent-plan-act-reflect
Author: WenyuChiou

16stars4forks

How to install agent-plan-act-reflect?

wenyuchiou/agent-collab-skills/agent-plan-act-reflect

$npx -y skills add WenyuChiou/agent-collab-skills --skill agent-plan-act-reflect

Installs into the current project.

Summary

Use when a task needs single-agent self-correction across multiple iterations — write plan, execute, critique own output, revise plan, re-execute, until convergence or budget exhausted. Different from agent-debate (which is 2 agents arguing pro vs con); this is 1 agent looping

Files · 1

View on GitHub

SKILL.md

1	# agent-plan-act-reflect
2
3	Single-agent iterative self-correction loop. Composes existing
4	building blocks (task-splitter / shared-memory / acceptance-gate)
5	into one closed cycle.
6
7	This is the agent equivalent of test-driven development: write
8	spec, build, test, fail, revise, build again, until pass. Where
9	`agent-debate` is "2 agents disagree", PAR is "1 agent revises".
10
11	## When to use
12
13	Good for:
14	- A single agent owns the task end-to-end, but the first attempt
15	rarely lands clean (refactors, papers, optimizations, anything
16	with > 3 quality dimensions to balance)
17	- The success criterion is automatically checkable (tests, eval, linter)
18	- Budget allows 2-5 iterations
19	- You want a paper trail of what was tried + why it failed
20
21	Not for:
22	- Single-shot tasks (overkill)
23	- Tasks where two agents should argue opposing designs (use `agent-debate`)
24	- Multi-agent coordination (use `agent-task-splitter`)
25	- Pure exploration / ideation (no test criterion to drive iteration)
26	- 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)
27
28	## Inputs
29
30	User must provide:
31
32	1. Goal — single sentence, with concrete acceptance criterion
33	- Good: "Stage 6 §RAG section reads at < 10 grade-level + passes anchor strict"
34	- Bad: "Make Stage 6 better"
35	2. Max iterations — default 3. After this many cycles without
36	convergence, surface to user.
37	3. Critique source — what gives the "fail signal" each iteration:
38	- Test results (preferred — most objective)
39	- Subagent review (next-most objective)
40	- Eval framework score (ragas / promptfoo / etc.)
41	- Self-critique by the same agent (least reliable, only as fallback)
42	4. Optional: which delegate (Claude inline / Codex / Gemini). Default Claude inline.
43
44	## Workflow
45
46	```
47	write plan ──► .coord/par_<topic>.yml
48	│
49	▼
50	┌──────────────────────────────────────┐
51	│ Iteration loop (cap = max_iterations): │
52	│ │
53	│ Act ─► delegate executes │
54	│ writes result.md │
55	│ │
56	│ Reflect ─► run critique source │
57	│ (test / subagent / │
58	│ eval / self) │
59	│ │
60	│ Pass? ─► YES → exit loop with PASS │
61	│ NO → continue if N < │
62	│ max_iterations │
63	│ │
64	│ N = max?─► YES → exit loop with │
65	│ `EXHAUSTED` — │
66	│ surface to user │
67	│ NO → continue │
68	│ │
69	│ Revise ─► update .coord/par_ │
70	│ <topic>.yml with │
71	│ learned-from-failure │
72	└──────────────────────────────────────┘
73	│
74	▼
75	write final summary → .coord/par_<topic>_final.md
76	+ promote learned principles → .coord/memory.yml
77	```
78
79	Exit conditions (be explicit, prevents runaway loops):
80	- Verdict PASS at any iteration → exit immediately with status `PASS`
81	- N reaches `max_iterations` without PASS → exit with status `EXHAUSTED`, surface to user with summary of all failed attempts
82	- Any iteration fails with status `error` (test infrastructure crash, delegate timeout, etc.) → exit with status `ERROR`, do NOT continue
83
84	The loop NEVER continues past `max_iterations`. The anti-pattern says
85	"don't go past 5"; the workflow enforces this by failing closed.
86
87	## Outputs
88
89	- `.coord/par_<topic>.yml` — running state (plan + iteration history)
90	- `.coord/par_<topic>_final.md` — final summary + lessons (≤ 500 words)
91	- Promoted principles → `.coord/memory.yml` (via `agent-shared-memory`)
92
93	## par_<topic>.yml schema
94
95	```yaml
96	goal: "Stage 6 §RAG passes plain-language test"
97	acceptance_criterion: "subagent code-reviewer scores >= 8/10 on clarity"
98	max_iterations: 3
99	critique_source: subagent
100	delegate: claude-inline
101
102	iterations:
103	- n: 1
104	plan_summary: "Drop encyclopedic table; replace with prose + 3 concrete examples"
105	artifact: ".coord/par_rag_iter1.md"
106	critique:
107	score: 6
108	issues:
109	- "Examples still too abstract (no specific Yelp/database)"
110	- "DSPy reference confuses scope"
111	verdict: FAIL
112	revise: "Add concrete Yelp example; drop DSPy until next iteration"
113
114	- n: 2
115	plan_summary: "Apply iter-1 revisions"
116	artifact: ".coord/par_rag_iter2.md"
117	critique:
118	score: 8
119	issues:
120	- "Heading hierarchy still inconsistent"
121	verdict: CONDITIONAL PASS
122	revise: "Fix heading levels; minor polish"
123
124	- n: 3
125	plan_summary: "Final polish"
126	artifact: ".coord/par_rag_iter3.md"

People who liked this also viewed

6 picks

Type

agent-plan-act-reflect

16stars4forks

View on GitHub

How to install agent-plan-act-reflect?

wenyuchiou/agent-collab-skills/agent-plan-act-reflect

$npx -y skills add WenyuChiou/agent-collab-skills --skill agent-plan-act-reflect

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# agent-plan-act-reflect
2
3	Single-agent iterative self-correction loop. Composes existing
4	building blocks (task-splitter / shared-memory / acceptance-gate)
5	into one closed cycle.
6
7	This is the agent equivalent of test-driven development: write
8	spec, build, test, fail, revise, build again, until pass. Where
9	`agent-debate` is "2 agents disagree", PAR is "1 agent revises".
10
11	## When to use
12
13	Good for:
14	- A single agent owns the task end-to-end, but the first attempt
15	rarely lands clean (refactors, papers, optimizations, anything
16	with > 3 quality dimensions to balance)
17	- The success criterion is automatically checkable (tests, eval, linter)
18	- Budget allows 2-5 iterations
19	- You want a paper trail of what was tried + why it failed
20
21	Not for:
22	- Single-shot tasks (overkill)
23	- Tasks where two agents should argue opposing designs (use `agent-debate`)
24	- Multi-agent coordination (use `agent-task-splitter`)
25	- Pure exploration / ideation (no test criterion to drive iteration)
26	- 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)
27
28	## Inputs
29
30	User must provide:
31
32	1. Goal — single sentence, with concrete acceptance criterion
33	- Good: "Stage 6 §RAG section reads at < 10 grade-level + passes anchor strict"
34	- Bad: "Make Stage 6 better"
35	2. Max iterations — default 3. After this many cycles without
36	convergence, surface to user.
37	3. Critique source — what gives the "fail signal" each iteration:
38	- Test results (preferred — most objective)
39	- Subagent review (next-most objective)
40	- Eval framework score (ragas / promptfoo / etc.)
41	- Self-critique by the same agent (least reliable, only as fallback)
42	4. Optional: which delegate (Claude inline / Codex / Gemini). Default Claude inline.
43
44	## Workflow
45
46	```
47	write plan ──► .coord/par_<topic>.yml
48	│
49	▼
50	┌──────────────────────────────────────┐
51	│ Iteration loop (cap = max_iterations): │
52	│ │
53	│ Act ─► delegate executes │
54	│ writes result.md │
55	│ │
56	│ Reflect ─► run critique source │
57	│ (test / subagent / │
58	│ eval / self) │
59	│ │
60	│ Pass? ─► YES → exit loop with PASS │
61	│ NO → continue if N < │
62	│ max_iterations │
63	│ │
64	│ N = max?─► YES → exit loop with │
65	│ `EXHAUSTED` — │
66	│ surface to user │
67	│ NO → continue │
68	│ │
69	│ Revise ─► update .coord/par_ │
70	│ <topic>.yml with │
71	│ learned-from-failure │
72	└──────────────────────────────────────┘
73	│
74	▼
75	write final summary → .coord/par_<topic>_final.md
76	+ promote learned principles → .coord/memory.yml
77	```
78
79	Exit conditions (be explicit, prevents runaway loops):
80	- Verdict PASS at any iteration → exit immediately with status `PASS`
81	- N reaches `max_iterations` without PASS → exit with status `EXHAUSTED`, surface to user with summary of all failed attempts
82	- Any iteration fails with status `error` (test infrastructure crash, delegate timeout, etc.) → exit with status `ERROR`, do NOT continue
83
84	The loop NEVER continues past `max_iterations`. The anti-pattern says
85	"don't go past 5"; the workflow enforces this by failing closed.
86
87	## Outputs
88
89	- `.coord/par_<topic>.yml` — running state (plan + iteration history)
90	- `.coord/par_<topic>_final.md` — final summary + lessons (≤ 500 words)
91	- Promoted principles → `.coord/memory.yml` (via `agent-shared-memory`)
92
93	## par_<topic>.yml schema
94
95	```yaml
96	goal: "Stage 6 §RAG passes plain-language test"
97	acceptance_criterion: "subagent code-reviewer scores >= 8/10 on clarity"
98	max_iterations: 3
99	critique_source: subagent
100	delegate: claude-inline
101
102	iterations:
103	- n: 1
104	plan_summary: "Drop encyclopedic table; replace with prose + 3 concrete examples"
105	artifact: ".coord/par_rag_iter1.md"
106	critique:
107	score: 6
108	issues:
109	- "Examples still too abstract (no specific Yelp/database)"
110	- "DSPy reference confuses scope"
111	verdict: FAIL
112	revise: "Add concrete Yelp example; drop DSPy until next iteration"
113
114	- n: 2
115	plan_summary: "Apply iter-1 revisions"
116	artifact: ".coord/par_rag_iter2.md"
117	critique:
118	score: 8
119	issues:
120	- "Heading hierarchy still inconsistent"
121	verdict: CONDITIONAL PASS
122	revise: "Fix heading levels; minor polish"
123
124	- n: 3
125	plan_summary: "Final polish"
126	artifact: ".coord/par_rag_iter3.md"

People who liked this also viewed

6 picks

Type