SDD Workflow Guide

SDD (spec-driven development) is one chain that takes a rough idea to a merged PR. It joins two systems that already existed in this repo but did not talk to each other: OpenSpec (OPSX), which produces the written spec and task list, and Superpowers, which does the actual implementation work. The rule is simple:

OpenSpec owns what to build. Superpowers owns how it gets built.

The workflow covers four independent OpenSpec roots:

Area	OpenSpec root	Default schema
Go backend	`backend/go`	`spec-driven-superpowers`
Bun backend	`backend/bun`	`spec-driven-superpowers`
Astro frontend	`frontend/astro`	`spec-driven-superpowers-fe`
SolidStart frontend	`frontend/solidstart`	`spec-driven-superpowers-fe`

Mobile roots are outside this workflow.

Why This Exists

Before this, both systems were installed and both wanted to be in charge. That caused three concrete problems. Two plans competed. /opsx:propose writes tasks.md. superpowers:writing-plans writes its own plan file. Nothing said which one was authoritative, so an agent could implement from one while the other quietly went stale — and reviewers would read the stale one. Agents had to guess which code review to run. Saying “review this” could mean any of five things: code-review-to-github, code-review-workflow:respond, review-fix-loop, pr-workflow, or the built-in /code-review. Two of those are deliberately partial — code-review-to-github reviews but cannot post to GitHub, code-review-workflow:respond posts but needs threads to already exist — so picking the wrong one fails silently and looks like it worked. The chain had no PR step. The review skills operate on an open GitHub pull request, but nothing in the workflow created one, so review had nothing to attach to.

What’s Good About It

Benefit	How
One source of truth	After brainstorming, the OpenSpec change is authoritative. `superpowers:writing-plans` is explicitly out.
No silent wrong turns	`AGENTS.md` names `review-fix-loop` as the review step, so an unattended agent stops guessing.
Specs stay honest	`/opsx:archive` runs only after merge, so `openspec/specs/` never claims unshipped behaviour.
Tasks are shippable units	The custom schema forces one task = one independently-shippable outcome, with acceptance criteria and an explicit verification method.
Nothing runs away	Every arrow in the chain is a manual gate. Only the work inside `/sdd:execute` is automatic.
Thin, not clever	`/sdd:execute` is glue. It does not re-implement dispatch, TDD, or verification — it calls the Superpowers skills that already do those.

The Chain

Idea
  ↓ superpowers:brainstorming                       [MANUAL]  requirements, alternatives, direction
  ↓ /opsx:propose                                    [MANUAL]  schema from the owning root
OpenSpec: proposal → specs → design → tasks                  ← source of truth
  ↓ /sdd:execute                                    [MANUAL trigger, automatic inside]
      ├─ subagent-driven-development + the task's verification method
      ├─ systematic-debugging on failure
      ├─ tick tasks.md checkboxes
      └─ openspec validate --strict + verification-before-completion
  ↓ /pr-workflow:create                             [MANUAL]
  ↓ review-fix-loop                                 [MANUAL]  loops until clean
  ↓ merge                                           [MANUAL]
  ↓ /opsx:archive                                   [MANUAL]

Every arrow is a manual gate. No step auto-chains into the next. PR creation, merge, and archive are outward-facing or hard to undo, so a human decides when they happen.

Step-by-Step Guide

Run everything from the root that owns the change — backend/go, backend/bun, frontend/astro, or frontend/solidstart. Each has its own openspec/ directory; they are separate OpenSpec roots, not one shared one.

Step 1 — Brainstorm

superpowers:brainstorming

Explore the requirement, the alternatives, and the direction before any spec exists. This is the only step where the shape of the work is still open. Once brainstorming has run, skip /opsx:explore — it covers the same ground.

Step 2 — Propose the change

cd frontend/solidstart  # or frontend/astro, backend/go, backend/bun

/opsx:propose

This generates the OpenSpec artifacts in openspec/changes/<change-name>/:

Artifact	File	Purpose
proposal	`proposal.md`	Why the change is needed, and which capabilities it touches
specs	`specs/<capability>/spec.md`	What the system must do — requirements and scenarios
design	`design.md`	How it will be built — technical decisions and trade-offs
tasks	`tasks.md`	The implementation checklist

The schema is picked up automatically from openspec/config.yaml, which is set to spec-driven-superpowers in both backend roots and spec-driven-superpowers-fe in both frontend roots. You do not need to pass --schema.

Step 3 — Check the task shape

This is the one artifact that differs from stock OpenSpec, so it is worth a look before executing. Backend tasks use a **TDD:** line:

## 2. PostgreSQL reservation repository

- [ ] 2.1 Add PostgreSQL reservation repository

  **Depends on:** 1.1
  **Affected areas:** internal/inventory/adapters/postgres/, internal/inventory/domain/
  **Acceptance criteria:**
  - Reservation can be persisted and retrieved
  - Duplicate reservation constraints handled
  - Domain layer stays independent of PostgreSQL
  **TDD:** RED failing test -> GREEN minimum impl -> REFACTOR

