<SUBAGENT-STOP> If you were dispatched as a subagent to execute a specific task, skip this skill. </SUBAGENT-STOP>

<CRITICAL-OVERRIDE> Two superpowers skills have defaults that conflict with sdd-workflow. Both are OVERRIDDEN:

1. Brainstorming says its terminal state is writing-plans.

   • OVERRIDDEN: After brainstorming → invoke /opsx:propose "<name>", NOT writing-plans.
   • The pipeline is: brainstorming → /opsx:propose → review → /opsx:verify → writing-plans.

2. Writing-plans says its output path is docs/superpowers/plans/YYYY-MM-DD-<name>.md.

   • OVERRIDDEN: Output MUST go to openspec/changes/<name>/plan.md.
   • docs/superpowers/plans/ is a legacy path — do NOT use it.

If you invoke writing-plans immediately after brainstorming, you skip Steps 2-4 (the entire OpenSpec specification phase). If you write plan.md to docs/superpowers/plans/, it lives outside the OpenSpec traceability system. </CRITICAL-OVERRIDE>

<EXTREMELY-IMPORTANT> Spec-driven development means specs live in the file system, not in chat history. OpenSpec manages specification artifacts. Superpowers enforces execution discipline. This skill routes between them.

IF A SPEC EXISTS, YOU MUST READ IT BEFORE WRITING CODE. IF NO SPEC EXISTS FOR BEHAVIOR CHANGE, YOU MUST CREATE ONE FIRST.

This is not negotiable. This is not optional. You cannot rationalize your way out of this. </EXTREMELY-IMPORTANT>

Instruction Priority

1. User's explicit instructions (CLAUDE.md, AGENTS.md, direct requests) — highest priority
2. OpenSpec artifacts (proposal.md, specs/, design.md, tasks.md) — the authoritative spec baseline
3. SDD workflow skills — route and enforce process
4. Default system prompt — lowest priority

If the user says "skip the spec, just write code," follow the user's instructions. The user is in control.

SDD Workflow — Spec-Driven Development Router

The Rule

Before any code, human and AI agree on what to build. Specifications are files in openspec/. Every behavior change is traceable from proposal through archive. Run openspec init if openspec/ doesn't exist.

Announce at start: "I'm using the sdd-workflow skill to route this development task."

The 10-Step Pipeline

OpenSpec provides the specification skeleton (what). Superpowers enforces execution discipline (how). They connect in sequence with no overlap:

0. [Optional] superpowers:brainstorming  — Exploratory design for greenfield/fuzzy requirements.
                                           Output: design doc → feeds into Step 2.
                                           ⛔ After approval → go to Step 2, NOT writing-plans.

1. [User request]
     ↓
2. /opsx:propose <name>            — OpenSpec: Create proposal. Generate all 4 artifacts.
     ↓                               proposal.md + specs/ + design.md + tasks.md
3. [Manual review + iterate]       — OpenSpec: Refine specs. Review and revise each artifact.
     ↓                               Optional: /opsx:continue (step-by-step), /opsx:ff (fast-forward).
4. /opsx:verify                    — OpenSpec: Verify specs. 3-dimension validation gate.
     ↓
5. superpowers:writing-plans       — Superpowers: Generate implementation plan.
     ↓                               Output: openspec/changes/<name>/plan.md
6. /opsx:apply +                   — Superpowers: TDD execution. apply = scheduler, TDD = executor.
   @test-driven-development          RED → GREEN → REFACTOR per task.
     ↓
7. @requesting-code-review         — Superpowers: Code review.
     ↓
8. @verification-before-           — Superpowers: Pre-completion verification. Fresh test evidence.
   completion
     ↓
9. /opsx:archive <name>            — OpenSpec: Archive change. Delta merge + move to archive/.
     ↓
10. [Delivered]                    — Ship it.

Artifact Ownership

OpenSpec and Superpowers each produce plan-like files — they serve different roles and both belong in openspec/changes/<name>/:

Artifact	Owner	Granularity	Purpose	Example
tasks.md	OpenSpec (/opsx:propose)	Coarse checkbox items	WHAT to implement	- [ ] Implement Store interface
plan.md	Superpowers (writing-plans)	2-5min subtasks	HOW to implement	1. Define Store interface in store/store.go (2 min)

