han

han 5.4.0 fixes the personal-config probe that broke in every skill at once, and adds a second output style to the communication layer. On Claude Code 2.1.228 the inline probe carried by every Project Context block stopped loading and reported a "Contains expansion" error, which @VikiAnn reported in issue #178 and PR #184 fixed by moving the probe into a shared scripts/han-config-dir.sh that every plugin symlinks to. That one change is why all twelve children move this release. han-communication (1.2.0) ships the han-concise output style and promotes technical-detail separation into the canonical readability rule. han-coding (3.3.0) gates out-of-scope production changes in /tdd and /automated-test-planning. han-plugin-builder (2.2.0) adds an authoring rule for reaching an environment variable, and gives the guidance corpus tables of contents. han-core (3.1.1), han-documentation (1.0.1), han-research (1.0.1), han-planning (2.2.1), han-github (2.3.1), han-reporting (2.2.1), han-feedback (2.0.2), han-atlassian (2.3.1), and han-linear (1.1.1) carry the config-script change, the re-synced rule files, and their own small fixes.

What's Changed

• Han config expansion fix by @mxriverlynn in https://github.com/testdouble/han/pull/184
• feat(han-communication): honor the shape the reader asked for by @mxriverlynn in https://github.com/testdouble/han/pull/186
• feat(han-communication): add the han-concise output style and tighten technical-detail separation by @mxriverlynn in https://github.com/testdouble/han/pull/189
• fix(han-planning): correct two defects in the visual-material reference material by @mxriverlynn in https://github.com/testdouble/han/pull/190
• fix(han-coding): gate out-of-scope production changes in tdd and automated-test-planning by @mxriverlynn in https://github.com/testdouble/han/pull/191
• fix(han): bring skills back under Anthropic's authoring limits by @mxriverlynn in https://github.com/testdouble/han/pull/192
• V5.4.0 beta by @mxriverlynn in https://github.com/testdouble/han/pull/185

Issues closed

