design-an-api

Project Context

• git installed: !which git 2>/dev/null || echo "not installed"
• current branch: !git branch --show-current 2>/dev/null || echo "no git branch"
• default branch: !git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo unknown
• CLAUDE.md: !find . -maxdepth 1 -name "CLAUDE.md" -type f
• project-discovery.md: !find . -maxdepth 3 -name "project-discovery.md" -type f
• personal config directory: !bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"
• project .han/config.md: !cat .han/config.md 2>/dev/null || echo ""

As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md probe supplies content, apply it per config-rule.md, which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

Operating Principles

Read these before dispatching anything. They constrain every step below.

• A stated goal is required, and it is the scope governor. This skill designs a contract in service of one named goal: a ticket, an issue, a written requirement, or a described capability. If no goal resolves, stop and ask for one BECAUSE without a goal there is nothing to justify the design against, and the run degrades into designing a general-purpose framework for a single consumer.
• Every element of the contract carries a justification. Each named parameter, field, type, default, precedence rule, and failure behavior states exactly one of two things: the part of the stated goal it descends from, quoted or named; or the asked-for behavior it is a necessity of. An element that can fill neither does not enter the design. It moves to the cut list with what it would have done and why it was cut.
• Silence never cuts a necessity. The goal is short and does not enumerate what it depends on. A goal that never mentions a caching layer justifies cutting one. The same goal's silence about invalid input, error behavior, and types does not cut those, because they are necessities of the surface it did ask for.
• The agents own the judgment; the skill orchestrates. The skill resolves the goal and the interface, classifies size, selects the roster, fans agents out and in, runs the two human gates, and renders the design document. It produces no design content of its own.
• The four-agent spine always runs; specialists are signal-selected. han-core:codebase-explorer, han-core:software-architect, han-core:junior-developer, and han-core:adversarial-validator run at every size BECAUSE evidence, design, questioning, and attack are the irreducible core of a contract that survives contact. Every other specialist is added only when the interface's signals warrant it and the band allows it, BECAUSE dispatching an agent whose domain the contract never touches burns tokens and pulls the design toward concerns the goal did not ask for.
• Default to small. Start classification at small and escalate only when a higher-band signal is clearly present. Borderline signals stay at the smaller band. Under-dispatching is recoverable by re-running at a larger size; over-dispatching is not.
• This skill changes no code. It produces a design document. Implementation is a separate, later step, normally a tdd run against this document.
• Options before commitment. The architect produces two or three real options with one recommendation, not a single design with alternatives invented afterward to justify it. The user picks before three further agent rounds are spent refining one.
• The design document template lives at references/api-design-template.md. The skill renders that template by filling its sections. It does not invent a structure inline.
• The document is written for a named reader. As the skill writes the design document's synthesized prose, it sources the shared standard by invoking han-communication:readability-guidance and applies it, holding one audience above the writing: the engineer who will implement this contract and the reviewer who will approve it. Scope that frame per section so the specifics that reader needs — exact signatures, types, precedence rules, file paths — are preserved, never simplified away.

Design an API

Step 1: Resolve the Goal, the Interface, and the Starting Point

Bind $size. If the user passed small, medium, large, or dynamic as the first positional argument, bind $size to it. Anything else is part of the goal-and-interface context, not a size; bind $size to the literal none provided.

Resolve the goal. Take the remaining argument and conversation context as the goal this design serves. A ticket reference, issue URL, file path, or a described capability all qualify. Read the referenced material if it names a file or is fetchable from the conversation. Record the goal verbatim where it is quotable — the justification field in every later step cites it. If no goal resolves, stop and ask the user for the ticket, issue, or one-paragraph statement of what this change is for. Do not proceed without it.

Resolve the interface. Identify what is being designed: which component, function, module, route, or payload, and where it lives. Confirm it resolves to real files using Glob and Read. If the interface is genuinely new and has no file yet, resolve instead the module or directory it will live in and the consumers that will call it. If neither resolves, ask the user to name the surface before going further.

Resolve the starting point. Read the current branch and default branch values from Project Context. When default branch reads unknown, origin/HEAD is unset and there is no base to compare against: the working tree is the starting point, no question is asked, and the run continues. Otherwise run git diff --name-only {default branch}...HEAD and check whether any interface file resolved above appears in the output. Only when one does, ask the user in one short message whether to design from the branch as it stands or from the merge base, ignoring the branch's changes; read the merge-base state with git show when they choose the merge base. In every other case — no interface file changed on the branch, git unavailable, or the command fails — the working tree is the starting point and no question is asked. State the chosen starting point in one line.

