mirror of https://github.com/obra/superpowers.git synced 2026-06-11 21:29:07 +08:00

Files

Drew Ritter e5f337b89e fix(skills): plans reference the spec instead of restating it — end to end (SUP-333 A)

Consolidates the reference-discipline change with every consumer of it,
so this PR is independently mergeable (previously split across two
stacked PRs whose intermediate state left the SDD spec reviewer blind).

writing-plans: plans reference the spec — never restate, paraphrase,
or summarize it; spec owns WHAT/WHY, plan owns HOW; cite by path in
the header (**Spec:** template line) and by section where a task needs
context; No Placeholders repetition stays intra-plan; no-spec branch
scoped to conversational-requirements-only (eval-caught: an agent used
an unscoped no-spec branch to skip writing the spec entirely).

brainstorming: spec path loophole closed (claude shortened
docs/superpowers/specs/ to docs/specs/, documented run); an existing
differently-named docs dir is not a "user preference".

subagent-driven-development: Spec Context section — the controller
reads the plan-cited spec and pastes cited sections into implementer
and spec-reviewer prompts; the spec reviewer's diff-only rule gets a
spec-document exception. Without this, reference discipline starves
the pipeline of requirements.

executing-plans: Step 1 reads the spec the plan cites (the
non-subagent path; plans are no longer self-contained).

Eval evidence (quorum, full-stack text): cost-spec-plan-duplication
claude 3/3 pass (RED: 5/5 agents failed), codex pass, pi pass (the
683-line duplication RED agent); sdd-spec-context-consumed functional
pass with deterministic dispatch-prompt check;
writing-plans-no-spec-conversational 2/2 pass;
triggering-writing-plans canary 3/3.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-06-11 00:20:49 -07:00

2.6 KiB

Raw Blame History

name, description

name	description
executing-plans	Use when you have a written implementation plan to execute in a separate session with review checkpoints

Executing Plans

Overview

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 (Claude Code, Codex CLI, Codex App, Copilot CLI, and Gemini CLI all qualify; see the per-platform tool refs in ../using-superpowers/references/). If subagents are available, use superpowers:subagent-driven-development instead of this skill.

The Process

Step 1: Load and Review Plan

Read plan file, and the spec it cites in its **Spec:** header (plans reference requirements rather than restating them)
Review critically - identify any questions or concerns about the plan
If concerns: Raise them with your human partner before starting
If no concerns: Create todos for the plan items and proceed

Step 2: Execute Tasks

For each task:

Mark as in_progress
Follow each step exactly (plan has bite-sized steps)
Run verifications as specified
Mark as completed

Step 3: 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
Follow that skill to verify tests, present options, execute choice

When to Stop and Ask for Help

STOP executing immediately when:

Hit a blocker (missing dependency, test fails, instruction unclear)
Plan has critical gaps preventing starting
You don't understand an instruction
Verification fails repeatedly

Ask for clarification rather than guessing.

When to Revisit Earlier Steps

Return to Review (Step 1) when:

Partner updates the plan based on your feedback
Fundamental approach needs rethinking

Don't force through blockers - stop and ask.

Remember

Review plan critically first
Follow plan steps exactly
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

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

2.6 KiB Raw Blame History