I read through the documentation end to end while getting oriented in the suite, and hit two places where pages disagree with each other or with the skill definitions. Both are small, and both are the kind of thing a new reader trips on, because the contradicting statements sit in the two pages a new reader is told to start with.
Line numbers are from main as of the copy I read; the quoted text is the reliable anchor if they have drifted.
1. /design-an-api is missing from the quickstart's sizing-aware list
docs/quickstart.md:196 lists nine sizing-aware skills:
The sizing-aware skills (/architectural-analysis, /code-overview, /code-review, /code-walkthrough, /gap-analysis, /iterative-plan-review, /plan-a-feature, /plan-implementation, /research) classify the work as small, medium, or large before dispatching agents.
docs/concepts.md:136 lists ten for the same concept, and the extra one is /design-an-api.
The skill definition agrees with concepts.md. han-coding/skills/design-an-api/SKILL.md declares:
arguments: size
argument-hint: "[size: small | medium | large | dynamic] [the goal or ticket this serves, and the interface to design]"
So /design-an-api large "..." works, but a reader who only reads the quickstart has no way to know that.
Suggested fix: add /design-an-api to the docs/quickstart.md:196 list, keeping the alphabetical order it already uses. That is the whole change.
2. Two pages deny the han-reporting exception they document elsewhere
han-reporting/.claude-plugin/plugin.json declares "dependencies": ["han-communication"], with no han-core. Every other layer plugin declares both. That makes han-reporting the one layer you can install without the shared agent roster, and two pages say otherwise.
docs/choosing-a-han-plugin.md contradicts itself two lines apart. Line 78 states the exception correctly:
readability standard either way. (han-reporting is the exception: it depends on han-communication alone.)
Line 80 then generalizes over it, in bold:
That means every layer install comes with the shared agents. The real choice comes down to:
A reader skimming for the bold sentence, which is what bold invites, gets the wrong answer. The heading above it is "The one thing that surprises people", so this is the paragraph carrying the most weight on the page.
docs/concepts.md:260 denies the install exists at all:
The practical choice is core only, the bundled suite, or the suite plus whichever opt-in plugins you want. There is no planning-only, coding-only, GitHub-only, or reporting-only install.
Three of those four are right. Reporting-only is exactly the install that is possible: /plugin install han-reporting@han gives you /stakeholder-summary and /html-summary plus han-communication, and no han-core agents.
Suggested fix: in choosing-a-han-plugin.md, scope the bold claim to the layers it is true of ("every layer install except han-reporting comes with the shared agents"). In concepts.md, drop reporting-only from the list and say what han-reporting alone actually gives you.
Minor, while I am here
README.md:5 embeds the banner with no alt attribute:
<img src="images/han-banner.png">
Worth a short description for screen readers and for anyone whose images do not load.
Happy to open a PR for any or all of these if that is useful. Thanks for the suite, the layering is genuinely nice to read about.
I read through the documentation end to end while getting oriented in the suite, and hit two places where pages disagree with each other or with the skill definitions. Both are small, and both are the kind of thing a new reader trips on, because the contradicting statements sit in the two pages a new reader is told to start with.
Line numbers are from
mainas of the copy I read; the quoted text is the reliable anchor if they have drifted.1.
/design-an-apiis missing from the quickstart's sizing-aware listdocs/quickstart.md:196lists nine sizing-aware skills:docs/concepts.md:136lists ten for the same concept, and the extra one is/design-an-api.The skill definition agrees with
concepts.md.han-coding/skills/design-an-api/SKILL.mddeclares:So
/design-an-api large "..."works, but a reader who only reads the quickstart has no way to know that.Suggested fix: add
/design-an-apito thedocs/quickstart.md:196list, keeping the alphabetical order it already uses. That is the whole change.2. Two pages deny the
han-reportingexception they document elsewherehan-reporting/.claude-plugin/plugin.jsondeclares"dependencies": ["han-communication"], with nohan-core. Every other layer plugin declares both. That makeshan-reportingthe one layer you can install without the shared agent roster, and two pages say otherwise.docs/choosing-a-han-plugin.mdcontradicts itself two lines apart. Line 78 states the exception correctly:Line 80 then generalizes over it, in bold:
A reader skimming for the bold sentence, which is what bold invites, gets the wrong answer. The heading above it is "The one thing that surprises people", so this is the paragraph carrying the most weight on the page.
docs/concepts.md:260denies the install exists at all:Three of those four are right. Reporting-only is exactly the install that is possible:
/plugin install han-reporting@hangives you/stakeholder-summaryand/html-summaryplushan-communication, and nohan-coreagents.Suggested fix: in
choosing-a-han-plugin.md, scope the bold claim to the layers it is true of ("every layer install excepthan-reportingcomes with the shared agents"). Inconcepts.md, dropreporting-onlyfrom the list and say whathan-reportingalone actually gives you.Minor, while I am here
README.md:5embeds the banner with noaltattribute:Worth a short description for screen readers and for anyone whose images do not load.
Happy to open a PR for any or all of these if that is useful. Thanks for the suite, the layering is genuinely nice to read about.