Resolve project context. If CLAUDE.md is present, read its ## Project Discovery section for conventions. Fall back to project-discovery.md. These resolve language, framework, and convention questions so the agents infer less. If neither exists, the agents fall back to surrounding-code inference — note this in the briefs.

Resolve the output folder. The run writes three files: {folder}/context-brief.md, {folder}/design-options.md, and {folder}/api-design.md. Resolve {folder} in this order:

1. If the user specified an output folder, use it.
2. If the project or personal config sets an output-directory, place the run folder under it, per config-rule.md.
3. Otherwise, choose a 2-to-4-word kebab-case folder named for the interface, under a documentation root surfaced via CLAUDE.md, project-discovery.md, or a Glob fallback (docs/plans/, docs/).

Create the folder with mkdir -p. Check all three names with Glob before writing anything. If any of the three already exists there, write every file this run produces to a date-suffixed name (for example api-design-2026-08-07.md alongside context-brief-2026-08-07.md and design-options-2026-08-07.md) so one run's files stay together, and state which files were written; never silently overwrite. State the chosen folder in one short line and proceed without waiting for confirmation.

Step 2: Detect Signals and Classify Size

Run targeted Grep and Glob over the interface and its consumers to detect which domains the contract actually touches. These signals drive both the band and the roster:

• Consumer-spread signal: the interface has call sites beyond the module being changed — several components, several routes, or an exported surface other packages import.
• Ordering signal: async, lifecycle, mount-order, retry-order, or event-order behavior is part of the contract, not an implementation detail behind it.
• Data-contract signal: the interface carries persisted data, a schema or migration, a wire or event payload, or a document shape that another system reads.
• Trust-boundary signal: the interface accepts untrusted input (URL and query parameters, request bodies, uploads) or carries auth, tokens, secrets, or PII across the surface.
• Failure-path signal: the contract has to state what happens on failure — outbound calls, timeouts, retries, idempotency, partial writes, or a failure that would page someone.
• Boundary-data signal: the contract moves data across a module boundary, or how errors propagate across that boundary is itself part of what the design has to decide.
• System-seam signal: the interface crosses a deployable unit or bounded-context boundary — an RPC or HTTP contract with a sibling service, a message broker topic, or a shared store across services.

Classify the size. Default to small. Escalate only when a band's signal is clearly present; when a signal is borderline, stay at the smaller band.

• Small (default) — one interface with a contained consumer set inside one module, and none of the ordering, data-contract, trust-boundary, failure-path, boundary-data, or system-seam signals.
• Medium — a consumer-spread signal, OR exactly one of the ordering, data-contract, trust-boundary, failure-path, or boundary-data signals.
• Large — two or more of those cross-cutting signals together, OR a system-seam signal is present, OR $size is large.

Apply the size override. If $size is not none provided, use it: a band value is the band and skips the signal-based classification above, while dynamic forces the signal-based classification even when the project config sets a default band. If $size is none provided and the project config supplies a band via default-swarm-size (per config-rule.md), use that band, skip the signal-based classification, and announce the config as the source. In every case still select specialists by signal: a large band does not dispatch agents whose domain the contract never touches. A conversational override ("design this large") is equivalent to $size.

Step 3: Build the Roster and Announce It

Spine — dispatched at every size:

• han-core:codebase-explorer — discovers the current surface, its consumers, and the constraints the design has to live inside. Feeds the context brief. Runs in Step 4.
• han-core:software-architect — produces the options document and every later amendment. Runs in Steps 5, 7, 8, and 9.
• han-core:junior-developer — questions the chosen option as a generalist who was not in the room. Runs in Step 7.
• han-core:adversarial-validator — attacks the amended design and the evidence under it. Runs in Step 9.

Signal-selected specialists — added to the discovery wave when the signal is present and the band allows:

Specialist	Add when	Min band
han-core:structural-analyst	Consumer-spread signal	Medium
han-core:behavioral-analyst	Boundary-data signal	Medium
han-core:concurrency-analyst	Ordering signal	Medium
han-core:data-engineer	Data-contract signal	Medium
han-core:on-call-engineer	Failure-path signal	Medium
han-core:system-architect	System-seam signal	Large
han-core:adversarial-security-analyst	Trust-boundary signal	Medium

