han

Authoritative guidance for building Claude Code skills, agents, and plugins, plus init and update steps that install and refresh the plugin-building skills in the current repository. Use when you need the rules or best practices for a skill, agent, hook, or plugin — designing, reviewing, hardening, or checking one against the guidance. Run with `init` to vendor the guidance, skill-builder, and agent-builder skills into the current repository (so they run with no dependency on this plugin) plus a path-scoped rule index, or `update` to refresh an already-vendored copy. Does not run an interview to build a new skill or agent from scratch — use skill-builder or agent-builder. Does not write feature code, review application code, or build non-plugin features.

Break a work-items.md file (produced by /plan-work-items) into independently-grabbable GitHub issues, one per slice, in each slice's target repo. Use when you want to turn a work-items file into GitHub issues, publish work items as issue tickets, or create implementation tickets that can be worked on and tracked on GitHub. Does not produce the work-items file itself — use plan-work-items to break a plan into work items first. Does not review code or post pull request comments — use post-code-review-to-pr for that.

Builds a feature implementation plan from an existing feature specification (or equivalent context) through a project-manager-led team conversation. Use when the user wants to plan how to implement, build, deliver, or ship a feature that has already been specified. Does not specify what the feature should do — use plan-a-feature first. Does not refine or stress-test an already-written plan — use iterative-plan-review.

Break a trusted implementation plan (or other provided context) into independently-grabbable, atomic work items, written to a single work-items.md file. Use when the user wants to convert a plan into work items, create implementation tickets or tasks, divide a plan into work units, or break the plan down into grabbable pieces. Do not use when there is no implementation plan yet or the plan is not yet trusted — use plan-implementation to produce the plan or iterative-plan-review to harden it first. Does not sequence work into demoable delivery phases — use plan-a-phased-build for that. Does not write code — use tdd to implement a work item.

Write code through a disciplined, BDD-framed Test-Driven Development loop: build a behavior test list, then drive each behavior through red-green-refactor with an enforced observed-failure gate. Use when the user wants to implement, build, or write code test-first, "do TDD", follow "red-green-refactor", drive code from tests, choose the next test by the Transformation Priority Premise (TPP) or ZOMBIES ordering, or grow a feature behavior-by-behavior with tests leading. This skill writes and changes code; it does not produce a test plan document (use test-planning), review or audit existing code (use code-review), restructure existing code outside a TDD loop (use refactor), specify what a feature should do (use plan-a-feature), or find the root cause of a bug (use investigate).

Produces a human-readable, progressive-disclosure overview of unfamiliar code or a pull request's changes — why it exists (the real problem it solves or goal it serves for the business or a user), and from there what it does, how it flows, and where to start — so you can get up to speed before working on or reviewing it. Use when you want to understand, get oriented in, make sense of, explain, or get up to speed on a chunk of code, a file, a directory, a symbol, or a PR's changes. Writes the overview to a scratch file and changes no code. Does not review code quality or raise findings — use code-review for auditing changes or post-code-review-to-pr for posting them. Does not produce durable feature or system documentation — use project-documentation. Does not assess architecture or structural risk — use architectural-analysis. Does not diagnose bugs or root-cause failures — use investigate.

Run a comprehensive code review on local source files. Use this skill when the user asks to review, audit, inspect, evaluate, or check code, even if they never use the word "review." Does not post comments to GitHub pull requests — use post-code-review-to-pr for that. Does not analyze architectural structure or module boundaries — use architectural-analysis for that. Does not explain code or a PR to build understanding before reviewing — use code-overview for that. Does not capture feedback on Han's own skills — use han-feedback for that.

Researches an open-ended question — options, possible solutions, prior art, trade-offs, or how something works — and produces a durable, evidence-backed, adversarially-validated report that recommends an option without committing the team to any artifact. Use when you want to research approaches, weigh options, survey prior art or the state of the art, or understand how something works before committing to a direction. Does not diagnose a bug, failure, or root cause — use investigate. Does not specify a feature — use plan-a-feature. Does not create or update a coding standard — use coding-standard. Does not compare two concrete artifacts for gaps — use gap-analysis. Does not assess an existing module's architecture — use architectural-analysis. Does not capture feedback on Han's own skills — use han-feedback.

