The Design Plugin Workflow

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

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.

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

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

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

/design:plan authentication-service
/design: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.

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

See the Sprint Planning guide for a full walkthrough.

Retroactive enrichment

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

/design:organize SPEC-0003
/design: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.

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

/design:check src/auth/

And run a full audit at milestones:

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

/design:audit --scrum
/design: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

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

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

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

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

4. Prime and build

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

/design:check src/notifications/
/design:check src/websocket/
/design: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	GitHub MCP tools or 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	Gitea MCP tools	Creates issues via 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: /design:adr
• Spec gaps — requirements that were too vague or missing entirely. Update them: edit the spec, run /design:check
• Re-planning — specs evolved during implementation and the backlog needs updating. Re-run: /design:plan SPEC-0003
• Stale artifacts — decisions that no longer apply as the system evolved. Update their status: /design:status ADR-0003 deprecated

The design plugin's drift detection skills (/design:check and /design: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.