Skip to content

An agentic skills framework & software development methodology that works.

Add plan review loop and checkbox syntax to writing-plans skill

Jesse Vincent7b99c39c08cd
diff --git a/skills/writing-plans/SKILL.md b/skills/writing-plans/SKILL.md
index e9cbcfd4b..4dd064551 100644
--- a/skills/writing-plans/SKILL.md
+++ b/skills/writing-plans/SKILL.md
@@ -34,7 +34,7 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
```markdown
# [Feature Name] Implementation Plan
-> **For Claude:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan.
+> **For Claude:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** [One sentence describing what this builds]
@@ -55,7 +55,7 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`
-**Step 1: Write the failing test**
+- [ ] **Step 1: Write the failing test**
```python
def test_specific_behavior():
@@ -63,24 +63,24 @@ def test_specific_behavior():
assert result == expected
```
-**Step 2: Run test to verify it fails**
+- [ ] **Step 2: Run test to verify it fails**
Run: `pytest tests/path/test.py::test_name -v`
Expected: FAIL with "function not defined"
-**Step 3: Write minimal implementation**
+- [ ] **Step 3: Write minimal implementation**
```python
def function(input):
return expected
```
-**Step 4: Run test to verify it passes**
+- [ ] **Step 4: Run test to verify it passes**
Run: `pytest tests/path/test.py::test_name -v`
Expected: PASS
-**Step 5: Commit**
+- [ ] **Step 5: Commit**
```bash
git add tests/path/test.py src/path/file.py
@@ -95,6 +95,25 @@ git commit -m "feat: add specific feature"
- Reference relevant skills with @ syntax
- DRY, YAGNI, TDD, frequent commits
+## Plan Review Loop
+
+After completing each chunk of the plan:
+
+1. Dispatch plan-document-reviewer subagent (see plan-document-reviewer-prompt.md) for the current chunk
+ - Provide: chunk content, path to spec document
+2. If ❌ Issues Found:
+ - Fix the issues in the chunk
+ - Re-dispatch reviewer for that chunk
+ - Repeat until ✅ Approved
+3. If ✅ Approved: proceed to next chunk (or execution handoff if last chunk)
+
+**Chunk boundaries:** Use `## Chunk N: <name>` headings to delimit chunks. Each chunk should be ≤1000 lines and logically self-contained.
+
+**Review loop guidance:**
+- Same agent that wrote the plan fixes it (preserves context)
+- If loop exceeds 5 iterations, surface to human for guidance
+- Reviewers are advisory - explain disagreements if you believe feedback is incorrect
+
## Execution Handoff
After saving the plan: