claude-plugin-sdd (joestump) — Summary

Slug: claude-plugin-design-joestump Repo: joestump/claude-plugin-sdd Stars: 11 | Forks: 1 License: MIT Language: JavaScript Plugin name: sdd (v4.0.0) Install: via .claude/settings.json extraKnownMarketplaces Homepage: https://joestump.github.io/claude-plugin-sdd/

One-Line Description

Spec-Driven Development plugin for Claude Code — ADRs (MADR), OpenSpec specifications, sprint planning, parallel git-worktree implementation, PR review, Docusaurus doc generation, and an artifact dependency graph.

What It Is

claude-plugin-sdd is a 16-skill Claude Code plugin that implements the full SDD (Spec-Driven Development) lifecycle as slash commands inside Claude Code. It is the only framework in this corpus that treats architecture governance (decision records, formal specifications, drift detection, and issue tracking integration) as first-class operations within an AI coding session.

Core Value Proposition

The plugin bridges the gap between architecture documentation and code implementation. The workflow is: decide → specify → plan → implement (in parallel) → review → validate → document — all inside Claude Code without leaving the development environment. The artifact graph (/sdd:graph) makes every relationship between ADRs, specs, issues, and code files queryable.

Key Primitives

• ADR (/sdd:adr): MADR-format Architecture Decision Records with Mermaid diagrams, sequential numbering (ADR-0001...)
• Spec (/sdd:spec): OpenSpec paired spec.md + design.md with RFC 2119 requirements (MUST/SHALL/MAY), security-by-default, WCAG accessibility defaults
• Plan (/sdd:plan): breaks specs into tracker issues (GitHub/GitLab/Gitea/Jira/Linear) with foundation story detection, hotspot analysis, branch/PR conventions
• Work (/sdd:work): parallel implementation via git worktrees, up to 4 concurrent agents, pre-flight PR manifest, topological merge ordering
• Review (/sdd:review): reviewer-responder agent pairs, conflict-marker CI gate, spec-aware code review, squash-merge
• Audit (/sdd:audit): 6 drift categories (code vs. spec, code vs. ADR, ADR vs. spec, coverage gaps, stale artifacts, policy violations)
• Graph (/sdd:graph): artifact dependency DAG with validate/impact/ancestors/chain/orphans/cycles/backfill verbs
• Docs (/sdd:docs): scaffold or integration mode Docusaurus site with RFC 2119 highlighting, upgrade manifest (.sdd-docs.json)
• CLAUDE.md-native config: all configuration as markdown under ### SDD Configuration; no JSON config files

Status

Production quality for a personal/team plugin. 11 stars; self-hosted. v4.0.0.

claude-plugin-sdd (joestump) — Overview

Origin

Published by Joe Stump (joestump) as a Claude Code plugin. JavaScript/MIT. v4.0.0. 11 stars. Homepage: https://joestump.github.io/claude-plugin-sdd/.

Philosophy

The plugin operationalizes Spec-Driven Development: the idea that architectural decisions should be made explicitly (ADRs), requirements should be formalized (OpenSpec), and implementation should be traceable back to those decisions (governing comments, drift checks). Claude Code becomes the runtime for the entire governance lifecycle, not just a coding assistant.

From the CLAUDE.md governing comment convention:

// Governing: ADR-0001 (chose JWT over sessions), SPEC-0003 REQ "Token Validation"

Every line of production code should be traceable to an architectural decision and a formal requirement.

Design Goals

1. Full SDD lifecycle in Claude Code: decide → specify → plan → implement → review → validate → document — all as slash commands
2. CLAUDE.md-native config: no separate JSON config files; configuration is markdown prose in CLAUDE.md
3. Tracker-agnostic: supports GitHub, GitLab, Gitea, Jira, Linear, Beads — with graceful degradation to tasks.md
4. Parallel implementation by default: git worktrees + TeamCreate for concurrent agent workers
5. Architecture governance: drift detection, artifact graph, compliance checking across 6 categories

Core Artifact Formats

MADR (ADRs): YAML frontmatter + title + status + context + decision + consequences + Mermaid diagrams. Sequential: ADR-0001, ADR-0002.

OpenSpec (Specs): Paired spec.md + design.md. RFC 2119 requirements (MUST, SHALL, MAY). Scenarios with WHEN/THEN format. Sequential: SPEC-0001, SPEC-0002. Security sections mandatory for web-facing specs.

Artifact Graph: Queryable DAG of relationships between ADRs, specs, issues, and code. --json output is the stable contract for downstream consumers.

Plugin-as-Methodology