Roster caps by band are ceilings, not quotas: small runs the spine only (4 agents); medium adds at most two signalled specialists (up to 6 agents); large adds at most four, including han-core:system-architect when a system-seam signal is present (up to 8 agents). A band reached by override rather than by signal can sit well under its ceiling; add no specialist whose signal is absent just to fill the band. If more specialists are signalled than the cap allows, keep the band's count, prefer the specialists covering the strongest signals, and name the omitted domains in the design document's summary so the user can re-run larger.

Extra agents named in the project config's ## Extra Agents list join the signal-selected pool and compete under the same signals and band caps, per config-rule.md: add one only when a signal in the interface matches its stated specialty, count it against the band's cap, and skip an entry that does not resolve to a dispatchable agent with a one-line note.

Announce the decision in one line before dispatching, with per-specialist justification — for example:

Size: medium. Designing the query-parameter prefill contract on FlowProvider; consumer-spread signal (7 call sites) and a trust-boundary signal (values arrive from the URL). Roster (6): han-core:codebase-explorer, han-core:structural-analyst (consumer audit), han-core:adversarial-security-analyst (untrusted URL input), then han-core:software-architect, han-core:junior-developer, and han-core:adversarial-validator.

State git availability in the same message if git is absent. Proceed without a blocking confirmation; discovery is read-only and re-runnable, so a gate here would gate a reversible operation. If the user objects to the roster, honor the adjustment.

Running collaboratively. When the request asks to review each round as it lands, which is what pairing does when it hands work here, stop at this point and hand control back instead of continuing. Present the stop in the shape collaborative-stop-rule.md specifies. Absent such a request, continue as below; an ordinary invocation is unchanged.

For this skill a round is one dispatch step: the discovery wave, the options round, the question round, and the validation round. The two human gates below are unchanged and still fire regardless.

Step 4: Dispatch the Discovery Wave and Write the Context Brief

Launch han-core:codebase-explorer and every signalled specialist in a single message with one Agent call per agent so they run concurrently. Each brief must contain:

• The stated goal, verbatim.
• The resolved interface, its file paths, and its known consumers.
• The starting point from Step 1, so an agent reading a branch-modified file knows whether those changes count.
• The resolved project-context conventions, or a note that none were found and surrounding-code inference applies.
• The instruction to report findings with provenance: every finding carries a file path and line number, or is labelled as an inference.

Wait for the whole wave to return. Then write {folder}/context-brief.md: a numbered list of findings (F1, F2, F3, …), each carrying the finding, its provenance (a file:line citation, or the label inferred), and the agent that reported it. Merge duplicates and keep conflicting findings as separate numbered entries with both citations, rather than picking a winner. Apply the evidence rule from ../../references/evidence-rule.md to every finding. When a question the design depends on has no evidence at any tier, record it as an open item rather than guessing, and carry it into Step 8 alongside the open items the question round produces.

If a specialist returns nothing usable or fails, record a one-line note in the context brief naming the agent and the domain left uncovered, and continue. A missing specialist narrows the design's evidence; it does not stop the run. If han-core:codebase-explorer returns nothing usable, relaunch it once with the interface's file paths spelled out. If the second attempt also returns nothing, stop and tell the user the interface could not be discovered, naming the paths that were searched.

Step 5: Dispatch the Architect for Options

Launch han-core:software-architect with one Agent call. Pass it the stated goal verbatim, the full context brief, and the resolved project conventions. Its brief must ask for:

1. Two or three real options for the contract, each one a design someone could implement, not a strawman.
2. One recommendation with the reasoning that selects it over the others.
3. The rejected alternatives with the reason each was rejected.
4. For every element of every option — each parameter, field, type, default, precedence rule, lifecycle rule, and failure behavior — the justification defined in the Operating Principles: the part of the goal it descends from, or the asked-for behavior it is a necessity of.
5. A cut list of anything the interface could plausibly carry but the goal does not ask for, with what it would have done and why it was cut.
6. Pseudocode sketches of each option's signatures and types.

Write the returned options to {folder}/design-options.md.