Frontend tasks use **Verify:** instead:

## 2. Owner property list

- [ ] 2.1 Add the owner property-list page

  **Depends on:** 1.1
  **Affected areas:** apps/panel/src/routes/app/rental/
  **Acceptance criteria:**
  - Empty state shows when the owner has no properties
  - Each row links to that property's detail route
  **Verify:** render-test

Choose exactly one verification method per frontend task:

`Verify:`	Use for	Verification
`TDD`	Pure logic: guards, formatters, validators, permissions, data mapping, reducers, URL/query builders	RED failing test → GREEN minimum implementation → REFACTOR. Mandatory for logic, even inside a UI package.
`render-test`	Component states, conditional rendering, event handling, prop-driven variants	Build first, then add a jsdom render test using `@solidjs/testing-library` or the app’s equivalent. Assert on `data-*` attributes, roles, or visible text, never CSS classes.
`e2e`	Page or multi-step journeys crossing routes, authentication, or the network	Implement, then make the end-to-end spec pass. Derive its title from the matching `#### Scenario:` in `specs/`.
`browser`	Visual layout, spacing, colour, styling, responsive breakpoints	Check in the browser using `/ego-browser`, applying `panel-ui-style` for the admin panel. State exactly what to inspect in the acceptance criteria; no unit test is required.

If a task needs two methods, split it into two tasks — for example, logic under TDD and presentation under render-test or browser. The WHEN/THEN scenarios in specs/ already provide the BDD layer; do not duplicate them in Cucumber, .feature files, or a Gherkin runner. Rules both schemas enforce:

The checkbox line is the task. Never add a bare - [ ] Complete at the end of a task block. The parser captures the checkbox text as the task name, so every task would end up named “Complete” and openspec status becomes unreadable.
One task = one meaningful, independently-shippable outcome. No micro-steps. If a task cannot be verified on its own, fold it into its parent.
**Depends on:** names other task numbers, or none.

Verify the parse before moving on:

openspec instructions apply --change "<name>" --json

Task descriptions should read as real sentences (2.1 Add PostgreSQL reservation repository), and schemaName should be spec-driven-superpowers for backends or spec-driven-superpowers-fe for frontends.

Step 4 — Execute

/sdd:execute <change-name>

Or just /sdd:execute — it infers the change from context, auto-selects when only one is active, and asks when ambiguous. This is the only step with automation inside it. The skill:

Resolves the change and loads openspec instructions apply --json, reading every file in contextFiles.
Checks schemaName (see legacy changes below).
Picks the next unticked task, verifying its Depends on: prerequisites are already [x].
Dispatches that one task to superpowers:subagent-driven-development. Backend tasks follow superpowers:test-driven-development; frontend tasks follow their stated **Verify:** method. On an unexplained failure it uses superpowers:systematic-debugging before any fix.
Ticks - [ ] → - [x] once the task’s verification passes and its acceptance criteria hold: green tests for TDD, render-test, and e2e, or a reported browser check for browser.
Loops until no unticked tasks remain.
Runs openspec validate "<name>" --strict and superpowers:verification-before-completion.
Prints Next: /pr-workflow:create and stops.

Tasks run one at a time. superpowers:subagent-driven-development states it directly: “Never dispatch multiple implementation subagents in parallel (conflicts).” Since that skill owns the dispatch, /sdd:execute obeys it rather than inventing its own merge path. Depends on: is a correctness check — it refuses to start a task whose prerequisites are unticked — not a parallel scheduler.

Two more things the skill will not do: sub-agents never edit tasks.md (only the orchestrator writes it, so progress stays trustworthy after a failure), and the skill never touches GitHub — no git push, no gh, no PR, no archive.

Step 5 — Open the PR

/pr-workflow:create

Commits, pushes, opens a structured PR, assigns you, applies labels, and requests review from @alvincheah88.

Put the change’s proposal path in the PR body’s Related Spec section (backend/go/openspec/changes/<name>/proposal.md or, for example, frontend/solidstart/openspec/changes/<name>/proposal.md). The reviewer’s Spec axis anchors to it instead of guessing.

Step 6 — Review until clean

/review-fix-loop <pr-number>

Runs review → fix → review again until a round returns zero findings. Details in the Review-Fix Loop Guide. Do not substitute the built-in /code-review, and do not call the sub-skills yourself. They stay available when you name them explicitly:

Skill	What it does alone	Why it fails silently
`code-review-to-github`	Reviews, writes findings to a local file	Cannot post to GitHub — its sandbox blocks all network
`code-review-workflow:respond`	Fixes, replies, resolves	Needs review threads to already exist on the PR

If you name one, that one runs and nothing else.

Step 7 — Merge

Normal GitHub merge. Nothing special here — but it must happen before the next step.