Rule: plan.md refines tasks.md — it does NOT replace it. Both coexist in the same change directory. writing-plans reads tasks.md as input and outputs plan.md with detailed steps, file paths, and test names.

openspec/changes/<name>/
├── proposal.md    ← OpenSpec: why + scope boundary
├── specs/         ← OpenSpec: behavior delta specs
├── design.md      ← OpenSpec: technical decisions
├── tasks.md       ← OpenSpec: coarse implementation checklist (WHAT)
└── plan.md        ← Superpowers: refined subtasks (HOW)

docs/superpowers/specs/ and docs/superpowers/plans/ are legacy brainstorming output paths — they are NOT used by this workflow. All artifacts live under openspec/changes/<name>/.

OpenSpec Command Reference

Command	Description	When to use
/opsx:propose	Generate complete change artifacts in one step	Requirements are clear
/opsx:explore	Investigate without creating files	Fuzzy requirements, tech evaluation, approach comparison
/opsx:apply	Implement tasks from tasks.md item by item	Implementation phase
/opsx:archive	Archive and merge specs	Feature complete
/opsx:new	Create change skeleton only	Want fine-grained control over artifact creation
/opsx:continue	Generate the next artifact	Step-by-step review, confirm each artifact
/opsx:ff	Fast-forward: generate all remaining artifacts	Direction confirmed, accelerate
/opsx:verify	3-dimension validation of implementation	Pre-archive quality check
/opsx:sync	Sync specs without archiving	Parallel changes need reference
/opsx:bulk-archive	Batch archive multiple changes	Multi-feature unified wrap-up

Request Classification

When the user brings a development request, classify FIRST. Then route.

Boundedness Check — BEFORE routing to Step 2

A task is NOT "clearly bounded" (and therefore MUST route through Step 0: exploration or brainstorming) if ANY of these are true:

Signal	Example	Route to
Introduces concepts NOT in the current data model	"add users", "add sharing", "add permissions" — and the codebase has no User/Share/Permission struct	superpowers:brainstorming
Has multiple valid interpretations with different architectures	"add collaboration" could mean real-time sync, async assignment, or shared views	superpowers:brainstorming
Uses hedging or vague language	"somehow", "或者", "something like", "加点协作能力"	superpowers:brainstorming
Requires comparing 2+ approaches with significant trade-offs	"should we use WebSocket or polling?"	superpowers:brainstorming
You don't know which files would change without reading code first	Unfamiliar codebase or new feature area	/opsx:explore → then re-run Boundedness Check → if still fuzzy → superpowers:brainstorming

A task IS "clearly bounded" (can skip to Step 2) ONLY when ALL of these are true:

• The data model is already defined (structs/tables exist)
• There is exactly one obvious implementation approach
• The request uses specific, concrete language ("add a DELETE endpoint", "add a due_date field to Task")
• You can list the files that will change without reading any code

Signal priority: Brainstorming signals beat exploration signals. When a task matches BOTH a brainstorming signal AND the exploration signal, the flow is: /opsx:explore (read code, build context) → re-run Boundedness Check → superpowers:brainstorming (generate and compare approaches). Never skip the brainstorming step when ANY brainstorming signal is triggered.

Default rule: if you're not sure, it's not clearly bounded. Route to exploration or brainstorming.

CRITICAL: After /opsx:explore — Do NOT present options

/opsx:explore builds context. It does NOT authorize you to decide what to implement. After it completes:

• Do NOT present a numbered list of features and ask the user to pick
• Do NOT ask "你希望补充哪些功能？" or "Which features do you want?"
• Do NOT merge exploration + decision into one step

You MUST instead:

1. Re-run the Boundedness Check against the task
2. If ANY "not bounded" signal still applies → invoke superpowers:brainstorming to generate and compare approaches
3. Only skip brainstorming if the exploration revealed exactly ONE obvious gap (e.g., "this CRUD API is missing a DELETE handler")

