Sdd

SDD

Announce: "Using sdd — spec lock, Composer workers, Grok spec reviews, Grok outside-voice, worktree, typecheck+tests, Bugbot."

This skill overrides conflicting defaults in subagent-driven-development, using-git-worktrees, and finishing-a-development-branch. Follow upstream SDD process; apply only the deltas below.

Orchestrator rule: One controller session runs the full pipeline. Subagents implement, review, and fix only. The controller owns spec lock, git, dispatch, ledger, outside-voice, and sdd-ship.

Skill stack (order)

0. Spec lock — below; stop for user until locked (overrides SDD "continuous execution" until confirmed)
1. writing-plans — if there is no implementation plan yet; fold output into spec lock
2. using-git-worktrees — with workspace policy below (no consent prompt)
3. subagent-driven-development — with model policy below; continuous execution resumes after spec lock. Keep the upstream final whole-branch review (requesting-code-review / code-reviewer.md). That pass gets the plan.
4. Outside-voice — extra layer after that SDD final, before sdd-ship. No plan. Neither pass substitutes for the other.
5. sdd-ship — merge main, typecheck+tests, Bugbot (+ security on risky paths), push, PR, worktree cleanup

Never invoke finishing-a-development-branch or gstack-ship at the end of an SDD run.

Spec lock (before the loop)

Purpose: Turn a vague ask or draft plan into a locked spec the implementers will follow. Do not create a worktree or dispatch Task 1 until the user confirms.

When to skip

Skip only if all are true:

• .superpowers/sdd/spec-lock.md exists with Status: locked and today's intent matches
• Plan file path in spec lock matches the plan you will execute
• User said go, locked, execute the plan, or attached the plan with no new constraints

If resuming from progress ledger mid-run, skip spec lock but not worktree/tasks.

Phase A — Understand (controller reads, no subagents)

1. Read the user message, any attached plan (docs/superpowers/plans/…), and linked specs.
2. Light codebase read only — enough to ask informed questions (entrypoints, existing behavior, tests). No implementation.
3. Note ambiguities: scope boundaries, edge cases, platforms, copy rules, what is explicitly out of scope.

Phase B — Clarify (batched, not one-by-one)

If anything material is unclear, stop and ask in one batched message (use AskQuestion when available). Good clusters:

• Scope: what's in / out for this run
• Behavior: user-visible outcomes and edge cases
• Constraints: copy rules, paths, flags, "do not touch X"
• Success: how we know it's done (tests, manual checks)
• Plan: use existing plan vs write one; branch name preference

Do not start the implementation loop to "discover" product answers. Do not ask "should I continue?" — ask specific questions whose answers change the spec.

If the request is already precise and the plan has Global Constraints + tasks, summarize assumptions instead of interrogating.

Phase C — Write spec lock artifact

Run SDD scripts/sdd-workspace from repo root; write:

.superpowers/sdd/spec-lock.md

# Spec lock

Status: pending | locked
Date: YYYY-MM-DD
Plan: docs/superpowers/plans/….md (or "none — inline spec")

## Goal
(one sentence)

## In scope
- …

## Out of scope
- …

## Global constraints
(copy verbatim from plan/spec)

## Locked decisions
- Q: … → A: … (from user)

## Success criteria
- [ ] …

## Branch
feat/… (proposed)

## Open questions
(none when locked)

Set Status: pending until user confirms.

Phase D — Confirm (hard gate)

Present a short summary + link to spec-lock.md. Ask once:

Spec locked as above. Reply go to start the worktree and Task 1, or correct anything first.

Wait for user reply. Accept: go, locked, yes, ship it (meaning start build), or corrections. Apply corrections to spec-lock, then ask again.

On go: set Status: locked in spec-lock.md, then proceed to worktree + SDD.

Copy the Global constraints block into every implementer, per-task Grok, and SDD final (code-reviewer.md) dispatch verbatim.

Do not paste the plan, spec-lock, global constraints, task briefs, or implementer reports into the outside-voice dispatch. That pass is unbiased on purpose.

No plan yet

If there is no plan file:

1. Complete Phase B clarifications first.
2. Run writing-plans; save under docs/superpowers/plans/.
3. Complete spec lock (Phases C–D) referencing that plan.
4. User go → worktree → SDD Task 1.

Do not commit the plan file unless the user asks — untracked or user commits is fine.

Overrides SDD pre-flight

After spec lock, still run SDD Pre-Flight Plan Review for internal plan contradictions. If it finds conflicts with the locked spec, present one batched question (plan text vs lock) before Task 1 — do not silently pick a side.

Model policy

Overrides SDD "Model Selection" (cost tiers). Always set model explicitly on every Task dispatch.

Exact slugs only. Copy the model string verbatim into every Task model field.

Forbidden for workers: composer-2.5-fast, any Composer fast tier.

Forbidden for reviewers: composer-2.5, composer-2.5-fast, cursor-grok-4.5-high, any Grok slug without xhigh, any model with fast in the name. Reviews must use cursor-grok-4.6-xhigh only.

Workspace policy

Overrides using-git-worktrees consent step — preference is declared here.

1. Step 0: If already in a linked worktree (GIT_DIR != GIT_COMMON, not a submodule), use it. Do not nest worktrees.
2. Otherwise: Create .worktrees/<branch-name> from updated main (or repo default base branch).
3. Never implement on main/master without explicit user consent.
4. Verify .worktrees is gitignored (git check-ignore -q .worktrees); add to .gitignore and commit if missing.
5. Run project setup + verification ladder in the worktree before Task 1 (see below).
6. All SDD artifacts (briefs, reports, ledger) live in the worktree via scripts/sdd-workspace from the SDD skill directory.

Record worktree path and branch name in the progress ledger at start.

Verification ladder (local CI)

GitHub Actions may be unavailable (quota). Local checks are the ship gate:

Stop on typecheck or test failure. Do not treat "tests passed, types broken" as green.

Every implementer and fix dispatch must run this ladder and put command + result in the report file. Name the covering tests; still run typecheck when the script exists.

SDD execution

Follow subagent-driven-development exactly for:

• Pre-flight plan review
• Task briefs (scripts/task-brief)
• Implementer report files
• Review packages (scripts/review-package)
• Progress ledger (.superpowers/sdd/progress.md)
• Per-task review loops until spec ✅ and quality approved
• Final whole-branch review (requesting-code-review / code-reviewer.md) — keep this. It is the plan-fed SDD layer.

Apply model policy on every dispatch. Do not paste session history into implementer prompts.

Do not skip code-reviewer.md because outside-voice exists. Do not skip outside-voice because code-reviewer.md already ran.

Integrate main during the loop, not only at ship: after each completed task, git fetch origin for the base branch. If origin/<base> is not an ancestor of HEAD, merge it (--no-edit), re-run the verification ladder, then dispatch the next task. Skip the merge when already up to date.

After SDD final is clean (no open Critical/Important), run Outside-voice below. Then sdd-ship.

Controller: after outside-voice returns, triage the per-task Minor ledger yourself (do not show it to outside-voice). Promote a ledger Minor to Important only if it is user-facing (wrong copy, stuck billing, data loss). Do not silently discard the ledger.

Outside-voice (extra layer)

Gate before sdd-ship. Re-run only after a fix wave. A second reviewer that never saw the spec. It does not replace SDD final.

Dispatch: subagent_type: generalPurpose, model: cursor-grok-4.6-xhigh, description: "Outside-voice review", run_in_background: false. Working directory is the feature worktree. Do not start sdd-ship until this subagent returns.

Inputs (only these):

• Absolute worktree path and branch name
• Base SHA (git merge-base origin/<base> HEAD) and HEAD SHA
• Absolute path to the SDD review package (scripts/review-package MERGE_BASE HEAD). That file is commit list + stat + full diff. Tell the reviewer to ignore commit subjects as requirements.

Forbidden in the prompt: plan path, spec-lock.md, global constraints, task briefs, implementer reports, Minor ledger, "the user wanted X", "treat as Minor", "do not flag".

