The SDD Plugin Workflow

The SDD plugin follows a deliberate, four-phase workflow: Decide → Specify → Plan → Build. Each phase produces artifacts that inform the next, creating a traceable path from architectural intent to working code — with agents handling the heavy lifting at every step.

Client-facing work gets an optional phase in front of it: Capture Intent, which produces a PRD. Most projects never use it, and that is the intended outcome — see below.

Phase 0: Capture Intent (PRD) — optional

Client-facing requests arrive vague. "Add a dashboard." "Support SSO." The gap between that ask and a rigorous spec is the interrogation that precedes it, and a PRD is where that interrogation is recorded in the client's own language, with a sign-off boundary.

/sdd:prd Client portal approvals

Skip this phase for pure engineering decisions. A namespace rename or a caching strategy has no product intent upstream, and the plugin treats the absence of a PRD as normal — /sdd:check and /sdd:audit will never report an ADR or spec for not having one. Reach for a PRD only when the requester wants a client-ready document, or when the requirements have to be interrogated out of a stakeholder before engineering can start.

What makes it more than a template:

• Grill-first. The skill maps the request as a design tree and works the question frontier in rounds before drafting a line — exploring facts from the repository itself and putting only decisions to you. The Q&A rounds become the PRD's clarification log, which for client work is the visible evidence of the thinking behind the document.
• Success criteria in EARS syntax. "While the approval is pending, when the SLA window elapses without a human response, the system shall escalate to the next approver" is a check an execution agent can run. "Approvals should be timely" is not. The syntax is validated, so the difference stops depending on discipline.
• A blast radius confirmed against the code. Every existing surface the capability touches, each framed as a collision question and grepped rather than assumed.

PRDs live in docs/prds/ with sequential PRD-XXXX IDs and move through draft → client-review → approved → shipped. Those gates are enforced, not decorative: an approved PRD that governs no ADR or spec is a finding, and a shipped one whose success criteria carry no evidence is a critical one.

The lineage is PRD → ADR → spec pair → plan → work, and the handoff into the next phase is mechanical:

PRD section	Becomes
User stories	The spec's requirements
Success criteria (EARS)	The spec's WHEN/THEN scenarios
Blast radius / touch points	The impact analysis
Decision log	The ADRs the spec's design section cites

One PRD, several specs

A PRD often spans more than one capability, which is why PRDs live in their own directory rather than beside a spec. It declares governs: edges into every ADR and spec it produces, so /sdd:graph impact PRD-0001 answers "what does this client request actually touch?" across all of them.

Phase 1: Decide (ADR)

Every significant choice starts with an Architecture Decision Record. ADRs capture why you chose one approach over another — the context, the alternatives you considered, and the consequences you accepted.

/sdd:adr Add authentication using JWT tokens

This creates a MADR-format document with structured sections:

• Context and Problem Statement — what are you solving?
• Decision Drivers — what matters most?
• Considered Options — what alternatives did you evaluate?
• Decision Outcome — what did you pick and why?
• Pros and Cons — honest tradeoffs for each option
• Architecture Diagram — a Mermaid diagram showing the decision's impact

After creating the ADR, the agent suggests formalizing the decision into a specification with /sdd:spec.

Use --review for important decisions

For consequential decisions, add the --review flag to spawn a two-agent team: a drafter writes the ADR and an architect reviews it, with up to 2 revision rounds.

/sdd:adr Add authentication using JWT tokens --review

Phase 2: Specify (OpenSpec)

Once a decision is accepted, formalize the requirements as a specification. OpenSpec separates what the system does (spec.md) from how it works (design.md), so requirements and architecture can evolve independently.

/sdd:spec Authentication Service

This creates a paired set of documents:

spec.md — Requirements using RFC 2119 normative language:

• MUST, SHALL — mandatory requirements
• SHOULD, RECOMMENDED — strong suggestions
• MAY, OPTIONAL — permitted behavior
• WHEN/THEN scenarios for each requirement

design.md — Architecture and rationale:

• System context and goals
• Key decisions with rationale and alternatives
• Architecture diagrams
• Risks and mitigations