This plugin is unusual in that it encodes an entire development methodology (SDD), not just a set of tools. Installing the plugin means adopting:

• MADR for decision records
• OpenSpec for specifications
• RFC 2119 for requirements language
• Governing comments for code traceability
• The decide → specify → plan → build → review → audit → document workflow

The methodology is not optional — the skills assume these conventions exist and build on each other.

Scrum Ceremony Mode

--scrum flag on /sdd:plan and /sdd:audit activates a multi-agent "ceremony" with 5 specialist agents:

• Product Owner (PO)
• Scrum Master (SM)
• Engineer A
• Engineer B (Grumpy) — adversarial engineer who challenges estimates and feasibility
• Architect

These agents run a structured grooming session, producing prioritized stories with acceptance criteria. The "Grumpy" engineer pattern is unusual — explicitly building in a devil's advocate role to surface hidden complexity before work begins.

claude-plugin-sdd (joestump) — Architecture

Repository Structure

joestump/claude-plugin-sdd/
├── plugin.json                 # Plugin manifest (name, version, description)
├── .claude-plugin/             # Plugin definition (loaded by Claude Code)
├── .claude/
│   └── settings.json           # Auto-enables plugin via extraKnownMarketplaces
├── skills/                     # 18 skill definitions (slash commands)
│   ├── _index.json             # Skill registry index
│   ├── adr/                    # /sdd:adr skill
│   ├── spec/                   # /sdd:spec skill
│   ├── init/                   # /sdd:init skill
│   ├── prime/                  # /sdd:prime skill
│   ├── check/                  # /sdd:check skill
│   ├── audit/                  # /sdd:audit skill
│   ├── discover/               # /sdd:discover skill
│   ├── docs/                   # /sdd:docs skill
│   ├── list/                   # /sdd:list skill
│   ├── plan/                   # /sdd:plan skill
│   ├── organize/               # /sdd:organize skill
│   ├── enrich/                 # /sdd:enrich skill
│   ├── work/                   # /sdd:work skill
│   ├── review/                 # /sdd:review skill
│   ├── status/                 # /sdd:status skill
│   ├── graph/                  # /sdd:graph skill
│   ├── index/                  # /sdd:index skill (qmd semantic search)
│   ├── search/                 # /sdd:search skill
│   └── report-friction/        # /sdd:report-friction skill
├── templates/                  # File templates for ADRs, specs, docs
├── references/                 # Reference documents for agent context
├── docs/                       # Auto-generated artifact storage
│   ├── adrs/                   # ADR-0001-*.md, ADR-0002-*.md, etc.
│   └── openspec/specs/         # capability-name/{spec.md, design.md}
├── docs-site/                  # Scaffold mode Docusaurus site
├── CLAUDE.md                   # Project-level agent instructions + SDD config
├── .sdd-docs.json              # Docs upgrade manifest (version, checksums)
├── .claudeignore               # Files excluded from agent context
├── evals/                      # Skill evaluation tests
└── plan.md                     # Project planning document

Plugin Installation Architecture

Claude Code loads plugins via .claude/settings.json:

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

The plugin name is sdd. Skills are invoked as /sdd:<skill-name>. No npm install, no binary — Claude Code fetches and executes the skill markdown files directly.

Skill Architecture

Each skill is a directory under skills/ containing a prompt file (markdown) that Claude Code executes as a slash command. Skills are stateless — they read from files (CLAUDE.md, docs/adrs/, docs/openspec/) and write artifacts back to those locations.

Skills communicate state through:

1. CLAUDE.md: configuration, architecture context, governing comments
2. docs/adrs/: ADR files
3. docs/openspec/specs/: Spec and design files
4. Issue tracker: issues, labels, projects (via GitHub MCP or gh CLI)
5. Git worktrees: parallel implementation branches (.claude/worktrees/)

CLAUDE.md as Configuration Store

All plugin configuration is stored as markdown in CLAUDE.md under ### SDD Configuration. Skills parse this markdown section to read config values. No JSON config files — markdown is both human-readable and LLM-readable.

Example config section:

### SDD Configuration

#### Tracker
- **Type**: github
- **Owner**: joestump
- **Repo**: claude-plugin-sdd

Artifact Graph Architecture

/sdd:graph builds a queryable DAG:

• Nodes: ADRs, specs, issues, code files
• Edges: references (spec → ADR), implementations (issue → spec), governing comments (code → spec/ADR)
• Output formats: ASCII DAG (default), Mermaid, JSON (--json is the stable contract)
• Operations: validate, impact, ancestors, chain, orphans, cycles, backfill

