add skill: /han-coding:design-an-api

CLAUDE.md

@@ -20,7 +20,8 @@ implementation: specifying with `plan-a-feature`, planning the build with `plan-
 `iterative-plan-review`, plus the `discussion-facilitator` agent that audits a planning discussion in progress;
 depends on `han-communication` and `han-core` and is bundled by the `han` meta-plugin),
 `han-coding` (the coding skills
-you reach for while working in code: writing it with `tdd` and `refactor`, plus reviewing, overviewing, analyzing,
+you reach for while working in code: writing it with `tdd` and `refactor`, designing an interface contract with
+`design-an-api`, plus reviewing, overviewing, analyzing,
 testing, investigating, and standardizing it with `code-review`, `code-overview`, `architectural-analysis`,
 `automated-test-planning`, `manual-test-planning`, `investigate`, and `coding-standard`; depends on `han-communication` and `han-core` and is bundled by
 the `han` meta-plugin),
@@ -109,7 +110,7 @@ han-plugin-builder skill:
 │   ├── skills/         # Planning skill directories, each with SKILL.md + references/
 │   ├── docs/           # In-plugin long-form docs: docs/skills/{name}.md + docs/agents/discussion-facilitator.md
 │   └── references/     # Both kinds: han-planning-owned canonical files (planning-boundary-rule.md, scope-justification-rule.md, operator-escalation-rule.md) beside vendored copies (yagni-rule.md, evidence-rule.md, config-rule.md). Each owned file opens by saying so; do not overwrite one in a re-sync sweep
-├── han-coding/         # Coding plugin: tdd, refactor, code-review, code-overview, architectural-analysis, automated-test-planning, manual-test-planning, investigate, coding-standard (the skills for working in code; depends on han-communication and han-core; bundled by the han meta-plugin)
+├── han-coding/         # Coding plugin: tdd, refactor, design-an-api, code-review, code-overview, architectural-analysis, automated-test-planning, manual-test-planning, investigate, coding-standard (the skills for working in code; depends on han-communication and han-core; bundled by the han meta-plugin)
 │   ├── README.md       # Light front door + scent-line skills list
 │   ├── .claude-plugin/
 │   │   └── plugin.json

docs/skills/README.md

@@ -31,6 +31,9 @@ skill-and-agent split is fuzzy, read [Concepts](../concepts.md) first.
   or specified files, with a size-scaled roster of specialist agents.
 - [`/coding-standard`](../../han-coding/docs/skills/coding-standard.md) — Create and update coding standards from
   existing patterns or evidence-based research.
+- [`/design-an-api`](../../han-coding/docs/skills/design-an-api.md) — Design the contract for an API change inside one
+  codebase, with every element justified from one stated goal and the design run past a question round and an
+  adversarial validation round.
 - [`/edit-for-readability`](../../han-communication/docs/skills/edit-for-readability.md) — Rewrite the prose of a target
   you already have against the shared readability standard, preserving every fact.
 - [`/explanation-guidance`](../../han-communication/docs/skills/explanation-guidance.md) — Surface the shared standard

docs/workflows.md

@@ -80,8 +80,10 @@ prepare the ground for a test-first build.
 flowchart TD
     review["/code-review"] --> refactor["/refactor"]
     arch["/architectural-analysis"] --> refactor
+    arch --> design["/design-an-api"]
+    design --> tdd["/tdd"]
     review --> pr["/post-code-review-to-pr"]
-    refactor --> tdd["/tdd"]
+    refactor --> tdd
     tdd --> prdesc["/update-pr-description"]
     investigate["/investigate"] --> iterate["/iterative-plan-review"]
 ```
@@ -95,6 +97,10 @@ flowchart TD
   work orders.
 - **[`/refactor`](../han-coding/docs/skills/refactor.md) → [`/tdd`](../han-coding/docs/skills/tdd.md).** Preparatory
   refactoring makes the change easy, then `/tdd` makes the easy change.