Triage a raw, vague issue or bug report into a structured document that names what is known, what is missing, and what to do next. Use when an incoming issue, bug report, or problem description is too vague or incomplete for investigation or planning, and recommend the right next han skill. Does not investigate root causes or trace code paths — use investigate for debugging, diagnosis, and root cause analysis. Does not plan features or build solutions — use plan-a-feature or plan-implementation for that.

Turn a work-items.md file (produced by /plan-work-items) into Linear issues, one per slice, in a single target Linear team. Use when you want to publish work items as Linear issues, create implementation tickets to track in Linear, or push a broken-down plan into a Linear team. Requires a configured Linear MCP server and a target team. Reads the team's real workflow states, labels, Projects, and members and resolves every option against them before creating anything; defaults each issue to the team's initial state, unassigned, uncategorized, with no parent or Project unless you ask. Links within-file `Depends on` relationships as native Linear "blocked by" relations and annotates the source file so re-runs resume cleanly. Does not produce the work-items file itself — use plan-work-items first. Does not post to Jira — use work-items-to-jira. Does not post to GitHub — use work-items-to-issues.

Cut a Han release: update CHANGELOG.md with the changes since the last release, bump every plugin that changed, tag the suite version vX.Y.Z, and publish a GitHub release whose notes attribute every merged pull request to its author, credit every closed issue to the person who opened it, the people who contributed to it, and the people who worked on the fix, and link back to the full changelog for that version. Han ships as a parent meta-plugin (`han`) plus child plugins (`han-core`, `han-github`, `han-reporting`, and any future `han-*` extension); the skill versions each plugin independently. Use when releasing, cutting a release, shipping a new Han version, publishing release notes, or tagging a version. Reads each plugin's target version from its plugin.json; when a plugin has not been bumped past the latest tag yet, it proposes a semantic-versioning bump and confirms the whole plan before continuing. Requires the gh CLI, jq, and a clean git checkout. This is a repository-maintenance skill for the Han repo

Update Han plugin documentation so every skill, agent, guidance doc, index, and cross-reference is current and accurate. On a non-default branch, scopes the pass to entities the branch actually touched. On the default branch, performs a full documentation sweep across the whole plugin. Use when updating, refreshing, syncing, auditing, or verifying Han's docs after changing skills, agents, references, or top-level guidance — including "update the docs", "doc sweep", "refresh documentation", "audit the docs", "make sure the docs are current". This is a repository-maintenance skill for the Han repo itself, not a general documentation skill — use /project-documentation to document features in arbitrary projects, /han-release to cut a release (and update CHANGELOG), and /update-pr-description for PR bodies.

Performs deep architectural analysis of a specified module, directory, or feature area by examining structural coupling, data flow, concurrency patterns, risk, and SOLID alignment. Use when the user wants to assess, evaluate, or review the architecture, design quality, dependency structure, coupling, cohesion, or technical debt of an existing part of the codebase. Not for investigating specific bugs, runtime errors, or failures — use investigate. Not for test planning — use test-planning. Not for file-level code review — use code-review. Not for researching open-ended options, prior art, or how something works — use research. Not for writing documentation or architectural decision records.

Restructure existing code without changing its behavior, through a test-gated refactoring loop: a named target, a green suite over that target before any edit, a planned sequence of small named refactorings, and the full suite re-run after every step. Use when the user wants to refactor, restructure, clean up, simplify, or improve the design of existing code, or to apply refactoring recommendations from a code-review or architectural-analysis report. This skill changes code; it does not review code (use code-review), assess architecture (use architectural-analysis), or build new behavior test-first (use tdd). Do not use it on code inside an active tdd loop; the refactor step of tdd owns that cleanup.

