diff --git a/skills/superpowers-brainstorming/spec-document-reviewer-prompt.md b/skills/superpowers-brainstorming/spec-document-reviewer-prompt.md index 35acbb6..6826d58 100644 --- a/skills/superpowers-brainstorming/spec-document-reviewer-prompt.md +++ b/skills/superpowers-brainstorming/spec-document-reviewer-prompt.md @@ -7,7 +7,7 @@ Use this template when dispatching a spec document reviewer subagent. **Dispatch after:** Spec document is written to docs/superpowers/specs/ ``` -Task tool (general-purpose): +Agent tool (`subagent_type: "general-purpose"`): description: "Review spec document" prompt: | You are a spec document reviewer. Verify this spec is complete and ready for planning. diff --git a/skills/superpowers-dispatching-parallel-agents/SKILL.md b/skills/superpowers-dispatching-parallel-agents/SKILL.md index 9682ebd..3c06e84 100644 --- a/skills/superpowers-dispatching-parallel-agents/SKILL.md +++ b/skills/superpowers-dispatching-parallel-agents/SKILL.md @@ -68,13 +68,30 @@ Each agent gets: ### 3. Dispatch in Parallel -```typescript -// In Claude Code / AI environment -Task("Fix agent-tool-abort.test.ts failures") -Task("Fix batch-completion-behavior.test.ts failures") -Task("Fix tool-approval-race-conditions.test.ts failures") -// All three run concurrently +Issue every dispatch in **one** message — several `Agent` tool uses in a single +assistant turn run concurrently; one per turn runs them in series. + ``` +Agent(description: "fix abort tests", subagent_type: "general-purpose", prompt: ...) +Agent(description: "fix batch tests", subagent_type: "general-purpose", prompt: ...) +Agent(description: "fix approval tests", subagent_type: "general-purpose", prompt: ...) +``` + +Options that matter for this pattern: + +- `run_in_background: true` (the default) returns immediately and notifies on + completion. Set it to `false` only when your very next action depends on the result. +- `isolation: "worktree"` gives an agent its own git worktree. Use it whenever two + agents might touch the same files — parallel writers to one tree is the failure this + skill's independence rule exists to avoid, and a worktree makes it structural rather + than a matter of discipline. +- `model` overrides the model per agent; cheap mechanical fan-out does not need the + same model as the reasoning that planned it. + +For a fan-out with real structure — phases, a verify pass per finding, fan-in — the +`Workflow` tool expresses it directly with `agent()`, `parallel()` and `pipeline()`. +It spawns many agents and costs accordingly, so it runs **only on explicit opt-in from +the operator**; do not reach for it just because a task looks parallel. ### 4. Review and Integrate diff --git a/skills/superpowers-executing-plans/SKILL.md b/skills/superpowers-executing-plans/SKILL.md index f2defc9..96801be 100644 --- a/skills/superpowers-executing-plans/SKILL.md +++ b/skills/superpowers-executing-plans/SKILL.md @@ -14,14 +14,16 @@ Load plan, review critically, execute all tasks, report when complete. **Announce at start:** "I'm using the executing-plans skill to implement this plan." -**Note:** Tell your human partner that Superpowers works much better with access to subagents. The quality of its work will be significantly higher if run on a platform with subagent support (such as Claude Code or Codex). If subagents are available, use superpowers:subagent-driven-development instead of this skill. +**Note:** This skill is the fallback for harnesses with no subagents. Claude Code has +them — the `Agent` tool — so on this fleet prefer `superpowers-subagent-driven-development` +and use this skill only where `Agent` is genuinely unavailable (Crush, Pi, OpenCode). ## The Process ### Step 1: Load and Review Plan 1. Read plan file 2. Review critically - identify any questions or concerns about the plan -3. If concerns: Raise them with your human partner before starting +3. If concerns: Raise them with the operator before starting 4. If no concerns: Create TodoWrite and proceed ### Step 2: Execute Tasks diff --git a/skills/superpowers-receiving-code-review/SKILL.md b/skills/superpowers-receiving-code-review/SKILL.md index e079e7b..a2e7dd1 100644 --- a/skills/superpowers-receiving-code-review/SKILL.md +++ b/skills/superpowers-receiving-code-review/SKILL.md @@ -54,7 +54,7 @@ WHY: Items may be related. Partial understanding = wrong implementation. **Example:** ``` -your human partner: "Fix 1-6" +the operator: "Fix 1-6" You understand 1,2,3,6. Unclear on 4,5. ❌ WRONG: Implement 1,2,3,6 now, ask about 4,5 later @@ -63,7 +63,7 @@ You understand 1,2,3,6. Unclear on 4,5. ## Source-Specific Handling -### From your human partner +### From the operator - **Trusted** - implement after understanding - **Still ask** if scope unclear - **No performative agreement** @@ -84,11 +84,11 @@ IF suggestion seems wrong: IF can't easily verify: Say so: "I can't verify this without [X]. Should I [investigate/ask/proceed]?" -IF conflicts with your human partner's prior decisions: - Stop and discuss with your human partner first +IF conflicts with the operator's prior decisions: + Stop and discuss with the operator first ``` -**your human partner's rule:** "External feedback - be skeptical, but check carefully" +**the operator's rule:** "External feedback - be skeptical, but check carefully" ## YAGNI Check for "Professional" Features @@ -100,7 +100,7 @@ IF reviewer suggests "implementing properly": IF used: Then implement properly ``` -**your human partner's rule:** "You and reviewer both report to me. If we don't need this feature, don't add it." +**the operator's rule:** "You and reviewer both report to me. If we don't need this feature, don't add it." ## Implementation Order @@ -123,13 +123,13 @@ Push back when: - Violates YAGNI (unused feature) - Technically incorrect for this stack - Legacy/compatibility reasons exist -- Conflicts with your human partner's architectural decisions +- Conflicts with the operator's architectural decisions **How to push back:** - Use technical reasoning, not defensiveness - Ask specific questions - Reference working tests/code -- Involve your human partner if architectural +- Involve the operator if architectural **Signal if uncomfortable pushing back out loud:** "Strange things are afoot at the Circle K" @@ -200,7 +200,7 @@ Reviewer: "Implement proper metrics tracking with database, date filters, CSV ex **Unclear Item (Good):** ``` -your human partner: "Fix items 1-6" +the operator: "Fix items 1-6" You understand 1,2,3,6. Unclear on 4,5. ✅ "Understand 1,2,3,6. Need clarification on 4 and 5 before implementing." ``` diff --git a/skills/superpowers-requesting-code-review/SKILL.md b/skills/superpowers-requesting-code-review/SKILL.md index f02f306..b9a1a73 100644 --- a/skills/superpowers-requesting-code-review/SKILL.md +++ b/skills/superpowers-requesting-code-review/SKILL.md @@ -36,7 +36,9 @@ HEAD_SHA=$(git rev-parse HEAD) **2. Dispatch code reviewer subagent:** -Use Task tool with `general-purpose` type, fill template at `code-reviewer.md` +Use the `Agent` tool with `subagent_type: "general-purpose"`, filling the template at +`code-reviewer.md`. A reviewer needs no write access and benefits from none — if the +harness offers a read-only agent type, prefer it. **Placeholders:** - `{DESCRIPTION}` - Brief summary of what you built diff --git a/skills/superpowers-requesting-code-review/code-reviewer.md b/skills/superpowers-requesting-code-review/code-reviewer.md index 525e4b4..7163ca9 100644 --- a/skills/superpowers-requesting-code-review/code-reviewer.md +++ b/skills/superpowers-requesting-code-review/code-reviewer.md @@ -5,7 +5,7 @@ Use this template when dispatching a code reviewer subagent. **Purpose:** Review completed work against requirements and code quality standards before it cascades into more work. ``` -Task tool (general-purpose): +Agent tool (`subagent_type: "general-purpose"`): description: "Review code changes" prompt: | You are a Senior Code Reviewer with expertise in software architecture, diff --git a/skills/superpowers-subagent-driven-development/SKILL.md b/skills/superpowers-subagent-driven-development/SKILL.md index f59e442..4f960e1 100644 --- a/skills/superpowers-subagent-driven-development/SKILL.md +++ b/skills/superpowers-subagent-driven-development/SKILL.md @@ -14,7 +14,7 @@ Execute plan by dispatching fresh subagent per task, with two-stage review after **Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration -**Continuous execution:** Do not pause to check in with your human partner between tasks. Execute all tasks from the plan without stopping. The only reasons to stop are: BLOCKED status you cannot resolve, ambiguity that genuinely prevents progress, or all tasks complete. "Should I continue?" prompts and progress summaries waste their time — they asked you to execute the plan, so execute it. +**Continuous execution:** Do not pause to check in with the operator between tasks. Execute all tasks from the plan without stopping. The only reasons to stop are: BLOCKED status you cannot resolve, ambiguity that genuinely prevents progress, or all tasks complete. "Should I continue?" prompts and progress summaries waste their time — they asked you to execute the plan, so execute it. ## When to Use diff --git a/skills/superpowers-subagent-driven-development/code-quality-reviewer-prompt.md b/skills/superpowers-subagent-driven-development/code-quality-reviewer-prompt.md index 51f901a..9c5573c 100644 --- a/skills/superpowers-subagent-driven-development/code-quality-reviewer-prompt.md +++ b/skills/superpowers-subagent-driven-development/code-quality-reviewer-prompt.md @@ -7,7 +7,7 @@ Use this template when dispatching a code quality reviewer subagent. **Only dispatch after spec compliance review passes.** ``` -Task tool (general-purpose): +Agent tool (`subagent_type: "general-purpose"`): Use template at requesting-code-review/code-reviewer.md DESCRIPTION: [task summary, from implementer's report] diff --git a/skills/superpowers-subagent-driven-development/implementer-prompt.md b/skills/superpowers-subagent-driven-development/implementer-prompt.md index 400c103..55e2426 100644 --- a/skills/superpowers-subagent-driven-development/implementer-prompt.md +++ b/skills/superpowers-subagent-driven-development/implementer-prompt.md @@ -3,7 +3,7 @@ Use this template when dispatching an implementer subagent. ``` -Task tool (general-purpose): +Agent tool (`subagent_type: "general-purpose"`): description: "Implement Task N: [task name]" prompt: | You are implementing Task N: [task name] diff --git a/skills/superpowers-subagent-driven-development/spec-reviewer-prompt.md b/skills/superpowers-subagent-driven-development/spec-reviewer-prompt.md index ab5ddb8..7437664 100644 --- a/skills/superpowers-subagent-driven-development/spec-reviewer-prompt.md +++ b/skills/superpowers-subagent-driven-development/spec-reviewer-prompt.md @@ -5,7 +5,7 @@ Use this template when dispatching a spec compliance reviewer subagent. **Purpose:** Verify implementer built what was requested (nothing more, nothing less) ``` -Task tool (general-purpose): +Agent tool (`subagent_type: "general-purpose"`): description: "Review spec compliance for Task N" prompt: | You are reviewing whether an implementation matches its specification. diff --git a/skills/superpowers-using-superpowers/references/gemini-tools.md b/skills/superpowers-using-superpowers/references/gemini-tools.md index 91ef404..e2146d1 100644 --- a/skills/superpowers-using-superpowers/references/gemini-tools.md +++ b/skills/superpowers-using-superpowers/references/gemini-tools.md @@ -24,11 +24,11 @@ When a skill says to dispatch a named agent type, use `@generalist` with the ful | Skill instruction | Gemini CLI equivalent | |-------------------|----------------------| -| `Task tool (superpowers:implementer)` | `@generalist` with the filled `implementer-prompt.md` template | -| `Task tool (superpowers:spec-reviewer)` | `@generalist` with the filled `spec-reviewer-prompt.md` template | -| `Task tool (superpowers:code-reviewer)` | `@code-reviewer` (bundled agent) or `@generalist` with the filled review prompt | -| `Task tool (superpowers:code-quality-reviewer)` | `@generalist` with the filled `code-quality-reviewer-prompt.md` template | -| `Task tool (general-purpose)` with inline prompt | `@generalist` with your inline prompt | +| `Agent tool (superpowers:implementer)` | `@generalist` with the filled `implementer-prompt.md` template | +| `Agent tool (superpowers:spec-reviewer)` | `@generalist` with the filled `spec-reviewer-prompt.md` template | +| `Agent tool (superpowers:code-reviewer)` | `@code-reviewer` (bundled agent) or `@generalist` with the filled review prompt | +| `Agent tool (superpowers:code-quality-reviewer)` | `@generalist` with the filled `code-quality-reviewer-prompt.md` template | +| `Agent tool (general-purpose)` with inline prompt | `@generalist` with your inline prompt | ### Prompt filling diff --git a/skills/superpowers-verification-before-completion/SKILL.md b/skills/superpowers-verification-before-completion/SKILL.md index 62a2551..0ff2b7f 100644 --- a/skills/superpowers-verification-before-completion/SKILL.md +++ b/skills/superpowers-verification-before-completion/SKILL.md @@ -111,7 +111,7 @@ Skip any step = lying, not verifying ## Why This Matters From 24 failure memories: -- your human partner said "I don't believe you" - trust broken +- the operator said "I don't believe you" - trust broken - Undefined functions shipped - would crash - Missing requirements shipped - incomplete features - Time wasted on false completion → redirect → rework diff --git a/skills/superpowers-writing-plans/plan-document-reviewer-prompt.md b/skills/superpowers-writing-plans/plan-document-reviewer-prompt.md index 2db2806..850c6c1 100644 --- a/skills/superpowers-writing-plans/plan-document-reviewer-prompt.md +++ b/skills/superpowers-writing-plans/plan-document-reviewer-prompt.md @@ -7,7 +7,7 @@ Use this template when dispatching a plan document reviewer subagent. **Dispatch after:** The complete plan is written. ``` -Task tool (general-purpose): +Agent tool (`subagent_type: "general-purpose"`): description: "Review plan document" prompt: | You are a plan document reviewer. Verify this plan is complete and ready for implementation. diff --git a/skills/superpowers-writing-skills/SKILL.md b/skills/superpowers-writing-skills/SKILL.md index 568511a..b7fde38 100644 --- a/skills/superpowers-writing-skills/SKILL.md +++ b/skills/superpowers-writing-skills/SKILL.md @@ -246,7 +246,7 @@ Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] **Compress examples:** ```markdown # ❌ BAD: Verbose example (42 words) -your human partner: "How did we handle authentication errors in React Router before?" +the operator: "How did we handle authentication errors in React Router before?" You: I'll search past conversations for React Router authentication patterns. [Dispatch subagent with search query: "React Router authentication error handling 401"] @@ -318,7 +318,7 @@ digraph when_flowchart { See @graphviz-conventions.dot for graphviz style rules. -**Visualizing for your human partner:** Use `render-graphs.js` in this directory to render a skill's flowcharts to SVG: +**Visualizing for the operator:** Use `render-graphs.js` in this directory to render a skill's flowcharts to SVG: ```bash ./render-graphs.js ../some-skill # Each diagram separately ./render-graphs.js ../some-skill --combine # All diagrams in one SVG