Disk deny-list (put in the prompt): do not Read, Grep, or Glob docs/superpowers/plans/**, .superpowers/sdd/spec-lock.md, .superpowers/sdd/progress.md, **/task-*-brief.md, **/task-*-report.md. If one of those is opened, stop reading it and ignore its contents.

Read-only: do not mutate the working tree, index, HEAD, or branch. No extra worktrees. Use Read, git show, git diff, git log only. Do not run the full test suite.

Correctness oracle: grade against (a) existing surrounding product behavior on the call path and (b) tests in the diff. Do not invent "the feature should also…". Open a file not in the diff only when a named risk requires it and a changed function actually calls it, or the review package already lists that path.

Prompt body (use verbatim after the inputs and deny-list):

You are an outside-voice reviewer. You have not seen the implementation plan and you must not infer one. Read the review package once, then trace how this change fails for a real user of this repo.

Look for: realistic user inputs that flip the wrong branch; sticky billing/checkout/session state; scheduled jobs suppressed too broadly or forever; a sibling handler already on the call path that this diff makes wrong; auth or permission checks bypassed on crafted requests; silent wrong behavior, not style.

Output:

Critical (must fix)

Important (should fix)

Minor (do not block ship)

Assessment: Ready for sdd-ship? Yes | No

File:line, what happens to the user, how to fix. No compliments section.

After it returns:

• Ship iff no Critical and no Important. Ignore Assessment when it contradicts those buckets. Minors cannot yield a block. "With fixes" is not a verdict.
• Critical / Important → one Composer 2.5 fixer (run_in_background: false) with: worktree path, findings list, global constraints only (not plan/tasks), covering tests, verification ladder, intent-prefixed fix: commit. Then re-run this same outside-voice pass.
• Max 2 extra outside-voice rounds after the first. If Critical/Important remain, stop. List findings. Do not invoke sdd-ship.
• Minor → ledger only.

Finish (no menu)

When SDD final and outside-voice are both clean (no open Critical/Important):

1. Do not present finishing-a-development-branch options.
2. Invoke sdd-ship immediately and run it to completion.
3. Always report the PR URL. Report worktree removed or kept with the reason from sdd-ship (Actions failure).

Do not ship with open Critical/Important from SDD final or outside-voice.

Red flags

Never:

• Skip worktree for "small" changes
• Use Composer for review or Grok for implementation
• Use fast-tier models (composer-2.5-fast, Grok without xhigh, or any *fast* slug) for workers or reviewers
• Skip SDD code-reviewer.md final because outside-voice exists, or skip outside-voice because code-reviewer.md already ran
• Give the plan, spec-lock, briefs, or reports to the outside-voice reviewer (prompt or disk)
• Keep the worktree after a green ship (sdd-ship removes it). Exception: keep it if GitHub Actions actually failed (not quota)
• Call gstack-ship as SDD finish (use only for standalone versioned releases)
• Start worktree or Task 1 before spec lock go (unless resuming from ledger)
• Skip typecheck when package.json has a typecheck script
• Skip Bugbot or push with open Bugbot findings (unless user explicitly says ship anyway)
• Skip security-review on diffs that touch auth, billing, SMS, crypto, SQL, or new HTTP surface
• Omit model on Task dispatches (inherits session model = wrong cost/behavior)
• Wait on GitHub Actions as a hard ship gate (quota may be exhausted; local ladder is the gate)
• Add gstack local adversarial review army, VERSION, CHANGELOG, or draft-PR-at-task-1

Always:

• Spec lock + user go before worktree and Task 1 (unless skip conditions met)
• Pass locked Global constraints to implementers, per-task Grok, and SDD final; never to outside-voice
• Resume from progress ledger after compaction
• Run the verification ladder (typecheck then tests) before Task 1, after each task merge, and in sdd-ship
• Merge origin/<base> when it has moved, both mid-loop and in sdd-ship
• Run SDD final, then outside-voice, then sdd-ship (Bugbot; security if risky)
• Push branch and open/update PR only after local review gates are clean
• Remove worktree after a green ship, unless Actions failed for a real reason