Skip to main content

Commands

All design plugin skills are invoked as Claude Code slash commands.

Creating Artifacts​

/design:adr​

Create a new Architecture Decision Record using the MADR format.

Usage:

/design:adr [description]
/design:adr [description] --review

What it does:

  • Creates docs/adrs/ADR-XXXX-short-title.md with the next sequential number
  • Includes all MADR sections: Context, Decision Drivers, Considered Options, Decision Outcome, Pros and Cons, Architecture Diagram
  • Sets status to proposed in YAML frontmatter
  • With --review, spawns a drafter + architect team (max 2 revision rounds)
  • After writing, suggests formalizing the decision into a specification with /design:spec, which can then break requirements into sprint issues

Examples:

/design:adr Add JWT-based authentication
/design:adr Switch from REST to GraphQL for the public API --review

/design:spec​

Create a new OpenSpec specification with paired requirements and design documents, then optionally plan a sprint by breaking requirements into trackable issues.

Usage:

/design:spec [capability name]
/design:spec [capability name] --review

What it does:

  • Creates docs/openspec/specs/{capability-name}/spec.md with RFC 2119 normative requirements and WHEN/THEN scenarios
  • Creates docs/openspec/specs/{capability-name}/design.md with architecture, rationale, and tradeoffs
  • Assigns the next sequential SPEC-XXXX number
  • With --review, spawns a drafter + architect team (max 2 revision rounds)
  • After writing the spec, suggests running /design:plan to break requirements into trackable issues

Examples:

/design:spec Authentication Service
/design:spec WebSocket Gateway --review

Sprint Planning​

/design:plan​

Break an existing spec into story-sized tracker issues, organized into projects with branch naming and PR conventions. Use --scrum for a full team-groomed sprint planning ceremony.

Usage:

/design:plan [spec-name or SPEC-XXXX]
/design:plan [spec-name or SPEC-XXXX] --scrum
/design:plan [spec-name or SPEC-XXXX] [--review] [--project <name>] [--no-projects] [--branch-prefix <prefix>] [--no-branches]

What it does:

  • Accepts a spec directory name (e.g., authentication-service) or a spec number (e.g., SPEC-0003). If omitted, lists available specs and asks which one to plan.
  • Groups requirements into 3-4 story-sized issues by functional area — not one issue per requirement. Each story targets a 200–500 line PR with task checklists for requirement traceability.
  • Detects available issue trackers: Beads, GitHub (via MCP or gh CLI), GitLab (via MCP or glab CLI), Gitea (via MCP), Jira (via MCP), and Linear (via MCP)
  • Saves your tracker preference to .claude-plugin-design.json so you're not prompted again
  • Creates an epic for the spec and story issues with requirement checklists and acceptance criteria referencing spec and requirement numbers
  • Creates tracker-native projects with descriptions, READMEs, iteration fields, and named views (GitHub) or milestones and board columns (Gitea)
  • Adds ### Branch sections: feature/{issue-number}-{slug} for stories, epic/{issue-number}-{slug} for epics. Customize with --branch-prefix, skip with --no-branches.
  • Adds ### PR Convention sections with tracker-specific close keywords
  • Falls back to a structured tasks.md file co-located with the spec if no tracker is available

--scrum mode (full team-groomed ceremony):

  • Audits spec completeness before planning — generates missing design.md files and proposes specs for any unspec'd issues
  • Spawns a five-agent scrum team: Product Owner, Scrum Master, Engineer A, Engineer B (grumpy, high-bar), and Architect
  • Each agent reviews all stories and submits role-specific feedback in parallel
  • Dissent is resolved in one negotiation round; the Scrum Master tiebreaks
  • Organize and enrich run automatically after grooming — no separate commands needed
  • Emits a sprint report: accepted, revised, deferred, and new spec proposals

See the Sprint Planning guide for a full walkthrough.

Examples:

/design:plan authentication-service
/design:plan SPEC-0003
/design:plan SPEC-0003 --scrum
/design:plan --scrum                    # groom full backlog
/design:plan SPEC-0003 --review
/design:plan SPEC-0003 --project "Auth Sprint"
/design:plan SPEC-0003 --no-branches
/design:plan SPEC-0003 --branch-prefix hotfix

/design:organize​

Retroactively group existing issues into tracker-native projects.

Usage:

/design:organize [SPEC-XXXX or spec-name]
/design:organize [SPEC-XXXX or spec-name] --project "Sprint 1"
/design:organize [SPEC-XXXX or spec-name] --dry-run

