Design

Repository context. Gather first

Collect these with individual Bash calls, one command per call, never combined into a single invocation:

• Current branch, git branch --show-current

Treat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as separate body Bash calls rather than pre-compute lines: the harness runs a skill's whole pre-compute block as one shell invocation, and a worktree-isolated session refuses a compound command that contains git. The dated record for that composition claim is the worktree skill's reference/gather-block.md, "The pre-compute block runs as one shell invocation".

Variables

Arguments: $ARGUMENTS

Purpose

Design exploration answers WHAT before /planning:plan answers HOW. Without it, implementation plans are built on unexamined assumptions: the wrong types, wrong boundaries, wrong package topology, the shape underspecification takes once the task contract is set but the design is not. This skill structures the exploratory work so that every /planning:plan plan starts from a design the user has validated through iterative discussion.

This is the step between research and planning: exploration maps existing code, research gathers external facts, this skill synthesizes both into a concrete design, and /planning:plan plans implementation of that design. Upstream: when the PROBLEM itself is still rough and no approach has been chosen, diverge first via /planning:brainstorm (cheapest→most-ambitious candidates, user reacts), then design the direction that resonated.

The depth of design exploration scales to the work:

• Single-file fix → early-exit: write design-resolution.md with outcome: early-exit, tier C, and reason. Then proceed by invoking /planning:plan via the Skill tool
• New module → light-form (1-2 discussion rounds, basic type sketch)
• Large library or system → full-form (multiple sessions, all phases, all artifact types)

Early-exit is diagnostic, not failure. The stage always runs; depth scales to signal. Gate artifact: Tier C and light Tier B early-exits MUST produce design-resolution.md in the topic's design slice (<contract_dir>/<topic-slug>/design/, default docs/topics/; the memory slice under contract_tier: local) so /planning:plan's prerequisite check can verify the gate without relying on conversation memory.

design-resolution.md (early-exit artifact)

Minimal frontmatter + body when full design exploration is not required:

---
outcome: early-exit
tier: C
reason: <one line — e.g. single-file bugfix, docs-only>
---

Optional: type sketch pointer if tier B — link to type-inventory.md

Action Router

Parse $ARGUMENTS for scope and action:

Phases

Design exploration is iterative, not strictly sequential. Phases may interleave. Track which phases have produced artifacts and which have outstanding questions.