Step 8 — Archive

git checkout main && git pull

/opsx:archive

openspec archive folds the change’s delta specs into the root openspec/specs/ — the record of what the system does now.

Never archive before merge. Doing so makes openspec/specs/ claim behaviour that is still sitting in an open PR, and it blocks editing specs/ if review finds a requirement wrong.

Commit the archive result as its own small bookkeeping commit. Keep it out of the feature PR.

Legacy Changes

A change created before this workflow pins its own schema in <change>/.openspec.yaml, and that overrides the root config.yaml. Changing the root default does not migrate existing changes:

$ cat backend/bun/openspec/changes/architecture-improvements/.openspec.yaml
schema: spec-driven
created: 2026-04-09

Such a change still resolves to spec-driven, and its tasks carry no Depends on: or acceptance-criteria metadata. /sdd:execute detects this from schemaName, announces it, and runs the tasks strictly in listed order. It will not rewrite a live change’s tasks.md into the new shape.

Reference

Files

Path	What it is
`backend/{bun,go}/openspec/config.yaml`	Sets `schema: spec-driven-superpowers`
`backend/{bun,go}/openspec/schemas/spec-driven-superpowers/`	The forked schema — `schema.yaml` + 4 templates
`frontend/{astro,solidstart}/openspec/config.yaml`	Sets `schema: spec-driven-superpowers-fe`
`frontend/{astro,solidstart}/openspec/schemas/spec-driven-superpowers-fe/`	The frontend schema — `schema.yaml` + 4 templates, with per-task `Verify` methods
`<root>/openspec/changes/<name>/`	An in-flight change in any of the four roots above
`<root>/openspec/specs/`	Shipped behaviour, written by `/opsx:archive`
`.agents/skills/sdd-execute/SKILL.md`	The executor skill (symlinked into `.claude/skills/`)
`.claude/commands/sdd/execute.md`	The `/sdd:execute` slash command wrapper

Useful commands

openspec doctor                                      # is this OpenSpec root healthy?
openspec list --json                                 # what changes are active?
openspec instructions apply --change "<n>" --json    # tasks, progress, context files
openspec validate "<n>" --strict                     # validate one change
openspec schema validate spec-driven-superpowers     # from a backend root
openspec schema validate spec-driven-superpowers-fe  # from a frontend root

openspec validate --strict with no target fails outside an interactive terminal. Always name the change.

Schema copies, kept in sync by hand

Each schema exists as two real directories: spec-driven-superpowers in the two backend roots and spec-driven-superpowers-fe in the two frontend roots. Keep copies of the same schema in sync; the backend **TDD:** and frontend **Verify:** task formats intentionally differ. Symlinking does not work: the OpenSpec runtime enumerates the schemas directory and skips symlinks, because isDirectory() is false for one. The failure is confusing — openspec schema which reports success (it checks the path directly and bypasses enumeration), then openspec status fails with Unknown schema 'spec-driven-superpowers'. Available: spec-driven.

schema which passing is not proof a schema works. Verify with openspec instructions apply --change <name> --json and check schemaName.

If you edit one copy, edit the other copy of that schema. Only the tasks artifact is customised, so drift has a small surface — but it is real.

Review-Fix Loop Guide — the review step in detail
Code Review Process — how findings are triaged and answered
backend/go/AGENTS.md, backend/bun/AGENTS.md, frontend/astro/AGENTS.md, and frontend/solidstart/AGENTS.md — the routing rules agents read

Overview

Development Tools

Authentication

Guides

SDD Workflow Guide

SDD Workflow Guide

Why This Exists

What’s Good About It

The Chain

Step-by-Step Guide

Step 1 — Brainstorm

Step 2 — Propose the change

Step 3 — Check the task shape

Step 4 — Execute

Step 5 — Open the PR

Step 6 — Review until clean

Step 7 — Merge

Step 8 — Archive

Legacy Changes

Reference

Files

Useful commands

Schema copies, kept in sync by hand

​SDD Workflow Guide

​Why This Exists

​What’s Good About It

​The Chain

​Step-by-Step Guide

​Step 1 — Brainstorm

​Step 2 — Propose the change

​Step 3 — Check the task shape

​Step 4 — Execute

​Step 5 — Open the PR

​Step 6 — Review until clean

​Step 7 — Merge

​Step 8 — Archive

​Legacy Changes

​Reference

​Files

​Useful commands

​Schema copies, kept in sync by hand

​Related

SDD Workflow Guide

Why This Exists

What’s Good About It

The Chain

Step-by-Step Guide

Step 1 — Brainstorm

Step 2 — Propose the change

Step 3 — Check the task shape

Step 4 — Execute

Step 5 — Open the PR

Step 6 — Review until clean

Step 7 — Merge

Step 8 — Archive

Legacy Changes

Reference

Files

Useful commands

Schema copies, kept in sync by hand

Related