• Personal-config context probe fails to load on Claude Code 2.1.228, "Contains expansion", breaks every skill with a Project Context block (#178) — opened by @VikiAnn, fixed in #184 by @mxriverlynn
• Han Feedback: han-readability (2026-08-11) (#177) — opened by @mxriverlynn, fixed in #186 by @mxriverlynn
• Skill guidance check: one description 411 characters over the 1024 limit, 111 reference files without a table of contents (#182) — opened by @kasparovabi, fixed in #192 by @mxriverlynn
• Han Feedback: plan-a-feature-readability-guidance-explanation-guidance (2026-08-19) (#187) — opened by @mxriverlynn, fixed in #190 by @mxriverlynn
• Han Feedback: automated-test-planning-tdd (2026-08-19) (#188) — opened by @mxriverlynn, fixed in #191 by @mxriverlynn

han v5.4.0

One shared script replaces the inline config probe

Every skill carrying a Project Context block read the personal configuration directory with an inline echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}". Claude Code 2.1.228 refused that form with a "Contains expansion" error, so the block failed to load and the skill lost its personal configuration. @VikiAnn reported it in issue #178, and PR #184 replaced the inline probe with scripts/han-config-dir.sh at the repository root. Every plugin carries a symlink to that one script, and scripts/han-config-dir.bats tests it beside it.

CLAUDE.md and CONTRIBUTING.md record the script, the symlink each plugin carries, and where its tests live. CONTRIBUTING.md also gains an "Adding an output style" checklist, so a second style cannot ship without a long-form doc and a plugin README scent line, and docs/templates/coverage-rule.md extends the coverage rule to output styles for the same reason.

The readability docs describe the reworked standard

docs/readability.md covers the reworked standard: th

han 5.3.0 adds a collaborative working mode to the suite. /pairing builds work in reviewable pieces and hands each one back before starting the next, so you steer while the work happens instead of reviewing a finished result, and it covers code, design decisions, and writing alike. han-core (3.1.0) ships the skill and the shared stop contract behind it. han-coding (3.2.0) and han-planning (2.2.0) wire five existing skills to hand control back at boundaries they already had, so /pairing drives them without either side inventing a second mechanism. The suite-level docs thread the new mode through every catalog, and this release also repairs three defects the pairing branch left in its own documentation. han-communication (1.1.1), han-documentation (1.0.0), han-research (1.0.0), han-github (2.3.0), han-reporting (2.2.0), han-feedback (2.0.1), han-atlassian (2.3.0), han-linear (1.1.0), and han-plugin-builder (2.1.0) are unchanged.

What's Changed

• feat(han-core): add the pairing collaborative working mode by @mxriverlynn in https://github.com/testdouble/han/pull/179

han v5.3.0

The cross-plugin catalogs carry the pairing mode

docs/skills/README.md gains a scent line for /pairing. docs/concepts.md and README.md add it to the sentence describing what han-core carries, and docs/choosing-a-han-plugin.md adds it in four places, including the install table row for the shared agents and project discovery. That page also promised an install of han-core alone gave you "no other skills", which stopped being true the moment /pairing landed there.

docs/workflows.md draws /pairing into both diagrams as a dotted drives edge rather than a solid arrow, because it wraps the skills it runs rather than chaining after them. The planning diagram draws it driving /plan-implementation, /iterative-plan-review, and /tdd; the code-quality diagram draws it driving /refactor, /tdd, and /design-an-api. The prose beside each says the same thing in words, and names the wrapper relationship explicitly so the dotted edge is not read as a chain.

CLAUDE.md adds /pairing to the han-core catalog and gains a Collaborative working mode section pointing at the canonical stop rule and naming the skills that consume it.

The planning and research artifacts behind the skill

docs/plans/pairing-skill/ records the specification, the implementation plan, and the decision, scope, and iteration artifacts, including the rename from pair-with-me and the boundary widening from code work to any kind of work. docs/research/collaborative-output-style.md and docs/research/non-code-chunk-boundaries.md carry the evidence the design rests on, both adversarially validated.

han-core v3.1.0

/pairing builds work in reviewable pieces you steer

/pairing splits a request into concerns, sorts each one, proposes a plan before any work starts, then builds one piece at a time and ends the turn after each. The pacing is the deliverable rather than an interruption in it, so the skill never continues past a stop to be helpful.

Splitting comes before sorting. Two asks that produce two things you would check separately are two concerns, and changing code and answering a question about it are always separate however small either one is, because checking an edit means reading a diff and checking an answer means reading the answer. Bundled, the answer arrives before the edit it rests on has been verified. When the split is genuinely unclear the skill splits anyway and says so in the plan, where merging the two back costs you nothing.

Each concern then sorts through an ordered test, first match winning: skill-backed when a flagged skill covers it, decision work when it produces a choice that commits you to something, prose work when it produces prose someone will read, and open-ended otherwise, where the plan supplies the boundaries with no rule behind them. Concerns sort independently, so one

han 5.2.0 adds two skills to the coding layer. /design-an-api designs the contract for an API change before anyone writes code, and /code-walkthrough paces you through a set of changes one step at a time in conversation. han-coding (3.1.0) ships both. han-core (3.0.1), han-planning (2.1.1), and han-communication (1.1.1) record the dispatch pairings and skill boundaries the two new skills create. The suite-level docs place both in the sizing, concepts, workflow, and how-to catalogs, and the repo's own /han-release skill gets the fix that unblocked this release. han-documentation (1.0.0), han-research (1.0.0), han-github (2.3.0), han-reporting (2.2.0), han-feedback (2.0.1), han-atlassian (2.3.0), han-linear (1.1.0), and han-plugin-builder (2.1.0) are unchanged.

What's Changed

• add skill: /han-coding:design-an-api by @mxriverlynn in https://github.com/testdouble/han/pull/175
• feat(han-coding): add the code-walkthrough skill by @mxriverlynn in https://github.com/testdouble/han/pull/176

Issues closed

• Han Feedback: software-architect-junior-developer-adversarial-validator (2026-08-06) (#173) — opened by @mxriverlynn, fixed in #175 by @mxriverlynn

han v5.2.0

/han-release stops reading an unchanged plugin's tag as a collision

Step 9 of .claude/skills/han-release/SKILL.md computed a tag name for every plugin in the marketplace and stopped the run on any remote-at-other-commit state. An unchanged child keeps its version, so it keeps the tag an earlier release gave it, and that tag points at that earlier release commit by design. Read literally, the gate stopped every release after the first: cutting v5.1.0 tripped it on 11 of 13 plugins.

Step 9.1 now splits plugins into two sets from the version plan. Being tagged this release covers every plugin whose target differs from its baseline, plus every new plugin from Step 3a. Carried forward covers every unchanged child. Step 9.3 reads remote-at-other-commit against the set the plugin is in, since the state means opposite things for the two. A carried-forward tag passes when git merge-base --is-ancestor puts it inside this release's own history, and stops otherwise. A plugin being tagged now stops unconditionally with no ancestor check, which leaves the original collision protection intact.

Step 11.1 carried the same rule at the publish gate and would have blocked the run after the tags were already pushed, so it now holds each set to its own rule and rejects absent or local-only in either. Step 10 gains the carried-forward skip, and Step 12 distinguishes it from a remote-at-commit skip when reporting. .claude/skills/han-release/scripts/remote-tag-state.sh is unchanged in behavior: its header comment no longer calls remote-at-other-commit unrecoverable, and says the caller decides, because the script cannot see the version plan.

The cross-plugin catalogs list both new skills

docs/sizing.md adds /code-walkthrough and /design-an-api to the sizing-aware list, to the at-a-glance table with each band's roster and output, and to the per-skill Sizing link list. docs/concepts.md adds both to the sizing-aware list and to the sentence describing what han-coding carries. docs/quickstart.md names /code-walkthrough in its sizing note. docs/skills/README.md gains a scent line for each. CLAUDE.md names both in the han-coding catalog and completes the vendored reference lists in the layout tree, which had omitted config-rule.md from the han-core, han-documentation, han-research, and han-coding entries.

docs/workflows.md adds two chains. /architectural-analysis → /design-an-api → /tdd joins the code-quality diagram and its prose: judge the structure you are designing into, shape the contract against one stated goal, then implement it test-first, with the analysis step optional because /design-an-api runs its own discovery wave. /code-walkthrough → /code-review joins the linear chain

han 5.1.0 adds a selectable output style that holds the readability standard across a whole session, not only inside the skills that source it. han-communication (1.1.0) ships the style and its long-form doc; the suite-level docs gain the coverage rule and the operator guidance that make an output style a first-class component of the repo. han-core (3.0.0), han-documentation (1.0.0), han-research (1.0.0), han-planning (2.1.0), han-coding (3.0.0), han-github (2.3.0), han-reporting (2.2.0), han-feedback (2.0.1), han-atlassian (2.3.0), han-linear (1.1.0), and han-plugin-builder (2.1.0) are unchanged.

What's Changed

• feat(han-communication): add the han-readability output style by @mxriverlynn in https://github.com/testdouble/han/pull/174

han v5.1.0

Output styles are a new component kind for this repo, so the shared surfaces that describe what a plugin ships had nowhere to name one. This release adds that place.

Coverage rule extended to output styles

docs/templates/coverage-rule.md now requires a long-form doc for every output style, in {plugin}/docs/output-styles/{name}.md, alongside the existing requirement for every skill and every agent. The rule gains an output-style variant section describing the heading deviations, following the precedent set by the inline-guidance variant: the deviations are described in the rule itself rather than in a fourth template file. The variant renames When to use it and How to invoke it to When to select it and How to select it (a style is selected once in /config, not called per task), replaces What you get back with What it changes (no artifact comes back), and adds What it does not reach for the boundaries that surprise people. It drops How to get the most out of it, YAGNI, and Sources. There is no repo-root output-styles index; add one when a second plugin ships a style.

Operator docs name the style and its limits

docs/readability.md gains a section on applying the standard to a whole session, naming the three limits: the style does not reach dispatched subagents, it carries the built-in voice only because a static system prompt cannot run the .han/config.md probe, and it is a derived copy that can drift from the canonical rule and voice files. docs/choosing-a-han-plugin.md and CONTRIBUTING.md name the style in the han-communication scent. CLAUDE.md gains the output-styles/ layout line and a doc-map entry warning that the style is derived from han-communication/references/readability-rule.md and han-communication/references/writing-voice.md, so an edit to either one needs a matching check against the style.

The new docs/research/readability-guidance-in-output-styles.md is the standalone research report behind the change. It is not tied to a plan and changes no skill behavior. Contributed by @mxriverlynn.

han-communication v1.1.0

The plugin ships a new component kind: the Han Readability output style, in han-communication/output-styles/han-readability.md. Select it under Output style in /config and every turn of the session is written to the readability standard, instead of only the turns inside a skill that invokes readability-guidance. It takes effect on the next session or after /clear, because Claude Code reads the output style once at session start. The style lives in the auto-discovered default output-styles/ directory, so plugin.json needs no outputStyles field.

The style distills the audience frame, output properties, fidelity guard, and six-criterion self-check from han-communication/references/readability-rule.md together with the blocklist from han-communication/references/writing-voice.md. It sets keep-coding-instructions: true, so Claude Code's software engineering behavior is unchanged: the style changes how work is written up, not how it is done.

Three boundaries are stated in the style's long-form doc at `han-communication/docs/output-styles/han-re