+- **[`/architectural-analysis`](../han-coding/docs/skills/architectural-analysis.md) →
+  [`/design-an-api`](../han-coding/docs/skills/design-an-api.md) → [`/tdd`](../han-coding/docs/skills/tdd.md).** Judge
+  the structure you are designing into, shape the contract against one stated goal, then implement it test-first. The
+  analysis step is optional; `/design-an-api` runs its own discovery wave when you start there.
 - **[`/investigate`](../han-coding/docs/skills/investigate.md) →
   [`/iterative-plan-review`](../han-planning/docs/skills/iterative-plan-review.md).** Root-cause the bug, then stress-test
   the proposed fix.

han-coding/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "han-coding",
-  "description": "Coding-facing skills for the Han suite: writing, reviewing, testing, investigating, and standardizing code. Home of the tdd skill, which drives a feature or behavior through a BDD-framed red-green-refactor loop with an enforced observed-failure gate, and the refactor skill, which restructures existing code without changing its behavior through a test-gated refactoring loop, plus code-review (comprehensive review of local changes), code-overview (a progressive-disclosure, understand-now overview of unfamiliar code or a PR's changes), architectural-analysis (module-level coupling, data flow, concurrency, risk, and SOLID assessment), automated-test-planning (coverage-gap and edge-case test plans), manual-test-planning (plain-language manual test plans a person runs by hand), investigate (evidence-based root-cause debugging), and coding-standard (creating and updating coding standards). Depends on han-core and han-communication; bundled by the han meta-plugin.",
+  "description": "Coding-facing skills for the Han suite: writing, reviewing, testing, investigating, and standardizing code. Home of the tdd skill, which drives a feature or behavior through a BDD-framed red-green-refactor loop with an enforced observed-failure gate, and the refactor skill, which restructures existing code without changing its behavior through a test-gated refactoring loop, plus design-an-api (designing an interface contract for one stated goal through an options round, a question round, and an adversarial validation round), code-review (comprehensive review of local changes), code-overview (a progressive-disclosure, understand-now overview of unfamiliar code or a PR's changes), architectural-analysis (module-level coupling, data flow, concurrency, risk, and SOLID assessment), automated-test-planning (coverage-gap and edge-case test plans), manual-test-planning (plain-language manual test plans a person runs by hand), investigate (evidence-based root-cause debugging), and coding-standard (creating and updating coding standards). Depends on han-core and han-communication; bundled by the han meta-plugin.",
   "version": "3.0.0",
   "dependencies": ["han-communication", "han-core"]
 }

han-coding/README.md

@@ -12,6 +12,9 @@ specialist agents to cover each dimension in parallel. Reach for it once there i
   enforced observed-failure gate; it writes code, not a document.
 - [`/refactor`](docs/skills/refactor.md) — Restructure existing code without changing its behavior through a test-gated
   loop that re-runs the full suite after every small step.
+- [`/design-an-api`](docs/skills/design-an-api.md) — Design the contract for an API change inside one codebase, with
+  every element justified from one stated goal and the design run past a question round and an adversarial validation
+  round.
 - [`/code-review`](docs/skills/code-review.md) — Run a comprehensive code review on the current branch or specified
   files, with a size-scaled roster of specialist agents.
 - [`/code-overview`](docs/skills/code-overview.md) — Produce a human-readable, progressive-disclosure overview of

han-coding/docs/skills/design-an-api.md