The graph is built from static analysis of markdown references and governing comments — no separate graph database.

Parallel Execution Architecture

/sdd:work uses:

1. TeamCreate — creates a coordinated agent team with shared message bus (SendMessage)
2. Git worktrees — one isolated working directory per issue (.claude/worktrees/)
3. Pre-flight PR manifest — workers broadcast file claims and type creations to prevent conflicts
4. Topological merge ordering — resolves optimal merge sequence based on file overlap analysis

Workers are up to 4 concurrent agents (configurable via CLAUDE.md Max parallel agents). Excess issues queue and start as active agents complete.

claude-plugin-sdd (joestump) — Components

Skills (18 total)

ADR Component (MADR Format)

---
status: proposed
date: 2026-05-26
decision-makers: ["joe"]
---

# ADR-0001: Choose a web framework

## Context
[problem statement]

## Decision
We will use [X] because [Y].

## Consequences
### Good
- [benefit]
### Bad
- [drawback]

## Architecture Diagram
[Mermaid diagram]

Stored in docs/adrs/ADR-0001-short-title.md. Sequential numbering, YAML frontmatter.

Spec Component (OpenSpec Format)

docs/openspec/specs/capability-name/
├── spec.md      # Requirements (RFC 2119), scenarios (WHEN/THEN)
└── design.md    # Architecture diagram, component breakdown, Mermaid

spec.md structure:

• SPEC-XXXX number, title, status, date
• Requirements by functional area (MUST/SHALL/MAY/SHOULD)
• Scenarios: #### Scenario: Name\nWHEN [condition]\nTHEN [outcome]
• Security section: mandatory for web-facing specs (auth, authz, input validation, CSRF)
• Accessibility section: mandatory for UI specs (WCAG, keyboard nav, screen reader)

Plan Component

Plan produces:

• Epic: one per spec
• Stories: 3-4 issues per functional area (200-500 line PR target)
• Foundation stories: extracted shared types/packages, labeled foundation, merge before feature work
• Issue bodies with acceptance criteria (SPEC-XXXX REQ "...")
• Branch conventions: ### Branch\nfeature/{issue-number}-{slug}
• PR conventions: ### PR Convention\nCloses #N
• Tracker-native projects with Sprint iteration fields and named views

Foundation story detection: identifies requirements that create shared types, base packages, or helpers needed by 2+ stories. Prevents duplicate implementations.

Hotspot analysis: scans git log to find files modified by ≥N% of recent PRs (configurable threshold). Stories touching hotspot files are serialized to prevent merge conflicts.

Work Component

Parallel implementation engine:

• TeamCreate call to spawn coordinated agent team
• Pre-flight PR manifest: each worker declares file claims and type creations via SendMessage
• Git worktree per issue: .claude/worktrees/{issue-number}-{slug}/
• Workers read spec.md + design.md + referenced ADRs for architecture context
• Workers leave governing comments: // Governing: ADR-0001, SPEC-0003 REQ "..."
• Workers assess PR size: trivially small PRs (<30 lines) get additional issues bundled before opening
• Topological merge ordering: isolated PRs first, dependent PRs rebase in tier order
• Design doc isolation: workers forbidden from modifying spec/ADR/root CLAUDE.md files

Review Component

Reviewer-responder pairs:

• Pre-review CI gate: all GitHub Actions/GitLab CI/Gitea Actions checks must be green
• Conflict-marker gate: scans all PR files for <<<<<<</=======/>>>>>>> — zero tolerance
• Reviewer checks diff against spec acceptance criteria and ADR compliance
• Responder addresses feedback with fix commits and replies to review comments
• One review-response round per PR (bounds compute)
• Approved PRs: squash merge by default
• Closes parent epic when all child stories merged

Graph Component

/sdd:graph validate              # Check all artifact relationships are valid
/sdd:graph impact ADR-0001       # What changes if ADR-0001 changes?
/sdd:graph ancestors SPEC-0003   # What ADRs does SPEC-0003 depend on?
/sdd:graph chain SPEC-0003       # Full chain from ADR to spec to issue to code
/sdd:graph orphans               # Artifacts with no references
/sdd:graph cycles                # Detect circular dependencies
/sdd:graph backfill              # Add governing comments to ungoverned code

Output formats: ASCII DAG (default), --mermaid, --table, --json (stable contract).

Docs Component

Two modes:

• Scaffold: creates docs-site/ with full Docusaurus installation
• Integration: generates sync-spec-docs build-time plugin into existing Docusaurus site