Multiple specs per ADR

A single ADR might spawn multiple specs. For example, an ADR about "choosing a microservices architecture" could lead to separate specs for the API gateway, service discovery, and inter-service communication.

Phase 3: Plan (Sprint Planning)

Once a spec exists, break it down into trackable work items with /sdd:plan:

/sdd:plan authentication-service
/sdd:plan SPEC-0003

The plan skill groups requirements into 3–4 story-sized issues by functional area — not one issue per requirement. Each story targets a 200–500 line PR and contains a task checklist that maps every requirement back to its story for full traceability. This keeps PRs reviewable and the tracker uncluttered.

The skill handles the full planning pipeline automatically:

1. Detects your issue tracker — checks for Beads, GitHub, GitLab, Gitea, Jira, and Linear. Saves your choice to .claude-plugin-design.json so you're not asked again.

2. Creates an epic and stories — one epic per spec, 3–4 story issues grouped by functional area (Setup, Core Logic, Validation, Extensions). Each story body contains a ## Requirements checklist with requirement names, normative statements, and WHEN/THEN scenarios from the spec.

3. Creates and enriches projects — a tracker-native project with description and README (GitHub Projects V2 gets iteration fields and named views; Gitea gets milestones and board columns).

4. Adds branch and PR conventions — every issue body gets a ### Branch section (feature/{issue-number}-{slug}) and a ### PR Convention section with the tracker-specific close keyword.

5. Produces a plan report — counts of epics, stories, and requirements covered, with links to where everything lives.

Falls back to a tasks.md file co-located with the spec if no tracker is available.

Use --scrum for a fully groomed sprint

Add --scrum to run a complete team-groomed ceremony: spec completeness audit, five-agent backlog review (including a grumpy high-bar engineer), dissent resolution, and automatic organize + enrich — all in one command.

/sdd:plan SPEC-0003 --scrum
/sdd:plan --scrum            # groom full backlog

See the Sprint Planning guide for a full walkthrough.

Retroactive enrichment

Already have issues from a previous /sdd:plan run? Use /sdd:organize to group them into projects and /sdd:enrich to add branch naming and PR conventions to their bodies — without re-creating the issues.

/sdd:organize SPEC-0003
/sdd:enrich SPEC-0003

Phase 4: Build (Execute + Validate)

With decisions recorded, requirements specified, and work items planned, it's time to build. Prime the session with architecture context and let agents work through the backlog.

/sdd:prime authentication

This loads the relevant ADRs and specs into context. Agents pick up unblocked tasks, claim them, and work through the backlog with full architectural awareness.

Governing comments

As agents implement code, they leave governing comments that trace implementation back to decisions and requirements:

// Governing: ADR-0001 (chose JWT over sessions), SPEC-0003 REQ "Token Validation"
function validateToken(token: string): Claims {
  // ...
}

These comments serve two purposes:

• Future agents (and humans) can understand why code is written a certain way
• /sdd:check uses them to detect drift between code and specs

Check for drift as you go

As implementation progresses, use drift detection to catch divergence early:

/sdd:check src/auth/

And run a full audit at milestones:

/sdd:audit

Use --scrum on audit to triage findings

After a full audit, --scrum replaces the raw findings table with a prioritized remediation roadmap. A six-role triage team groups findings into functional themes, assigns P1/P2/P3 priority and effort estimates, and separates "fix the code" findings from "update the spec" findings.

/sdd:audit --scrum
/sdd:audit auth --scrum    # scoped to auth domain

Example: End-to-End

Here's a concrete example of the full workflow for adding a notification system to a project.

1. Record the decision

/sdd:adr Add WebSocket-based real-time notifications --review

The drafter and architect produce an ADR exploring WebSockets vs SSE vs polling. The team accepts WebSockets for bidirectional communication needs.

2. Write the specifications

/sdd:spec Notification Service

The agent writes SPEC-0004 with requirements for event types, delivery rules, and notification preferences — each with WHEN/THEN scenarios.

3. Plan the sprint

/sdd:plan SPEC-0004