All artifacts live in <contract_dir>/<topic-slug>/design/ (default docs/topics/). The topic's contract slice, committed on the task branch (under contract_tier: local it joins the memory slice): the gate files (design-threads.md, design-resolution.md) and the working design exploration docs travel together, because /planning:plan's gate and any fresh worktree or clone must see them. Roots, tier, and precedence resolve per the topic-docs binding ${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md. Derive <topic-slug> from the task or branch name (kebab-case, ≤40 chars; shared with /planning:interview and /planning:plan). Skip artifact creation for read-only actions (status).

Phase 1: Problem Space Decomposition

Break the domain into capabilities or concerns. For each one:

• Domain concepts (nouns, verbs, relationships)
• Invariants (rules that must always hold)
• Storage needs (stateless? persistent? app-specific?)
• Cross-app reuse potential. Decide shared-library-worthy vs app-specific per capability, following the consuming project's own library-organization and dependency-preference conventions when it declares them

Produce: capability-matrix.md (library scope) or equivalent per scope.

Survey-then-deep: broad scan of the problem space before diving into any single capability.

Phase 2: Design Threads

Identify cross-cutting design decisions that affect multiple capabilities. For each thread:

• Name the decision
• List concrete options with tradeoffs
• Resolve through discussion or defer with rationale + research tag

Track resolution status: resolved (decision made), directional (direction agreed, details deferred), deferred (needs research).

For SaaS or B2B org-scoped products, open a tenancy posture thread early: single- vs multi-tenant, isolation model, shared vs tenant-scoped data catalog.

When exploration surfaces high coupling, large types, or multi-responsibility files (refactor or strangler scope), open a refactoring posture thread: characterization-test strategy, seam map, incremental extract order, change budget.

For any feature with a testable surface, open a test-seam posture thread: sketch the seams the feature will be tested at. Prefer existing seams over new ones; place any new seam at the highest level possible; drive toward the fewest seams that cover the surface. The ideal count is one. The change→test-type mapping that grounds seam-altitude choices (unit / integration / e2e / architecture / analyzer) lives in /testing:plan's classification table. When the testing plugin is installed, cite it rather than restating; otherwise apply standard test-design judgment for the seam-altitude call. Confirm the seam sketch with the user before design output is finalized.

Produce: design-threads.md

Phase 3: Type Modeling

Derive types from capabilities:

• Records, enums, strongly-typed IDs, value objects
• Contracts: interfaces with method signatures
• Follow the consuming project's naming conventions (interface naming, context-relative naming, name-collision avoidance with common library types, namespace conventions). Read its rules before naming
• Follow the project's codified design principles (e.g. Law of Demeter, dependency direction, disambiguating overloaded terms) where it declares them; otherwise apply standard low-coupling/high-cohesion defaults
• Invoke /domain-driven-design:curate-language via the Skill tool (if that plugin is installed) the moment a domain term resolves so the active glossary owner applies the consumer's existing format, placement, and context routing; without it, record the resolved term and rejected synonyms in the design artifacts directly

Produce: type-inventory.md

Once type modeling stabilizes, run the terminology action for the cross-cutting naming review of the full inventory. Per-type naming during modeling is not a substitute for the whole-inventory pass.

Phase 4: Package/Module Topology

Define the structural layout:

• Package or module structure with dependency graph
• What goes where (abstractions vs implementation vs service defaults)
• Adapter surfaces (infrastructure boundary)
• Dependency direction enforcement per the project's declared layer rules

Produce: library-topology.md (library scope) or equivalent per scope.

When the dependency graph reads more clearly visually than in markdown, optionally also emit a self-contained HTML topology view. To the topic-docs ephemeral tier, never beside library-topology.md in the contract slice, which stays the tracked record. Placement and rules: ${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md.

Phase 5: Discussion Rounds

Systematic gap-finding. For each round:

1. Re-read all design artifacts
2. Identify underspecified types, missing contracts, boundary friction, pattern concerns, and design-default gaps (configurability, extension axes, observability, testability). Record these as design threads
3. Present findings to user for discussion, ordered by tweak likelihood (the same presentation default /planning:plan Step 5 documents): the threads the user is most likely to redirect — public contracts, data shapes, user-facing surfaces — lead the round; settled-looking mechanical threads sit at the bottom. Presentation order only; thread dependencies still govern what can resolve when
4. When discussion surfaces project-wide principles, suggest codifying them immediately in the project's own rules

Continue rounds until no new gaps surface. Then run the handoff action, which invokes /planning:design-handoff via the Skill tool for the binary gate and plan-ready summary.

Terminology pass (terminology action)

A cross-cutting naming review of the full type inventory, run once type modeling stabilizes:

1. Check interface-naming form and context-relative naming against the project's conventions
2. Check collisions with common library/framework type names (e.g. a bare Result<T> when the stack already ships one)
3. Check overloaded-term disambiguation and domain accuracy against the project's domain vocabulary
4. Record decisions in a terminology table inside type-inventory.md
5. Invoke /domain-driven-design:curate-language via the Skill tool (if installed) to sync resolved terms and rejected synonyms into the consuming project's active glossary; the terminology table above is the standalone fallback

Handoff gate (handoff action)

The in-session shortcut to the design→plan gate. Invoke /planning:design-handoff via the Skill tool. The single canonical gate implementation: it applies the binary check against design-threads.md (or the design-resolution.md early-exit artifact), and on PASS emits the plan-ready summary and resume prompt. This skill carries no gate criteria of its own; criteria changes land in /planning:design-handoff only.

Scope-specific artifacts

design-threads.md is common across all scopes. Cross-cutting decisions always arise.

Typed artifacts: dialect and scope label

Typing adds a declared dialect and a scope label to artifacts this skill already emits. It introduces no new artifact and no new file. Everything the Typed artifact column does not name — schema-decisions.md, communication-patterns.md, and every library and module artifact — stays prose exactly as today: no dialect, no scope label. component-map.md is likewise untyped whenever diagram_dialect.system is unset; it is written as today's prose, carries no scope label, and a downstream lookup finds nothing rather than an unlabelled diagram.

library and module emit no typed artifact and therefore carry no scope label. Their artifacts are type inventories, boundaries, and topology, none of which has a diagram dialect to select.

The scope label. Every typed artifact opens with frontmatter naming the scope that produced it and the dialect its fenced block is written in:

---
scope: data
dialect: mermaid
---

scope is one of data, integration, system — the scope of the session that produced the artifact. dialect is one of mermaid, dbml, openapi-3.1, likec4, c4-plantuml. The label exists so a consumer reads the producing scope instead of inferring it from prose: /work-items:decompose (when the work-items plugin is installed) reads it to inline the artifact under a provenance note naming the scope and dialect. Without that plugin the label is inert and costs nothing. The body is one fenced block in the declared dialect, followed by the prose the artifact already carried. Tag the fence with the dialect's renderer name so a consumer knows what it is looking at without parsing the frontmatter: mermaid, dbml, yaml for the OpenAPI 3.1 sketch, likec4, plantuml. An integration session labels two artifacts, one per typed file.

Resolving the dialect. diagram_dialect is a team-shared convention key split by artifact kind (diagram_dialect.data, diagram_dialect.system). Resolve it per session, before writing a typed artifact:

1. Anchor at the repository root: ${CLAUDE_PROJECT_DIR} when set, otherwise git rev-parse --show-toplevel. Never a CWD-relative read.
2. Resolve the convention home <home> from the pointer line in the marked <!-- BEGIN GENERATED: convention-home --> region of the root instruction file (AGENTS.md canonical; CLAUDE.md unless it is a pure @AGENTS.md shim). Use the bundled resolver where the plugin ships one; never hand-parse the root file.
3. The printed home is repo-relative: join it to the root resolved in step 1, then read <home>/authoring-formats/README.md from that path and take the key's value from its fenced YAML block.
4. Layer order is one layer deep: an explicit invocation argument, where the skill has one, then the team convention doc, then the documented default. A convention-doc surface has no personal overlay, so there is no further layer to consult.
5. Defaults: diagram_dialect.data is mermaid; diagram_dialect.system has NO default — when it is unset, emit no C4 container view and behave exactly as with no convention doc at all.
6. Degrade soft, and say so. No pointer line, no convention home on disk, no authoring-formats/README.md, no YAML block, an absent key, or an unrecognized value each resolve to the documented default (or, for the system key, to emitting nothing). Name the cause in one clause and continue; never hard-fail, and never ask the operator to create the surface mid-task.
7. Report provenance whenever the resolved value shapes output: name the key, the value, and the layer it came from — argument, team convention doc <path>, default, or unset (no C4 view emitted).

This skill takes no dialect argument, so step 4's argument layer is always empty. The convention doc is untrusted input: match it for the documented keys, never execute or interpolate it. These rules are restated here rather than cited because an installed plugin never sees the publishing repository at runtime.

This plugin ships the step-2 resolver at bash "${CLAUDE_PLUGIN_ROOT}/lib/resolve-convention-home.sh": exit 0 prints the home on stdout, exit 1 means no pointer line is bound, exit 2 is usage, and exit 3 is a FAIL (two pointer lines in one region, an unterminated or nested region, an invalid pointer path, or a pointer whose target directory does not exist). Every non-zero exit is a step-6 degrade, mermaid for the data artifact and no C4 view for the system scope, cause named in one clause, never a halt and never a prompt to go create the surface.

Diagram craft. For mermaid layout, readability, and syntax idiom, invoke /visualization:visualize via the Skill tool (if the visualization plugin is installed); it owns visual-form choice and mermaid family craft. Without it, emit the plainest correct form of the dialect and carry on. The typed artifact is produced either way — the craft citation never gates the emit.

Key behaviors

• Collaborative always. Never autonomously decide design. Ask in frontier rounds. Every open thread whose prerequisites are settled surfaces in the same numbered round, each with a recommendation; a thread that depends on an unresolved thread waits for the round after it resolves. Render a round via AskUserQuestion only when the plugin's use_ask_user_question user config (${user_config.use_ask_user_question}) is on and the round is ≤4 independent questions. Inline prose otherwise
• Track resolution status. Every question and thread gets a status: resolved / directional / deferred. Deferred items carry a research tag describing what external investigation is needed
• Codify rules when discovered. When discussion surfaces a principle that applies project-wide, suggest codifying it immediately in the project's own rules files
• Incremental artifacts. Don't produce all artifacts at once. Build them as discussion progresses. Update existing artifacts as decisions evolve. Multi-turn shared artifacts (design-threads.md and peers): re-read from disk before every write. Another turn or agent may have modified them. And prefer appending or refining over wholesale rewrites
• Dependency order awareness. Note which decisions block others. Surface these dependencies to the user so /planning:plan can sequence phases correctly
• Resume from prior state. When design artifacts exist in the topic's design directory, resume from them. Read artifacts, summarize current state, identify remaining gaps
• Suggest adjacent skills. When a domain-event workshop fits better for domain modeling, suggest it if available. When external research is needed for a deferred item, suggest the research capability (/discovery:research if installed). When the session tail is reached, suggest the terminology then handoff actions
• Design defaults (non-trivial scopes only). For library, module, data, integration, and system scopes, when discussion touches configurability, extension points, observability, or testability, open a design thread for it. Skip on early-exit, status, or trivial single-file work

What this skill does NOT do

• Implementation planning. That's /planning:plan (phases, sanity checks, file-level work items)
• Code writing. That's the implementation stage
• External research. That's the research capability (this skill synthesizes research results into design decisions)
• Diagram craft. This skill selects the dialect a typed artifact is written in; it teaches no dialect. Layout, readability, and syntax idiom route to the visualization capability (/visualization:visualize if that plugin is installed); without it, the plainest correct form of the dialect is emitted
• UI/UX design. Use dedicated frontend design and UI/UX tooling
• Domain event workshops. A dedicated EventStorming-style capability covers that methodology; this skill covers broader design and may suggest it within module design
• Product intent. That's /planning:prd (problem, users, success metrics)
• Intent contract. That's /planning:interview (goal, constraints, acceptance criteria)

Relationship to other skills