Wrong: Explore → "Here are 4 options, pick one" → implement Right: Explore → Boundedness Check → Brainstorming → /opsx:propose → review → implement

digraph sdd_routing {
    "User request received" [shape=doublecircle];
    "Is it a one-line fix?\n(typo, log line, comment)" [shape=diamond];
    "Make change,\nverify directly" [shape=box style=filled fillcolor="#ccffcc"];
    "Is it a bug with\nunclear cause?" [shape=diamond];
    "superpowers:systematic-debugging\n(root cause first)" [shape=box style=filled fillcolor="#ffcccc"];
    "Are there OpenSpec\nartifacts already?" [shape=diamond];
    "Read existing artifacts,\npick up where left off" [shape=box style=filled fillcolor="#ccccff"];
    "Run Boundedness Check.\nIs it clearly bounded?" [shape=diamond];
    "Unfamiliar codebase\nor uncertain approach?" [shape=diamond];
    "/opsx:propose\n(generate 4 artifacts)" [shape=box style=filled fillcolor="#ffffcc"];
    "/opsx:explore\n(build context first)" [shape=box style=filled fillcolor="#ffffcc"];
    "superpowers:brainstorming\n(Socratic design)" [shape=box style=filled fillcolor="#ffffcc"];
    "Route to 10-Step\nPipeline Step 2" [shape=doublecircle];

    "User request received" -> "Is it a one-line fix?\n(typo, log line, comment)";
    "Is it a one-line fix?\n(typo, log line, comment)" -> "Make change,\nverify directly" [label="yes"];
    "Is it a one-line fix?\n(typo, log line, comment)" -> "Is it a bug with\nunclear cause?" [label="no"];
    "Is it a bug with\nunclear cause?" -> "superpowers:systematic-debugging\n(root cause first)" [label="yes"];
    "Is it a bug with\nunclear cause?" -> "Are there OpenSpec\nartifacts already?" [label="no"];
    "Are there OpenSpec\nartifacts already?" -> "Read existing artifacts,\npick up where left off" [label="yes"];
    "Are there OpenSpec\nartifacts already?" -> "Run Boundedness Check.\nIs it clearly bounded?" [label="no"];
    "Run Boundedness Check.\nIs it clearly bounded?" -> "Unfamiliar codebase\nor uncertain approach?" [label="no — see\nBoundedness Check"];
    "Run Boundedness Check.\nIs it clearly bounded?" -> "Route to 10-Step\nPipeline Step 2" [label="yes — meets ALL\nclear-boundary criteria"];
    "Unfamiliar codebase\nor uncertain approach?" -> "/opsx:explore\n(build context first)" [label="need to read\ncode first"];
    "Unfamiliar codebase\nor uncertain approach?" -> "superpowers:brainstorming\n(Socratic design)" [label="greenfield\nor approach\ncomparison"];
    "/opsx:explore\n(build context first)" -> "Run Boundedness Check.\nIs it clearly bounded?";
    "superpowers:brainstorming\n(Socratic design)" -> "Run Boundedness Check.\nIs it clearly bounded?";
}

Phase Detection

Check the file system to determine where you are in the workflow:

What exists	Phase	Next action
No openspec/ directory	Uninitialized	Run openspec init first
openspec/ exists, no change dir	Ready for proposal	Route to Step 2: /opsx:propose <name> or Step 0: exploration
openspec/changes/<name>/ with 4 artifacts, unreviewed	Specs need review	Steps 3-4: Manual review → /opsx:verify
openspec/changes/<name>/ with reviewed artifacts	Ready for execution	Step 5: superpowers:writing-plans
tasks.md has unchecked items	In progress	Step 6: /opsx:apply + @test-driven-development
All tasks checked, not archived	Ready for delivery	Steps 7-8: review → verify → Step 9: /opsx:archive

Transition Rules

Step 0: Explore → Brainstorming Gate