What it does:

  • Finds issues in your tracker that reference the specified spec
  • Creates one tracker-native project per epic (default), or a single combined project with --project
  • Skips projects that already exist (idempotent)
  • Use --dry-run to preview without creating projects

Examples:

/design:organize SPEC-0003
/design:organize authentication-service --project "Auth Sprint"
/design:organize SPEC-0003 --dry-run

/design:enrich​

Retroactively add branch naming and PR convention sections to existing issue bodies.

Usage:

/design:enrich [SPEC-XXXX or spec-name]
/design:enrich [SPEC-XXXX or spec-name] --branch-prefix hotfix
/design:enrich [SPEC-XXXX or spec-name] --dry-run

What it does:

  • Finds issues in your tracker that reference the specified spec
  • Appends ### Branch sections with feature/{issue-number}-{slug} naming convention (or custom prefix with --branch-prefix)
  • Appends ### PR Convention sections with tracker-specific close keywords
  • Skips issues that already have these sections (idempotent)
  • Use --dry-run to preview changes without modifying issues

Examples:

/design:enrich SPEC-0003
/design:enrich authentication-service --branch-prefix hotfix
/design:enrich SPEC-0003 --dry-run

Implementation​

/design:work​

Pick up tracker issues and implement them in parallel using git worktrees. Each issue gets its own worktree and worker agent.

Usage:

/design:work [SPEC-XXXX | issue numbers]
/design:work [SPEC-XXXX | issue numbers] [--max-agents N] [--draft] [--dry-run] [--no-tests]

