[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M77M7P5AF889JA85BVERH7X6":3,"skill-same:01M77M7P5AF889JA85BVERH7X6":76},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":28,"commitSha":29,"skillDirectory":30,"forksCount":31,"repositoryHtmlUrl":32,"repositoryHomepageUrl":6,"ownerHtmlUrl":33,"ownerBlogUrl":34,"ownerDescription":35,"updatedAt":36,"install":37,"resources":49},"01M77M7P5AF889JA85BVERH7X6","design",null,"Resolve design decisions (types, contracts, package topology, module boundaries) in discussion rounds before \u002Fplanning:plan, as design artifacts. Use when: 'design this', 'type modeling', 'figure out the abstractions', 'model this domain', 'what should the types look like', 'how should I structure this', 'where do the module boundaries go', or entering \u002Fplanning:plan without exploring the design space. Skip when scanning existing code for module friction: \u002Farchitecture:improve does that, and \u002Fplanning:design resolves decisions before \u002Fplanning:plan. Handoff gate: \u002Fplanning:design-handoff.","melodic-software\u002Fclaude-code-plugins","melodic-software","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F58273638?v=4","01M77JVQTXNGKCE4MDFY2BC936","Melodic Software","01M77JVQVN9QDWKAH6W03ANP76",30,"MIT","https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fplanning\u002Fskills\u002Fdesign\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\ndescription: \"Resolve design decisions (types, contracts, package topology, module boundaries) in discussion rounds before \u002Fplanning:plan, as design artifacts. Use when: 'design this', 'type modeling', 'figure out the abstractions', 'model this domain', 'what should the types look like', 'how should I structure this', 'where do the module boundaries go', or entering \u002Fplanning:plan without exploring the design space. Skip when scanning existing code for module friction: \u002Farchitecture:improve does that, and \u002Fplanning:design resolves decisions before \u002Fplanning:plan. Handoff gate: \u002Fplanning:design-handoff.\"\nargument-hint: \"[library|module|data|integration|system] [status|thread \u003Cname>|discuss|terminology|handoff]\"\nuser-invocable: true\ndisable-model-invocation: false\nmetadata:\n  workflow-stage: design\n  summary: Resolve types, contracts, and module boundaries before planning\n---\n\n**Arguments.** `[library|module|data|integration|system] [status|thread \u003Cname>|discuss|terminology|handoff]`.\ne.g., \u002Fplanning:design library, \u002Fplanning:design module, \u002Fplanning:design status, \u002Fplanning:design discuss,\n\u002Fplanning:design handoff\n\n## Repository context. Gather first\n\nCollect these with **individual** Bash calls, one command per call, never combined:\n\n- Current branch, `git branch --show-current`\n\nTreat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as\nbody Bash calls, not pre-compute lines. How the harness runs a skill's injected commands:\n[How injected commands run](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fskills#how-injected-commands-run).\n\n## Variables\n\nArguments: `$ARGUMENTS`\n\n## Purpose\n\nDesign answers WHAT before `\u002Fplanning:plan` answers HOW: types, boundaries and package topology the\nuser has validated through discussion. Exploration maps existing code, research gathers external\nfacts, this skill turns both into a design. When the PROBLEM is still rough and no approach is\nchosen, diverge first via `\u002Fplanning:brainstorm` (cheapest→most-ambitious candidates, user\nreacts), then design the direction that resonated.\n\n**Level this skill decides: interfaces and contracts**, the types, boundaries and module shapes\nother code depends on; behavior is the interview's Brief, and files and symbols are\n`\u002Fplanning:plan`'s.\n\nDepth scales to the work:\n\n- Single-file fix → early-exit: write `design-resolution.md` with `outcome: early-exit`, tier `C`,\n  and reason. Then invoke `\u002Fplanning:design-handoff` via the Skill tool, which writes PLAN.md's\n  one-line `## Design` record and hands off to `\u002Fplanning:plan`\n- New module → light-form (1-2 discussion rounds, basic type sketch)\n- Large library or system → full-form (multiple sessions, all phases, all artifact types)\n\nThe stage always runs; early-exit is a valid outcome. **Gate artifact:** Tier C and light Tier B\nearly-exits MUST produce `design-resolution.md` in the topic's design slice\n(`\u003Cmemory_dir>\u002F\u003Ctopic-slug>\u002Fdesign\u002F`, default `.work\u002F`) so `\u002Fplanning:plan`'s prerequisite check\ncan verify the gate without conversation memory.\n\n### design-resolution.md (early-exit artifact)\n\n```markdown\n---\noutcome: early-exit\ntier: C\nreason: \u003Cone line, e.g. single-file bugfix, docs-only>\n---\n\nTier B (required): the type sketch, inline or as a link to type-inventory.md.\n\u002Fplanning:design-handoff quotes it into PLAN.md's `### Contracts`.\n```\n\n## Gates\n\nThese hold after a compaction re-attach. Later sections say how to carry them out.\n\n- **Collaborative always.** Never autonomously decide design. Ask in frontier rounds (Key\n  behaviors).\n- **Abstract is never the agent's pick.** A variation-point verdict of abstract comes only from the\n  user: interactively ask, recommending contain; unattended, apply contain and record the question\n  as a human decision. Full rule:\n  [`${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fvariation-points.md`](${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fvariation-points.md)\n  \"Autonomy\".\n- **Every recommendation carries a `Basis:` line**: `verified` with the `file:line`, tool output,\n  or URL it rests on, or `judgment` (non-consequential only). A consequential one (cross-repo,\n  shared infrastructure, irreversible, or security) is grounded before it is presented; one\n  research cannot settle is withheld, recorded as a `deferred` thread whose research tag names\n  the evidence that would settle it.\n\n## Action Router\n\nParse `$ARGUMENTS` for scope and action:\n\n| Argument | Action |\n|----------|--------|\n| *(empty)* | **Auto-detect**. Read the PLAN.md Brief + conversation to determine scope and phase. Resume if design artifacts exist. Ask if ambiguous |\n| `library` | **Library\u002FAPI design**. Packages, types, contracts, dependency graph |\n| `module` | **Module design**. Domain model, boundaries, contracts. Suggest a domain-event workshop (e.g. EventStorming) when the environment provides one |\n| `data` | **Data model design**. Entities, relationships, schema decisions |\n| `integration` | **Integration design**. Cross-system contracts, sequence flows, error handling |\n| `system` | **System design**. Components, communication patterns, deployment topology |\n| `status` | **Status report**. Resolution state per thread and question |\n| `thread \u003Cname>` | **Deep-dive**. One design thread |\n| `discuss` | **Discussion round**. Systematic gap-finding across all artifacts |\n| `terminology` | **Naming review**. Cross-cutting naming pass over the full type inventory (see \"Terminology pass\") |\n| `handoff` | **Handoff gate**. Delegates to `\u002Fplanning:design-handoff` (see \"Handoff gate\") |\n\n## Phases\n\nPhases may interleave. Track which have produced artifacts and which have open questions.\n\nAll artifacts live in `\u003Cmemory_dir>\u002F\u003Ctopic-slug>\u002Fdesign\u002F` (default `.work\u002F`), never committed;\n`\u002Fplanning:plan`'s gate reads the gate files (`design-threads.md`, `design-resolution.md`) from\nthere. Placement:\n[`${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fartifact-protocol.md`](${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fartifact-protocol.md).\n`\u002Fplanning:design-handoff` writes the durable content (module layout, contracts, variation\nverdicts, conventions followed) into PLAN.md's `## Design`, the copy that reaches the plan, the\nimplementer's brief, and the pull request body or linked issue where PLAN.md is published. Derive\n`\u003Ctopic-slug>` from the task or branch name (kebab-case, ≤40 chars; shared with `\u002Fplanning:interview` and `\u002Fplanning:plan`). Skip\nartifact creation for read-only actions (`status`).\n\n### Phase 1: Problem Space Decomposition\n\nRead the Brief's `### Problem` before decomposing; absent, start from the `Problem`, `Intent (why,\nin the user's words)` and `Chosen direction` lines of `\u003Cmemory_dir>\u002F\u003Ctopic-slug>\u002Fbrainstorm.md`'s\n`## Handoff` block when it exists; with neither, establish it:\n[`${CLAUDE_PLUGIN_ROOT}\u002Fcontext\u002Fproblem-framing.md`](..\u002F..\u002Fcontext\u002Fproblem-framing.md). Its\n`time_units` user layer is `${user_config.time_units}` (unexpanded means unset).\n\nScan the whole problem space broadly before diving into any single capability. For each capability\nor concern:\n\n- Domain concepts (nouns, verbs, relationships)\n- Invariants (rules that must always hold)\n- Storage needs (stateless? persistent? app-specific?)\n- Cross-app reuse: shared-library-worthy vs app-specific, following the consuming project's\n  library-organization and dependency-preference conventions when it declares them\n\nWhen the work adds a requirement to existing code, ask before Phase 3: had this requirement been\nknown when the code was first written, which types and boundaries would it have? Take that answer\nas the target shape, not the current shape with the requirement bolted on.\n\nProduce: `capability-matrix.md` (library scope) or equivalent per scope.\n\n### Phase 2: Design Threads\n\nIdentify cross-cutting decisions that affect multiple capabilities. For each thread: name the\ndecision, list concrete options with tradeoffs, and resolve through discussion or defer with\nrationale + research tag. Status: **resolved** (decision made), **directional** (direction agreed,\ndetails deferred), **deferred** (needs research).\n\n**Two-candidate step.** Take it when the codebase has nothing to copy for the thread, more than one\napproach is workable, and the decision is hard to reverse (a public contract, a stored format, a\nboundary other modules will build on):\n\n1. Write the criteria the candidates will be judged by into the thread before drafting any\n   candidate.\n2. Draft at least two candidates that differ in structure: who owns the state, where the module\n   split falls, or what shape the contract takes. A renamed or reordered copy of the first is not a\n   second candidate.\n3. Judge each against the written criteria, and record the rejected ones with the reason in\n   `design-threads.md`.\n\nWhen the thread is about how a screen or interaction looks or feels, invoke\n`\u002Fprototype:explore-directions` via the Skill tool when it is among the available skills. When the\ncandidates differ in logic or state (the rules, a state machine, a data model, an API surface) and\na run can settle the fork, invoke `\u002Fprototype:pressure-test observe` via the Skill tool when it is\namong the available skills, because running each candidate on the same inputs shows which one\nholds where arguing them only predicts it. The test: name the event sequence or record that the\ncriteria turn on; when nobody can yet say with confidence how each candidate handles it, a run\nsettles the fork (pstack's `exhaust-the-design-space` principle). Confirm the scope of the\nthrowaway with the user before either route. When neither route applies or its skill is\nunavailable, run the three steps here, describing each candidate in prose.\n\nOpen these threads when their trigger holds:\n\n- **Shared-state**: a type can be read and changed by more than one concurrent actor (threads,\n  processes, overlapping requests, background jobs). Cover which actors write it, what a reader\n  sees halfway through an update, and whether the type is confined to one owner, immutable, or\n  guarded.\n- **Tenancy posture** (early): SaaS or B2B org-scoped products. Single- vs multi-tenant, isolation\n  model, shared vs tenant-scoped data catalog.\n- **Refactoring posture**: exploration surfaces high coupling, large types, or multi-responsibility\n  files (refactor or strangler scope). Characterization-test strategy, seam map, incremental\n  extract order, change budget.\n- **Test-seam posture**: any feature with a testable surface. Sketch where its tests will attach;\n  reuse an existing seam before adding one, put any new seam as high in the stack as it can go, and\n  aim for the fewest seams that cover the surface. The change→test-type mapping lives in\n  `\u002Ftesting:plan`'s classification table; cite it when the `testing` plugin is enabled, otherwise\n  apply standard test-design judgment. The sketch is input, not the decision: `\u002Fplanning:plan`'s\n  Test strategy names the test boundaries from it and its Step 5 approval settles them; a seam the\n  design needs as a contract still goes in Contracts.\n\n**Variation-point pass.** Always for `integration`, `module`, and `system`; for `library` and\n`data`, when the design touches an external system or a domain category. List every variation\npoint (every external integration is one), ask the two questions (likelihood of a second variant,\ncost of change after shipping), and open one thread per point that resolves to a verdict: abstract\nnow, contain now and abstract later (the default for anything external), or leave inline (internal\none-offs only). Run the leak test on every abstraction and contained boundary, and place seams\nwhere the solution's existing architecture style already puts them. Questions, verdicts, leak test,\nautonomy rule, and sources:\n[`${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fvariation-points.md`](${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fvariation-points.md).\nA variation-intent answer from `\u002Fplanning:interview` is settled, never re-asked.\n\nProduce: `design-threads.md`\n\n### Phase 3: Type Modeling\n\nThe phase ends with a `type-inventory.md` in which every type traces to a call site that needs it,\nand each type's shape is set by the operations its busiest paths run on it. Two checks prove it:\n\n- **Call sites before types.** From consumer code, sketch two or three brief calls into the new\n  contract, written as its users will write them, before any type has a name; for a library or\n  API, at least one sits inside the importing package. A type enters the inventory only if those\n  calls need it, given the capabilities.\n- **Operations set structure.** Each entry lists its operations (lookup by key, ordered walk,\n  append, bulk replace) with the busiest-path ones flagged, and its structure is the one those\n  flagged operations favor.\n\nApply [`reference\u002Ftype-discipline.md`](reference\u002Ftype-discipline.md): Phase 3 meets each of its\nsituations while it fills `type-inventory.md`, so find the row that matches and make its decision.\nIdioms for one language sit in that language's own file under `reference\u002Ftype-discipline\u002F`; open\none only after detecting the language:\n\n| Language | File | Loaded when |\n|---|---|---|\n| TypeScript | [`reference\u002Ftype-discipline\u002Ftypescript.md`](reference\u002Ftype-discipline\u002Ftypescript.md) | the repository has a `tsconfig.json`, or the change touches `.ts`, `.tsx`, `.mts` or `.cts` files |\n\nThe inventory covers:\n\n- Records, enums, strongly-typed IDs, value objects\n- Contracts: interfaces with method signatures\n- Read and follow the consuming project's naming conventions (interface naming, context-relative\n  naming, collisions with common library types, namespaces) before naming\n- Follow the project's codified design principles (e.g. Law of Demeter, dependency direction,\n  disambiguating overloaded terms) where declared; otherwise low-coupling\u002Fhigh-cohesion defaults\n- Invoke `\u002Fdomain-driven-design:ubiquitous-language curate` via the Skill tool (if that plugin is enabled)\n  the moment a domain term resolves, so the glossary owner applies the consumer's format,\n  placement, and context routing; without it, record the resolved term and rejected synonyms in\n  the design artifacts\n\nProduce: `type-inventory.md`\n\nClose Phase 3 by auditing the inventory: for each type, follow one value from where it is made to\nwhere it is read. A fault at any stop sends that type back to the design threads.\n\n1. **Where it is made.** When a schema, spec or migration already describes the shape, the entry\n   derives from it instead of redrawing it. A value from outside the program becomes this type\n   where it arrives, and nothing further in validates that input again.\n2. **What it holds.** Try to write a mix of field values the domain forbids; a type that accepts it\n   is too loose. For each type the design strengthened, name the function that would fail on part\n   of its input without the extra strength; with none, the strength guards nothing, and that is a\n   fault too.\n3. **Where it is read.** Picture one more variant: every reading site must then fail to compile,\n   not keep running silently. On the same path, every cast, assertion or suppression has a check\n   in front of it.\n\nOnce type modeling stabilizes, run the `terminology` action over the whole inventory; per-type\nnaming during modeling does not replace it.\n\n### Phase 4: Package\u002FModule Topology\n\n- Package or module structure with dependency graph\n- What goes where (abstractions vs implementation vs service defaults)\n- Adapter surfaces (infrastructure boundary)\n- Dependency direction enforcement per the project's declared layer rules\n\nProduce: `library-topology.md` (library scope) or equivalent per scope.\n\nWhen the dependency graph reads more clearly visually, optionally also emit a self-contained HTML\ntopology view to the OS temp directory, never beside `library-topology.md`, which stays the record.\nRules:\n[`${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fartifact-protocol.md`](${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fartifact-protocol.md).\nResolve `medium` first per\n[`${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Frendered-view.md`](${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Frendered-view.md)\n\"Other optional views\", with this plugin's `medium` option `${user_config.medium}`, or `\"\"` when that\nreads empty or unsubstituted (never put a `${user_config.*}` string in a shell command), and follow\nits result, which names the report line to print.\n\n### Phase 5: Discussion Rounds\n\nEach round:\n\n1. Re-read all design artifacts.\n2. Record as design threads: underspecified types, missing contracts, boundary friction, pattern\n   concerns, and design-default gaps (configurability, extension axes, observability,\n   testability).\n3. Present findings ordered by tweak likelihood (the presentation default `\u002Fplanning:plan` Step 5\n   documents): public contracts, data shapes, and user-facing surfaces lead; settled-looking\n   mechanical threads sit at the bottom. Order only; thread dependencies still govern what can\n   resolve when.\n4. When discussion surfaces project-wide principles, suggest codifying them in the project's own\n   rules.\n\nContinue until no new gaps surface, then run the `handoff` action.\n\n## Lifecycle and reversibility\n\nSkip on early-exit, `status`, or trivial single-file work. Otherwise call each significant decision\na one-way or two-way door, prompt an ADR for each one-way door, and scale investment by subdomain\nand quality bar: [`reference\u002Freversibility.md`](reference\u002Freversibility.md).\n\n## Terminology pass (`terminology` action)\n\nOver the full type inventory, once type modeling stabilizes:\n\n1. Check interface-naming form and context-relative naming against the project's conventions\n2. Check collisions with common library\u002Fframework type names (e.g. a bare `Result\u003CT>` when the\n   stack already ships one)\n3. Check overloaded-term disambiguation and domain accuracy against the project's domain\n   vocabulary\n4. Record decisions in a terminology table inside `type-inventory.md`\n5. Invoke `\u002Fdomain-driven-design:ubiquitous-language curate` via the Skill tool (if enabled) to sync resolved\n   terms and rejected synonyms into the project's glossary; the table above is the standalone\n   fallback\n\n## Handoff gate (`handoff` action)\n\nInvoke `\u002Fplanning:design-handoff` via the Skill tool. It is the only gate implementation: it checks\n`design-threads.md` (or the `design-resolution.md` early-exit artifact) and on PASS emits the\nplan-ready summary and resume prompt. This skill carries no gate criteria of its own; criteria changes land in\n`\u002Fplanning:design-handoff` only.\n\nOn PASS, offer an interactive design view of PLAN.md's `## Design` (its sections, a tick for each one\nthe reader questions, a copy-out of the reply, sent to this session when connected). PLAN.md stays the\nrecord. Build it only with `${CLAUDE_PLUGIN_ROOT}\u002Fscripts\u002Fbuild-view.mjs` from that record, never\nhand-written; it runs the shared medium resolver and publish gate with this plugin's `medium` option\n`${user_config.medium}`, or `\"\"` when that reads empty or unsubstituted (never put a\n`${user_config.*}` string in a shell command), and you print the report line it prints. Procedure:\n[`${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Frendered-view.md`](${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Frendered-view.md).\n\n**Stub files (`scaffold_stubs`)**. Before invoking the gate, resolve `scaffold_stubs`, lowest layer\nfirst: the default `false`; the plugin's user config (`${user_config.scaffold_stubs}`, where a\nliteral unexpanded value means unset); then the `scaffold_stubs` key of the repository's\n`docs\u002Fconventions\u002Fplanning.yaml`, which wins when set, read only when the working directory's git\nroot is neither `$HOME` nor an ancestor of it. Only the bare booleans `true` and `false` are valid:\nany other value, a quoted `\"true\"` included, is named with its file (or user config), key and\nvalue, and that layer is dropped, so a valid higher layer still wins and otherwise the key is\n`false`. Report one line naming the value and its layer, e.g.\n`scaffold_stubs: true (docs\u002Fconventions\u002Fplanning.yaml)`. Keys and layers:\n[`${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fconfig.md`](${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fconfig.md).\n\nWith `true`, add a `## Stub scaffold` section to `design-threads.md` (or to `design-resolution.md`\non an early exit) listing every new file the design introduces, each with the signatures it will\ndeclare (types, function and method signatures, exported constants), from the resolved type\ninventory and contracts. Each stub body is the language's ordinary not-implemented form (for\nexample `raise NotImplementedError` in Python or `todo!()` in Rust), with no per-language reference\nfile. After the gate passes, the handoff output names those files and signatures so\n`\u002Fplanning:plan` can place the stub phase. With `false`, write no such section and name no stubs.\n\n## Scope-specific artifacts\n\n| Scope | Primary artifacts | Typed artifact | Dialect |\n|-------|-------------------|----------------|---------|\n| `library` | capability-matrix.md, type-inventory.md, library-topology.md, design-threads.md | none | none (no typed artifact, so no scope label) |\n| `module` | domain-model.md, module-boundary.md, contracts.md, design-threads.md | none | none (no typed artifact, so no scope label) |\n| `data` | entity-relationships.md, schema-decisions.md, design-threads.md | `entity-relationships.md` | mermaid `erDiagram` by default; DBML when `diagram_dialect.data` resolves to `dbml` |\n| `integration` | contract-spec.md, sequence-flows.md, design-threads.md | `sequence-flows.md`, `contract-spec.md` | mermaid `sequenceDiagram` for the flows; an OpenAPI 3.1 sketch for the contract spec |\n| `system` | component-map.md, communication-patterns.md, design-threads.md | `component-map.md`, and only when `diagram_dialect.system` names a dialect | a C4 container view in LikeC4 or C4-PlantUML, never Mermaid's [C4 diagrams](https:\u002F\u002Fmermaid.js.org\u002Fsyntax\u002Fc4.html#c4-diagrams) |\n\n`design-threads.md` is common across all scopes.\n\n### Typed artifacts: dialect and scope label\n\nTyping adds a declared dialect and a scope label to artifacts this skill already emits; no new\nfile. Everything the **Typed artifact** column does not name (`schema-decisions.md`,\n`communication-patterns.md`, every `library` and `module` artifact) stays prose with no dialect and\nno scope label. `component-map.md` is likewise untyped prose with no scope label whenever\n`diagram_dialect.system` is unset, so a downstream lookup finds nothing rather than an unlabeled\ndiagram.\n\n**The scope label.** Every typed artifact opens with frontmatter naming the producing scope and the\ndialect of its fenced block:\n\n```markdown\n---\nscope: data\ndialect: mermaid\n---\n```\n\n`scope` is one of `data`, `integration`, `system`. `dialect` is one of `mermaid`, `dbml`,\n`openapi-3.1`, `likec4`, `c4-plantuml`. `\u002Fwork-items:decompose` (when the `work-items` plugin is\nenabled) reads the label to inline the artifact under a provenance note naming scope and dialect;\nwithout that plugin the label is inert. The body is one fenced block in the declared dialect,\nfollowed by the artifact's prose. Tag the fence with the renderer name: `mermaid`, `dbml`, `yaml`\nfor the OpenAPI 3.1 sketch, `likec4`, `plantuml`. An `integration` session labels two artifacts,\none per typed file.\n\n**Resolving the dialect.** `diagram_dialect` is a team-shared convention key split by artifact kind\n(`diagram_dialect.data`, `diagram_dialect.system`). Resolve it per session, before writing a typed\nartifact, through\n[`${CLAUDE_PLUGIN_ROOT}\u002Fcontext\u002Fauthoring-formats.md`](..\u002F..\u002Fcontext\u002Fauthoring-formats.md)\n\"Resolution ladder\", where `\u003Cplugin-root>` is `${CLAUDE_PLUGIN_ROOT}` and `\u003Cproject-root>` is `${CLAUDE_PROJECT_DIR}` (unexpanded or empty means unset). This skill takes no dialect argument, so the argument layer is always empty.\n`diagram_dialect.data` defaults to `mermaid`, and every degrade writes the data artifact in\n`mermaid`. `diagram_dialect.system` has NO default: unset or degraded, emit no C4 container view\nand behave exactly as with no convention doc at all, reporting its provenance as\n`unset (no C4 view emitted)`.\n\n**Diagram craft.** For mermaid layout, readability, and syntax idiom, invoke\n`\u002Fvisualization:visualize` via the Skill tool (if the `visualization` plugin is enabled). Without\nit, emit the plainest correct form of the dialect. The typed artifact is produced either way.\n\n## Key behaviors\n\n- **Frontier rounds.** Every open thread whose prerequisites are settled surfaces in the same\n  numbered round, each with a recommendation; a thread that depends on an unresolved thread waits\n  for the round after it resolves. Render a round via `AskUserQuestion` only when the plugin's\n  `use_ask_user_question` user config (`${user_config.use_ask_user_question}`; unexpanded or empty means off) is on and the round\n  is independent questions that fit one `AskUserQuestion` call (the per-call question limit:\n  \u003Chttps:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fagent-sdk\u002Fuser-input#limitations>). Inline prose otherwise\n- **Grounding steps.** Ground a consequential recommendation in the affected code plus its\n  consumers and in external research that reads official docs first, routed to\n  `\u002Fdiscovery:explore` and `\u002Fdiscovery:research` if enabled. A recommendation that changes is\n  restated as old → new → why. Contract:\n  [`${CLAUDE_PLUGIN_ROOT}\u002Fcontext\u002Frecommendation-basis.md`](..\u002F..\u002Fcontext\u002Frecommendation-basis.md)\n- **Self-answer before asking.** Each candidate question first passes\n  [`${CLAUDE_PLUGIN_ROOT}\u002Fcontext\u002Fself-answer.md`](..\u002F..\u002Fcontext\u002Fself-answer.md): a fact it settles\n  is stated with its basis and source tag, not asked\n- **Track resolution status.** Every question and thread is resolved \u002F directional \u002F deferred.\n  Deferred items carry a research tag naming the external investigation needed\n- **Codify rules when discovered.** When discussion surfaces a project-wide principle, suggest\n  codifying it immediately in the project's own rules files\n- **Incremental artifacts.** Build artifacts as discussion progresses and update them as decisions\n  evolve. Re-read multi-turn shared artifacts (`design-threads.md` and peers) from disk before\n  every write, since another turn or agent may have changed them, and prefer appending or refining\n  over wholesale rewrites\n- **Dependency order awareness.** Surface which decisions block others so `\u002Fplanning:plan` can\n  sequence phases\n- **Resume from prior state.** When design artifacts exist in the topic's design directory, read\n  them, summarize current state, and identify remaining gaps\n- **Suggest adjacent skills.** When a domain-event workshop fits better for domain modeling,\n  suggest it if available. Suggest `\u002Fdiscovery:research` (if enabled) for a deferred item needing\n  external research, and the `terminology` then `handoff` actions at the session tail\n- **Design defaults (non-trivial scopes only).** For `library`, `module`, `data`, `integration`,\n  and `system` scopes, when discussion touches configurability, extension points, observability,\n  or testability, open a design thread for it. Extension points start from the Phase 2\n  variation-point pass. Skip on early-exit, `status`, or trivial single-file work. Apply\n  [`reference\u002Fdesign-defaults.md`](reference\u002Fdesign-defaults.md) first (quality bar, consumer\n  standards, the Brief's quality requirements, generalize-now-or-wait, per-tenant configurability\n  as vendor guidance), then recommend from every principle\n  [`design-principles.md`](${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fdesign-principles.md) lists.\n\n## What this skill does NOT do\n\n- **Implementation planning**: `\u002Fplanning:plan` (phases, sanity checks, file-level work items)\n- **Code writing**: the implementation stage\n- **External research**: the research capability; this skill synthesizes its results\n- **Diagram craft**: this skill selects the dialect; layout and idiom route to\n  `\u002Fvisualization:visualize` if enabled, else the plainest correct form is emitted\n- **UI\u002FUX design**: user research, flows and information architecture are\n  `\u002Fuser-experience:shape` (if enabled); look and response are `\u002Fuser-interface:design` (if\n  enabled)\n- **Domain event workshops**: an EventStorming-style capability; this skill may suggest it within\n  module design\n- **Product intent**: `\u002Fplanning:prd` (problem, users, success metrics)\n- **Intent contract**: `\u002Fplanning:interview` (goal, constraints, acceptance criteria)\n\n## Next\n\n- Design finished, to gate and write into PLAN.md's `## Design`, which \u002Fplanning:plan reads: \u002Fplanning:design-handoff.\n- The contract is a UI component's props API (parts, variants, controlled state): \u002Fuser-interface:design.\n\n## Relationship to other skills\n\n| Skill | Relationship |\n|-------|-------------|\n| `\u002Fplanning:interview` | **Before.** Locks the brief (scope + constraints); design explores the solution space within them |\n| `\u002Fdomain-driven-design:ubiquitous-language curate` | **During.** Owns project-glossary updates when design resolves domain language; not type or boundary design |\n| `\u002Fvisualization:visualize` (if enabled) | **During.** Owns visual-form choice and mermaid craft for a typed artifact's fenced block |\n| `\u002Fnaming:name-it-better` (if enabled) | **During.** Proposes candidates for a name the design leaves undecided; the human picks, and the pick is recorded in the terminology table |\n| `\u002Farchitecture:record-decision` (if enabled) | **During.** Records the ADR for a one-way door when its thread resolves ([`reference\u002Freversibility.md`](reference\u002Freversibility.md)) |\n| `\u002Fwork-items:decompose` (if enabled) | **After.** Reads a typed artifact's `scope` and `dialect` label to inline it into the spec container with a provenance note, and quotes each slice's part of PLAN.md's `## Design` into that slice's body |\n| `\u002Fdiscovery:explore` (if enabled) | **Before.** Maps existing code; design creates what SHOULD exist |\n| `\u002Fdiscovery:research` (if enabled) | **Before + parallel.** Gathers external facts; deferred research items can run in parallel |\n| `\u002Fplanning:design-handoff` | **The gate.** Owns the design→plan gate criteria and the plan-ready summary |\n| `\u002Fplanning:plan` | **After the handoff gate.** Produces HOW; when design artifacts exist it consumes them instead of re-deriving design |\n","**Arguments.** `[library|module|data|integration|system] [status|thread \u003Cname>|discuss|terminology|handoff]`.\ne.g., \u002Fplanning:design library, \u002Fplanning:design module, \u002Fplanning:design status, \u002Fplanning:design discuss,\n\u002Fplanning:design handoff\n\n## Repository context. Gather first\n\nCollect these with **individual** Bash calls, one command per call, never combined:\n\n- Current branch, `git branch --show-current`\n\nTreat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as\nbody Bash calls, not pre-compute lines. How the harness runs a skill's injected commands:\n[How injected commands run](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fskills#how-injected-commands-run).\n\n## Variables\n\nArguments: `$ARGUMENTS`\n\n## Purpose\n\nDesign answers WHAT before `\u002Fplanning:plan` answers HOW: types, boundaries and package topology the\nuser has validated through discussion. Exploration maps existing code, research gathers external\nfacts, this skill turns both into a design. When the PROBLEM is still rough and no approach is\nchosen, diverge first via `\u002Fplanning:brainstorm` (cheapest→most-ambitious candidates, user\nreacts), then design the direction that resonated.\n\n**Level this skill decides: interfaces and contracts**, the types, boundaries and module shapes\nother code depends on; behavior is the interview's Brief, and files and symbols are\n`\u002Fplanning:plan`'s.\n\nDepth scales to the work:\n\n- Single-file fix → early-exit: write `design-resolution.md` with `outcome: early-exit`, tier `C`,\n  and reason. Then invoke `\u002Fplanning:design-handoff` via the Skill tool, which writes PLAN.md's\n  one-line `## Design` record and hands off to `\u002Fplanning:plan`\n- New module → light-form (1-2 discussion rounds, basic type sketch)\n- Large library or system → full-form (multiple sessions, all phases, all artifact types)\n\nThe stage always runs; early-exit is a valid outcome. **Gate artifact:** Tier C and light Tier B\nearly-exits MUST produce `design-resolution.md` in the topic's design slice\n(`\u003Cmemory_dir>\u002F\u003Ctopic-slug>\u002Fdesign\u002F`, default `.work\u002F`) so `\u002Fplanning:plan`'s prerequisite check\ncan verify the gate without conversation memory.\n\n### design-resolution.md (early-exit artifact)\n\n```markdown\n---\noutcome: early-exit\ntier: C\nreason: \u003Cone line, e.g. single-file bugfix, docs-only>\n---\n\nTier B (required): the type sketch, inline or as a link to type-inventory.md.\n\u002Fplanning:design-handoff quotes it into PLAN.md's `### Contracts`.\n```\n\n## Gates\n\nThese hold after a compaction re-attach. Later sections say how to carry them out.\n\n- **Collaborative always.** Never autonomously decide design. Ask in frontier rounds (Key\n  behaviors).\n- **Abstract is never the agent's pick.** A variation-point verdict of abstract comes only from the\n  user: interactively ask, recommending contain; unattended, apply contain and record the question\n  as a human decision. Full rule:\n  [`${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fvariation-points.md`](${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fvariation-points.md)\n  \"Autonomy\".\n- **Every recommendation carries a `Basis:` line**: `verified` with the `file:line`, tool output,\n  or URL it rests on, or `judgment` (non-consequential only). A consequential one (cross-repo,\n  shared infrastructure, irreversible, or security) is grounded before it is presented; one\n  research cannot settle is withheld, recorded as a `deferred` thread whose research tag names\n  the evidence that would settle it.\n\n## Action Router\n\nParse `$ARGUMENTS` for scope and action:\n\n| Argument | Action |\n|----------|--------|\n| *(empty)* | **Auto-detect**. Read the PLAN.md Brief + conversation to determine scope and phase. Resume if design artifacts exist. Ask if ambiguous |\n| `library` | **Library\u002FAPI design**. Packages, types, contracts, dependency graph |\n| `module` | **Module design**. Domain model, boundaries, contracts. Suggest a domain-event workshop (e.g. EventStorming) when the environment provides one |\n| `data` | **Data model design**. Entities, relationships, schema decisions |\n| `integration` | **Integration design**. Cross-system contracts, sequence flows, error handling |\n| `system` | **System design**. Components, communication patterns, deployment topology |\n| `status` | **Status report**. Resolution state per thread and question |\n| `thread \u003Cname>` | **Deep-dive**. One design thread |\n| `discuss` | **Discussion round**. Systematic gap-finding across all artifacts |\n| `terminology` | **Naming review**. Cross-cutting naming pass over the full type inventory (see \"Terminology pass\") |\n| `handoff` | **Handoff gate**. Delegates to `\u002Fplanning:design-handoff` (see \"Handoff gate\") |\n\n## Phases\n\nPhases may interleave. Track which have produced artifacts and which have open questions.\n\nAll artifacts live in `\u003Cmemory_dir>\u002F\u003Ctopic-slug>\u002Fdesign\u002F` (default `.work\u002F`), never committed;\n`\u002Fplanning:plan`'s gate reads the gate files (`design-threads.md`, `design-resolution.md`) from\nthere. Placement:\n[`${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fartifact-protocol.md`](${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fartifact-protocol.md).\n`\u002Fplanning:design-handoff` writes the durable content (module layout, contracts, variation\nverdicts, conventions followed) into PLAN.md's `## Design`, the copy that reaches the plan, the\nimplementer's brief, and the pull request body or linked issue where PLAN.md is published. Derive\n`\u003Ctopic-slug>` from the task or branch name (kebab-case, ≤40 chars; shared with `\u002Fplanning:interview` and `\u002Fplanning:plan`). Skip\nartifact creation for read-only actions (`status`).\n\n### Phase 1: Problem Space Decomposition\n\nRead the Brief's `### Problem` before decomposing; absent, start from the `Problem`, `Intent (why,\nin the user's words)` and `Chosen direction` lines of `\u003Cmemory_dir>\u002F\u003Ctopic-slug>\u002Fbrainstorm.md`'s\n`## Handoff` block when it exists; with neither, establish it:\n[`${CLAUDE_PLUGIN_ROOT}\u002Fcontext\u002Fproblem-framing.md`](..\u002F..\u002Fcontext\u002Fproblem-framing.md). Its\n`time_units` user layer is `${user_config.time_units}` (unexpanded means unset).\n\nScan the whole problem space broadly before diving into any single capability. For each capability\nor concern:\n\n- Domain concepts (nouns, verbs, relationships)\n- Invariants (rules that must always hold)\n- Storage needs (stateless? persistent? app-specific?)\n- Cross-app reuse: shared-library-worthy vs app-specific, following the consuming project's\n  library-organization and dependency-preference conventions when it declares them\n\nWhen the work adds a requirement to existing code, ask before Phase 3: had this requirement been\nknown when the code was first written, which types and boundaries would it have? Take that answer\nas the target shape, not the current shape with the requirement bolted on.\n\nProduce: `capability-matrix.md` (library scope) or equivalent per scope.\n\n### Phase 2: Design Threads\n\nIdentify cross-cutting decisions that affect multiple capabilities. For each thread: name the\ndecision, list concrete options with tradeoffs, and resolve through discussion or defer with\nrationale + research tag. Status: **resolved** (decision made), **directional** (direction agreed,\ndetails deferred), **deferred** (needs research).\n\n**Two-candidate step.** Take it when the codebase has nothing to copy for the thread, more than one\napproach is workable, and the decision is hard to reverse (a public contract, a stored format, a\nboundary other modules will build on):\n\n1. Write the criteria the candidates will be judged by into the thread before drafting any\n   candidate.\n2. Draft at least two candidates that differ in structure: who owns the state, where the module\n   split falls, or what shape the contract takes. A renamed or reordered copy of the first is not a\n   second candidate.\n3. Judge each against the written criteria, and record the rejected ones with the reason in\n   `design-threads.md`.\n\nWhen the thread is about how a screen or interaction looks or feels, invoke\n`\u002Fprototype:explore-directions` via the Skill tool when it is among the available skills. When the\ncandidates differ in logic or state (the rules, a state machine, a data model, an API surface) and\na run can settle the fork, invoke `\u002Fprototype:pressure-test observe` via the Skill tool when it is\namong the available skills, because running each candidate on the same inputs shows which one\nholds where arguing them only predicts it. The test: name the event sequence or record that the\ncriteria turn on; when nobody can yet say with confidence how each candidate handles it, a run\nsettles the fork (pstack's `exhaust-the-design-space` principle). Confirm the scope of the\nthrowaway with the user before either route. When neither route applies or its skill is\nunavailable, run the three steps here, describing each candidate in prose.\n\nOpen these threads when their trigger holds:\n\n- **Shared-state**: a type can be read and changed by more than one concurrent actor (threads,\n  processes, overlapping requests, background jobs). Cover which actors write it, what a reader\n  sees halfway through an update, and whether the type is confined to one owner, immutable, or\n  guarded.\n- **Tenancy posture** (early): SaaS or B2B org-scoped products. Single- vs multi-tenant, isolation\n  model, shared vs tenant-scoped data catalog.\n- **Refactoring posture**: exploration surfaces high coupling, large types, or multi-responsibility\n  files (refactor or strangler scope). Characterization-test strategy, seam map, incremental\n  extract order, change budget.\n- **Test-seam posture**: any feature with a testable surface. Sketch where its tests will attach;\n  reuse an existing seam before adding one, put any new seam as high in the stack as it can go, and\n  aim for the fewest seams that cover the surface. The change→test-type mapping lives in\n  `\u002Ftesting:plan`'s classification table; cite it when the `testing` plugin is enabled, otherwise\n  apply standard test-design judgment. The sketch is input, not the decision: `\u002Fplanning:plan`'s\n  Test strategy names the test boundaries from it and its Step 5 approval settles them; a seam the\n  design needs as a contract still goes in Contracts.\n\n**Variation-point pass.** Always for `integration`, `module`, and `system`; for `library` and\n`data`, when the design touches an external system or a domain category. List every variation\npoint (every external integration is one), ask the two questions (likelihood of a second variant,\ncost of change after shipping), and open one thread per point that resolves to a verdict: abstract\nnow, contain now and abstract later (the default for anything external), or leave inline (internal\none-offs only). Run the leak test on every abstraction and contained boundary, and place seams\nwhere the solution's existing architecture style already puts them. Questions, verdicts, leak test,\nautonomy rule, and sources:\n[`${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fvariation-points.md`](${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fvariation-points.md).\nA variation-intent answer from `\u002Fplanning:interview` is settled, never re-asked.\n\nProduce: `design-threads.md`\n\n### Phase 3: Type Modeling\n\nThe phase ends with a `type-inventory.md` in which every type traces to a call site that needs it,\nand each type's shape is set by the operations its busiest paths run on it. Two checks prove it:\n\n- **Call sites before types.** From consumer code, sketch two or three brief calls into the new\n  contract, written as its users will write them, before any type has a name; for a library or\n  API, at least one sits inside the importing package. A type enters the inventory only if those\n  calls need it, given the capabilities.\n- **Operations set structure.** Each entry lists its operations (lookup by key, ordered walk,\n  append, bulk replace) with the busiest-path ones flagged, and its structure is the one those\n  flagged operations favor.\n\nApply [`reference\u002Ftype-discipline.md`](reference\u002Ftype-discipline.md): Phase 3 meets each of its\nsituations while it fills `type-inventory.md`, so find the row that matches and make its decision.\nIdioms for one language sit in that language's own file under `reference\u002Ftype-discipline\u002F`; open\none only after detecting the language:\n\n| Language | File | Loaded when |\n|---|---|---|\n| TypeScript | [`reference\u002Ftype-discipline\u002Ftypescript.md`](reference\u002Ftype-discipline\u002Ftypescript.md) | the repository has a `tsconfig.json`, or the change touches `.ts`, `.tsx`, `.mts` or `.cts` files |\n\nThe inventory covers:\n\n- Records, enums, strongly-typed IDs, value objects\n- Contracts: interfaces with method signatures\n- Read and follow the consuming project's naming conventions (interface naming, context-relative\n  naming, collisions with common library types, namespaces) before naming\n- Follow the project's codified design principles (e.g. Law of Demeter, dependency direction,\n  disambiguating overloaded terms) where declared; otherwise low-coupling\u002Fhigh-cohesion defaults\n- Invoke `\u002Fdomain-driven-design:ubiquitous-language curate` via the Skill tool (if that plugin is enabled)\n  the moment a domain term resolves, so the glossary owner applies the consumer's format,\n  placement, and context routing; without it, record the resolved term and rejected synonyms in\n  the design artifacts\n\nProduce: `type-inventory.md`\n\nClose Phase 3 by auditing the inventory: for each type, follow one value from where it is made to\nwhere it is read. A fault at any stop sends that type back to the design threads.\n\n1. **Where it is made.** When a schema, spec or migration already describes the shape, the entry\n   derives from it instead of redrawing it. A value from outside the program becomes this type\n   where it arrives, and nothing further in validates that input again.\n2. **What it holds.** Try to write a mix of field values the domain forbids; a type that accepts it\n   is too loose. For each type the design strengthened, name the function that would fail on part\n   of its input without the extra strength; with none, the strength guards nothing, and that is a\n   fault too.\n3. **Where it is read.** Picture one more variant: every reading site must then fail to compile,\n   not keep running silently. On the same path, every cast, assertion or suppression has a check\n   in front of it.\n\nOnce type modeling stabilizes, run the `terminology` action over the whole inventory; per-type\nnaming during modeling does not replace it.\n\n### Phase 4: Package\u002FModule Topology\n\n- Package or module structure with dependency graph\n- What goes where (abstractions vs implementation vs service defaults)\n- Adapter surfaces (infrastructure boundary)\n- Dependency direction enforcement per the project's declared layer rules\n\nProduce: `library-topology.md` (library scope) or equivalent per scope.\n\nWhen the dependency graph reads more clearly visually, optionally also emit a self-contained HTML\ntopology view to the OS temp directory, never beside `library-topology.md`, which stays the record.\nRules:\n[`${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fartifact-protocol.md`](${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fartifact-protocol.md).\nResolve `medium` first per\n[`${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Frendered-view.md`](${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Frendered-view.md)\n\"Other optional views\", with this plugin's `medium` option `${user_config.medium}`, or `\"\"` when that\nreads empty or unsubstituted (never put a `${user_config.*}` string in a shell command), and follow\nits result, which names the report line to print.\n\n### Phase 5: Discussion Rounds\n\nEach round:\n\n1. Re-read all design artifacts.\n2. Record as design threads: underspecified types, missing contracts, boundary friction, pattern\n   concerns, and design-default gaps (configurability, extension axes, observability,\n   testability).\n3. Present findings ordered by tweak likelihood (the presentation default `\u002Fplanning:plan` Step 5\n   documents): public contracts, data shapes, and user-facing surfaces lead; settled-looking\n   mechanical threads sit at the bottom. Order only; thread dependencies still govern what can\n   resolve when.\n4. When discussion surfaces project-wide principles, suggest codifying them in the project's own\n   rules.\n\nContinue until no new gaps surface, then run the `handoff` action.\n\n## Lifecycle and reversibility\n\nSkip on early-exit, `status`, or trivial single-file work. Otherwise call each significant decision\na one-way or two-way door, prompt an ADR for each one-way door, and scale investment by subdomain\nand quality bar: [`reference\u002Freversibility.md`](reference\u002Freversibility.md).\n\n## Terminology pass (`terminology` action)\n\nOver the full type inventory, once type modeling stabilizes:\n\n1. Check interface-naming form and context-relative naming against the project's conventions\n2. Check collisions with common library\u002Fframework type names (e.g. a bare `Result\u003CT>` when the\n   stack already ships one)\n3. Check overloaded-term disambiguation and domain accuracy against the project's domain\n   vocabulary\n4. Record decisions in a terminology table inside `type-inventory.md`\n5. Invoke `\u002Fdomain-driven-design:ubiquitous-language curate` via the Skill tool (if enabled) to sync resolved\n   terms and rejected synonyms into the project's glossary; the table above is the standalone\n   fallback\n\n## Handoff gate (`handoff` action)\n\nInvoke `\u002Fplanning:design-handoff` via the Skill tool. It is the only gate implementation: it checks\n`design-threads.md` (or the `design-resolution.md` early-exit artifact) and on PASS emits the\nplan-ready summary and resume prompt. This skill carries no gate criteria of its own; criteria changes land in\n`\u002Fplanning:design-handoff` only.\n\nOn PASS, offer an interactive design view of PLAN.md's `## Design` (its sections, a tick for each one\nthe reader questions, a copy-out of the reply, sent to this session when connected). PLAN.md stays the\nrecord. Build it only with `${CLAUDE_PLUGIN_ROOT}\u002Fscripts\u002Fbuild-view.mjs` from that record, never\nhand-written; it runs the shared medium resolver and publish gate with this plugin's `medium` option\n`${user_config.medium}`, or `\"\"` when that reads empty or unsubstituted (never put a\n`${user_config.*}` string in a shell command), and you print the report line it prints. Procedure:\n[`${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Frendered-view.md`](${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Frendered-view.md).\n\n**Stub files (`scaffold_stubs`)**. Before invoking the gate, resolve `scaffold_stubs`, lowest layer\nfirst: the default `false`; the plugin's user config (`${user_config.scaffold_stubs}`, where a\nliteral unexpanded value means unset); then the `scaffold_stubs` key of the repository's\n`docs\u002Fconventions\u002Fplanning.yaml`, which wins when set, read only when the working directory's git\nroot is neither `$HOME` nor an ancestor of it. Only the bare booleans `true` and `false` are valid:\nany other value, a quoted `\"true\"` included, is named with its file (or user config), key and\nvalue, and that layer is dropped, so a valid higher layer still wins and otherwise the key is\n`false`. Report one line naming the value and its layer, e.g.\n`scaffold_stubs: true (docs\u002Fconventions\u002Fplanning.yaml)`. Keys and layers:\n[`${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fconfig.md`](${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fconfig.md).\n\nWith `true`, add a `## Stub scaffold` section to `design-threads.md` (or to `design-resolution.md`\non an early exit) listing every new file the design introduces, each with the signatures it will\ndeclare (types, function and method signatures, exported constants), from the resolved type\ninventory and contracts. Each stub body is the language's ordinary not-implemented form (for\nexample `raise NotImplementedError` in Python or `todo!()` in Rust), with no per-language reference\nfile. After the gate passes, the handoff output names those files and signatures so\n`\u002Fplanning:plan` can place the stub phase. With `false`, write no such section and name no stubs.\n\n## Scope-specific artifacts\n\n| Scope | Primary artifacts | Typed artifact | Dialect |\n|-------|-------------------|----------------|---------|\n| `library` | capability-matrix.md, type-inventory.md, library-topology.md, design-threads.md | none | none (no typed artifact, so no scope label) |\n| `module` | domain-model.md, module-boundary.md, contracts.md, design-threads.md | none | none (no typed artifact, so no scope label) |\n| `data` | entity-relationships.md, schema-decisions.md, design-threads.md | `entity-relationships.md` | mermaid `erDiagram` by default; DBML when `diagram_dialect.data` resolves to `dbml` |\n| `integration` | contract-spec.md, sequence-flows.md, design-threads.md | `sequence-flows.md`, `contract-spec.md` | mermaid `sequenceDiagram` for the flows; an OpenAPI 3.1 sketch for the contract spec |\n| `system` | component-map.md, communication-patterns.md, design-threads.md | `component-map.md`, and only when `diagram_dialect.system` names a dialect | a C4 container view in LikeC4 or C4-PlantUML, never Mermaid's [C4 diagrams](https:\u002F\u002Fmermaid.js.org\u002Fsyntax\u002Fc4.html#c4-diagrams) |\n\n`design-threads.md` is common across all scopes.\n\n### Typed artifacts: dialect and scope label\n\nTyping adds a declared dialect and a scope label to artifacts this skill already emits; no new\nfile. Everything the **Typed artifact** column does not name (`schema-decisions.md`,\n`communication-patterns.md`, every `library` and `module` artifact) stays prose with no dialect and\nno scope label. `component-map.md` is likewise untyped prose with no scope label whenever\n`diagram_dialect.system` is unset, so a downstream lookup finds nothing rather than an unlabeled\ndiagram.\n\n**The scope label.** Every typed artifact opens with frontmatter naming the producing scope and the\ndialect of its fenced block:\n\n```markdown\n---\nscope: data\ndialect: mermaid\n---\n```\n\n`scope` is one of `data`, `integration`, `system`. `dialect` is one of `mermaid`, `dbml`,\n`openapi-3.1`, `likec4`, `c4-plantuml`. `\u002Fwork-items:decompose` (when the `work-items` plugin is\nenabled) reads the label to inline the artifact under a provenance note naming scope and dialect;\nwithout that plugin the label is inert. The body is one fenced block in the declared dialect,\nfollowed by the artifact's prose. Tag the fence with the renderer name: `mermaid`, `dbml`, `yaml`\nfor the OpenAPI 3.1 sketch, `likec4`, `plantuml`. An `integration` session labels two artifacts,\none per typed file.\n\n**Resolving the dialect.** `diagram_dialect` is a team-shared convention key split by artifact kind\n(`diagram_dialect.data`, `diagram_dialect.system`). Resolve it per session, before writing a typed\nartifact, through\n[`${CLAUDE_PLUGIN_ROOT}\u002Fcontext\u002Fauthoring-formats.md`](..\u002F..\u002Fcontext\u002Fauthoring-formats.md)\n\"Resolution ladder\", where `\u003Cplugin-root>` is `${CLAUDE_PLUGIN_ROOT}` and `\u003Cproject-root>` is `${CLAUDE_PROJECT_DIR}` (unexpanded or empty means unset). This skill takes no dialect argument, so the argument layer is always empty.\n`diagram_dialect.data` defaults to `mermaid`, and every degrade writes the data artifact in\n`mermaid`. `diagram_dialect.system` has NO default: unset or degraded, emit no C4 container view\nand behave exactly as with no convention doc at all, reporting its provenance as\n`unset (no C4 view emitted)`.\n\n**Diagram craft.** For mermaid layout, readability, and syntax idiom, invoke\n`\u002Fvisualization:visualize` via the Skill tool (if the `visualization` plugin is enabled). Without\nit, emit the plainest correct form of the dialect. The typed artifact is produced either way.\n\n## Key behaviors\n\n- **Frontier rounds.** Every open thread whose prerequisites are settled surfaces in the same\n  numbered round, each with a recommendation; a thread that depends on an unresolved thread waits\n  for the round after it resolves. Render a round via `AskUserQuestion` only when the plugin's\n  `use_ask_user_question` user config (`${user_config.use_ask_user_question}`; unexpanded or empty means off) is on and the round\n  is independent questions that fit one `AskUserQuestion` call (the per-call question limit:\n  \u003Chttps:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fagent-sdk\u002Fuser-input#limitations>). Inline prose otherwise\n- **Grounding steps.** Ground a consequential recommendation in the affected code plus its\n  consumers and in external research that reads official docs first, routed to\n  `\u002Fdiscovery:explore` and `\u002Fdiscovery:research` if enabled. A recommendation that changes is\n  restated as old → new → why. Contract:\n  [`${CLAUDE_PLUGIN_ROOT}\u002Fcontext\u002Frecommendation-basis.md`](..\u002F..\u002Fcontext\u002Frecommendation-basis.md)\n- **Self-answer before asking.** Each candidate question first passes\n  [`${CLAUDE_PLUGIN_ROOT}\u002Fcontext\u002Fself-answer.md`](..\u002F..\u002Fcontext\u002Fself-answer.md): a fact it settles\n  is stated with its basis and source tag, not asked\n- **Track resolution status.** Every question and thread is resolved \u002F directional \u002F deferred.\n  Deferred items carry a research tag naming the external investigation needed\n- **Codify rules when discovered.** When discussion surfaces a project-wide principle, suggest\n  codifying it immediately in the project's own rules files\n- **Incremental artifacts.** Build artifacts as discussion progresses and update them as decisions\n  evolve. Re-read multi-turn shared artifacts (`design-threads.md` and peers) from disk before\n  every write, since another turn or agent may have changed them, and prefer appending or refining\n  over wholesale rewrites\n- **Dependency order awareness.** Surface which decisions block others so `\u002Fplanning:plan` can\n  sequence phases\n- **Resume from prior state.** When design artifacts exist in the topic's design directory, read\n  them, summarize current state, and identify remaining gaps\n- **Suggest adjacent skills.** When a domain-event workshop fits better for domain modeling,\n  suggest it if available. Suggest `\u002Fdiscovery:research` (if enabled) for a deferred item needing\n  external research, and the `terminology` then `handoff` actions at the session tail\n- **Design defaults (non-trivial scopes only).** For `library`, `module`, `data`, `integration`,\n  and `system` scopes, when discussion touches configurability, extension points, observability,\n  or testability, open a design thread for it. Extension points start from the Phase 2\n  variation-point pass. Skip on early-exit, `status`, or trivial single-file work. Apply\n  [`reference\u002Fdesign-defaults.md`](reference\u002Fdesign-defaults.md) first (quality bar, consumer\n  standards, the Brief's quality requirements, generalize-now-or-wait, per-tenant configurability\n  as vendor guidance), then recommend from every principle\n  [`design-principles.md`](${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fdesign-principles.md) lists.\n\n## What this skill does NOT do\n\n- **Implementation planning**: `\u002Fplanning:plan` (phases, sanity checks, file-level work items)\n- **Code writing**: the implementation stage\n- **External research**: the research capability; this skill synthesizes its results\n- **Diagram craft**: this skill selects the dialect; layout and idiom route to\n  `\u002Fvisualization:visualize` if enabled, else the plainest correct form is emitted\n- **UI\u002FUX design**: user research, flows and information architecture are\n  `\u002Fuser-experience:shape` (if enabled); look and response are `\u002Fuser-interface:design` (if\n  enabled)\n- **Domain event workshops**: an EventStorming-style capability; this skill may suggest it within\n  module design\n- **Product intent**: `\u002Fplanning:prd` (problem, users, success metrics)\n- **Intent contract**: `\u002Fplanning:interview` (goal, constraints, acceptance criteria)\n\n## Next\n\n- Design finished, to gate and write into PLAN.md's `## Design`, which \u002Fplanning:plan reads: \u002Fplanning:design-handoff.\n- The contract is a UI component's props API (parts, variants, controlled state): \u002Fuser-interface:design.\n\n## Relationship to other skills\n\n| Skill | Relationship |\n|-------|-------------|\n| `\u002Fplanning:interview` | **Before.** Locks the brief (scope + constraints); design explores the solution space within them |\n| `\u002Fdomain-driven-design:ubiquitous-language curate` | **During.** Owns project-glossary updates when design resolves domain language; not type or boundary design |\n| `\u002Fvisualization:visualize` (if enabled) | **During.** Owns visual-form choice and mermaid craft for a typed artifact's fenced block |\n| `\u002Fnaming:name-it-better` (if enabled) | **During.** Proposes candidates for a name the design leaves undecided; the human picks, and the pick is recorded in the terminology table |\n| `\u002Farchitecture:record-decision` (if enabled) | **During.** Records the ADR for a one-way door when its thread resolves ([`reference\u002Freversibility.md`](reference\u002Freversibility.md)) |\n| `\u002Fwork-items:decompose` (if enabled) | **After.** Reads a typed artifact's `scope` and `dialect` label to inline it into the spec container with a provenance note, and quotes each slice's part of PLAN.md's `## Design` into that slice's body |\n| `\u002Fdiscovery:explore` (if enabled) | **Before.** Maps existing code; design creates what SHOULD exist |\n| `\u002Fdiscovery:research` (if enabled) | **Before + parallel.** Gathers external facts; deferred research items can run in parallel |\n| `\u002Fplanning:design-handoff` | **The gate.** Owns the design→plan gate criteria and the plan-ready summary |\n| `\u002Fplanning:plan` | **After the handoff gate.** Produces HOW; when design artifacts exist it consumes them instead of re-deriving design |\n",{"metadata":24,"description":7,"argument-hint":26,"user-invocable":27,"disable-model-invocation":20},{"summary":25,"workflow-stage":5},"Resolve types, contracts, and module boundaries before planning","[library|module|data|integration|system] [status|thread \u003Cname>|discuss|terminology|handoff]",true,"main","4f2dcaaff35e8f9fccc6a9f4d82a5830ab17a5c5","plugins\u002Fplanning\u002Fskills\u002Fdesign",7,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins","https:\u002F\u002Fgithub.com\u002Fmelodic-software","https:\u002F\u002Fmelodicsoftware.com","Independent software studio building developer tools, automation, and application services, with roots in music.","2026-11-15 05:15:06",{"source":8,"skillName":5,"commands":38,"prompt":48,"zipAvailable":27},[39,42,45],{"tool":40,"command":41},"npx","npx skills add melodic-software\u002Fclaude-code-plugins --skill design",{"tool":43,"command":44},"bunx","bunx skills add melodic-software\u002Fclaude-code-plugins --skill design",{"tool":46,"command":47},"pnpm","pnpm dlx skills add melodic-software\u002Fclaude-code-plugins --skill design","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fplanning\u002Fskills\u002Fdesign\u002FSKILL.md",[50,56,60,64,68,72],{"path":51,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":54,"sourceHtmlUrl":55},"evals\u002Fevals.json","REFERENCE","参考文档",22992,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fplanning\u002Fskills\u002Fdesign\u002Fevals\u002Fevals.json",{"path":57,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":58,"sourceHtmlUrl":59},"reference\u002Fdesign-defaults.md",5894,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fplanning\u002Fskills\u002Fdesign\u002Freference\u002Fdesign-defaults.md",{"path":61,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":62,"sourceHtmlUrl":63},"reference\u002Freversibility.md",5269,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fplanning\u002Fskills\u002Fdesign\u002Freference\u002Freversibility.md",{"path":65,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":66,"sourceHtmlUrl":67},"reference\u002Ftype-discipline.md",3737,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fplanning\u002Fskills\u002Fdesign\u002Freference\u002Ftype-discipline.md",{"path":69,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":70,"sourceHtmlUrl":71},"reference\u002Ftype-discipline\u002Ftypescript.md",7651,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fplanning\u002Fskills\u002Fdesign\u002Freference\u002Ftype-discipline\u002Ftypescript.md",{"path":73,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":74,"sourceHtmlUrl":75},"templates\u002Fdesign-view.html",7339,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fplanning\u002Fskills\u002Fdesign\u002Ftemplates\u002Fdesign-view.html",[77,84,91,98,103,110],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":19},"01M7DYYDG31B9YX7N9MB9QW2GW","track","Backlog reads through the bound tracker: search open and closed items, view one item with its comments and state history. Use when another skill searches or reads tracker items.","https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fsession-flow\u002Fevals\u002Frecall-still-reports-reopened-bug\u002Fwork-items-stub\u002Fskills\u002Ftrack\u002FSKILL.md",[],[],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":19},"01M7DYXVBAVG3NV30PA7GKW9Q6","reviewer-media","Reviewer media for one pull request: decides whether it needs a narrated walkthrough, builds the storyboard from \u002Freview:explain-change's digest, has \u002Fexplainer-video:produce render it and hands the manifest to \u002Fsource-control:pull-request media. Use when asked for 'reviewer media', 'a walkthrough video for this PR', 'a produced video of this change', or when pull-request ready or monitor hands a PR over.","https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Freview\u002Fskills\u002Freviewer-media\u002FSKILL.md",[],[],{"skillNo":92,"name":93,"nameZh":6,"description":94,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":95,"categories":96,"keywords":97,"publishedAt":19},"01M7DYRZ5YD44AMYH26YR25GZ8","route","Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.","https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdiscovery\u002Fevals\u002Fex-model-pin-without-override\u002Fmulti-agent-stub\u002Fskills\u002Froute\u002FSKILL.md",[],[],{"skillNo":99,"name":93,"nameZh":6,"description":94,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":19},"01M7DYRTVT4FWTGDJY0HCCFJMZ","https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdiscovery\u002Fevals\u002Fex-model-override-from-route\u002Fmulti-agent-stub\u002Fskills\u002Froute\u002FSKILL.md",[],[],{"skillNo":104,"name":105,"nameZh":6,"description":106,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":109,"publishedAt":19},"01M7DYNZC8PNW3T27V2ADKECKJ","principles","Module-design vocabulary for architecture findings, and the checks built on it. Use when: 'what is a deep module', 'what is a seam', 'deep vs shallow module', 'what is the deletion test', 'leverage and locality', 'module design vocabulary', 'which word do we use for X in architecture findings'. Scanning a codebase for friction is \u002Farchitecture:improve.","https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Farchitecture\u002Fskills\u002Fprinciples\u002FSKILL.md",[],[],{"skillNo":111,"name":112,"nameZh":6,"description":113,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":114,"categories":115,"keywords":116,"publishedAt":19},"01M7DYNMCZNEWBFHV9KTSS6H60","write","Structured five-field bug report (title, steps to reproduce, expected vs actual, justified severity, suggested fix location) from an informal description, read-only. Use when the user names a defect they observed, or asks for one written up ('report a bug', 'file a bug', 'write this up as a bug').","https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Farchitecture\u002Fevals\u002Fdeepening-defect-goes-to-bugs-write\u002Fbugs-stub\u002Fskills\u002Fwrite\u002FSKILL.md",[],[]]