If the architect returns one option, or returns options whose elements carry no justification, relaunch it once with the missing requirement restated. If the second attempt still returns one option, carry that option forward and record in the design document that only one viable option was produced, with the architect's stated reason. If the second attempt still leaves elements unjustified, do not carry those elements: move each one to the cut list with what it would have done and the note that no justification was produced for it, so the gap reaches the user in Step 6 rather than passing as designed.

Step 6: Human Gate — The User Picks an Option

Before writing the question, invoke han-communication:explanation-guidance to source the shared explanation standard into your context. After that skill returns, proceed immediately to the question below — do not stop there. The standard stays in context for Step 8, so do not invoke it a second time.

Present the options to the user with AskUserQuestion: one option per choice, the recommendation named first and labelled as recommended, each with its one-line reasoning. Apply the explanation standard to the wording, so each option reads as an outcome the user could observe rather than a mechanism. Include the cut list in the surrounding message so the user sees what the design is giving up.

Handle the response:

• User picks the recommendation or another option — carry it forward as the chosen design.
• User picks a rejected alternative or amends an option — carry their choice forward, and record their direction as the justification for the elements it changes. Operator direction is itself a valid justification.
• User asks for a different option entirely — return to Step 5 with their feedback, once. If a second round still does not produce an acceptable option, present what exists and ask for the constraint that is missing.

Step 7: Dispatch the Question Round and Amend

Launch han-core:junior-developer with one Agent call. Pass it the stated goal verbatim, the context brief, and the chosen option in full. Its brief must ask it to reframe the contract in simpler terms and raise the clarifying questions a generalist who was not in the room would ask: unstated prerequisites, conflicts with the project's own conventions, names that do not say what they hold, and behavior the contract leaves undefined. Ask for numbered questions.

Sort the returned questions into three buckets:

1. Settled by the goal — the stated goal already answers it. Answer it, cite the goal, and do not escalate. Re-deciding a question the goal already decided wastes the user's turn.
2. Settled by the context brief — a finding answers it. Answer it, cite the finding number.
3. Open — neither the goal nor the brief settles it, and the answer changes the contract. These go to Step 8.

Then relaunch han-core:software-architect with one Agent call, passing the chosen option, every question, and the answers from buckets 1 and 2, and ask it to amend the design accordingly. Hold the open items until Step 8 answers them.

Step 8: Human Gate — Open Items, One at a Time

If Step 7 and Step 4 left no open item, say so in one line, skip this gate, and go straight to Step 9. The gate exists to settle open items; with none to settle it has nothing to ask and no answer to fold in.

Otherwise surface the open items — those the question round produced in Step 7, plus any no-evidence item recorded in Step 4 — one at a time, each as its own AskUserQuestion call. Never batch them BECAUSE each answer routinely settles or reshapes the ones behind it, and a batch asks the user to decide in an order the design does not follow.

Apply the explanation standard already in your context from Step 6 to each question's wording. Each question leads with the plain-language consequence of the choice, names two to four candidate answers, and says what changes in the contract depending on the answer. After each answer, re-check the remaining open items: drop the ones the answer just settled, and re-word the ones it changed.

When every open item is answered, relaunch han-core:software-architect with one Agent call carrying the answers, and have it fold them into the amended design. Record each answer in the design document as the justification for the elements it settles.

Step 9: Dispatch the Adversarial Validation Round

Launch han-core:adversarial-validator with one Agent call. Pass it, verbatim and unsummarized, the stated goal, the full context brief with every finding and its citation, the amended design with its justifications, and the cut list. Do not summarize — the validator needs the detail to attack effectively. Its job is to try to break the contract: find the consumer the design forgets, the input state it does not define behavior for, the invariant a caller can violate, the justification that does not actually follow from the goal, and the finding whose evidence does not support what the design built on it.

Record its output as numbered validation findings (V1, V2, V3, …), and mark each one:

• Rejected — the finding does not hold. Record why, citing the goal, a context-brief finding, or a user decision from Step 6 or Step 8.
• Accepted — the finding holds. Once every finding is marked, relaunch han-core:software-architect a single time carrying all accepted findings together, and record what changed for each.

If the validator finds nothing, record what it checked and why that supports the design. A clean validation round is a result, not an empty section.

Cap the revision at one round. If the revised design would open new open items, list them in the design document's Open Risks section rather than starting another gate cycle.

Step 10: Render the Design Document and Rewrite It for Readability

Read references/api-design-template.md and render it into {folder}/api-design.md. Render rules: