Test behavior through the public API, never internals. Every recommended test verifies observable behavior at a\npublic seam: the inputs a real caller supplies, the outputs and side effects they observe, and the interactions the\nunit has with the other objects and services it collaborates with. Do not recommend tests that reach into private\nmethods, internal state, or implementation structure — those tests pin the how and break on every refactor. When two\ndesigns would produce the same observable behavior, the test must pass for both. If a behavior can only be observed by\ninspecting internals, that is a signal the behavior belongs at a different seam, not a license to test the internal;\nnote it and move the recommendation to the public boundary that exposes it. This is the depth ceiling: cover the\ncritical behaviors a caller depends on, and stop. Do not specify tests for every branch, every private helper, or\nevery intermediate value.
\nYAGNI is a first-class operating principle for tests. Apply the evidence-based YAGNI rule from\n../../references/yagni-rule.md. A test is worth recommending only when (a) the code\nunder review commits to a behavior the test verifies and (b) the failure mode the test would catch is realistic for\nthis codebase. Tests for code paths that don't exist yet, hypothetical adversaries the code doesn't face, hypothetical\nscaling problems the workload doesn't have, \"completeness\" with existing tests, or symmetry (\"we have a test for\ncreate, so we should have one for delete\") are YAGNI candidates and go to the Deferred Tests section with the trigger\nthat would justify writing them. When many speculative low-level tests can be replaced by one durable behavioral test\nthat catches the same realistic failure modes, recommend the single test instead. Every test is ongoing maintenance\nand a brittleness surface.
\nDispatch in proportion to the question. The size band chosen in Step 1.5 caps the roster, and a narrow question\ngets one agent and a prose answer rather than a team and a full document. Never dispatch the full roster for a\nquestion a single agent can settle BECAUSE the dispatch overhead exceeds the work, and a reader who asked one\nquestion pays for a document they did not want.
\nwhich git 2>/dev/null || echo \"not installed\"find . -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.
Resolve project config: read CLAUDE.md's ## Project Discovery section for test command (under\n### Commands and Tests, not ### Frameworks and Tooling), language, and framework; fall back to project-discovery.md.\nStore found values for use in later steps.
Scope determination: Check git installed from Project Context. If empty or not installed, skip to Mode C\nbelow.
Run ${CLAUDE_SKILL_DIR}/scripts/detect-test-context.sh and parse its output. If git-available: false, skip to Mode\nC below.
Mode A: Full git context — git-available: true and the output contains a changed-files-start block with content.
Mode B: Uncommitted changes — git-available: true but output contains changed-files: none.
git diff (unstaged changes), git diff --cached (staged changes), and git status --short\n(untracked files) to identify changed files; if any files are found, use those as scopeMode C: No git / no changes found — git missing, not in a repo, or no changes detected in any state.
\nnode_modules/, .git/, vendor/,\ndist/, build/, __pycache__/, lock files; present the discovered files and ask the user to confirm scopeBuild a list of source files to analyze: expand directories to find source files; identify relevant source files from\nbranch changes or project structure for descriptions.
\nDefault to small. Start the classification at small and only escalate to medium or large when the signals below\nclearly require it. When a signal is borderline, stay at the smaller band.
\nClassify from the user's own request first, and from Step 1's file list only when the request settles nothing. A\nnarrow question asked on a branch with many changed files is still small BECAUSE Step 1 falls back to the whole\nchanged-files list whenever the user named no scope, and that list describes the branch rather than the question.
\nSize override. If $size is non-empty (the user passed small, medium, large, or dynamic as the first\nargument), use it: a band value is the size and skips the signal-based classification above, while dynamic forces the\nsignal-based classification even when the config sets a default band. If $size is empty and either .han/config.md\nsupplies a band via default-swarm-size (per ../../references/config-rule.md), use\nthat band and skip the signal-based classification. Anything that is not one of the four accepted values is trailing\ncontext, not a size.
Bind $focus. Read the user's free-form argument string from the invocation (everything after the optional $size\npositional). If non-empty, bind $focus to that string verbatim; if empty, bind it to none provided. This binding is\nthe description Step 2 passes to each agent prompt.
State the chosen band and mode in one line with the justification before dispatching anything (for example,\nSmall: the request names two proposed contexts on one method, so focused mode, Medium: passed via $size, or\nMedium: from the project .han/config.md default-swarm-size, naming whichever file supplied it). Accept the user's\noverride of the band, the mode, or both.
In focused mode, dispatch only han-core:test-engineer in Step 2, skip the conditional specialists, answer in prose\nper Step 4's focused-mode rules, and skip the two reviewers in Step 5. Step 3 runs in full either way. Its\nbehavioral, prerequisite, and YAGNI sweeps decide what may be recommended at all, so skipping them would let a focused\nanswer recommend a test that cannot be written without an out-of-scope production change. In full mode, run every\nstep as written.
In focused mode, dispatch item 1 alone and skip the conditional-dispatch section entirely.
\nLaunch the testing agents in parallel using the Agent tool with run_in_background: true. Pass each agent the\nfile list from Step 1. In Mode A or Mode B, include on branch {branch} in agent prompts if a branch name was detected\nby the script; in Mode C or when no branch was detected, omit the branch reference entirely. When $focus is anything\nother than none provided, include it in every agent prompt so they can focus their analysis; it is what the\n{any additional context from user arguments} placeholder below resolves to.
Launch han-core:test-engineer agent — prompt: \"Analyze test coverage for the following files{on branch if applicable}: . Recommend tests only at the public API: the inputs a real caller supplies, the outputs\nand side effects they observe, and the interactions the unit has with the objects and services it collaborates with.\nDo not recommend tests that reach into private methods, internal state, or implementation structure — if two\nimplementations would produce the same observable behavior, the test must pass for both. Cover the critical behaviors\na caller depends on and stop; do not specify a test for every branch, private helper, or intermediate value. Apply\nthe YAGNI rule from ../../references/yagni-rule.md — recommend a test only when the\ncode commits to a behavior the test verifies AND the failure mode is realistic for this codebase. Symmetry,\ncompleteness, and hypothetical scaling are YAGNI; defer those to the Deferred Tests section with the trigger that\nwould justify writing them. \"
\nLaunch han-core:edge-case-explorer agent — prompt: \"Explore edge cases for the following files{on branch if applicable}: . Focus on inputs, integration points, and error paths observable through the public API\nand through interactions with collaborating objects and services — not internal state or private implementation.\nApply the YAGNI rule from ../../references/yagni-rule.md — raise an edge case only\nwhen a real caller produces the input, the failure mode has plausible production trigger, or the case is\ncritical-path correctness regardless of caller. Hypothetical adversaries the code doesn't face and symmetry-driven\nboundaries go to Dropped Edge Cases with the trigger that would justify revisiting. {any additional context from user\narguments}\"
\nSkip this whole section in focused mode. Otherwise inspect the file list before launching, and skip any that do not\napply.
\nLaunch han-core:concurrency-analyst agent — only if the file list touches threads, async/await, goroutines,\nactors, shared mutable state across requests, timers, locks, or message queues. Prompt: \"Identify concurrency test\ngaps for the following files{on branch if applicable}: . Focus on race conditions, lock ordering,\nshared-resource contention, deadlock potential, and async error handling that should be covered by tests. {any\nadditional context from user arguments}\"
\nLaunch han-core:adversarial-security-analyst agent — only if the file list touches authentication, authorization,\ninput validation, data isolation, session handling, crypto, file uploads, external API calls with secrets, or SQL/ORM\nquery construction. Prompt: \"Identify negative security tests that should exist for the following files{on branch\n if applicable}: . Focus on exploit paths that tests could catch before production — authorization\nbypass, injection, broken isolation, insecure defaults. Return test recommendations, not general threat modeling.\n\"
\nExtra agents named in the project config's ## Extra Agents list join this conditional-dispatch pool under the same\nfile-list-signal selection, per ../../references/config-rule.md: dispatch one only\nwhen the file list carries a signal matching its stated specialty, and skip an entry that does not resolve to a\ndispatchable agent with a one-line note.
Wait for every dispatched agent to complete and collect full output for processing in Step 3.
\nCombine findings from every dispatched agent into a unified, prioritized test plan:
\norder,\na new validation, a changed return value, a schema column, or any other edit to shipped code, is not a test to\nwrite. It is a production change wearing a test's clothes, and folding it into the plan hands the implementer a code\nchange nobody authorized. Move it out of the priority tiers into Blocked by a Production Change, recording the\nchange it needs, the file that would carry it, and who else consumes that file, so a reader can see the blast radius\nand open a separate ticket. Run this sweep before IDs are assigned, and run it over security items too: an honest\nfinding at CRIT is still out of scope if it cannot be tested without first changing shipped code.Reason: YAGNI — {gate failure} and the trigger that would justify writing the test (a third real customer hits the\nedge case, the feature actually ships the path, a measured production failure occurs, etc.). When several recommended\nlow-level tests can be replaced by one durable behavioral test that catches the same realistic failure modes, replace\nthem with the single test and record the dropped low-level tests under Deferred with\nReason: YAGNI — single behavioral test catches the same realistic failure modes.Before generating, invoke han-communication:readability-guidance to source the shared readability standard into your\ncontext, then apply it as you write the plan's plain-language spine (Summary, What Needs Testing and Why, What Each Test\nCovers), holding the named audience: the engineer who will implement the tests. The frame governs how a fact is said,\nnever whether a required fact appears — keep the file:line references, test levels, and TP-IDs the plan depends on.
In focused mode, do not use the template. Answer in prose: the verdict on what was asked, the reasoning that\nsettles it, and any test worth writing, with the file:line references and test levels the engineer needs. Write no\nsection that the question did not ask for BECAUSE a reader who asked one question should not have to search a\nnine-section document for its answer. Skip the rest of this step's template rules and go to Step 5.
\nIn full mode, use the template at template.md for the output structure. The test plan leads\nwith plain language and defers the implementation detail.
\nWriting rules:
\nLead with behavior. These rules make the plan a human-readable overview first and an implementation outline second:
\n## Technical Reference region. Describe what needs testing and what would break without it, in\nfunctional terms a reader who has not seen the code can follow. Name files, types, and test levels only where they\naid understanding.## Technical Reference region, below the plain-language spine. A reader who only needs to know what to test and why\ncan stop above.Fill in all sections:
\nIn focused mode, skip the two reviewers below and go straight to the readability editor and the self-check that\nfollow them. The two reviewers audit a document's structure and its plain-language layer, and a focused answer has\nneither BECAUSE it is a few paragraphs rather than a layered document.
\nIn full mode, dispatch two reviewers against the generated test plan, in parallel, using the Agent tool. The plan is produced\nin-channel, so embed the full plan text in each agent's prompt (in place of {plan text} below). If the plan was\nwritten to a file, pass that path instead and let the agent read it.
Launch han-core:information-architect agent — prompt: \"Audit the following test plan for findability,\norientation, and comprehension. The intended audience is an engineer or technically-literate stakeholder who needs to\nunderstand what needs testing and why before reading the implementation detail. Check: (1) Do the plain-language\nSummary, What Needs Testing and Why, and What Each Test Covers sections appear before the ## Technical Reference\nregion? If the plain-language content is missing or sits below the reference detail, that is a finding. (2) Does the\nSummary paragraph read for someone who has not seen the code — no file paths, TP-IDs, or framework jargon? (3) Does\nthe heading list let a scanning reader see where the plain-language overview ends and the deep Technical Reference\nbegins? (4) Do the What Each Test Covers lines cross-link to their TP-IDs so a reader can move from plain language to\ndetail? Return a list of structural edits; do not return an empty list unless the plan leads with plain language and\ndefers the implementation detail.\\n\\n\"
Launch han-core:junior-developer agent — prompt: \"Review the following test plan as a generalist teammate who has\nnot seen this code. Reading only the plain-language sections (Summary, What Needs Testing and Why, What Each Test\nCovers), can you understand what needs testing and why it matters without dropping into the Technical Reference? Flag\nany plain-language line that is unclear, leans on undefined jargon, assumes context a reader would not have, or\nstates a test without conveying what would break if it were missing. Return a list of clarity findings with the\nsection and line they apply to; return an empty list only if the plain-language layer stands on its own.\\n\\n{plan\ntext}\"
\nApply every actionable edit the agents return. For findings that require author judgment (scope or audience ambiguity),\nsurface them to the user with a recommended resolution; do not silently resolve.
\nOnce every actionable edit is applied and the plan is final, dispatch han-communication:readability-editor (one Agent\ncall) to audit and rewrite the plan's prose against the readability standard. If the plan was written to a file, pass the\neditor that file path; if it is in-channel, pass the plan text and apply the returned rewrite. Also pass the named\naudience: the engineer who will implement the tests; the editor reads han-communication's own canonical rule, so pass no\nrule path. It must preserve every fact and operate on prose regions only — never inside code fences, tables, or the\nTP-NNN test identifiers, which must survive unchanged so they still resolve. Apply its rewrite to the plan.
Then run the standardized readability self-check (the shared standard is in your context from\nhan-communication:readability-guidance) over the plan's prose regions only — never inside code fences, tables, or the\nTP-NNN identifiers. Confirm each criterion and fix any failure before presenting:
Run the readability rule's standardized self-check, which is already in your context from the readability-guidance\ninvocation above. Correct every failure before presenting. Its fidelity criterion is not optional: the standard governs\nhow the content is said, and drops a required fact only when the reader asked for less and losing it would not change\nwhat they do next.