forge-sdd

forge-sdd

A spec-driven design system for Claude Code — visual brainstorming with forge, structured plans with SDD defaults, and subagent/agent-team execution with the TDD, worktree, and commit hygiene of superpowers.

forge-sdd turns the superpowers brainstorm → plan → execute pipeline from prose-only into visual decision-making. Every architecture question becomes a forge topic with three rendered variations. Every accepted variation becomes a structured decision record that survives context compaction. Every plan cross-references the decisions it implements. Every execution phase runs under the right workflow: subagents by default, agent teams where parallel exploration genuinely pays off.

---

Why this exists

Superpowers gives you a rigorous spec-driven workflow — but every stage is text. For UI and architecture decisions, text is a lossy translation layer. You describe visual intent in prose, Claude interprets, rounds of drift follow:

You:    We need to redesign auth. Tokens should rotate, MFA should be optional,
        and sessions need to be auditable.
Claude: Here's a plan using JWT cookies with rolling refresh...
You:    Actually I meant event-sourced sessions, and MFA might be required
        for some tenants, and auditability is a hard compliance requirement
        so it needs to be at the storage layer not the app layer...
Claude: [regenerates with partial understanding]
You:    Close, but the refresh strategy is wrong, and the topology has
        the wrong boundary between the auth service and...

forge solved this for UI (draw variations, click what you like). forge-sdd solves it for everything upstream of UI — architecture, topology, library choices, cross-cutting concerns:

You:    /sdd-brainstorm auth redesign
Claude: [creates forge topic "auth-session"]
        Topic ready at http://localhost:4546 — 3 approaches:
          A: JWT cookies + rolling refresh
          B: Server sessions (Redis)
          C: Event-sourced sessions (Kafka)

[you open the browser, look at three diagrammed approaches]
[you click "Like" on C]
[you drop a pin on C's MFA box: "must be tenant-configurable"]
[you drop a pin on A's refresh strategy: "use refresh tokens not rolling"]

Claude: ✓ Decision recorded: d-003 — Session storage: event-sourced
          Rationale: auditability; tenant-configurable MFA
          Addressed: pin-7 (refresh tokens over rolling)
          → Next: Auth — token rotation details

[you drill into the MFA sub-topic, accept a variation]
[continue for data model, deployment topology, API shape…]

Claude: Spec at docs/sdd/specs/2026-04-19-auth-redesign-design.md.
        Review and tell me to proceed — I'll advance to plan-writing.

You stay in visual flow through the design phase, and Claude walks out with a durable, structured understanding of what you picked and why.

---

The pipeline

Three stages, each its own skill, connected by persisted state:

┌──────────────────────┐   ┌──────────────────────┐   ┌──────────────────────┐
│ 1. Brainstorm        │   │ 2. Plan              │   │ 3. Execute           │
│                      │   │                      │   │                      │
│ /sdd-brainstorm      │──▶│ /sdd-plan            │──▶│ /sdd-execute         │
│                      │   │                      │   │                      │
│ forge topics per     │   │ fork of superpowers  │   │ subagent dispatch    │
│ cluster; decision    │   │ writing-plans with   │   │ (default) + agent    │
│ records on accept    │   │ UI skill defaults    │   │ teams for tagged     │
│                      │   │ and parallel         │   │ phases; native plan  │
│                      │   │ workstream shape     │   │ mode gate at entry   │
└──────────┬───────────┘   └──────────┬───────────┘   └──────────┬───────────┘
           │                          │                          │
           ▼                          ▼                          ▼
    spec.md                      plan.md                 worktree branch
    decisions.json             (commit shas              + squash-on-merge
                                land in-place)           + finishing-a-branch

Each stage produces a durable artifact. You can resume from any stage, or start at a later stage with a hand-written input.

---

Quick start

1. Prerequisites

• Claude Code ≥ 2.1.32
• Bun ≥ 1.0 (curl -fsSL https://bun.sh/install | bash)
• forge plugin installed
• superpowers plugin installed
• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 — only required if any phase in a plan uses execution: team

2. Install the plugin

/plugin marketplace add mahuebel/forge-sdd
/plugin install forge-sdd@forge-sdd-marketplace