which git 2>/dev/null || echo \"not installed\"git branch --show-current 2>/dev/null || echo \"no git branch\"git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo unknownfind . -maxdepth 1 -name \"CLAUDE.md\" -type ffind . -maxdepth 3 -name \"project-discovery.md\" -type fbash \"${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh\" 2>/dev/null || echo \"$HOME/.claude\"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\nthat returns no file is no personal configuration: continue silently. When that file or the project .han/config.md\nprobe supplies content, apply it per config-rule.md, which governs precedence\nbetween the two files, relative-path resolution, and what to do with a file that reads but cannot be used.
Read these before dispatching anything. They constrain every step below.
\nhan-core:codebase-explorer,\nhan-core:software-architect, han-core:junior-developer, and han-core:adversarial-validator run at every size\nBECAUSE evidence, design, questioning, and attack are the irreducible core of a contract that survives contact. Every\nother specialist is added only when the interface's signals warrant it and the band allows it, BECAUSE dispatching an\nagent whose domain the contract never touches burns tokens and pulls the design toward concerns the goal did not ask\nfor.tdd run against this document.han-communication:readability-guidance and applies it, holding one audience\nabove the writing: the engineer who will implement this contract and the reviewer who will approve it. Scope that\nframe per section so the specifics that reader needs — exact signatures, types, precedence rules, file paths — are\npreserved, never simplified away.Bind $size. If the user passed small, medium, large, or dynamic as the first positional argument, bind\n$size to it. Anything else is part of the goal-and-interface context, not a size; bind $size to the literal\nnone provided.
Resolve the goal. Take the remaining argument and conversation context as the goal this design serves. A ticket\nreference, issue URL, file path, or a described capability all qualify. Read the referenced material if it names a file\nor is fetchable from the conversation. Record the goal verbatim where it is quotable — the justification field in every\nlater step cites it. If no goal resolves, stop and ask the user for the ticket, issue, or one-paragraph statement of\nwhat this change is for. Do not proceed without it.
\nResolve the interface. Identify what is being designed: which component, function, module, route, or payload, and\nwhere it lives. Confirm it resolves to real files using Glob and Read. If the interface is genuinely new and has no\nfile yet, resolve instead the module or directory it will live in and the consumers that will call it. If neither\nresolves, 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\ndefault branch reads unknown, origin/HEAD is unset and there is no base to compare against: the working tree is\nthe starting point, no question is asked, and the run continues. Otherwise run\ngit diff --name-only {default branch}...HEAD and check whether any interface file resolved above appears in the\noutput. Only when one does, ask the user in one short message whether to design from the branch as it stands or from\nthe merge base, ignoring the branch's changes; read the merge-base state with git show when they choose the merge\nbase. In every other case — no interface file changed on the branch, git unavailable, or the command fails — the\nworking 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\nback to project-discovery.md. These resolve language, framework, and convention questions so the agents infer less. If\nneither 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,\nand {folder}/api-design.md. Resolve {folder} in this order:
output-directory, place the run folder under it, per\nconfig-rule.md.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\nalready exists there, write every file this run produces to a date-suffixed name (for example api-design-2026-08-07.md\nalongside context-brief-2026-08-07.md and design-options-2026-08-07.md) so one run's files stay together, and state\nwhich files were written; never silently overwrite. State the chosen folder in one short line and proceed without\nwaiting for confirmation.
Run targeted Grep and Glob over the interface and its consumers to detect which domains the contract actually\ntouches. These signals drive both the band and the roster:
Classify the size. Default to small. Escalate only when a band's signal is clearly present; when a signal is\nborderline, stay at the smaller band.
\n$size is\nlarge.Apply the size override. If $size is not none provided, use it: a band value is the band and skips the\nsignal-based classification above, while dynamic forces the signal-based classification even when the project config\nsets a default band. If $size is none provided and the project config supplies a band via default-swarm-size (per\nconfig-rule.md), use that band, skip the signal-based classification, and announce\nthe config as the source. In every case still select specialists by signal: a large band does not dispatch agents\nwhose domain the contract never touches. A conversational override (\"design this large\") is equivalent to $size.
Spine — dispatched at every size:
\nhan-core:codebase-explorer — discovers the current surface, its consumers, and the constraints the design has to\nlive 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:
\n| Specialist | \nAdd when | \nMin band | \n
|---|---|---|
han-core:structural-analyst | \nConsumer-spread signal | \nMedium | \n
han-core:behavioral-analyst | \nBoundary-data signal | \nMedium | \n
han-core:concurrency-analyst | \nOrdering signal | \nMedium | \n
han-core:data-engineer | \nData-contract signal | \nMedium | \n
han-core:on-call-engineer | \nFailure-path signal | \nMedium | \n
han-core:system-architect | \nSystem-seam signal | \nLarge | \n
han-core:adversarial-security-analyst | \nTrust-boundary signal | \nMedium | \n
Roster caps by band are ceilings, not quotas: small runs the spine only (4 agents); medium adds at most two\nsignalled specialists (up to 6 agents); large adds at most four, including han-core:system-architect when a\nsystem-seam signal is present (up to 8 agents). A band reached by override rather than by signal can sit well under its\nceiling; add no specialist whose signal is absent just to fill the band. If more specialists are signalled than the cap\nallows, keep the band's count, prefer the specialists covering the strongest signals, and name the omitted domains in\nthe 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\nsame signals and band caps, per config-rule.md: add one only when a signal in the\ninterface matches its stated specialty, count it against the band's cap, and skip an entry that does not resolve to a\ndispatchable agent with a one-line note.
Announce the decision in one line before dispatching, with per-specialist justification — for example:
\n\n\nSize: medium. Designing the query-parameter prefill contract on
\nFlowProvider; consumer-spread signal (7 call\nsites) and a trust-boundary signal (values arrive from the URL). Roster (6):han-core:codebase-explorer,\nhan-core:structural-analyst(consumer audit),han-core:adversarial-security-analyst(untrusted URL input), then\nhan-core:software-architect,han-core:junior-developer, andhan-core:adversarial-validator.
State git availability in the same message if git is absent. Proceed without a blocking confirmation; discovery is\nread-only and re-runnable, so a gate here would gate a reversible operation. If the user objects to the roster, honor\nthe adjustment.
\nRunning collaboratively. When the request asks to review each round as it lands, which is what\npairing does when it hands work here, stop at this point and hand control back instead of continuing. Present the stop\nin the shape collaborative-stop-rule.md specifies. Absent such a request,\ncontinue 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\nvalidation round. The two human gates below are unchanged and still fire regardless.
\nLaunch han-core:codebase-explorer and every signalled specialist in a single message with one Agent call per agent\nso they run concurrently. Each brief must contain:
Wait for the whole wave to return. Then write {folder}/context-brief.md: a numbered list of findings (F1, F2, F3, …),\neach carrying the finding, its provenance (a file:line citation, or the label inferred), and the agent that reported\nit. Merge duplicates and keep conflicting findings as separate numbered entries with both citations, rather than\npicking a winner. Apply the evidence rule from ../../references/evidence-rule.md to\nevery finding. When a question the design depends on has no evidence at any tier, record it as an open item rather than\nguessing, 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\ndomain left uncovered, and continue. A missing specialist narrows the design's evidence; it does not stop the run. If\nhan-core:codebase-explorer returns nothing usable, relaunch it once with the interface's file paths spelled out. If\nthe second attempt also returns nothing, stop and tell the user the interface could not be discovered, naming the paths\nthat were searched.
Launch han-core:software-architect with one Agent call. Pass it the stated goal verbatim, the full context brief,\nand the resolved project conventions. Its brief must ask for:
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\nmissing requirement restated. If the second attempt still returns one option, carry that option forward and record in\nthe design document that only one viable option was produced, with the architect's stated reason. If the second attempt\nstill leaves elements unjustified, do not carry those elements: move each one to the cut list with what it would have\ndone and the note that no justification was produced for it, so the gap reaches the user in Step 6 rather than passing\nas designed.
\nBefore writing the question, invoke han-communication:explanation-guidance to source the shared explanation standard\ninto your context. After that skill returns, proceed immediately to the question below — do not stop there. The\nstandard 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\nlabelled as recommended, each with its one-line reasoning. Apply the explanation standard to the wording, so each option\nreads as an outcome the user could observe rather than a mechanism. Include the cut list in the surrounding message so\nthe user sees what the design is giving up.
Handle the response:
\nLaunch han-core:junior-developer with one Agent call. Pass it the stated goal verbatim, the context brief, and the\nchosen option in full. Its brief must ask it to reframe the contract in simpler terms and raise the clarifying questions\na generalist who was not in the room would ask: unstated prerequisites, conflicts with the project's own conventions,\nnames that do not say what they hold, and behavior the contract leaves undefined. Ask for numbered questions.
Sort the returned questions into three buckets:
\nThen relaunch han-core:software-architect with one Agent call, passing the chosen option, every question, and the\nanswers from buckets 1 and 2, and ask it to amend the design accordingly. Hold the open items until Step 8 answers\nthem.
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\nto settle open items; with none to settle it has nothing to ask and no answer to fold in.
\nOtherwise surface the open items — those the question round produced in Step 7, plus any no-evidence item recorded in\nStep 4 — one at a time, each as its own AskUserQuestion call. Never batch them BECAUSE\neach answer routinely settles or reshapes the ones behind it, and a batch asks the user to decide in an order the design\ndoes not follow.
Apply the explanation standard already in your context from Step 6 to each question's wording. Each question leads with\nthe plain-language consequence of the choice, names two to four candidate answers, and says what changes in the contract\ndepending on the answer. After each answer, re-check the remaining open items: drop the ones the answer just settled,\nand re-word the ones it changed.
\nWhen every open item is answered, relaunch han-core:software-architect with one Agent call carrying the answers, and\nhave it fold them into the amended design. Record each answer in the design document as the justification for the\nelements it settles.
Launch han-core:adversarial-validator with one Agent call. Pass it, verbatim and unsummarized, the stated goal, the\nfull context brief with every finding and its citation, the amended design with its justifications, and the cut list.\nDo not summarize — the validator needs the detail to attack effectively. Its job is to try to break the contract: find\nthe consumer the design forgets, the input state it does not define behavior for, the invariant a caller can violate,\nthe justification that does not actually follow from the goal, and the finding whose evidence does not support what the\ndesign built on it.
Record its output as numbered validation findings (V1, V2, V3, …), and mark each one:
\nhan-core:software-architect a single time\ncarrying 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\nresult, not an empty section.
\nCap the revision at one round. If the revised design would open new open items, list them in the design document's Open\nRisks section rather than starting another gate cycle.
\nRead references/api-design-template.md and render it into\n{folder}/api-design.md. Render rules:
Then invoke han-communication:readability-guidance to source the shared readability standard into your context. After\nthat skill returns, proceed immediately to the rewrite below — do not stop there. Dispatch\nhan-communication:readability-editor with one Agent call to audit and rewrite the document. Pass it the\nfile path and the named audience: the engineer who will implement this contract and the reviewer who will approve it.\nThe editor reads han-communication's own canonical rule, so pass no rule path. It preserves every fact and edits prose\nregions only — never inside code fences, pseudocode sketches, type signatures in code blocks, or finding-ID and\nfile:line citation identifiers. Apply its rewrite to the file.
Then run the readability rule's standardized self-check, which is in your context from the readability-guidance\ninvocation above, over the document's prose regions only. Correct every failure before presenting. Its fidelity\ncriterion is not optional: the standard governs how the content is said, and drops a required fact only when the reader\nasked for less and losing it would not change what they do next.
Present the design to the user in a short closing message covering:
\ntdd run that implements the contract.