Produce a standalone test plan by analyzing code for test coverage gaps and edge cases. Use when you need to create, generate, or draft a test plan for a branch, need to analyze test coverage, or need to identify what tests to write for specific files or directories. Does not write test code — use tdd to implement behavior test-first. Does not refine existing plans — use iterative-plan-review. Does not review code quality, security, or style — use code-review for full code review. Does not evaluate architectural testability or structural coupling — use architectural-analysis for architectural assessment.

Discovers the core attributes of the current code repository and its projects — languages, frameworks, tooling, and where things live — and writes a concise reference section directly into the project's AGENTS.md or CLAUDE.md for other skills, agents, and hooks to consume. Use when scanning, analyzing, or detecting the project's technology stack, build tools, or repository structure. Does not create or update project documentation — use project-documentation for writing feature or system docs.

Create or update a runbook for an operational scenario — an incident an alert fires for, a recurring scheduled task, or a known failure mode on a live service — using a consistent template. Use when writing, drafting, authoring, or updating a runbook for an alert, incident, on-call procedure, scheduled maintenance, or operational SOP. Applies a YAGNI preflight requiring the scenario to be real before producing the runbook. Does not produce feature or system documentation — use project-documentation. Does not record architectural decisions — use architectural-decision-record. Does not create coding standards — use coding-standard.

Run a full pull request review and post review comments directly to the current branch's GitHub PR. Requires the gh CLI to be installed and a PR to already exist for the current branch. Use when you want review feedback posted to GitHub as PR comments. For local code review without posting to GitHub, use code-review instead. Does not write or update PR descriptions — use update-pr-description for that.

Generate a PR description from the current branch's changes against a GitHub PR, using the gh CLI. Use when writing, drafting, or updating pull request descriptions, PR summaries, or PR bodies. Does not review code or post review comments — use code-review for local review or post-code-review-to-pr for posting a review to GitHub.

Applies Han's shared Human-Readable Output Standard to a target you already have — a file on disk, text pasted into the prompt, or a draft already produced in the conversation — by dispatching the readability-editor to rewrite its prose so the main point comes first, headings are descriptive, each paragraph carries one idea, and sentences stay short and active, while preserving every fact. Use when you want to make a document or draft readable, edit or polish prose for readability, clean up writing, tighten wording, or re-apply the readability standard to something already written. Rewrites prose only, leaving code, diagrams, and citation identifiers unchanged. Does not write new feature or system documentation — use project-documentation. Does not restructure code or review it — use refactor to restructure code and code-review to audit it. Does not judge the underlying work or raise findings; it only rewrites the writing.

Creates and maintains project documentation for features, systems, and components. Use when documenting how a feature, system, or component works — including writing, updating, or organizing docs. Does not scan or detect the project's technology stack — use project-discovery for repository analysis and config detection. Does not create architectural decision records — use architectural-decision-record for ADRs. Does not create or update coding standards — use coding-standard instead. Does not generate PR descriptions — use update-pr-description for that. Does not produce runbooks for operational scenarios — use runbook for that. Does not rewrite existing prose for readability — use edit-for-readability for that. Does not produce an ephemeral, understand-now overview of code or a PR — use code-overview for that.

Convert a stakeholder summary markdown file into a single self-contained HTML executive report — bottom line and decision asks up front, supporting detail later — styled with a Test Double-derived palette and self-contained mermaid diagrams. Use when the user wants to turn a stakeholder summary, executive summary, or business summary into an HTML report, generate an HTML version of a summary doc, or produce a shareable HTML file from a summary markdown. Produces an HTML sibling file only; does not publish anything.

Produces a plain-language stakeholder summary from an existing feature specification, for sharing with non-technical stakeholders before implementation kicks off. Use when the user wants to draft a stakeholder summary, executive summary, or business summary of a feature spec or PRD. Does not write the spec itself — use plan-a-feature. Does not sequence the build into phases — use plan-a-phased-build. Does not produce an implementation plan — use plan-implementation.