@@ -0,0 +1,154 @@
+# /design-an-api
+
+Operator documentation for the `/design-an-api` skill in the han plugin. This document helps you decide _when_ and _how_
+to use the skill. For what the skill does internally, read the skill definition at
+[`han-coding/skills/design-an-api/SKILL.md`](../../skills/design-an-api/SKILL.md).
+
+> See also: [Plugin README](../../README.md) · [Repo root](../../../README.md) ·
+> [All skills](../../../docs/skills/README.md) · [All agents](../../../docs/agents/README.md) ·
+> [YAGNI](../../../docs/yagni.md)
+
+## TL;DR
+
+- **What it does.** Designs the contract for an API change inside one codebase, running the design past a question round
+  and an adversarial validation round before you commit to it.
+- **When to use it.** You know what the capability should do, and you need to decide the shape of the interface that
+  delivers it, sized for roughly one pull request.
+- **What you get back.** A run folder holding a context brief, a design-options document, and the final design document
+  that a `/tdd` run implements against.
+
+## Key concepts
+
+- **The stated goal.** One ticket, issue, or written requirement the whole design answers to. The skill will not run
+  without one, because it is the only thing the design can be justified against.
+- **The justification field.** Every parameter, field, type, default, precedence rule, and failure behavior names either
+  the goal language it descends from or the asked-for behavior it is a necessity of.
+- **The cut list.** Anything the interface could plausibly carry that the goal never asks for, recorded with what it
+  would have done so you can put it back.
+- **The two gates.** You pick the design option, and later you answer each open item one at a time. Everything else
+  runs unattended.
+
+## When to use it
+
+**Invoke when:**
+
+- A ticket asks for a capability and the real work is deciding the interface: a component's props, a function surface,
+  URL or query parameters, an event payload, or a module boundary.
+- You are about to change a shared surface and want the consumer audit and the failure behavior settled before anyone
+  writes code.
+- A branch already carries a half-built attempt and you want the contract redesigned from the merge base instead.
+
+**Do not invoke for:**
+
+- **Deciding what a feature should do.** Use [`/plan-a-feature`](../../../han-planning/docs/skills/plan-a-feature.md)
+  instead; it settles behavior, this settles contract shape.
+- **Planning how to deliver the work.** Use
+  [`/plan-implementation`](../../../han-planning/docs/skills/plan-implementation.md) instead.
+- **Judging the architecture already in the codebase.** Use
+  [`/architectural-analysis`](./architectural-analysis.md) instead; it assesses what exists rather than designing what
+  comes next.
+- **Writing the code.** Use [`/tdd`](./tdd.md) to implement the design, or [`/refactor`](./refactor.md) to restructure
+  existing code without changing its behavior.
+
+## How to invoke it
+
+Run `/design-an-api` in Claude Code.
+
+Give it:
+
+1. **The goal.** A ticket reference, issue URL, file path, or one paragraph describing what this change is for. A sharp
+   goal names the user-visible outcome ("a link can prefill the first two steps of the signup flow"). A thin goal names
+   only the mechanism ("add query param support"), which gives the justification field nothing to cite.
+2. **The interface.** Which component, function, module, route, or payload is being designed, and where it lives. A new
+   surface with no file yet is fine; name the module it will live in.
+3. **A size, optionally.** `small`, `medium`, `large`, or `dynamic` as the first argument. Leave it off and the skill
+   classifies from signals it detects in the interface and its consumers.
+
+Example prompts:
+
+- `/design-an-api`. _"Design the change to FlowProvider that lets URL query values prefill a flow's steps, per
+  ticket ABC-142."_
+- `/design-an-api medium https://github.com/acme/app/issues/88 the exported cache client surface in src/cache/`.
+
+## What you get back
+
+Three files in one run folder, placed under your configured `output-directory` or a folder named for the interface
+under the project's documentation root:
+
+- **`context-brief.md`.** Numbered findings `F1`, `F2`, `F3`, … from the discovery wave. Each finding carries a
+  `file:line` citation or the label `inferred`, plus the agent that reported it. Conflicting findings stay as separate
+  entries with both citations rather than being resolved silently.
+- **`design-options.md`.** The two or three options the architect produced, with one recommendation, the rejected
+  alternatives and why, and pseudocode sketches of each option's signatures.
+- **`api-design.md`.** The deliverable. It holds the designed contract in three parts (surface, invariants, failure
+  behavior), the justification table, the options considered, the questions resolved (`Q1`, `Q2`, … each with its
+  answer's source), the validation findings (`V1`, `V2`, … each accepted or rejected), the cut list, and the open
+  risks.
+
+If any of the three files already exists in the folder, the run date-suffixes all three so one run's files stay
+together, and tells you which names it wrote. It never overwrites.
+
+## How to get the most out of it
+
+- **Paste the ticket, do not paraphrase it.** The justification field quotes the goal. A paraphrase you wrote from
+  memory becomes the scope authority, and it drifts.
+- **Answer the open items with the consequence in mind.** Each one is surfaced with candidate answers and what changes
+  in the contract; the answer you give becomes the recorded justification for those elements.
+- **Read the cut list before you approve.** It is the only place the design tells you what it deliberately left out.
+  Reinstating an entry is one sentence, and your direction becomes its justification.
+- **Re-run larger when the closing summary names an omitted domain.** The band cap can drop a signalled specialist. The
+  summary says which one.
+- **Pair with `/tdd` next.** The design document is written to be the input to a test-first implementation run.
+
+## YAGNI
+
+This skill is enforcing, not advisory. An element that cannot fill its justification field does not enter the design at
+all; it moves to the cut list with what it would have done and why it was cut. The cut list appears in the closing
+message as well as the document, so a wrong cut is visible in the turn rather than buried in a file you have no reason
+to open.
+
+One floor bounds that discipline: silence never cuts a necessity. A goal that never mentions a caching layer justifies
+cutting one, but the same goal's silence about invalid input, error behavior, and types cuts nothing, because those are
+necessities of the surface it did ask for. See [YAGNI](../../../docs/yagni.md) for the shared evidence and
+simpler-version gates this sits beside.
+
+## Cost and latency
+
+A small run dispatches four agents in sequence-with-one-parallel-wave: the discovery wave, then the architect, the
+junior developer, and the adversarial validator. A large run adds as many as four signalled specialists to the discovery
+wave, for up to eight agents total. Only signalled specialists are added, so a run at a size you set by hand can sit
+under its band's ceiling. The architect is the most expensive single participant, because it runs up to four times: once
+for options and once after each of the question round, the open items, and the validation round.
+
+This is an infrequent, high-signal run. It sits before implementation, not inside a tight loop.
+
+## In more detail
+
+The skill exists because the arrangement it packages was already working by hand. A session documented in
+[issue #173](https://github.com/testdouble/han/issues/173) dispatched `han-core:software-architect`,
+`han-core:junior-developer`, and `han-core:adversarial-validator` directly, against a hand-assembled context brief, to
+design a query-parameter prefill contract on a shared React flow provider. The designed API shipped essentially as
+specified and survived a later code review. One junior-developer question reversed a naming decision before any code
+existed.
+
+What the skill adds to that arrangement is the discovery step the session assembled ad hoc, the size band that scales
+the roster, and the two gates in fixed positions. What it deliberately does not add is the full analyst fan-out that
+`/architectural-analysis` runs: that roster is built to assess an existing module across every dimension, and it is
+oversized for shaping one contract.
+
+## Related documentation
+
+- [Plugin README](../../README.md). The plugin's front door: its skills, agents, and how they fit together.
+- [Repo root README](../../../README.md). The Han suite landing page. Start here if you arrived from outside the docs
+  tree.
+- [YAGNI](../../../docs/yagni.md). The evidence-based "You Aren't Gonna Need It" rule: the two gates, the
+  acceptable-evidence list, the named anti-patterns, and the deferral format.
+- [`/tdd`](./tdd.md). The implementation run this design document feeds.
+- [`/architectural-analysis`](./architectural-analysis.md). Assesses the module you are about to change, when you want
+  the existing structure judged before designing into it.
+- [`software-architect`](../../../han-core/docs/agents/software-architect.md). Produces the options and every
+  amendment.
+- [`junior-developer`](../../../han-core/docs/agents/junior-developer.md). Questions the chosen option as a generalist
+  who was not in the room.
+- [`adversarial-validator`](../../../han-core/docs/agents/adversarial-validator.md). Attacks the amended design and the
+  evidence under it.

han-coding/skills/architectural-analysis/SKILL.md

@@ -6,8 +6,8 @@ description:
   review the architecture, design quality, dependency structure, coupling, cohesion, or technical debt of an existing
   part of the codebase. Not for investigating specific bugs, runtime errors, or failures — use investigate. Not for test
   planning — use automated-test-planning. Not for file-level code review — use code-review. Not for researching open-ended
-  options, prior art, or how something works — use research. Not for writing documentation or architectural decision
-  records."
+  options, prior art, or how something works — use research. Not for designing a new interface or contract — use
+  design-an-api. Not for writing documentation or architectural decision records."
 arguments: size
 argument-hint: "[size: small | medium | large | dynamic] [focus area: module, directory, or feature to analyze]"
 allowed-tools: Read, Glob, Grep, Agent, Bash(find *)