Skip to main content

Getting Started

The SDD plugin brings architecture governance to Claude Code. It lets you record decisions as ADRs, formalize them into specifications, plan sprints, implement issues in parallel, and validate that your code stays aligned with your architecture -- all without leaving the CLI.

Prerequisites​

Starting with v5.0.0, the plugin has a hard runtime dependency on qmd, an on-device hybrid retrieval engine (BM25 + vector + LLM rerank). qmd powers the plugin's smart-context features: topic-filtered priming, drift detection on changed files, and pre-search of related decisions when authoring ADRs and specs.

Install qmd globally before running /sdd:init:

npm install -g @tobilu/qmd
# or
bun install -g @tobilu/qmd

/sdd:init runs command -v qmd as a preflight check and refuses to set up the project if qmd is missing. The first time qmd embeds a corpus, it auto-downloads its GGUF models (~2 GB total) and caches them in ~/.cache/qmd/. Subsequent embeds and queries reuse the cached models.

If you previously used the plugin at v4.x, qmd was not required — see the CHANGELOG for the v5 upgrade notes.

Installation​

Add the plugin to your project's .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "claude-plugin-sdd": {
      "source": {
        "source": "github",
        "repo": "joestump/claude-plugin-sdd"
      }
    }
  },
  "enabledPlugins": {
    "sdd@claude-plugin-sdd": true
  }
}

Then restart Claude Code. All 15 skills will be available as /sdd:* commands.

Quick Start​

Walk through the simplest useful workflow: create an ADR, then a spec, plan a sprint, and implement it.

1. Initialize the plugin​

/sdd:init

This sets up your project's CLAUDE.md with an Architecture Context section that references docs/adrs/ and docs/openspec/specs/. It also adds a skills reference table so future sessions know what commands are available. Safe to re-run -- it won't duplicate content.

2. Record your first decision​

/sdd:adr We need to choose between REST and GraphQL for our API

This creates an ADR in docs/adrs/ using MADR format. The ADR captures the context, options considered, decision outcome, and consequences. It includes a Mermaid architecture diagram and uses sequential numbering (ADR-0001, ADR-0002, etc.).

3. Formalize into a specification​

/sdd:spec api-layer

This creates a paired spec.md and design.md in docs/openspec/specs/api-layer/. The spec uses RFC 2119 language (MUST, SHALL, MAY) to define requirements, while the design document captures architecture diagrams and implementation details. These two files are always kept in sync -- when one changes, the other is reviewed for alignment.

4. Plan your sprint​

/sdd:plan SPEC-0001

This breaks your spec into trackable issues in your issue tracker (GitHub, GitLab, Gitea, Jira, Linear, or Beads). It creates an epic for the spec with story-sized issues grouped by functional area, each with acceptance criteria that reference specific spec requirements. Branch naming conventions and PR templates are added to each issue automatically.

5. Implement and validate​

/sdd:work SPEC-0001
/sdd:review SPEC-0001
/sdd:check src/

/sdd:work picks up the open issues and implements them in parallel using git worktrees -- each issue gets its own isolated branch and a worker agent that reads the spec, writes code, runs tests, and opens a PR. /sdd:review then pairs reviewer and responder agents to check each PR against the spec's acceptance criteria and merge approved work. Finally, /sdd:check verifies that the implementation hasn't drifted from your ADRs and specs.

What's Next​