Docs: Why a focus on solo and small teams?#27
Merged
Conversation
Standalone research report cataloguing the six categories of org-level lift in enterprise AI coding tooling: governance and compliance, shared prompt registries, retrieval over org knowledge, model customization, MCP context servers, and PR-layer AI review. Used to inform issue #25's "Why solo and small teams" article so the article can credibly describe what Han deliberately does not provide. Validated via adversarial-validator; eight findings reshaped the evidence chain (broken corroboration, miscategorized artifact, vendor laundering, missing category). Recommendation ordering survived; several individual product claims softened with explicit caveats.
New article at docs/why-solo-and-small-teams.md with two parts: (1) Han acts as a full team on its own by dispatching specialist sub-agents that fill the role gaps a solo or small-team engineer does not have headcount for; (2) Han intentionally provides no org-level lift on its output, with concrete examples of what that lift looks like in the wild (GitHub Copilot Enterprise org custom instructions, Anthropic Claude Enterprise governance) drawn from the enterprise AI tooling research report. Linked from docs/concepts.md (sizing question pulled to the top so readers encounter it before the skill-and-agent model) and from README.md (positioned between "what this plugin does" and the path picker so a new reader encounters the sizing answer first).
#25) Information-architect and junior-developer reviews returned ~25 findings between them. Applied the must-fix and should-fix items: Voice and conventions: - Drop two "actually" uses (banned per writing-voice profile) - Switch agent prose names to backticked agent IDs with links to the agent long-form docs, matching concepts.md convention - Add "Han is a Claude Code plugin" framing for search-arrival readers who have not read README first - Add explicit "per Anthropic's own product pages" qualifier to the Claude Enterprise paragraph so vendor-claimed evidence carries across from the research report instead of being promoted to fact Structure and findability: - Add audience / time / outcome orientation block under H1 (EPPO) - Promote the verdict to a "Short answer" blockquote at the top so the named "decide in two minutes" task is answerable in seconds - Convert H2s from declarative sentences ("Han acts as a full team on its own") to navigational labels ("What Han gives a small team", "What Han does not give a large team or enterprise") - Add H3 sub-boundaries inside Section 2 (categories, examples, what-it-means) so the three topic types each have an anchor - Pull the binary self-selection decision into a visually distinct closing blockquote with separate "if Han is your fit" and "if not" paths - Add a third concrete example (org-hosted MCP context servers) alongside Copilot Enterprise and Claude Enterprise, since MCP is the category most directly relevant to a Claude Code plugin's audience and addresses non-GitHub readers - Add reason for "intentional" non-lift (personal project, no SLA, not staffed to run an org-level operations surface) so the claim is grounded rather than asserted - Add a "concluded Han is not your fit" path in "Where to go next" so the disqualified reader has somewhere to go - Mark the research report as canonical source for the category set to prevent silent drift if categories evolve Surrounding docs: - Reorder README callout to lead with the secondary-audience hook ("Evaluating Han for a larger org?") so the engineering leader the article exists for encounters the relevance cue first - Move concepts.md callout below the TL;DR so the primary audience (solo / small-team engineers) gets their reward before the sizing-question gate
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #25. Adds a "why solo and small teams" intro article so a reader encounters Han's sizing positioning before deciding whether the plugin fits their situation, and lands the underlying enterprise-AI-tooling research that grounds the article's "what Han deliberately does not provide" section.
The article has two parts, mirroring the issue's content outline:
/code-review,/plan-a-feature, and/investigatewith linked agent IDs.The article was reviewed by both
information-architectandjunior-developerbefore this PR was opened, and the must-fix and should-fix findings from both reviews were applied (orientation block, promoted verdict, navigational H2 labels, H3 sub-boundaries, decision-rule closing block, MCP added as a third example for non-GitHub readers, banned "actually" uses dropped, backticked agent IDs, README callout reordered to lead with the secondary-audience hook, concepts.md callout moved below the TL;DR so the primary audience is not taxed).Key file changes
docs/why-solo-and-small-teams.md(new). The intro article. Linked fromREADME.md(between "what this plugin does" and the path picker) and fromdocs/concepts.md(callout positioned after the TL;DR so the primary audience reaches their reward first).docs/research/enterprise-ai-tooling-integration.md(new). Standalone research report cataloguing six categories of org-level lift in enterprise AI coding tooling (governance and compliance, shared prompt registries, retrieval over org knowledge, model customization, MCP context servers, PR-layer AI review) across 11 indexed artifacts. Produced by the/han:researchskill at small size with oneresearch-analystand theadversarial-validator. The validator returned 8 findings that reshaped the evidence chain: broken corroboration (A1 does not actually corroborate A2 on knowledge-base retirement), miscategorized artifact (Amazon Q Customizations moved from O2 retrieval to O3 model customization), vendor laundering (WorkOS on Augment Code is vendor-adjacent, not independent), phantom citation (applied-ai.com source was never actually fetched), and a missing category (PR-layer AI review surfaced as new O6). Recommendation ordering survived; several individual product claims were softened with explicit caveats. This research is the canonical source the article cites for the category set, so the article can stay short while the report carries the evidence weight.docs/concepts.md. New callout below the TL;DR pointing readers evaluating Han for a larger org to the new article.README.md. New callout between the "what this plugin does" paragraph and the path picker, leading with the secondary-audience hook ("Evaluating Han for a larger org?") so the engineering leader the article exists for encounters the relevance cue before the affirmative claim.No plugin entity counts changed. No skills, agents, or templates were added or renamed. CHANGELOG.md and plugin.json are unchanged per the PR template's release-handling rule.