summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJesse Vincent <jesse@fsck.com>2026-02-21 08:54:23 -0800
committerJesse Vincent <jesse@fsck.com>2026-02-21 08:54:23 -0800
commit7cefe7498cc2eb66facddd3300e7b7cd1799ba0f (patch)
tree80fec20573b33be76610753aa2585514f5de5c36
parent41512d6f3a6ccdc2882af075e8cde6bc982edd79 (diff)
Add workflow checkpoints and scaling to SDD, refine handoffsbrainstorming-skill-scaling
- brainstorming: check in with user before transitioning to writing-plans - writing-plans: structured execution handoff (record context, advise compaction, give exact continuation prompt with subagent detection) - SDD: add scaling paragraph with GATE + orchestrator boundary, graphviz decision diamonds for review elision, check-in before finishing, replace TodoWrite with generic task list language, tighten Red Flags
-rw-r--r--skills/brainstorming/SKILL.md3
-rw-r--r--skills/subagent-driven-development/SKILL.md36
-rw-r--r--skills/writing-plans/SKILL.md22
3 files changed, 40 insertions, 21 deletions
diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md
index 7ea2a96..f02aadc 100644
--- a/skills/brainstorming/SKILL.md
+++ b/skills/brainstorming/SKILL.md
@@ -123,7 +123,8 @@ After writing the spec document:
**Implementation:**
-- Invoke the writing-plans skill to create a detailed implementation plan
+- Check in with the user before transitioning: "The design is ready. Want me to move on to writing the implementation plan?"
+- On confirmation, invoke the writing-plans skill
- Do NOT invoke any other skill. writing-plans is the next step.
**Design for isolation and clarity:**
diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md
index 7cbe4a9..694aca1 100644
--- a/skills/subagent-driven-development/SKILL.md
+++ b/skills/subagent-driven-development/SKILL.md
@@ -7,6 +7,8 @@ description: Use when executing implementation plans with independent tasks in t
Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.
+Scale the review process to the task. A one-line config change doesn't need the same review rigor as a new subsystem. **GATE — when you believe review stages or the final reviewer can be safely collapsed or elided, ask the user for permission.** Do not elide silently, and do not replace a skipped review subagent with orchestrator judgment — the orchestrator never implements or reviews code.
+
**Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration
## When to Use
@@ -47,26 +49,34 @@ digraph process {
"Implementer subagent asks questions?" [shape=diamond];
"Answer questions, provide context" [shape=box];
"Implementer subagent implements, tests, commits, self-reviews" [shape=box];
+ "Two-stage review warranted?" [shape=diamond];
+ "Ask user permission\nto elide or collapse reviews" [shape=box];
"Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [shape=box];
"Spec reviewer subagent confirms code matches spec?" [shape=diamond];
"Implementer subagent fixes spec gaps" [shape=box];
"Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [shape=box];
"Code quality reviewer subagent approves?" [shape=diamond];
"Implementer subagent fixes quality issues" [shape=box];
- "Mark task complete in TodoWrite" [shape=box];
+ "Mark task complete in your task list" [shape=box];
}
- "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
+ "Read plan, extract all tasks with full text, note context, create your task list" [shape=box];
"More tasks remain?" [shape=diamond];
+ "Final reviewer warranted?" [shape=diamond];
+ "Ask user permission\nto elide final review" [shape=box];
"Dispatch final code reviewer subagent for entire implementation" [shape=box];
+ "Check in with user\nbefore finishing" [shape=box];
"Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
- "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./implementer-prompt.md)";
+ "Read plan, extract all tasks with full text, note context, create your task list" -> "Dispatch implementer subagent (./implementer-prompt.md)";
"Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
"Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
"Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";
"Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"];
- "Implementer subagent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)";
+ "Implementer subagent implements, tests, commits, self-reviews" -> "Two-stage review warranted?";
+ "Two-stage review warranted?" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [label="yes"];
+ "Two-stage review warranted?" -> "Ask user permission\nto elide or collapse reviews" [label="no — may be\noverkill"];
+ "Ask user permission\nto elide or collapse reviews" -> "Mark task complete in your task list";
"Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" -> "Spec reviewer subagent confirms code matches spec?";
"Spec reviewer subagent confirms code matches spec?" -> "Implementer subagent fixes spec gaps" [label="no"];
"Implementer subagent fixes spec gaps" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [label="re-review"];
@@ -74,11 +84,15 @@ digraph process {
"Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";
"Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];
"Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"];
- "Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"];
- "Mark task complete in TodoWrite" -> "More tasks remain?";
+ "Code quality reviewer subagent approves?" -> "Mark task complete in your task list" [label="yes"];
+ "Mark task complete in your task list" -> "More tasks remain?";
"More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
- "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
- "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch";
+ "More tasks remain?" -> "Final reviewer warranted?" [label="no"];
+ "Final reviewer warranted?" -> "Dispatch final code reviewer subagent for entire implementation" [label="yes"];
+ "Final reviewer warranted?" -> "Ask user permission\nto elide final review" [label="no — may be\noverkill"];
+ "Ask user permission\nto elide final review" -> "Check in with user\nbefore finishing";
+ "Dispatch final code reviewer subagent for entire implementation" -> "Check in with user\nbefore finishing";
+ "Check in with user\nbefore finishing" -> "Use superpowers:finishing-a-development-branch";
}
```
@@ -128,7 +142,7 @@ You: I'm using Subagent-Driven Development to execute this plan.
[Read plan file once: docs/superpowers/plans/feature-plan.md]
[Extract all 5 tasks with full text and context]
-[Create TodoWrite with all tasks]
+[Create your task list with all tasks]
Task 1: Hook installation script
@@ -233,7 +247,7 @@ Done!
**Never:**
- Start implementation on main/master branch without explicit user consent
-- Skip reviews (spec compliance OR code quality)
+- Skip any review without explicit user permission
- Proceed with unfixed issues
- Dispatch multiple implementation subagents in parallel (conflicts)
- Make subagent read plan file (provide full text instead)
@@ -258,7 +272,7 @@ Done!
**If subagent fails task:**
- Dispatch fix subagent with specific instructions
-- Don't try to fix manually (context pollution)
+- Don't try to fix manually — the orchestrator never implements or reviews code (context pollution)
## Integration
diff --git a/skills/writing-plans/SKILL.md b/skills/writing-plans/SKILL.md
index 2fc2e1e..b7679a0 100644
--- a/skills/writing-plans/SKILL.md
+++ b/skills/writing-plans/SKILL.md
@@ -166,15 +166,19 @@ After completing each chunk of the plan:
After saving the plan:
-**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Ready to execute?"**
+**1. Record context.** Before anything else, verify all artifacts are saved and the plan is self-contained:
+- Spec document path (if one was written)
+- Plan document path
+- Key architectural decisions, constraints, or user preferences that affect implementation but aren't captured in the plan — add them to the plan now
-**Execution path depends on harness capabilities:**
+**2. Advise compaction.** Execution works better with a fresh window. Tell the user:
-**If harness has subagents (Claude Code, etc.):**
-- **REQUIRED:** Use superpowers:subagent-driven-development
-- Do NOT offer a choice - subagent-driven is the standard approach
-- Fresh subagent per task + two-stage review
+> "The plan is saved to `docs/superpowers/plans/<filename>.md`. Before we start implementation, I recommend compacting this session — execution works better with a fresh window."
-**If harness does NOT have subagents:**
-- Execute plan in current session using superpowers:executing-plans
-- Batch execution with checkpoints for review
+**3. Give exact continuation prompt.** Tell the user exactly what to say after compacting. Use the actual filename, not a placeholder.
+
+If you can dispatch subagents (Claude Code, etc.):
+
+> "After compacting, say: **Execute the plan at `docs/superpowers/plans/<filename>.md` using subagent-driven-development.**"
+
+If you cannot dispatch subagents, ask the user: "The plan is ready. I can't dispatch subagents in this environment — should I execute the tasks in this thread?"