Evidence-based investigation of issues, bugs, API calls, integrations, and other aspects of software development that need a deep dive to find the root cause and solutions. Use when you need to debug, troubleshoot, diagnose, or figure out why something is broken. Does not review code for quality or style — use code-review for auditing changes or post-code-review-to-pr for posting review feedback to GitHub. Does not assess architectural health or structural risk — use architectural-analysis for architectural concerns. Does not research open-ended options, prior art, or how something works when nothing is broken — use research for that. Does not capture feedback on Han's own skills — use han-feedback for that.

Create, extract, or convert an ADR (architectural decision record) using the ADR template. Use when creating new ADRs, extracting an ADR from existing documentation, converting a document into an ADR, recording an architecture or design decision, or updating the status of an existing ADR. Does not create or update enforceable coding standards or conventions — use coding-standard for that. Does not write feature or system documentation — use project-documentation instead.

Performs a gap analysis between two artifacts (a current state and a desired state) and produces a plain-language, stakeholder-readable report indexed by stable gap IDs. Use when the user wants to compare, evaluate, audit, or reconcile one artifact against another. Does not investigate runtime bugs — use investigate. Does not assess module-level architecture — use architectural-analysis. Does not research open-ended options with no second artifact to compare against — use research.

Builds a new Claude Code agent (subagent) from scratch through a relentless, evidence-based interview that walks the agent's design tree decision-by-decision — entity fit, domain focus and vocabulary, role identity, anti-patterns, description, model tier, tools, and self-containment — then reviews the finished agent against the plugin-building guidance and applies every fix it finds. Use when creating, authoring, scaffolding, designing, or drafting a new agent or subagent. Does not build a skill or slash command — use skill-builder. Does not serve, vendor, or refresh the authoring guidance itself — use guidance.

Creates and updates coding standards, conventions, rules, and guidelines for the current project. Use when creating new standards from scratch, converting existing documents into coding standards, or updating existing standards. Does not create architectural decision records — use architectural-decision-record for ADRs. Does not write feature or system documentation — use project-documentation for that. Does not research open-ended options — use research. Does not produce runbooks for operational scenarios — use runbook for that.

Builds a feature specification from scratch through a relentless, evidence-based interview that walks the design tree decision-by-decision, resolving dependencies as it goes. Use when the user wants to plan, design, scope, specify, or flesh out a new feature, capability, or system behavior before implementation. Produces a feature specification focused on system behaviors, not implementation detail. Does not refine or stress-test an existing plan — use iterative-plan-review. Does not document already-built features — use project-documentation. Does not research open-ended options before there is a feature to specify — use research.

Splits a body of context into a sequence of vertical-slice build phases where each phase is independently demonstrable to a real user and each builds on the previous. Use when the user wants to plan, sequence, phase, slice, break down, or order the build of a feature, capability, system, or initiative, and produces a plain-language phased build outline. Does not produce implementation detail — use plan-implementation. Does not specify behavior that has not been decided — use plan-a-feature. Does not perform gap analysis between two artifacts — use gap-analysis. Does not break a plan into independently-grabbable work items — use plan-work-items.

Produces a progressive-disclosure overview of unfamiliar code or a pull request's changes with code-overview and publishes the resulting overview to a user-specified Confluence location. Use when the user wants code or a PR explained, oriented, or made sense of AND the overview posted to a Confluence space or page. Requires a configured Atlassian MCP server. Does not produce the overview to a local file only — use code-overview. Does not publish an arbitrary existing markdown file — use markdown-to-confluence. Does not document an already-understood feature to Confluence — use project-documentation-to-confluence. Does not root-cause a bug to Confluence — use investigate-to-confluence. Does not plan or specify a new feature to Confluence — use plan-a-feature-to-confluence. Does not publish to Jira — use work-items-to-jira.

