Design Skill

Produce dense design documents that guide implementation by downstream agents (Sonnet/Haiku).

Mode Detection

TDD Mode: Test-first culture, user mentions TDD/tests, behavioral verification needed. General Mode: Infrastructure, refactoring, migrations, prototypes. Default.

Mode determines downstream consumer: TDD → /plan-tdd, General → /plan-adhoc.

Process

0. Complexity Triage

Before doing design work, assess whether design is actually needed:

Simple (no design needed):

• •Single file, obvious implementation, no architectural decisions
• •→ Execute directly. Update session.md with what was done.

Moderate (planning needed, not design):

• •Clear requirements, no architectural uncertainty, well-defined scope
• •→ Skip design. Route to /plan-adhoc (or /plan-tdd in TDD mode), which has its own tier assessment.

Complex (design needed):

• •Architectural decisions, multiple valid approaches, uncertain requirements, significant codebase impact
• •→ Proceed with Phases A-C below.

Session state check: If session has significant pending work (>5 tasks), suggest /shelve before proceeding.

Phase A: Research + Outline

Objective: Load context, explore codebase, research external resources, produce plan outline.

A.1. Documentation Checkpoint

Purpose: Systematic documentation loading — replaces ad-hoc memory discovery.

Hierarchy (each level is fallback when previous didn't answer):

Not all levels needed for every task. Level 1 is always loaded. Levels 2-5 are conditional on task domain.

Level 1 clarification: Memory-index is an ambient awareness index — keyword-rich entries that surface relevant knowledge. It is NOT the only way to discover local knowledge. For targeted doc collection (e.g., "what do we know about agent patterns?"), the designer can also:

• •Delegate quiet-explore to read and summarize agents/decisions/ and agent-core/fragments/
• •Use Grep to search for specific topics across decision/fragment files
• •These approaches work well when the doc volume is small enough to read completely

Flexibility: The checkpoint is domain-aware, not prescriptive. Designer identifies what domain the task touches and loads relevant docs for that domain. No fixed "always read X" list beyond level 1 core.

Design decision escalation does NOT apply here. /opus-design-question is for planning/execution phases that hit unexpected architectural choices. Design sessions exist to make those decisions — the designer reasons through them directly.

A.2. Explore Codebase

CRITICAL: Delegate exploration. Opus must not grep/glob/browse directly.

Use Task tool with subagent_type="quiet-explore". Specify report path: plans/<job-name>/reports/explore-<topic>.md. Agent writes findings to file and returns filepath.

A.3-4. External Research (if needed)

Context7: Call MCP tools directly from main session (unavailable in sub-agents). Write results to report file: plans/<job-name>/reports/context7-<topic>.md.

Web research: WebSearch/WebFetch for external patterns, prior art, or specifications.

A.5. Produce Plan Outline

Output: Freeform summary presented to user in conversation (not a file).

Content:

• •Approach summary
• •Key decisions
• •Open questions
• •Scope boundaries

Plugin-topic detection: If design involves Claude Code plugin components (hooks, agents, skills), note in outline: "Plugin-topic: [component type] — load plugin-dev:[skill-name] before planning."

Example outline (for reference — adapt to task):

Approach: Add rate limiting middleware to API gateway using token bucket algorithm.
Key decisions: Per-user limits (not global), Redis-backed counters, 429 response with Retry-After header.
Open questions: Should rate limits vary by endpoint? Should admin users be exempt?
Scope: API gateway only. Dashboard/monitoring out of scope.
Plugin-topic: Involves hook development (PreToolUse validation) — load plugin-dev:hook-development before planning.

Escape hatch: If user input already specifies approach, decisions, and scope (e.g., detailed problem.md), compress A+B by presenting outline and asking for validation in a single message.

Phase B: Iterative Discussion

Objective: Validate approach with user before expensive design generation.

Process:

• •User provides feedback on outline
• •Designer responds with incremental deltas only — not full outline regeneration
• •Loop until user validates approach
• •This is conversation, not document generation — keep it light

Termination: If user feedback fundamentally changes the approach (not refining it), restart Phase A with updated understanding. Phase B is for convergence, not exploration of new directions.

Convergence guidance: If after 3 rounds the outline is not converging, ask user whether to proceed with current state or restart with different constraints.

Phase C: Generate Design

Objective: Produce full design document, review, fix, commit.

C.1. Create Design Document

Output: plans/<job-name>/design.md

Content principles:

• •Dense, not verbose - downstream agents are intelligent
• •Decisions with rationale, not just conclusions
• •Concrete file paths and integration points
• •Explicit scope boundaries (in/out)

Structure guidance (adapt as needed):

• •Problem statement
• •Requirements (functional, non-functional, out of scope)
• •Architecture/approach
• •Key design decisions with rationale
• •Implementation notes (affected files, testing strategy)
• •Documentation Perimeter (see below)
• •Next steps

TDD mode additions: Spike test strategy, confirmation markers for uncertain decisions, "what might already work" analysis.

Documentation Perimeter section:

Include this section specifying what the planner should read before starting:

## Documentation Perimeter

**Required reading (planner must load before starting):**
- `agents/decisions/architecture.md` — module patterns, path handling
- `agent-core/fragments/delegation.md` — quiet execution pattern
- `plans/{job-name}/reports/explore-{topic}.md` — exploration results

**Context7 references:**
- `/anthropics/claude-code` — hook configuration patterns (query: "PostToolUse hooks")

**Additional research allowed:** Planner may do additional Context7 queries or exploration for technical implementation details not covered above.

Rationale: Designer has deepest understanding of what knowledge the task requires. Encoding this explicitly prevents planner from either under-reading (missing critical context) or over-reading (wasting tokens on irrelevant docs).

Plugin-related topics (hooks, agents, skills, plugins): When the design involves Claude Code plugin components, include a skill-loading directive in "Next steps":

• •Hooks → Load plugin-dev:hook-development before planning
• •Agents → Load plugin-dev:agent-development before planning
• •Skills → Load plugin-dev:skill-development before planning
• •Plugin structure → Load plugin-dev:plugin-structure before planning
• •MCP integration → Load plugin-dev:mcp-integration before planning

This ensures the planner has domain-specific guidance loaded before creating the runbook.

C.3. Vet Design

CRITICAL: Delegate to opus subagent for review.

Use Task tool with subagent_type="general-purpose", model="opus":

Review plans/<job-name>/design.md for:
1. Completeness - Missing requirements or edge cases?
2. Clarity - Ambiguous decisions or insufficient rationale?
3. Feasibility - Implementation complexity realistic?
4. Consistency - Conflicts with existing patterns?

Return concise feedback with actionable fixes.

C.4. Apply Fixes

Address all high and medium priority feedback from vet review.

Update design.md with corrections. Low priority items can be deferred or documented as known limitations.

C.5. Handoff and Commit

CRITICAL: As the final action, invoke /handoff --commit.

This tail-call chains:

1. •/handoff updates session.md with completed design work
2. •Tail-calls /commit which commits the design document
3. •/commit displays STATUS showing next pending task

The next pending task will typically be the planning phase (/plan-adhoc or /plan-tdd).

Why: Universal tail behavior ensures consistent workflow termination. User always sees what's next.

Output Expectations

Design documents are consumed by planning agents (/plan-tdd or /plan-adhoc).

Minimize designer output tokens by relying on planner inference:

• •Omit obvious details planners can infer
• •Focus on non-obvious decisions and constraints
• •Provide enough context for autonomous planning
• •Flag areas requiring user confirmation

Large tasks require planning anyway - dense design output naturally aligns with planning needs.

Constraints

• •High-capability model only (deep reasoning required)
• •Delegate exploration (cost/context management)
• •Dense output (minimize designer output tokens)