Skip to main content

Getting Started

The design 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.

Installation​

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

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

Then restart Claude Code. All 15 skills will be available as /design:* 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​

/design: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​

/design: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​

/design: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​

/design: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​

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

/design: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. /design:review then pairs reviewer and responder agents to check each PR against the spec's acceptance criteria and merge approved work. Finally, /design:check verifies that the implementation hasn't drifted from your ADRs and specs.

What's Next​