Runs an evidence-based investigation of a bug, failure, or unexpected behavior with investigate and publishes the resulting investigation report to a user-specified Confluence location. Use when the user wants something debugged, diagnosed, or root-caused AND the findings posted to a Confluence space or page. Requires a configured Atlassian MCP server. Does not investigate to a local file only — use investigate. Does not publish an arbitrary existing markdown file — use markdown-to-confluence. Does not document an already-understood feature to Confluence — use project-documentation-to-confluence. Does not plan or specify a new feature to Confluence — use plan-a-feature-to-confluence. Does not publish to Jira — use work-items-to-jira.

Capture structured feedback on the Han skills and agents used in the current session and optionally post it as a GitHub issue to testdouble/han. Use at the end of any session where one or more han-* skills or agents ran, to rate a run, log what worked and what didn't, or submit observations for maintainers. Does not review code, investigate bugs, or research options; use code-review, investigate, or research for those. Does not provide feedback on skills or agents from non-Han plugins.

Publishes a local Markdown file to a user-specified Confluence location, creating a new page or updating an existing one through the Atlassian MCP server. Use when the user wants to post, publish, push, or sync a Markdown file to a Confluence space or page. Requires a configured Atlassian MCP server. Does not write or generate the Markdown itself — point it at an existing file, or use project-documentation-to-confluence for the document-then-publish flow, or plan-a-feature-to-confluence for the plan-then-publish flow. Does not publish to Jira — use work-items-to-jira.

Builds a feature specification from scratch with plan-a-feature and publishes it to a user-specified Confluence location, posting the spec as a parent page and each companion artifact (decision log, team findings, technical notes) as a child page beneath it. Use when the user wants a new feature planned, designed, scoped, or specified AND posted to a Confluence space or page. Requires a configured Atlassian MCP server. Does not plan to local files only — use plan-a-feature. Does not publish an arbitrary existing markdown file — use markdown-to-confluence. Does not refine or stress-test an existing plan — use iterative-plan-review. Does not document already-built features to Confluence — use project-documentation-to-confluence.

Creates or updates project documentation for a feature, system, or component and publishes it to a user-specified Confluence location. Use when the user wants feature or system documentation written to Confluence, posted to a Confluence space or page, or synced to a Confluence location. Requires a configured Atlassian MCP server. Does not document to local files only — use project-documentation for that. Does not publish an arbitrary existing markdown file — use markdown-to-confluence for that. Does not plan or specify a new feature to Confluence — use plan-a-feature-to-confluence for that. Does not create architectural decision records — use architectural-decision-record. Does not create coding standards — use coding-standard. Does not produce runbooks — use runbook.

Break a work-items.md file (produced by /plan-work-items) into independently-grabbable Jira tickets, one per slice, in a single Jira project. Use when you want to turn a work-items file into Jira tickets, publish work items as Jira issues, or create implementation tickets that can be worked on and tracked in Jira. Requires a configured Atlassian MCP server. Does not produce the work-items file itself — use plan-work-items to break a plan into work items first. Does not post to GitHub — use work-items-to-issues for GitHub issues.

Sharpens and stress-tests an existing plan file through multiple codebase-grounded review passes, editing it in place and recording every finding and iteration in cross-referenced companion files. Use this skill whenever the user wants to iterate on, refine, tighten, or improve a plan. Also use it when the user asks to verify, validate, or confirm feasibility of an approach. Does not implement plan steps, write test plans, review code, or investigate bugs, and does not generate new plans from scratch — use plan-a-feature for a new plan.

Builds a new Claude Code skill from scratch through a relentless, evidence-based interview that walks the skill's design tree decision-by-decision — entity fit, use cases, name, description, workflow steps, tools, and progressive-disclosure layout — then reviews the finished skill against the plugin-building guidance and applies every fix it finds. Use when creating, authoring, scaffolding, designing, or drafting a new skill or slash command. Does not build an agent or subagent — use agent-builder. Does not serve, vendor, or refresh the authoring guidance itself — use guidance.