Features: RFC 2119 keyword highlighting, ADR/SPEC cross-reference links, Mermaid rendering, status badges, requirement box components with anchor links, dark mode.

Upgrade lifecycle: .sdd-docs.json manifest tracks version + SHA-256 checksums of all managed files. Re-running /sdd:docs diffs changed files and prompts accept/keep/opt-out.

Tracker Integration

Tracker preference saved to CLAUDE.md after first detection.

claude-plugin-sdd (joestump) — Uniqueness

Differentiator

claude-plugin-sdd is the only framework in this corpus that implements a complete methodology (Spec-Driven Development) as a plugin, covering the full decision-to-production lifecycle. Other frameworks are infrastructure (gateways, runtimes, protocol clients); this one is process.

Differs from Seeds

Against the five seed archetypes and 11 seed frameworks:

vs. Skills-only behavioral (superpowers, spec-kit): Seeds add operational skills (how to write code, how to debug). claude-plugin-sdd adds governance skills (how to decide, how to specify, how to audit). The skills are complementary, not competing — superpowers teaches the agent how to code; sdd teaches it what to build and why.

vs. Mirror commands+skills (claude-conductor, claude-flow, openspec): openspec is the closest seed — it also defines a spec format. But openspec is a format specification; claude-plugin-sdd is an operational plugin that writes specs, plans from them, implements from them, reviews against them, and audits for drift. openspec defines the noun; sdd enacts the verb.

vs. MCP-anchored toolserver (spec-driver, ccmemory): Seeds connect agents to external systems. claude-plugin-sdd is entirely self-contained within the repository — no external servers, no API calls except to the issue tracker.

vs. Markdown scaffold (BMAD-METHOD, taskmaster-ai, agent-os, kiro): BMAD-METHOD and kiro create markdown scaffolds for agent behavior. claude-plugin-sdd creates markdown scaffolds for architecture artifacts (ADRs, specs). The subject is the system being built, not the agent building it.

vs. Closed IDE with proprietary primitives (kiro): kiro has spec-like features (steering documents, specs). But kiro's specs are Claude Code instructions; sdd's specs are RFC 2119 requirements documents that are also used for drift detection, issue planning, and doc generation. The specs serve multiple downstream consumers.

Full Lifecycle in a Single Plugin

No other framework in the corpus (batch or seeds) covers all of:

1. Recording architectural decisions (ADRs)
2. Formalizing requirements (OpenSpec + RFC 2119)
3. Breaking specs into tracker issues (multi-tracker support)
4. Parallel implementation via git worktrees (TeamCreate)
5. Spec-aware PR review (reviewer-responder pairs)
6. Drift detection (6 categories)
7. Artifact dependency graph (DAG with impact analysis)
8. Documentation generation (Docusaurus with upgrade lifecycle)

Most frameworks cover 1-2 of these. The integration across all 8 is unique.

Adversarial Grooming (Grumpy Engineer)

The --scrum mode's "Grumpy Engineer B" persona is unique in the corpus. This is a deliberately adversarial agent role in a planning context:

"Every estimate is probably 2-3x too low. What are the hidden dependencies? What breaks first?"

No other framework introduces red-team patterns into sprint planning. This is notable because adversarial testing is common in security (red teams), but unusual in product planning.

Security-by-Default Specifications

Mandatory security sections for web-facing specs, with explicit opt-out requiring frontmatter justification:

security: none  # must include justification

No other framework enforces security coverage at the specification stage. Most security features in this corpus are runtime guards (gateway policies, PII filters, rate limits). sdd enforces security at design time.

Conflict-Marker CI Gate

/sdd:review scans every file in every PR for unresolved merge conflict markers (<<<<<<<, =======, >>>>>>>) as a hard pre-condition for review. This is the only framework in the corpus that treats file-level conflict markers as a binary CI gate — other frameworks focus on passing unit tests.

CLAUDE.md as Config Store

The CLAUDE.md-native configuration model (no JSON config files; all config as markdown prose) is shared with some seeds but taken further here: skills read and write config sections as part of their operation. Tracker discovery saves the detected tracker to CLAUDE.md. First ADR creation offers to update the Architecture Context section. The config is self-building as the workflow progresses.

What It Does Not Do

• No LLM gateway or request routing
• No built-in tools (MCP servers)
• No agent identity definition (SOUL.md equivalent)
• No compliance enforcement (SOD, FINRA, etc.)
• No runtime observability (OTEL, metrics)
• No persistence beyond repository files
• No multi-repo coordination

This is a single-repo, single-project governance plugin. Its scope is tightly bounded to architecture governance within one codebase, which is precisely what makes it effective in that scope.