When the Boundedness Check routes to /opsx:explore (because you don't know which files would change), /opsx:explore is read-only reconnaissance — it builds context, NOT decisions. After it completes:

1. Re-run the Boundedness Check. The task is still "not clearly bounded" unless the codebase exploration revealed a single obvious gap.
2. If ANY "not bounded" signal still applies → route to superpowers:brainstorming. Do NOT present options to the user. Do NOT ask the user what to implement. Brainstorming is where options are generated and compared.
3. If the task is now clearly bounded (rare after a fuzzy request) → proceed to Step 2: /opsx:propose.

Why: /opsx:explore answers "what exists." superpowers:brainstorming answers "what should we build." Mixing them (explore → offer choices → implement) skips design entirely. The DOT graph shows the loop: explore → Boundedness Check — this must execute, not be skipped.

Step 0 → Step 2: The Critical Handoff

Brainstorming (Step 0) is optional. When requirements are already clear, skip to Step 2.

The brainstorming skill says its terminal state is writing-plans. THIS IS OVERRIDDEN. When brainstorming is invoked through sdd-workflow, the pipeline is: brainstorming → /opsx:propose → review → /opsx:verify → writing-plans.

When brainstorming completes and the user approves the design:

1. DO NOT invoke writing-plans — this bypasses OpenSpec Steps 2-4
2. DO NOT write code — the spec isn't locked yet
3. DO invoke /opsx:propose "<name>" — feed the approved brainstorming design as context
4. DO verify openspec/changes/<name>/ contains: proposal.md, specs/, design.md, tasks.md
5. Only then proceed to Step 3.

Why: Brainstorming produces an exploratory design (Phase 1 — Superpowers). OpenSpec locks it into auditable, mergeable artifacts (Phase 2 — OpenSpec). docs/superpowers/specs/ is transient; openspec/changes/<name>/ is permanent and traceable. Skipping Step 2 means specs can't be verified, archived, or traced.

Steps 2-10: Linear Execution

Step 2: /opsx:propose <name>     → If Step 0 was done, feed its output as context.
                                    Confirm artifacts before Step 3.

Step 3: Manual review + iterate   → Review proposal/specs/design/tasks item by item.
                                    Optional: /opsx:continue (step) | /opsx:ff (fast-forward).
                                    Standard: every in-scope item has a task checkbox.

Step 4: /opsx:verify              → 3-dimension validation (complete/correct/consistent).
                                    Pass before entering execution phase.

Step 5: superpowers:writing-plans → MUST save to openspec/changes/<name>/plan.md
                                    (NOT docs/superpowers/plans/).
                                    Output: 2-5 minute granular subtasks.

Step 6: /opsx:apply +             → apply = scheduler, TDD = executor.
  @test-driven-development          RED → GREEN → REFACTOR per task.
                                    On error: @systematic-debugging → return to apply.
                                    All tasks complete → Step 7.

Step 7: @requesting-code-review   → Dispatch code-reviewer. Fix Critical/Important issues.

Step 8: @verification-before-     → Fresh go test ./... / pytest / etc.
  completion                        Evidence required BEFORE claiming completion.

Step 9: /opsx:archive <name>      → Delta merge into openspec/specs/.
                                    Change moved to openspec/changes/archive/.
                                    project.md updated.

Step 10: Done                     → Ship it.

Tool Selection Matrix

When both OpenSpec and Superpowers offer a tool for the same phase:

Scenario	Use This	Not That	Why
Reading existing code	/opsx:explore	@brainstorming	Explore reads code; brainstorming generates ideas
Defining new feature	@brainstorming	/opsx:explore	Brainstorming compares approaches
Generating spec artifacts	/opsx:propose	@writing-plans	Propose creates 4 artifacts; writing-plans refines
Refining task granularity	@writing-plans	Manual only	Writing-plans converts to 2-5min units
Executing tasks	/opsx:apply + @test-driven-development	Either alone	Apply schedules; TDD executes
Debugging failures	@systematic-debugging	Direct fixes	Root cause investigation first
Code review	@requesting-code-review + @receiving-code-review	"Looks good to me"	Structured independent review
Claiming completion	@verification-before-completion	"Should work now"	Fresh evidence required
Archiving work	/opsx:archive	Manual file moves	Archive does delta merge + timestamp

Red Flags

These thoughts mean STOP — you're rationalizing skipping the SDD process:

Thought	Reality
"This is simple, I don't need a spec"	Simple changes cause complex bugs. A 5-line proposal.md saves hours.
"I'll write the spec after the code"	Specs-after describe what you built, not what's needed.
"The spec is in the conversation history"	Conversation history evaporates. Files persist. Write it down.
"I already know what to build"	Knowing ≠ having it reviewed. Specs are the agreement.
"Specs slow me down"	Rework from misaligned expectations is slower.
"This is just a prototype"	Prototypes become production. Spec now saves pain later.
"I'll just explore the codebase first"	Use /opsx:explore — structured, not aimless browsing.
"I remember how this codebase works"	Code evolves. Your memory is stale. Read the specs.
"This task is clearly bounded, skip brainstorming"	⛔ STOP. Run the Boundedness Check. Does the task introduce concepts NOT in the current data model? Does it have multiple valid interpretations? If yes → brainstorming. "Add collaboration" on a single-user app is NOT clearly bounded.
"I already explored the codebase, I can just list options"	⛔ STOP. /opsx:explore answers "what exists," not "what to build." After explore, re-run Boundedness Check. If the task is still fuzzy → superpowers:brainstorming. Presenting a menu of options is NOT a substitute for Socratic design.
"The user said '完善' or 'improve' — that's clear enough"	Vague verbs imply the user trusts you to figure out WHAT to improve. That's exactly what brainstorming is for. Explore the codebase → brainstorm what should change → THEN propose.
"Brainstorming says go to writing-plans"	⛔ OVERRIDDEN. sdd-workflow pipeline: brainstorming → /opsx:propose → review → verify → THEN writing-plans.
"I'll write the design doc — that's the spec"	docs/superpowers/specs/ is transient. /opsx:propose creates permanent openspec/changes/<name>/ artifacts.
"The brainstorming design IS the OpenSpec design"	No. Brainstorming output is INPUT to /opsx:propose. It must be translated into the 4 OpenSpec artifacts.

All of these mean: follow the SDD process. No shortcuts.

Skill Priority

When multiple tools could apply to a development task:

1. Classification first — Use the decision tree. One-line fix? Bug? Behavior change?
2. Exploration before specification — /opsx:explore to read code. /opsx:propose to generate artifacts. Never invert.
3. Review before execution — Steps 3-4 gate. Specs must be reviewed before any code.
4. Plan before implementing — Step 5: writing-plans refines tasks.md. Save to openspec/changes/<name>/plan.md.
5. TDD during execution — Step 6: /opsx:apply + @test-driven-development. RED → GREEN → REFACTOR.
6. Verify before claiming — Step 8: @verification-before-completion with fresh evidence. Then Step 9: /opsx:archive.

Skill Types

Rigid — Follow exactly. Don't adapt away the sequence:

• /opsx:propose, /opsx:apply, /opsx:archive — CLI tools with defined behavior
• @test-driven-development — RED → GREEN → REFACTOR, no shortcuts
• @systematic-debugging — Root cause before fixes
• @verification-before-completion — Fresh evidence required
• sdd-workflow (this skill) — Follow the routing exactly

Flexible — Adapt principles to context:

• @brainstorming — Socratic design, adapt depth to complexity (but terminal routing is OVERRIDDEN by sdd-workflow)
• @writing-plans — Task granularity scales with feature complexity
• /opsx:explore — Depth of exploration matches uncertainty level

Related Skills

• sdd-review-specs — Structured review of OpenSpec 4 artifacts before implementation
• superpowers:brainstorming — Socratic design for greenfield features
• superpowers:writing-plans — Convert coarse tasks to 2-5min bite-sized units
• superpowers:test-driven-development — RED-GREEN-REFACTOR cycle
• superpowers:systematic-debugging — Root cause investigation before fixes
• superpowers:verification-before-completion — Evidence before completion claims
• superpowers:requesting-code-review — Structured code review
• superpowers:finishing-a-development-branch — Merge/PR/keep/discard decisions

User Instructions

Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows. The SDD process is the HOW — it exists to ensure alignment before code, not to slow you down.

If you want to bypass a step (skip review, write code directly, skip the spec), say so explicitly. The user is in control. The skill routes, the user decides.