The agent:

• Detects Beads (finds .beads/ in the project root) and offers to save the preference to .claude-plugin-design.json
• Creates an epic: "Implement Notification Service"
• Groups requirements into 3 stories by functional area:
  • Story 1: "Setup & Event Schema" (REQ "Event Types", REQ "Schema Validation")
  • Story 2: "Delivery Engine & Preferences" (REQ "Delivery Rules", REQ "Preferences")
  • Story 3: "Connection Management & Reconnection" (REQ "WebSocket Lifecycle", REQ "Backoff Strategy")
• Each story body contains a task checklist:

  ## Requirements
  - [ ] **REQ "Event Types"** (SPEC-0004): system MUST validate events against registered schemas
    - WHEN unregistered event type is received THEN reject with 422 status
  - [ ] **REQ "Schema Validation"** (SPEC-0004): payloads MUST conform to registered schema
  
  ## Acceptance Criteria
  - [ ] Per SPEC-0004 REQ "Event Types": validation enforced at ingestion boundary
  - [ ] Governing: ADR-0005 (chose WebSocket-based notifications)

• Creates a GitHub Project "Notification Service" with All Work, Board, and Roadmap views, a Sprint iteration field, and a README with spec references and story index
• Adds branch names to each story: feature/42-setup-event-schema, feature/43-delivery-engine-preferences
• Adds PR conventions: each story body includes Closes #42 and Part of #41 (epic)
• Reports: "Created 1 epic, 3 stories covering 6 requirements in GitHub."

You can then plan a second spec the same way:

/sdd:spec WebSocket Gateway
/sdd:plan SPEC-0005

4. Prime and build

/sdd:prime notifications

Agents pick up unblocked tasks with full context from the ADRs and specs. The event type registry and WebSocket connection manager are unblocked and can be worked in parallel by different team members.

As they implement, agents leave governing comments:

// Governing: ADR-0005, SPEC-0004 REQ "Event Types"
const eventSchema = z.object({
  type: z.string().min(1),
  payload: z.record(z.unknown()),
  timestamp: z.string().datetime(),
});

5. Validate alignment

/sdd:check src/notifications/
/sdd:check src/websocket/
/sdd:audit --review

The audit catches that the reconnection implementation uses linear backoff instead of the exponential backoff specified in the WebSocket Gateway spec. Fixed before it ships.

Supported Issue Trackers

The sprint planning step detects and supports multiple issue trackers:

Tracker	Detection	Notes
Beads	.beads/ directory or bd CLI	Preferred for AI-agent workflows. Supports epics, tasks, sub-tasks, and dependency tracking.
GitHub Issues	gh CLI	Creates issues with labels and milestone grouping.
GitLab Issues	GitLab MCP tools or glab CLI	Creates issues via the GitLab API.
Gitea Issues	tea CLI with a login for the host	Creates issues via tea, and tea api for the rest of the Gitea API.
Jira	Jira MCP tools	Creates epics and stories in your Jira project.
Linear	Linear MCP tools	Creates issues in your Linear team.

If no tracker is detected, the agent outputs a structured tasks.md file co-located with the spec that you can use to track work manually.

The Feedback Loop

The workflow is not strictly linear. As you build, you'll discover:

• New decisions — implementation reveals choices the ADR didn't anticipate. Record them: /sdd:adr
• Spec gaps — requirements that were too vague or missing entirely. Update them: edit the spec, run /sdd:check
• Re-planning — specs evolved during implementation and the backlog needs updating. Re-run: /sdd:plan SPEC-0003
• Stale artifacts — decisions that no longer apply as the system evolved. Update their status: /sdd:status ADR-0003 deprecated
• Scope drift on client work — what shipped no longer matches what was signed off. The PRD's success criteria are the check: /sdd:audit reports a shipped PRD whose criteria have no met evidence, which is the earliest point at which "we built something else" becomes visible.

The SDD plugin's drift detection skills (/sdd:check and /sdd:audit) close this loop by surfacing misalignment before it becomes entrenched. Governing comments left by agents during implementation make drift detection faster and more accurate.