# Sdd

> SDD preset for Cursor: spec lock with user Q&A before the loop, Composer 2.5 (not fast) implementers, Grok 4.6 xhigh spec reviewers plus an extra no-plan outside-voice Grok pass, always git worktree in .worktrees/, local typecheck+tests as CI, Bugbot plus path-scoped security, auto ship via sdd-ship. Use with subagent-driven-development when executing plans, /sdd, or whenever the user wants the SDD workflow.

- Skill: `0nate4/sdd` (Agent Skill)
- Install (CLI): `npx skillmds@latest add 0nate4/sdd`
- Raw SKILL.md: https://api.skillmd.com/api/skills/0nate4/sdd/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: 0NATE4 (https://skillmd.com/u/0nate4)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/0nate4/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`**

```markdown
# 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.

| Role | Model | Notes |
|------|-------|-------|
| Implementer subagent (per task) | `composer-2.5` | Every task, including multi-file integration |
| Fix subagent (review loops) | `composer-2.5` | Same as implementer |
| Task reviewer (spec + quality) | `cursor-grok-4.6-xhigh` | Per-task. **Gets the plan.** |
| SDD final whole-branch | `cursor-grok-4.6-xhigh` | `code-reviewer.md`. **Gets the plan.** |
| Outside-voice (extra layer) | `cursor-grok-4.6-xhigh` | After SDD final. **No plan.** |
| Controller (orchestrator) | Session default | Do not downgrade |

**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:

| Repo signal | Command |
|-------------|---------|
| `package.json` has `"typecheck"` | `npm run typecheck` **first** |
| `package.json` + vitest | `npx vitest run --exclude '**/.worktrees/**'` |
| `package.json` + `"test"` (node) | `npm test` |
| `Cargo.toml` | `cargo test` |
| `go.mod` | `go test ./...` |

**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