What it does:

  • If a spec is provided, finds all open issues referencing that spec. If issue numbers are given, works on those. If empty, proposes a batch from the backlog with a bias toward unblocking work and feature development.
  • Creates a coordination team with up to N worker agents (default 3)
  • Each worker gets its own git worktree with the branch name from the issue's ### Branch section
  • Workers implement the acceptance criteria, leave governing comments (// Governing: SPEC-XXXX REQ "..."), run tests, and create PRs
  • Workers assess PR size — trivially small changes are bundled with additional issues rather than opening tiny standalone PRs
  • Respects dependency ordering: blocked issues wait until prerequisites complete
  • Falls back to single-agent sequential mode if team creation fails
  • Skips epics and issues without ### Branch sections (suggests /design:enrich)
  • After completion, suggests /design:review for automated spec-aware PR review

Examples:

/design:work SPEC-0003
/design:work 42 43 47
/design:work                          # propose from backlog
/design:work SPEC-0003 --max-agents 5
/design:work SPEC-0003 --draft
/design:work SPEC-0003 --dry-run
/design:work SPEC-0003 --no-tests

/design:review​

Review and merge PRs produced by /design:work using reviewer-responder agent pairs. Each pair processes PRs through exactly one review-response round.

Usage:

/design:review [SPEC-XXXX or PR numbers]
/design:review [SPEC-XXXX or PR numbers] [--pairs N] [--no-merge] [--dry-run]

What it does:

  • If a spec is provided, finds all open PRs referencing that spec. If PR numbers are given, reviews those. If empty, asks which spec's PRs to review.
  • Creates N reviewer-responder pairs (default 2) and distributes PRs round-robin
  • Phase 1 — Review: Reviewers check CI status, then review the diff against spec acceptance criteria and ADR compliance. Clean PRs are approved immediately.
  • Phase 2 — Response: For PRs with requested changes, responders reuse the existing worktree (or create one), address feedback, push fixes, and reply to each review comment
  • Phase 3 — Merge: After response, reviewers re-check CI and either approve
    • merge (squash by default) or leave comments for human follow-up
  • Automatically closes parent epics when all child stories are merged
  • Only supports GitHub, GitLab, and Gitea (PR/MR capability required)
  • Falls back to single-agent sequential mode if team creation fails

Examples:

/design:review SPEC-0003
/design:review 101 102 105
/design:review SPEC-0003 --pairs 3
/design:review SPEC-0003 --no-merge
/design:review SPEC-0003 --dry-run

Drift Detection​

/design:check​

Quick-check a file, directory, ADR, or spec for drift. Designed for use during development — like running a linter.

Usage:

/design:check [target]

What it does:

  • Scans the target against governing ADRs and specs
  • Produces a concise findings table with severity levels
  • Checks for code-vs-spec drift, code-vs-ADR drift, and ADR-vs-spec inconsistencies
  • Always runs in single-agent mode (no --review)

Examples:

/design:check src/auth/
/design:check ADR-0001
/design:check docs/openspec/specs/auth-service/spec.md

/design:audit​

Comprehensive analysis of the entire project (or a scope) for all forms of drift, coverage gaps, stale artifacts, and policy violations. Use --scrum for a team-triaged remediation roadmap.

Usage:

/design:audit [scope]
/design:audit [scope] --review
/design:audit [scope] --scrum

What it does:

  • Examines the project for: code-vs-spec drift, code-vs-ADR drift, ADR-vs-spec inconsistencies, coverage gaps, stale artifact detection, and policy violations
  • Produces a structured report with findings (critical, warning, info) grouped by category
  • With --review, spawns an auditor + reviewer team (max 2 revision rounds)

--scrum mode (team-triaged remediation):

  • Runs the full standard audit first, then layers a triage ceremony on top
  • Groups raw findings into 4–8 functional themes (e.g., "Authentication drift", "Billing API Contracts") instead of raw category tables
  • Spawns a five-agent triage team: Product Owner (business priority), Scrum Master (effort estimates), Engineer A (complexity), Engineer B (false-positive challenge), Architect (source-of-truth validation)
  • ADRs/specs are the source of truth — Engineer B can challenge a finding as intentional evolution, but the Architect decides: code fix or artifact update
  • Produces a prioritized roadmap: P1/P2/P3 × XS–XL per theme, plus an artifact update queue for findings where the spec needs updating (not the code)
  • Offers to create tracker issues for P1 and P2 themes after the report

See the Sprint Planning guide for triage workflow details.

Examples:

/design:audit
/design:audit src/
/design:audit --review
/design:audit --scrum
/design:audit auth --scrum       # scope triage to auth domain

Discovery​

/design:discover​

Discover implicit architectural decisions and spec-worthy subsystems in an existing codebase. Ideal for bootstrapping design artifacts on projects that already have code.

Usage:

/design:discover [scope]

What it does:

  • Analyzes dependencies, frameworks, architectural patterns, project structure, and configuration
  • Produces a read-only report of suggested ADRs and specs
  • Each suggestion includes evidence from the codebase and a ready-to-use command to create the artifact
  • Reads existing artifacts to avoid duplicating already-documented decisions

Examples:

/design:discover
/design:discover src/api/

Documentation​

/design:docs​

Generate a Docusaurus documentation site from your ADRs and specs, with RFC 2119 highlighting, status badges, cross-references, and Mermaid diagrams.

Usage:

/design:docs [project name]

What it does:

  • First run (no site exists): Scaffolds a complete Docusaurus site in docs-site/
  • First run (existing Docusaurus site): Offers integration mode — installs a build-time plugin into your existing site
  • Subsequent runs: Detects changes via .design-docs.json manifest and performs a diff-based upgrade, preserving your customizations
  • Transforms ADR markdown into MDX with badges, keyword highlighting, and cross-reference links
  • Transforms OpenSpec markdown into MDX with requirement boxes and domain badges

Examples:

/design:docs
/design:docs my-project

Session Management​

/design:init​

Set up your project's CLAUDE.md with design plugin references. Run once when you install the plugin.

Usage:

/design:init

What it does:

  • Creates CLAUDE.md (or updates it) with an ## Architecture Context section referencing docs/adrs/ and docs/openspec/specs/
  • Adds a table of available design plugin skills
  • Idempotent — safe to run multiple times

/design:prime​

Load ADR and spec context into the current session for architecture-aware responses. Run at the start of each session.

Usage:

/design:prime [topic]

What it does:

  • Reads all ADRs and specs, summarizes each, and presents them in structured tables
  • With a topic argument, uses semantic matching to load only relevant artifacts (e.g., /design:prime security loads auth, encryption, and access control ADRs)
  • Read-only — never modifies files

Examples:

/design:prime
/design:prime authentication
/design:prime deployment

Lifecycle Management​

/design:list​

List all ADRs and specs with their status.

Usage:

/design:list [adr|spec|all]

What it does:

  • Scans docs/adrs/ and docs/openspec/specs/
  • Presents a formatted table with ID, Title, Status, and Date columns
  • Read-only

/design:status​

Update the status of an ADR or spec.

Usage:

/design:status [ID] [new status]

Valid statuses:

  • ADRs: proposed, accepted, deprecated, superseded
  • Specs: draft, review, approved, implemented, deprecated

Examples:

/design:status ADR-0001 accepted
/design:status SPEC-0003 implemented