Create Superpowers Lite fork
This commit is contained in:
mujing
@@ -1,14 +1,14 @@
|
||||
{
|
||||
"name": "superpowers-dev",
|
||||
"description": "Development marketplace for Superpowers core skills library",
|
||||
"name": "superpowers-lite-dev",
|
||||
"description": "Development marketplace for the manual-only Superpowers Lite skills library",
|
||||
"owner": {
|
||||
"name": "Jesse Vincent",
|
||||
"email": "jesse@fsck.com"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "superpowers",
|
||||
"description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
|
||||
"name": "superpowers-lite",
|
||||
"description": "Manual-only skills library: TDD, debugging, collaboration, lightweight plans, and phase reviews",
|
||||
"version": "5.1.0",
|
||||
"source": "./",
|
||||
"author": {
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "superpowers",
|
||||
"description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
|
||||
"name": "superpowers-lite",
|
||||
"description": "Manual-only Superpowers fork: TDD, debugging, collaboration, lightweight plans, and phase reviews",
|
||||
"version": "5.1.0",
|
||||
"author": {
|
||||
"name": "Jesse Vincent",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "superpowers",
|
||||
"name": "superpowers-lite",
|
||||
"version": "5.1.0",
|
||||
"description": "An agentic skills framework & software development methodology that works: planning, TDD, debugging, and collaboration workflows.",
|
||||
"description": "A manual-only fork of Superpowers with lightweight planning and phase-based execution workflows.",
|
||||
"author": {
|
||||
"name": "Jesse Vincent",
|
||||
"email": "jesse@fsck.com",
|
||||
@@ -22,9 +22,9 @@
|
||||
],
|
||||
"skills": "./skills/",
|
||||
"interface": {
|
||||
"displayName": "Superpowers",
|
||||
"shortDescription": "Planning, TDD, debugging, and delivery workflows for coding agents",
|
||||
"longDescription": "Use Superpowers to guide agent work through brainstorming, implementation planning, test-driven development, systematic debugging, parallel execution, code review, and finish-the-branch workflows.",
|
||||
"displayName": "Superpowers Lite",
|
||||
"shortDescription": "Manual-only planning, execution, debugging, and delivery workflows",
|
||||
"longDescription": "Use Superpowers Lite only when explicitly requested. This fork keeps Superpowers-style brainstorming, planning, TDD, debugging, parallel execution, code review, and finish-the-branch workflows, but avoids automatic activation, keeps generated design and implementation plans out of git, and supports phase-based execution with one review per phase.",
|
||||
"developerName": "Jesse Vincent",
|
||||
"category": "Coding",
|
||||
"capabilities": [
|
||||
@@ -33,8 +33,8 @@
|
||||
"Write"
|
||||
],
|
||||
"defaultPrompt": [
|
||||
"I've got an idea for something I'd like to build.",
|
||||
"Let's add a feature to this project."
|
||||
"Use Superpowers Lite to brainstorm this change.",
|
||||
"Use superpowers-lite:writing-plans for this spec."
|
||||
],
|
||||
"websiteURL": "https://github.com/obra/superpowers",
|
||||
"privacyPolicyURL": "https://docs.github.com/en/site-policy/privacy-policies/github-general-privacy-statement",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "superpowers",
|
||||
"displayName": "Superpowers",
|
||||
"description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
|
||||
"name": "superpowers-lite",
|
||||
"displayName": "Superpowers Lite",
|
||||
"description": "Manual-only Superpowers fork: TDD, debugging, collaboration, lightweight plans, and phase reviews",
|
||||
"version": "5.1.0",
|
||||
"author": {
|
||||
"name": "Jesse Vincent",
|
||||
@@ -20,6 +20,5 @@
|
||||
],
|
||||
"skills": "./skills/",
|
||||
"agents": "./agents/",
|
||||
"commands": "./commands/",
|
||||
"hooks": "./hooks/hooks-cursor.json"
|
||||
"commands": "./commands/"
|
||||
}
|
||||
|
||||
1
.gitignore
vendored
1
.gitignore
vendored
@@ -1,5 +1,6 @@
|
||||
.worktrees/
|
||||
.private-journal/
|
||||
.superpowers-lite/
|
||||
.claude/
|
||||
.DS_Store
|
||||
node_modules/
|
||||
|
||||
@@ -1,99 +1,17 @@
|
||||
/**
|
||||
* Superpowers plugin for OpenCode.ai
|
||||
* Superpowers Lite plugin for OpenCode.ai
|
||||
*
|
||||
* Injects superpowers bootstrap context via system prompt transform.
|
||||
* Auto-registers skills directory via config hook (no symlinks needed).
|
||||
* Auto-registers the skills directory via config hook (no symlinks needed).
|
||||
* Does not inject bootstrap context; this fork is manual-only.
|
||||
*/
|
||||
|
||||
import path from 'path';
|
||||
import fs from 'fs';
|
||||
import os from 'os';
|
||||
import { fileURLToPath } from 'url';
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
|
||||
// Simple frontmatter extraction (avoid dependency on skills-core for bootstrap)
|
||||
const extractAndStripFrontmatter = (content) => {
|
||||
const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
|
||||
if (!match) return { frontmatter: {}, content };
|
||||
|
||||
const frontmatterStr = match[1];
|
||||
const body = match[2];
|
||||
const frontmatter = {};
|
||||
|
||||
for (const line of frontmatterStr.split('\n')) {
|
||||
const colonIdx = line.indexOf(':');
|
||||
if (colonIdx > 0) {
|
||||
const key = line.slice(0, colonIdx).trim();
|
||||
const value = line.slice(colonIdx + 1).trim().replace(/^["']|["']$/g, '');
|
||||
frontmatter[key] = value;
|
||||
}
|
||||
}
|
||||
|
||||
return { frontmatter, content: body };
|
||||
};
|
||||
|
||||
// Normalize a path: trim whitespace, expand ~, resolve to absolute
|
||||
const normalizePath = (p, homeDir) => {
|
||||
if (!p || typeof p !== 'string') return null;
|
||||
let normalized = p.trim();
|
||||
if (!normalized) return null;
|
||||
if (normalized.startsWith('~/')) {
|
||||
normalized = path.join(homeDir, normalized.slice(2));
|
||||
} else if (normalized === '~') {
|
||||
normalized = homeDir;
|
||||
}
|
||||
return path.resolve(normalized);
|
||||
};
|
||||
|
||||
// Module-level cache for bootstrap content.
|
||||
// The SKILL.md file does not change during a session, so reading + parsing it
|
||||
// once eliminates redundant fs.existsSync + fs.readFileSync + regex work on
|
||||
// every agent step. See #1202 for the full analysis.
|
||||
let _bootstrapCache = undefined; // undefined = not yet loaded, null = file missing
|
||||
|
||||
export const SuperpowersPlugin = async ({ client, directory }) => {
|
||||
const homeDir = os.homedir();
|
||||
export const SuperpowersPlugin = async () => {
|
||||
const superpowersSkillsDir = path.resolve(__dirname, '../../skills');
|
||||
const envConfigDir = normalizePath(process.env.OPENCODE_CONFIG_DIR, homeDir);
|
||||
const configDir = envConfigDir || path.join(homeDir, '.config/opencode');
|
||||
|
||||
// Helper to generate bootstrap content (cached after first call)
|
||||
const getBootstrapContent = () => {
|
||||
// Return cached result on subsequent calls
|
||||
if (_bootstrapCache !== undefined) return _bootstrapCache;
|
||||
|
||||
// Try to load using-superpowers skill
|
||||
const skillPath = path.join(superpowersSkillsDir, 'using-superpowers', 'SKILL.md');
|
||||
if (!fs.existsSync(skillPath)) {
|
||||
_bootstrapCache = null;
|
||||
return null;
|
||||
}
|
||||
|
||||
const fullContent = fs.readFileSync(skillPath, 'utf8');
|
||||
const { content } = extractAndStripFrontmatter(fullContent);
|
||||
|
||||
const toolMapping = `**Tool Mapping for OpenCode:**
|
||||
When skills reference tools you don't have, substitute OpenCode equivalents:
|
||||
- \`TodoWrite\` → \`todowrite\`
|
||||
- \`Task\` tool with subagents → Use OpenCode's subagent system (@mention)
|
||||
- \`Skill\` tool → OpenCode's native \`skill\` tool
|
||||
- \`Read\`, \`Write\`, \`Edit\`, \`Bash\` → Your native tools
|
||||
|
||||
Use OpenCode's native \`skill\` tool to list and load skills.`;
|
||||
|
||||
_bootstrapCache = `<EXTREMELY_IMPORTANT>
|
||||
You have superpowers.
|
||||
|
||||
**IMPORTANT: The using-superpowers skill content is included below. It is ALREADY LOADED - you are currently following it. Do NOT use the skill tool to load "using-superpowers" again - that would be redundant.**
|
||||
|
||||
${content}
|
||||
|
||||
${toolMapping}
|
||||
</EXTREMELY_IMPORTANT>`;
|
||||
|
||||
return _bootstrapCache;
|
||||
};
|
||||
|
||||
return {
|
||||
// Inject skills path into live config so OpenCode discovers superpowers skills
|
||||
@@ -106,30 +24,6 @@ ${toolMapping}
|
||||
if (!config.skills.paths.includes(superpowersSkillsDir)) {
|
||||
config.skills.paths.push(superpowersSkillsDir);
|
||||
}
|
||||
},
|
||||
|
||||
// Inject bootstrap into the first user message of each session.
|
||||
// Using a user message instead of a system message avoids:
|
||||
// 1. Token bloat from system messages repeated every turn (#750)
|
||||
// 2. Multiple system messages breaking Qwen and other models (#894)
|
||||
//
|
||||
// The hook fires on every agent step (not just every turn) because
|
||||
// opencode's prompt.ts reloads messages from DB each step. Fresh message
|
||||
// arrays may need injection again, so getBootstrapContent() must not do
|
||||
// repeated disk work.
|
||||
'experimental.chat.messages.transform': async (_input, output) => {
|
||||
const bootstrap = getBootstrapContent();
|
||||
if (!bootstrap || !output.messages.length) return;
|
||||
const firstUser = output.messages.find(m => m.info.role === 'user');
|
||||
if (!firstUser || !firstUser.parts.length) return;
|
||||
|
||||
// Guard: skip if first user message already contains bootstrap.
|
||||
// This prevents double injection when OpenCode passes an already
|
||||
// transformed in-memory message array through the hook again.
|
||||
if (firstUser.parts.some(p => p.type === 'text' && p.text.includes('EXTREMELY_IMPORTANT'))) return;
|
||||
|
||||
const ref = firstUser.parts[0];
|
||||
firstUser.parts.unshift({ ...ref, type: 'text', text: bootstrap });
|
||||
}
|
||||
};
|
||||
};
|
||||
|
||||
18
CLAUDE.md
18
CLAUDE.md
@@ -1,4 +1,4 @@
|
||||
# Superpowers — Contributor Guidelines
|
||||
# Superpowers Lite — Contributor Guidelines
|
||||
|
||||
## If You Are an AI Agent
|
||||
|
||||
@@ -52,9 +52,9 @@ Every PR must solve a real problem that someone actually experienced. "My review
|
||||
|
||||
Superpowers core contains general-purpose skills that benefit all users regardless of their project. Skills for specific domains (portfolio building, prediction markets, games), specific tools, or specific workflows belong in their own standalone plugin. Ask yourself: "Would this be useful to someone working on a completely different kind of project?" If not, publish it separately.
|
||||
|
||||
### Fork-specific changes
|
||||
### Upstream Compatibility
|
||||
|
||||
If you maintain a fork with customizations, do not open PRs to sync your fork or push fork-specific changes upstream. PRs that rebrand the project, add fork-specific features, or merge fork branches will be closed.
|
||||
This repository is a manual-only fork. Do not open PRs upstream for fork-specific changes such as manual activation, local-only planning artifacts, or phase-based review batching.
|
||||
|
||||
### Fabricated content
|
||||
|
||||
@@ -68,28 +68,28 @@ PRs containing multiple unrelated changes will be closed. Split them into separa
|
||||
|
||||
If your PR adds support for a new harness (IDE, CLI tool, agent runner), you MUST include a session transcript proving the integration works end-to-end.
|
||||
|
||||
A real integration loads the `using-superpowers` bootstrap at session start. The bootstrap is what causes skills to auto-trigger at the right moments. Without it, the skills are dead weight — present on disk but never invoked.
|
||||
Superpowers Lite integrations must not load the `using-superpowers` bootstrap at session start. The skills are intentionally manual-only and should activate only when the user explicitly names Superpowers Lite or a `superpowers-lite:*` skill.
|
||||
|
||||
**The acceptance test.** Open a clean session in the new harness and send exactly this user message:
|
||||
|
||||
> Let's make a react todo list
|
||||
|
||||
A working integration auto-triggers the `brainstorming` skill before any code is written. Paste the complete transcript in the PR.
|
||||
A working Superpowers Lite integration does not auto-trigger `brainstorming`. It proceeds normally until the user explicitly requests Superpowers Lite.
|
||||
|
||||
**These are not real integrations and will be closed:**
|
||||
|
||||
- Manually copying skill files into the harness
|
||||
- Wrapping with `npx skills` or similar at-runtime shims
|
||||
- Anything that requires the user to opt in to skills per-session
|
||||
- Anything where `brainstorming` does not auto-trigger on the acceptance test above
|
||||
- Anything that injects Superpowers Lite skills without explicit user opt-in
|
||||
- Anything where `brainstorming` auto-triggers on the acceptance test above
|
||||
|
||||
If you are not sure whether your integration loads the bootstrap at session start, it does not.
|
||||
If you are not sure whether your integration injects the bootstrap at session start, verify that it does not.
|
||||
|
||||
## Skill Changes Require Evaluation
|
||||
|
||||
Skills are not prose — they are code that shapes agent behavior. If you modify skill content:
|
||||
|
||||
- Use `superpowers:writing-skills` to develop and test changes
|
||||
- Use `superpowers-lite:writing-skills` to develop and test changes
|
||||
- Run adversarial pressure testing across multiple sessions
|
||||
- Show before/after eval results in your PR
|
||||
- Do not modify carefully-tuned content (Red Flags tables, rationalization lists, "human partner" language) without evidence the change is an improvement
|
||||
|
||||
@@ -1,2 +1,5 @@
|
||||
Superpowers Lite is manual-only. Do not load or apply skills from this repository unless the user explicitly asks for Superpowers Lite or names a `superpowers-lite:*` skill.
|
||||
|
||||
When explicitly activated, use:
|
||||
@./skills/using-superpowers/SKILL.md
|
||||
@./skills/using-superpowers/references/gemini-tools.md
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "superpowers",
|
||||
"description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
|
||||
"name": "superpowers-lite",
|
||||
"description": "Manual-only skills library: TDD, debugging, collaboration, lightweight plans, and phase reviews",
|
||||
"version": "5.1.0",
|
||||
"contextFileName": "GEMINI.md"
|
||||
}
|
||||
|
||||
@@ -1,10 +1,4 @@
|
||||
{
|
||||
"version": 1,
|
||||
"hooks": {
|
||||
"sessionStart": [
|
||||
{
|
||||
"command": "./hooks/run-hook.cmd session-start"
|
||||
}
|
||||
]
|
||||
}
|
||||
"hooks": {}
|
||||
}
|
||||
|
||||
@@ -1,16 +1,3 @@
|
||||
{
|
||||
"hooks": {
|
||||
"SessionStart": [
|
||||
{
|
||||
"matcher": "startup|clear|compact",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
|
||||
"async": false
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
"hooks": {}
|
||||
}
|
||||
|
||||
@@ -1,57 +1,6 @@
|
||||
#!/usr/bin/env bash
|
||||
# SessionStart hook for superpowers plugin
|
||||
# Superpowers Lite is manual-only. Session start must not inject skill context.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
# Determine plugin root directory
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||
PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
|
||||
|
||||
# Check if legacy skills directory exists and build warning
|
||||
warning_message=""
|
||||
legacy_skills_dir="${HOME}/.config/superpowers/skills"
|
||||
if [ -d "$legacy_skills_dir" ]; then
|
||||
warning_message="\n\n<important-reminder>IN YOUR FIRST REPLY AFTER SEEING THIS MESSAGE YOU MUST TELL THE USER:⚠️ **WARNING:** Superpowers now uses Claude Code's skills system. Custom skills in ~/.config/superpowers/skills will not be read. Move custom skills to ~/.claude/skills instead. To make this message go away, remove ~/.config/superpowers/skills</important-reminder>"
|
||||
fi
|
||||
|
||||
# Read using-superpowers content
|
||||
using_superpowers_content=$(cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md" 2>&1 || echo "Error reading using-superpowers skill")
|
||||
|
||||
# Escape string for JSON embedding using bash parameter substitution.
|
||||
# Each ${s//old/new} is a single C-level pass - orders of magnitude
|
||||
# faster than the character-by-character loop this replaces.
|
||||
escape_for_json() {
|
||||
local s="$1"
|
||||
s="${s//\\/\\\\}"
|
||||
s="${s//\"/\\\"}"
|
||||
s="${s//$'\n'/\\n}"
|
||||
s="${s//$'\r'/\\r}"
|
||||
s="${s//$'\t'/\\t}"
|
||||
printf '%s' "$s"
|
||||
}
|
||||
|
||||
using_superpowers_escaped=$(escape_for_json "$using_superpowers_content")
|
||||
warning_escaped=$(escape_for_json "$warning_message")
|
||||
session_context="<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**\n\n${using_superpowers_escaped}\n\n${warning_escaped}\n</EXTREMELY_IMPORTANT>"
|
||||
|
||||
# Output context injection as JSON.
|
||||
# Cursor hooks expect additional_context (snake_case).
|
||||
# Claude Code hooks expect hookSpecificOutput.additionalContext (nested).
|
||||
# Copilot CLI (v1.0.11+) and others expect additionalContext (top-level, SDK standard).
|
||||
# Claude Code reads BOTH additional_context and hookSpecificOutput without
|
||||
# deduplication, so we must emit only the field the current platform consumes.
|
||||
#
|
||||
# Uses printf instead of heredoc to work around bash 5.3+ heredoc hang.
|
||||
# See: https://github.com/obra/superpowers/issues/571
|
||||
if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
|
||||
# Cursor sets CURSOR_PLUGIN_ROOT (may also set CLAUDE_PLUGIN_ROOT)
|
||||
printf '{\n "additional_context": "%s"\n}\n' "$session_context"
|
||||
elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -z "${COPILOT_CLI:-}" ]; then
|
||||
# Claude Code sets CLAUDE_PLUGIN_ROOT without COPILOT_CLI
|
||||
printf '{\n "hookSpecificOutput": {\n "hookEventName": "SessionStart",\n "additionalContext": "%s"\n }\n}\n' "$session_context"
|
||||
else
|
||||
# Copilot CLI (sets COPILOT_CLI=1) or unknown platform — SDK standard format
|
||||
printf '{\n "additionalContext": "%s"\n}\n' "$session_context"
|
||||
fi
|
||||
|
||||
exit 0
|
||||
printf '{}\n'
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
{
|
||||
"name": "superpowers",
|
||||
"name": "superpowers-lite",
|
||||
"version": "5.1.0",
|
||||
"type": "module",
|
||||
"main": ".opencode/plugins/superpowers.js"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: brainstorming
|
||||
description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
|
||||
description: "Manual-only skill. Activate only after an explicit user request for superpowers-lite:brainstorming or Superpowers Lite brainstorming."
|
||||
---
|
||||
|
||||
# Brainstorming Ideas Into Designs
|
||||
@@ -10,7 +10,7 @@ Help turn ideas into fully formed designs and specs through natural collaborativ
|
||||
Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
|
||||
|
||||
<HARD-GATE>
|
||||
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
|
||||
When this skill was explicitly activated, do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it.
|
||||
</HARD-GATE>
|
||||
|
||||
## Anti-Pattern: "This Is Too Simple To Need A Design"
|
||||
@@ -26,7 +26,7 @@ You MUST create a task for each of these items and complete them in order:
|
||||
3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
|
||||
4. **Propose 2-3 approaches** — with trade-offs and your recommendation
|
||||
5. **Present design** — in sections scaled to their complexity, get user approval after each section
|
||||
6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
|
||||
6. **Write design doc** — save to `.superpowers-lite/specs/YYYY-MM-DD-<topic>-design.md` and keep it out of git
|
||||
7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
|
||||
8. **User reviews written spec** — ask user to review the spec file before proceeding
|
||||
9. **Transition to implementation** — invoke writing-plans skill to create implementation plan
|
||||
@@ -108,10 +108,11 @@ digraph brainstorming {
|
||||
|
||||
**Documentation:**
|
||||
|
||||
- Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
|
||||
- Before writing files, ensure `.superpowers-lite/` is listed in `.git/info/exclude` when the project is a git repository
|
||||
- Write the validated design (spec) to `.superpowers-lite/specs/YYYY-MM-DD-<topic>-design.md`
|
||||
- (User preferences for spec location override this default)
|
||||
- Use elements-of-style:writing-clearly-and-concisely skill if available
|
||||
- Commit the design document to git
|
||||
- Do not commit generated design documents unless the user explicitly asks
|
||||
|
||||
**Spec Self-Review:**
|
||||
After writing the spec document, look at it with fresh eyes:
|
||||
@@ -126,7 +127,7 @@ Fix any issues inline. No need to re-review — just fix and move on.
|
||||
**User Review Gate:**
|
||||
After the spec review loop passes, ask the user to review the written spec before proceeding:
|
||||
|
||||
> "Spec written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
|
||||
> "Spec written to `<path>` as a local, untracked artifact. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
|
||||
|
||||
Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ Use this template when dispatching a spec document reviewer subagent.
|
||||
|
||||
**Purpose:** Verify the spec is complete, consistent, and ready for implementation planning.
|
||||
|
||||
**Dispatch after:** Spec document is written to docs/superpowers/specs/
|
||||
**Dispatch after:** Spec document is written to .superpowers-lite/specs/
|
||||
|
||||
```
|
||||
Task tool (general-purpose):
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: dispatching-parallel-agents
|
||||
description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
|
||||
description: Manual-only skill. Activate only after an explicit user request for superpowers-lite:dispatching-parallel-agents.
|
||||
---
|
||||
|
||||
# Dispatching Parallel Agents
|
||||
|
||||
@@ -1,39 +1,50 @@
|
||||
---
|
||||
name: executing-plans
|
||||
description: Use when you have a written implementation plan to execute in a separate session with review checkpoints
|
||||
description: Manual-only skill. Activate only after an explicit user request for superpowers-lite:executing-plans.
|
||||
---
|
||||
|
||||
# Executing Plans
|
||||
|
||||
## Overview
|
||||
|
||||
Load plan, review critically, execute all tasks, report when complete.
|
||||
Load plan, review critically, group tasks into phases when useful, execute all phases, 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:** Tell your human partner that Superpowers Lite works better with access to subagents for larger plans. If subagents are available and the user explicitly wants that workflow, use superpowers-lite:subagent-driven-development instead of this skill.
|
||||
|
||||
## 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
|
||||
4. If no concerns: Create TodoWrite and proceed
|
||||
### Step 1: Confirm Branch, Load, and Review Plan
|
||||
1. Confirm the current git branch is not `main` or `master` with `git branch --show-current`
|
||||
2. If on `main` or `master`, stop and ask the user to switch or create a feature branch before implementation
|
||||
3. Read plan file
|
||||
4. Review critically - identify any questions or concerns about the plan
|
||||
5. If concerns: Raise them with your human partner before starting
|
||||
6. If no concerns: Create TodoWrite and proceed
|
||||
|
||||
### Step 2: Execute Tasks
|
||||
### Step 2: Group Tasks Into Phases
|
||||
|
||||
For each task:
|
||||
Before implementation, decide whether adjacent tasks should run as one phase:
|
||||
|
||||
- Group tasks that touch the same files or complete one coherent behavior
|
||||
- Keep tasks separate when they are independent, risky, or easier to review alone
|
||||
- Preserve the plan's task checklist, but use phase-level review checkpoints
|
||||
|
||||
### Step 3: Execute Phases
|
||||
|
||||
For each phase:
|
||||
1. Mark as in_progress
|
||||
2. Follow each step exactly (plan has bite-sized steps)
|
||||
3. Run verifications as specified
|
||||
4. Mark as completed
|
||||
2. Follow each included task step exactly (plan has bite-sized steps)
|
||||
3. Run verifications specified by the included tasks
|
||||
4. Request or perform one review for the whole phase
|
||||
5. Mark all included tasks as completed only after the phase review is addressed
|
||||
|
||||
### Step 3: Complete Development
|
||||
### Step 4: Complete Development
|
||||
|
||||
After all tasks complete and verified:
|
||||
- Announce: "I'm using the finishing-a-development-branch skill to complete this work."
|
||||
- **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch
|
||||
- **REQUIRED SUB-SKILL:** Use superpowers-lite:finishing-a-development-branch
|
||||
- Follow that skill to verify tests, present options, execute choice
|
||||
|
||||
## When to Stop and Ask for Help
|
||||
@@ -60,11 +71,14 @@ After all tasks complete and verified:
|
||||
- Don't skip verifications
|
||||
- Reference skills when plan says to
|
||||
- Stop when blocked, don't guess
|
||||
- Never start implementation on main/master branch without explicit user consent
|
||||
- Work in the current branch by default; do not create or switch to a worktree unless the user explicitly asks
|
||||
- Never start implementation on `main` or `master`; ask the user to switch or create a feature branch
|
||||
|
||||
## Integration
|
||||
|
||||
**Required workflow skills:**
|
||||
- **superpowers:using-git-worktrees** - Ensures isolated workspace (creates one or verifies existing)
|
||||
- **superpowers:writing-plans** - Creates the plan this skill executes
|
||||
- **superpowers:finishing-a-development-branch** - Complete development after all tasks
|
||||
- **superpowers-lite:writing-plans** - Creates the plan this skill executes
|
||||
- **superpowers-lite:finishing-a-development-branch** - Complete development after all tasks
|
||||
|
||||
**Optional workflow skills:**
|
||||
- **superpowers-lite:using-git-worktrees** - Use only when the user explicitly asks for an isolated workspace
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: finishing-a-development-branch
|
||||
description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
|
||||
description: Manual-only skill. Activate only after an explicit user request for superpowers-lite:finishing-a-development-branch.
|
||||
---
|
||||
|
||||
# Finishing a Development Branch
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: receiving-code-review
|
||||
description: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
|
||||
description: Manual-only skill. Activate only after an explicit user request for superpowers-lite:receiving-code-review.
|
||||
---
|
||||
|
||||
# Code Review Reception
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: requesting-code-review
|
||||
description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements
|
||||
description: Manual-only skill. Activate only after an explicit user request for superpowers-lite:requesting-code-review.
|
||||
---
|
||||
|
||||
# Requesting Code Review
|
||||
@@ -12,7 +12,7 @@ Dispatch a code reviewer subagent to catch issues before they cascade. The revie
|
||||
## When to Request Review
|
||||
|
||||
**Mandatory:**
|
||||
- After each task in subagent-driven development
|
||||
- After each phase in subagent-driven development
|
||||
- After completing major feature
|
||||
- Before merge to main
|
||||
|
||||
@@ -48,7 +48,7 @@ Use Task tool with `general-purpose` type, fill template at `code-reviewer.md`
|
||||
## Example
|
||||
|
||||
```
|
||||
[Just completed Task 2: Add verification function]
|
||||
[Just completed Phase 2: Add verification function and CLI wiring]
|
||||
|
||||
You: Let me request code review before proceeding.
|
||||
|
||||
@@ -56,8 +56,8 @@ BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
|
||||
HEAD_SHA=$(git rev-parse HEAD)
|
||||
|
||||
[Dispatch code reviewer subagent]
|
||||
DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
|
||||
PLAN_OR_REQUIREMENTS: Task 2 from docs/superpowers/plans/deployment-plan.md
|
||||
DESCRIPTION: Added verifyIndex(), repairIndex(), and CLI wiring
|
||||
PLAN_OR_REQUIREMENTS: Phase 2 from .superpowers-lite/plans/deployment-plan.md
|
||||
BASE_SHA: a7981ec
|
||||
HEAD_SHA: 3df7661
|
||||
|
||||
@@ -75,7 +75,7 @@ You: [Fix progress indicators]
|
||||
## Integration with Workflows
|
||||
|
||||
**Subagent-Driven Development:**
|
||||
- Review after EACH task
|
||||
- Review after each phase, which may contain one or more related tasks
|
||||
- Catch issues before they compound
|
||||
- Fix before moving to next task
|
||||
|
||||
|
||||
@@ -1,17 +1,17 @@
|
||||
---
|
||||
name: subagent-driven-development
|
||||
description: Use when executing implementation plans with independent tasks in the current session
|
||||
description: Manual-only skill. Activate only after an explicit user request for superpowers-lite:subagent-driven-development.
|
||||
---
|
||||
|
||||
# Subagent-Driven Development
|
||||
|
||||
Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.
|
||||
Execute plan by dispatching fresh subagent per phase, where a phase may contain one or more related tasks. Run a two-stage review after each phase: spec compliance review first, then code quality review.
|
||||
|
||||
**Why subagents:** You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.
|
||||
|
||||
**Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration
|
||||
**Core principle:** Fresh subagent per coherent phase + two-stage review (spec then quality) = high quality without review overhead on every tiny task
|
||||
|
||||
**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 your human partner between phases unless blocked. Execute all tasks from the plan in the current branch without stopping. The only reasons to stop are: current branch is `main` or `master`, 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
|
||||
|
||||
@@ -35,18 +35,29 @@ digraph when_to_use {
|
||||
|
||||
**vs. Executing Plans (parallel session):**
|
||||
- Same session (no context switch)
|
||||
- Fresh subagent per task (no context pollution)
|
||||
- Two-stage review after each task: spec compliance first, then code quality
|
||||
- Fresh subagent per phase (no context pollution)
|
||||
- Two-stage review after each phase: spec compliance first, then code quality
|
||||
- Faster iteration (no human-in-loop between tasks)
|
||||
|
||||
## Phase Grouping
|
||||
|
||||
Before grouping phases, confirm the current git branch is not `main` or `master` with `git branch --show-current`. If it is, stop and ask the user to switch or create a feature branch. Do not create or switch to a worktree unless the user explicitly asks.
|
||||
|
||||
Before dispatching implementers, group tasks into phases:
|
||||
|
||||
- Group adjacent tasks when they touch the same files, complete one coherent behavior, or would create review churn if split
|
||||
- Keep a task as its own phase when it is risky, broad, independent, or likely to need a focused review
|
||||
- Never group tasks just to hide uncertainty; if grouping makes requirements harder to verify, split the phase
|
||||
- Record phase membership in TodoWrite so progress is visible at both phase and task level
|
||||
|
||||
## The Process
|
||||
|
||||
```dot
|
||||
digraph process {
|
||||
rankdir=TB;
|
||||
|
||||
subgraph cluster_per_task {
|
||||
label="Per Task";
|
||||
subgraph cluster_per_phase {
|
||||
label="Per Phase";
|
||||
"Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
|
||||
"Implementer subagent asks questions?" [shape=diamond];
|
||||
"Answer questions, provide context" [shape=box];
|
||||
@@ -57,15 +68,15 @@ digraph process {
|
||||
"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 phase tasks complete in TodoWrite" [shape=box];
|
||||
}
|
||||
|
||||
"Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
|
||||
"More tasks remain?" [shape=diamond];
|
||||
"Read plan, extract all tasks with full text, group into phases, note context, create TodoWrite" [shape=box];
|
||||
"More phases remain?" [shape=diamond];
|
||||
"Dispatch final code reviewer subagent for entire implementation" [shape=box];
|
||||
"Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
|
||||
"Use superpowers-lite: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, group into phases, note context, create TodoWrite" -> "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)";
|
||||
@@ -78,11 +89,11 @@ 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?";
|
||||
"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";
|
||||
"Code quality reviewer subagent approves?" -> "Mark phase tasks complete in TodoWrite" [label="yes"];
|
||||
"Mark phase tasks complete in TodoWrite" -> "More phases remain?";
|
||||
"More phases remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
|
||||
"More phases remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
|
||||
"Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers-lite:finishing-a-development-branch";
|
||||
}
|
||||
```
|
||||
|
||||
@@ -130,14 +141,15 @@ Implementer subagents report one of four statuses. Handle each appropriately:
|
||||
```
|
||||
You: I'm using Subagent-Driven Development to execute this plan.
|
||||
|
||||
[Read plan file once: docs/superpowers/plans/feature-plan.md]
|
||||
[Read plan file once: .superpowers-lite/plans/feature-plan.md]
|
||||
[Extract all 5 tasks with full text and context]
|
||||
[Create TodoWrite with all tasks]
|
||||
[Group into 3 phases: Phase 1 = Task 1, Phase 2 = Tasks 2-3, Phase 3 = Tasks 4-5]
|
||||
[Create TodoWrite with all phases and tasks]
|
||||
|
||||
Task 1: Hook installation script
|
||||
Phase 1: Hook installation script
|
||||
|
||||
[Get Task 1 text and context (already extracted)]
|
||||
[Dispatch implementation subagent with full task text + context]
|
||||
[Dispatch implementation subagent with full phase text + context]
|
||||
|
||||
Implementer: "Before I begin - should the hook be installed at user or system level?"
|
||||
|
||||
@@ -156,12 +168,12 @@ Spec reviewer: ✅ Spec compliant - all requirements met, nothing extra
|
||||
[Get git SHAs, dispatch code quality reviewer]
|
||||
Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved.
|
||||
|
||||
[Mark Task 1 complete]
|
||||
[Mark Phase 1 tasks complete]
|
||||
|
||||
Task 2: Recovery modes
|
||||
Phase 2: Recovery modes and CLI wiring
|
||||
|
||||
[Get Task 2 text and context (already extracted)]
|
||||
[Dispatch implementation subagent with full task text + context]
|
||||
[Get Task 2 and Task 3 text and context (already extracted)]
|
||||
[Dispatch implementation subagent with full phase text + context]
|
||||
|
||||
Implementer: [No questions, proceeds]
|
||||
Implementer:
|
||||
@@ -190,7 +202,7 @@ Implementer: Extracted PROGRESS_INTERVAL constant
|
||||
[Code reviewer reviews again]
|
||||
Code reviewer: ✅ Approved
|
||||
|
||||
[Mark Task 2 complete]
|
||||
[Mark Phase 2 tasks complete]
|
||||
|
||||
...
|
||||
|
||||
@@ -205,8 +217,8 @@ Done!
|
||||
|
||||
**vs. Manual execution:**
|
||||
- Subagents follow TDD naturally
|
||||
- Fresh context per task (no confusion)
|
||||
- Parallel-safe (subagents don't interfere)
|
||||
- Fresh context per phase (less confusion)
|
||||
- Parallel-safe when phases do not share files (subagents do not interfere)
|
||||
- Subagent can ask questions (before AND during work)
|
||||
|
||||
**vs. Executing Plans:**
|
||||
@@ -228,7 +240,7 @@ Done!
|
||||
- Code quality ensures implementation is well-built
|
||||
|
||||
**Cost:**
|
||||
- More subagent invocations (implementer + 2 reviewers per task)
|
||||
- More subagent invocations than inline work (implementer + 2 reviewers per phase)
|
||||
- Controller does more prep work (extracting all tasks upfront)
|
||||
- Review loops add iterations
|
||||
- But catches issues early (cheaper than debugging later)
|
||||
@@ -236,10 +248,10 @@ Done!
|
||||
## Red Flags
|
||||
|
||||
**Never:**
|
||||
- Start implementation on main/master branch without explicit user consent
|
||||
- Skip reviews (spec compliance OR code quality)
|
||||
- Start implementation on `main` or `master`
|
||||
- Skip phase reviews (spec compliance OR code quality)
|
||||
- Proceed with unfixed issues
|
||||
- Dispatch multiple implementation subagents in parallel (conflicts)
|
||||
- Dispatch multiple implementation subagents in parallel when phases share files or state
|
||||
- Make subagent read plan file (provide full text instead)
|
||||
- Skip scene-setting context (subagent needs to understand where task fits)
|
||||
- Ignore subagent questions (answer before letting them proceed)
|
||||
@@ -247,7 +259,7 @@ Done!
|
||||
- Skip review loops (reviewer found issues = implementer fixes = review again)
|
||||
- Let implementer self-review replace actual review (both are needed)
|
||||
- **Start code quality review before spec compliance is ✅** (wrong order)
|
||||
- Move to next task while either review has open issues
|
||||
- Move to next phase while either review has open issues
|
||||
|
||||
**If subagent asks questions:**
|
||||
- Answer clearly and completely
|
||||
@@ -260,20 +272,22 @@ Done!
|
||||
- Repeat until approved
|
||||
- Don't skip the re-review
|
||||
|
||||
**If subagent fails task:**
|
||||
**If subagent fails a phase:**
|
||||
- Dispatch fix subagent with specific instructions
|
||||
- Don't try to fix manually (context pollution)
|
||||
|
||||
## Integration
|
||||
|
||||
**Required workflow skills:**
|
||||
- **superpowers:using-git-worktrees** - Ensures isolated workspace (creates one or verifies existing)
|
||||
- **superpowers:writing-plans** - Creates the plan this skill executes
|
||||
- **superpowers:requesting-code-review** - Code review template for reviewer subagents
|
||||
- **superpowers:finishing-a-development-branch** - Complete development after all tasks
|
||||
- **superpowers-lite:writing-plans** - Creates the plan this skill executes
|
||||
- **superpowers-lite:requesting-code-review** - Code review template for reviewer subagents
|
||||
- **superpowers-lite:finishing-a-development-branch** - Complete development after all tasks
|
||||
|
||||
**Optional workflow skills:**
|
||||
- **superpowers-lite:using-git-worktrees** - Use only when the user explicitly asks for an isolated workspace
|
||||
|
||||
**Subagents should use:**
|
||||
- **superpowers:test-driven-development** - Subagents follow TDD for each task
|
||||
- **superpowers-lite:test-driven-development** - Subagents follow TDD for each task
|
||||
|
||||
**Alternative workflow:**
|
||||
- **superpowers:executing-plans** - Use for parallel session instead of same-session execution
|
||||
- **superpowers-lite:executing-plans** - Use for parallel session instead of same-session execution
|
||||
|
||||
@@ -4,15 +4,15 @@ Use this template when dispatching a code quality reviewer subagent.
|
||||
|
||||
**Purpose:** Verify implementation is well-built (clean, tested, maintainable)
|
||||
|
||||
**Only dispatch after spec compliance review passes.**
|
||||
**Only dispatch after phase spec compliance review passes.**
|
||||
|
||||
```
|
||||
Task tool (general-purpose):
|
||||
Use template at requesting-code-review/code-reviewer.md
|
||||
|
||||
DESCRIPTION: [task summary, from implementer's report]
|
||||
PLAN_OR_REQUIREMENTS: Task N from [plan-file]
|
||||
BASE_SHA: [commit before task]
|
||||
DESCRIPTION: [phase summary, from implementer's report]
|
||||
PLAN_OR_REQUIREMENTS: Phase N from [plan-file]
|
||||
BASE_SHA: [commit before phase]
|
||||
HEAD_SHA: [current commit]
|
||||
```
|
||||
|
||||
|
||||
@@ -1,16 +1,16 @@
|
||||
# Implementer Subagent Prompt Template
|
||||
|
||||
Use this template when dispatching an implementer subagent.
|
||||
Use this template when dispatching an implementer subagent for one execution phase. A phase may contain one task or several related tasks from the plan.
|
||||
|
||||
```
|
||||
Task tool (general-purpose):
|
||||
description: "Implement Task N: [task name]"
|
||||
description: "Implement Phase N: [phase name]"
|
||||
prompt: |
|
||||
You are implementing Task N: [task name]
|
||||
You are implementing Phase N: [phase name]
|
||||
|
||||
## Task Description
|
||||
## Phase Description
|
||||
|
||||
[FULL TEXT of task from plan - paste it here, don't make subagent read file]
|
||||
[FULL TEXT of every task in this phase from plan - paste it here, don't make subagent read file]
|
||||
|
||||
## Context
|
||||
|
||||
@@ -29,7 +29,7 @@ Task tool (general-purpose):
|
||||
## Your Job
|
||||
|
||||
Once you're clear on requirements:
|
||||
1. Implement exactly what the task specifies
|
||||
1. Implement exactly what the phase tasks specify
|
||||
2. Write tests (following TDD if task says to)
|
||||
3. Verify implementation works
|
||||
4. Commit your work
|
||||
@@ -38,6 +38,9 @@ Task tool (general-purpose):
|
||||
|
||||
Work from: [directory]
|
||||
|
||||
Use the current branch and current working tree. Do not create a git worktree
|
||||
or switch branches unless the controller explicitly instructed you to.
|
||||
|
||||
**While you work:** If you encounter something unexpected or unclear, **ask questions**.
|
||||
It's always OK to pause and clarify. Don't guess or make assumptions.
|
||||
|
||||
@@ -60,10 +63,10 @@ Task tool (general-purpose):
|
||||
no work. You will not be penalized for escalating.
|
||||
|
||||
**STOP and escalate when:**
|
||||
- The task requires architectural decisions with multiple valid approaches
|
||||
- The phase requires architectural decisions with multiple valid approaches
|
||||
- You need to understand code beyond what was provided and can't find clarity
|
||||
- You feel uncertain about whether your approach is correct
|
||||
- The task involves restructuring existing code in ways the plan didn't anticipate
|
||||
- The phase involves restructuring existing code in ways the plan didn't anticipate
|
||||
- You've been reading file after file trying to understand the system without progress
|
||||
|
||||
**How to escalate:** Report back with status BLOCKED or NEEDS_CONTEXT. Describe
|
||||
|
||||
@@ -1,18 +1,18 @@
|
||||
# Spec Compliance Reviewer Prompt Template
|
||||
|
||||
Use this template when dispatching a spec compliance reviewer subagent.
|
||||
Use this template when dispatching a spec compliance reviewer subagent after a phase implementation.
|
||||
|
||||
**Purpose:** Verify implementer built what was requested (nothing more, nothing less)
|
||||
|
||||
```
|
||||
Task tool (general-purpose):
|
||||
description: "Review spec compliance for Task N"
|
||||
description: "Review spec compliance for Phase N"
|
||||
prompt: |
|
||||
You are reviewing whether an implementation matches its specification.
|
||||
|
||||
## What Was Requested
|
||||
|
||||
[FULL TEXT of task requirements]
|
||||
[FULL TEXT of every task requirement included in this phase]
|
||||
|
||||
## What Implementer Claims They Built
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: systematic-debugging
|
||||
description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
|
||||
description: Manual-only skill. Activate only after an explicit user request for superpowers-lite:systematic-debugging.
|
||||
---
|
||||
|
||||
# Systematic Debugging
|
||||
@@ -176,7 +176,7 @@ You MUST complete each phase before proceeding to the next.
|
||||
- Automated test if possible
|
||||
- One-off test script if no framework
|
||||
- MUST have before fixing
|
||||
- Use the `superpowers:test-driven-development` skill for writing proper failing tests
|
||||
- Use the `superpowers-lite:test-driven-development` skill for writing proper failing tests
|
||||
|
||||
2. **Implement Single Fix**
|
||||
- Address the root cause identified
|
||||
@@ -284,8 +284,8 @@ These techniques are part of systematic debugging and available in this director
|
||||
- **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
|
||||
|
||||
**Related skills:**
|
||||
- **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1)
|
||||
- **superpowers:verification-before-completion** - Verify fix worked before claiming success
|
||||
- **superpowers-lite:test-driven-development** - For creating failing test case (Phase 4, Step 1)
|
||||
- **superpowers-lite:verification-before-completion** - Verify fix worked before claiming success
|
||||
|
||||
## Real-World Impact
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: test-driven-development
|
||||
description: Use when implementing any feature or bugfix, before writing implementation code
|
||||
description: Manual-only skill. Activate only after an explicit user request for superpowers-lite:test-driven-development.
|
||||
---
|
||||
|
||||
# Test-Driven Development (TDD)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: using-git-worktrees
|
||||
description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
|
||||
description: Manual-only skill. Activate only after an explicit user request for superpowers-lite:using-git-worktrees.
|
||||
---
|
||||
|
||||
# Using Git Worktrees
|
||||
|
||||
@@ -1,26 +1,20 @@
|
||||
---
|
||||
name: using-superpowers
|
||||
description: Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions
|
||||
description: Manual-only skill. Activate only after an explicit user request for Superpowers Lite or superpowers-lite:using-superpowers.
|
||||
---
|
||||
|
||||
<SUBAGENT-STOP>
|
||||
If you were dispatched as a subagent to execute a specific task, skip this skill.
|
||||
</SUBAGENT-STOP>
|
||||
# Superpowers Lite
|
||||
|
||||
<EXTREMELY-IMPORTANT>
|
||||
If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.
|
||||
Superpowers Lite is a manual-only workflow pack. Use it only when the user explicitly asks for Superpowers Lite or names a `superpowers-lite:*` skill.
|
||||
|
||||
IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
|
||||
|
||||
This is not negotiable. This is not optional. You cannot rationalize your way out of this.
|
||||
</EXTREMELY-IMPORTANT>
|
||||
Do not auto-trigger Superpowers Lite because a task looks creative, complex, buggy, or plan-worthy. If the user asks for ordinary coding help without naming this workflow, proceed normally under the host agent's default instructions.
|
||||
|
||||
## Instruction Priority
|
||||
|
||||
Superpowers skills override default system prompt behavior, but **user instructions always take precedence**:
|
||||
Superpowers Lite skills override default system prompt behavior after explicit activation, but **user instructions always take precedence**:
|
||||
|
||||
1. **User's explicit instructions** (CLAUDE.md, GEMINI.md, AGENTS.md, direct requests) — highest priority
|
||||
2. **Superpowers skills** — override default system behavior where they conflict
|
||||
2. **Superpowers Lite skills** — apply only after explicit user activation
|
||||
3. **Default system prompt** — lowest priority
|
||||
|
||||
If CLAUDE.md, GEMINI.md, or AGENTS.md says "don't use TDD" and a skill says "always use TDD," follow the user's instructions. The user is in control.
|
||||
@@ -41,68 +35,27 @@ Skills use Claude Code tool names. Non-CC platforms: see `references/copilot-too
|
||||
|
||||
# Using Skills
|
||||
|
||||
## The Rule
|
||||
## Manual Activation Rule
|
||||
|
||||
**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it.
|
||||
Use a Superpowers Lite skill only when the user explicitly requests one of these:
|
||||
|
||||
```dot
|
||||
digraph skill_flow {
|
||||
"User message received" [shape=doublecircle];
|
||||
"About to EnterPlanMode?" [shape=doublecircle];
|
||||
"Already brainstormed?" [shape=diamond];
|
||||
"Invoke brainstorming skill" [shape=box];
|
||||
"Might any skill apply?" [shape=diamond];
|
||||
"Invoke Skill tool" [shape=box];
|
||||
"Announce: 'Using [skill] to [purpose]'" [shape=box];
|
||||
"Has checklist?" [shape=diamond];
|
||||
"Create TodoWrite todo per item" [shape=box];
|
||||
"Follow skill exactly" [shape=box];
|
||||
"Respond (including clarifications)" [shape=doublecircle];
|
||||
- "Use Superpowers Lite"
|
||||
- "Use superpowers-lite:brainstorming"
|
||||
- "Use superpowers-lite:writing-plans"
|
||||
- "Use superpowers-lite:executing-plans"
|
||||
- Another explicit `superpowers-lite:*` skill name
|
||||
|
||||
"About to EnterPlanMode?" -> "Already brainstormed?";
|
||||
"Already brainstormed?" -> "Invoke brainstorming skill" [label="no"];
|
||||
"Already brainstormed?" -> "Might any skill apply?" [label="yes"];
|
||||
"Invoke brainstorming skill" -> "Might any skill apply?";
|
||||
|
||||
"User message received" -> "Might any skill apply?";
|
||||
"Might any skill apply?" -> "Invoke Skill tool" [label="yes, even 1%"];
|
||||
"Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
|
||||
"Invoke Skill tool" -> "Announce: 'Using [skill] to [purpose]'";
|
||||
"Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
|
||||
"Has checklist?" -> "Create TodoWrite todo per item" [label="yes"];
|
||||
"Has checklist?" -> "Follow skill exactly" [label="no"];
|
||||
"Create TodoWrite todo per item" -> "Follow skill exactly";
|
||||
}
|
||||
```
|
||||
|
||||
## Red Flags
|
||||
|
||||
These thoughts mean STOP—you're rationalizing:
|
||||
|
||||
| Thought | Reality |
|
||||
|---------|---------|
|
||||
| "This is just a simple question" | Questions are tasks. Check for skills. |
|
||||
| "I need more context first" | Skill check comes BEFORE clarifying questions. |
|
||||
| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
|
||||
| "I can check git/files quickly" | Files lack conversation context. Check for skills. |
|
||||
| "Let me gather information first" | Skills tell you HOW to gather information. |
|
||||
| "This doesn't need a formal skill" | If a skill exists, use it. |
|
||||
| "I remember this skill" | Skills evolve. Read current version. |
|
||||
| "This doesn't count as a task" | Action = task. Check for skills. |
|
||||
| "The skill is overkill" | Simple things become complex. Use it. |
|
||||
| "I'll just do this one thing first" | Check BEFORE doing anything. |
|
||||
| "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
|
||||
| "I know what that means" | Knowing the concept ≠ using the skill. Invoke it. |
|
||||
If the user asks for "a plan", "debug this", "review this", or "implement this" without naming Superpowers Lite, do not treat that as activation. The fork exists to stay out of the way until called.
|
||||
|
||||
## Skill Priority
|
||||
|
||||
When multiple skills could apply, use this order:
|
||||
After explicit activation, when multiple skills could apply, use this order:
|
||||
|
||||
1. **Process skills first** (brainstorming, debugging) - these determine HOW to approach the task
|
||||
2. **Implementation skills second** (frontend-design, mcp-builder) - these guide execution
|
||||
|
||||
"Let's build X" → brainstorming first, then implementation skills.
|
||||
"Fix this bug" → debugging first, then domain-specific skills.
|
||||
After the user opts in: "Let's build X" → brainstorming first, then implementation skills.
|
||||
After the user opts in: "Fix this bug" → debugging first, then domain-specific skills.
|
||||
|
||||
## Skill Types
|
||||
|
||||
@@ -112,6 +65,10 @@ When multiple skills could apply, use this order:
|
||||
|
||||
The skill itself tells you which.
|
||||
|
||||
## Local Artifacts
|
||||
|
||||
Generated design specs and implementation plans are local working artifacts. Keep them outside git by default under `.superpowers-lite/`, and ensure that path is ignored via `.git/info/exclude` before writing files.
|
||||
|
||||
## User Instructions
|
||||
|
||||
Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.
|
||||
Instructions say WHAT, not HOW, but in this fork ordinary "Add X" or "Fix Y" requests do not activate Superpowers Lite. The user must opt in.
|
||||
|
||||
@@ -24,10 +24,10 @@ 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 (superpowers-lite:implementer)` | `@generalist` with the filled `implementer-prompt.md` template |
|
||||
| `Task tool (superpowers-lite:spec-reviewer)` | `@generalist` with the filled `spec-reviewer-prompt.md` template |
|
||||
| `Task tool (superpowers-lite:code-reviewer)` | `@code-reviewer` (bundled agent) or `@generalist` with the filled review prompt |
|
||||
| `Task tool (superpowers-lite: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 |
|
||||
|
||||
### Prompt filling
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: verification-before-completion
|
||||
description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
|
||||
description: Manual-only skill. Activate only after an explicit user request for superpowers-lite:verification-before-completion.
|
||||
---
|
||||
|
||||
# Verification Before Completion
|
||||
|
||||
@@ -1,23 +1,25 @@
|
||||
---
|
||||
name: writing-plans
|
||||
description: Use when you have a spec or requirements for a multi-step task, before touching code
|
||||
description: Manual-only skill. Activate only after an explicit user request for superpowers-lite:writing-plans.
|
||||
---
|
||||
|
||||
# Writing Plans
|
||||
|
||||
## Overview
|
||||
|
||||
Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
|
||||
Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks that can later be grouped into execution phases. DRY. YAGNI. TDD. Frequent commits.
|
||||
|
||||
Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
|
||||
|
||||
**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
|
||||
|
||||
**Context:** If working in an isolated worktree, it should have been created via the `superpowers:using-git-worktrees` skill at execution time.
|
||||
**Execution context:** Plans are executed in the current branch by default. The execution skill only requires that the current branch is not `main` or `master`. Use `superpowers-lite:using-git-worktrees` only when the user explicitly asks for an isolated workspace.
|
||||
|
||||
**Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
|
||||
**Save plans to:** `.superpowers-lite/plans/YYYY-MM-DD-<feature-name>-implementation.md`
|
||||
- (User preferences for plan location override this default)
|
||||
|
||||
**Git tracking:** Generated design and implementation plans are local artifacts, not project deliverables. Before saving a plan in a git repository, ensure `.superpowers-lite/` is listed in `.git/info/exclude`. Do not add or commit generated plans unless the user explicitly asks.
|
||||
|
||||
## Scope Check
|
||||
|
||||
If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.
|
||||
@@ -42,6 +44,8 @@ This structure informs the task decomposition. Each task should produce self-con
|
||||
- "Run the tests and make sure they pass" - step
|
||||
- "Commit" - step
|
||||
|
||||
Execution may group several tasks into one phase when the tasks share files, are tightly coupled, or are cheaper to review together. Preserve bite-sized task detail in the plan, but add phase suggestions when grouping is obvious.
|
||||
|
||||
## Plan Document Header
|
||||
|
||||
**Every plan MUST start with this header:**
|
||||
@@ -49,7 +53,7 @@ This structure informs the task decomposition. Each task should produce self-con
|
||||
```markdown
|
||||
# [Feature Name] Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers-lite:subagent-driven-development (recommended) or superpowers-lite:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking, and tasks may be grouped into phases for execution and review.
|
||||
|
||||
**Goal:** [One sentence describing what this builds]
|
||||
|
||||
@@ -57,6 +61,8 @@ This structure informs the task decomposition. Each task should produce self-con
|
||||
|
||||
**Tech Stack:** [Key technologies/libraries]
|
||||
|
||||
**Suggested Phases:** [Group related tasks for execution/review, or "One task per phase" if no grouping is useful]
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
@@ -135,18 +141,18 @@ If you find issues, fix them inline. No need to re-review — just fix and move
|
||||
|
||||
After saving the plan, offer execution choice:
|
||||
|
||||
**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Two execution options:**
|
||||
**"Plan complete and saved to `.superpowers-lite/plans/<filename>.md` as a local, untracked artifact. Two execution options:**
|
||||
|
||||
**1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration
|
||||
**1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per phase, then run one review loop for that phase
|
||||
|
||||
**2. Inline Execution** - Execute tasks in this session using executing-plans, batch execution with checkpoints
|
||||
**2. Inline Execution** - Execute tasks in this session using executing-plans, batch tasks into phases with review checkpoints
|
||||
|
||||
**Which approach?"**
|
||||
|
||||
**If Subagent-Driven chosen:**
|
||||
- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development
|
||||
- Fresh subagent per task + two-stage review
|
||||
- **REQUIRED SUB-SKILL:** Use superpowers-lite:subagent-driven-development
|
||||
- Fresh subagent per phase + two-stage review
|
||||
|
||||
**If Inline Execution chosen:**
|
||||
- **REQUIRED SUB-SKILL:** Use superpowers:executing-plans
|
||||
- **REQUIRED SUB-SKILL:** Use superpowers-lite:executing-plans
|
||||
- Batch execution with checkpoints for review
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: writing-skills
|
||||
description: Use when creating new skills, editing existing skills, or verifying skills work before deployment
|
||||
description: Manual-only skill. Activate only after an explicit user request for superpowers-lite:writing-skills.
|
||||
---
|
||||
|
||||
# Writing Skills
|
||||
@@ -15,7 +15,7 @@ You write test cases (pressure scenarios with subagents), watch them fail (basel
|
||||
|
||||
**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
|
||||
|
||||
**REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.
|
||||
**REQUIRED BACKGROUND:** You MUST understand superpowers-lite:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.
|
||||
|
||||
**Official guidance:** For Anthropic's official skill authoring best practices, see anthropic-best-practices.md. This document provides additional patterns and guidelines that complement the TDD-focused approach in this skill.
|
||||
|
||||
@@ -159,7 +159,7 @@ When the description was changed to just "Use when executing implementation plan
|
||||
|
||||
```yaml
|
||||
# ❌ BAD: Summarizes workflow - Claude may follow this instead of reading skill
|
||||
description: Use when executing plans - dispatches subagent per task with code review between tasks
|
||||
description: Manual-only skill. Activate only after an explicit user request for superpowers-lite:executing-plans.
|
||||
|
||||
# ❌ BAD: Too much process detail
|
||||
description: Use for TDD - write test first, watch it fail, write minimal code, refactor
|
||||
@@ -280,8 +280,8 @@ wc -w skills/path/SKILL.md
|
||||
**When writing documentation that references other skills:**
|
||||
|
||||
Use skill name only, with explicit requirement markers:
|
||||
- ✅ Good: `**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development`
|
||||
- ✅ Good: `**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging`
|
||||
- ✅ Good: `**REQUIRED SUB-SKILL:** Use superpowers-lite:test-driven-development`
|
||||
- ✅ Good: `**REQUIRED BACKGROUND:** You MUST understand superpowers-lite:systematic-debugging`
|
||||
- ❌ Bad: `See skills/testing/test-driven-development` (unclear if required)
|
||||
- ❌ Bad: `@skills/testing/test-driven-development/SKILL.md` (force-loads, burns context)
|
||||
|
||||
@@ -390,7 +390,7 @@ Edit skill without testing? Same violation.
|
||||
- Don't "adapt" while running tests
|
||||
- Delete means delete
|
||||
|
||||
**REQUIRED BACKGROUND:** The superpowers:test-driven-development skill explains why this matters. Same principles apply to documentation.
|
||||
**REQUIRED BACKGROUND:** The superpowers-lite:test-driven-development skill explains why this matters. Same principles apply to documentation.
|
||||
|
||||
## Testing All Skill Types
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ You run scenarios without the skill (RED - watch agent fail), write skill addres
|
||||
|
||||
**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill prevents the right failures.
|
||||
|
||||
**REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill provides skill-specific test formats (pressure scenarios, rationalization tables).
|
||||
**REQUIRED BACKGROUND:** You MUST understand superpowers-lite:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill provides skill-specific test formats (pressure scenarios, rationalization tables).
|
||||
|
||||
**Complete worked example:** See examples/CLAUDE_MD_TESTING.md for a full test campaign testing CLAUDE.md documentation variants.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user