New to the han plugin? Pick the path that matches what you are trying to do right now. Each path is a short sequence (a few skills) that compose into a useful result. You can follow one path end to end, or jump off at any step.
See also: Plugin landing page · Concepts · How-to guides · Skills · Agents · Sizing · YAGNI
Have not installed Han yet? Read Choosing a Han plugin first to pick between the full suite and core only, then come back here.
If you want the full end-to-end recipe for one of these paths (specific prompts, what to do between steps, what to expect at each one), the how-to guides cover planning, bug triage, and research workflows in depth. The quickstart points you at the right path; the how-to walks you through it.
- Plan a new feature. You have an idea for a feature and need to figure out what it should do, how to build it, and then build it test-first.
- Investigate a bug or failure. Something is broken or behaving oddly and you need a root cause.
- Research your options. Nothing is broken; you have a question and want the options, prior art, and a recommendation before you commit.
- Review code or architecture. You want a second set of eyes on a branch, a PR, or an existing module.
- Set up a project for everything else. You want to document your project, formalize standards, and give every other skill richer context.
Not sure which? Start with the Concepts page, then come back.
You have a feature idea and want a specification grounded in evidence, then a plan for how to build it.
The full walkthrough, with prompts, decision points, and what to expect at each step, lives in How to plan a feature, end to end. The skills in the loop, in order:
/plan-a-feature → /stakeholder-summary (optional) → /plan-a-phased-build (optional) → /plan-implementation → /iterative-plan-review (optional) → /plan-work-items (optional) → /tdd (when you build it).
You are done when: you have a feature-specification.md and a feature-implementation-plan.md in the same folder, each with a cross-referenced decision log and review findings. If the feature was large enough to phase, you also have a build-phase-outline.md that orders the work into demoable vertical slices. When you build it, the code lands behavior by behavior through /tdd, with tests leading.
Something is broken. You want a root cause, not a guess.
The full walkthrough, including how to bring in production logs and when to triage instead of investigating right away, lives in How to triage and investigate a bug. The skills in the loop:
/issue-triage (as needed) → /investigate → /iterative-plan-review (optional).
You are done when: you have a report that names the root cause with file-level evidence, and a fix plan that has survived adversarial review.
You want feedback on something that is already written.
Start with the scope that matches:
- A branch or a few files →
/code-review. Always dispatchesjunior-developerandadversarial-security-analyst. Conditionally addstest-engineer,edge-case-explorer,structural-analyst,behavioral-analyst,concurrency-analyst,data-engineer, ordevops-engineerwhen the changed files trigger their domain. The roster scales with the size, defaulting to small. Runs quality checks and produces a review with findings classified by severity. - An open GitHub PR →
/post-code-review-to-pr. Everything/code-reviewdoes, plus ajunior-developerclarity check against the drafted review body, plus posts the review as comments on the PR. - A whole module or subsystem →
/architectural-analysis. Always dispatches a spine ofstructural-analyst,behavioral-analyst,risk-analyst, andsoftware-architectto examine coupling, data flow, risk, and SOLID alignment. Conditionally addsconcurrency-analyst,adversarial-security-analyst,data-engineer,devops-engineer,codebase-explorer, orsystem-architectwhen the focus area's signals call for them. The roster scales with the size, defaulting to small. For cross-service topology whensystem-architectis not auto-included, dispatch it separately. - Tests you want to plan, not review →
/test-planning. Dispatchestest-engineerandedge-case-explorer, plusconcurrency-analystoradversarial-security-analystwhen the files call for it. Produces a prioritized test plan. - An implementation against a spec, PRD, or design doc →
/gap-analysis. Compares two artifacts (current state vs. desired state) and produces a plain-language, stakeholder-readable report indexed by stableG-NNNgap IDs. Dispatchesgap-analyzerfor the primary analysis, then runs a validator-and-augmenter swarm by default, includingjunior-developer's actor-perspective sweep across human users, API callers, AI agents, and other actor types. Opt out withno swarmfor the lightweight pass. - A gap report or PRD that needs to be ordered into a phased build →
/plan-a-phased-build. Splits the source artifact into a numbered sequence of vertical-slice build phases. Each phase is a thin end-to-end deliverable demoable to a real person, and each one builds on the prior. Dispatchesinformation-architectagainst the rendered outline.
You are done when: you have a review artifact you trust, with findings tied to specific files, lines, and severity levels.
Every other path works better when the plugin has rich context about your project. If you have ten minutes before you need the real skill, spend it here.
/project-discovery. Scans the repository and writes a static reference (languages, frameworks, build tools, documentation structure). Other skills consume this automatically./project-documentation(as needed). Document features, systems, and components./code-reviewand/architectural-decision-recordread these docs as context./coding-standard(as needed). Formalize coding conventions, either from existing patterns or from research./code-reviewchecks these automatically./architectural-decision-record(as needed). Record architectural decisions.
You are done when: you have a project-discovery.md at the project root and the docs and standards you need to give other skills useful context.
You have a question, not a bug and not yet a feature. You want the options, the prior art, and a recommendation you can trust before you pick a direction.
The full walkthrough, including how to capture the recommendation as an ADR so the team has a single canonical record, lives in How to research a decision and capture it. The skills in the loop:
/research → /architectural-decision-record → /plan-a-feature (optional next step).
You are done when: you have a research report whose recommendation survived an adversarial pass, with every claim tied to a source you can check yourself, and the decision captured as an ADR. If the request was really a bug, a spec, a standard, an artifact comparison, or an architecture assessment, /research routes you to the skill that owns it instead.
You can reference multiple skills in one prompt and Claude runs them in sequence, feeding each one's output into the next. A few that work:
- "Investigate why webhook deliveries are failing intermittently, then create a plan to fix it and iterate on it." →
/investigate→/iterative-plan-review. - "Scan this repo, document the auth system, and create a coding standard for how we handle tokens." →
/project-discovery→/project-documentation→/coding-standard. - "Review my branch, then create an ADR for any architectural decisions in the diff." →
/code-review→/architectural-decision-record. - "Plan the retry feature, then plan the implementation, then create a test plan for it." →
/plan-a-feature→/plan-implementation→/test-planning. - "Spec the new onboarding flow, then write a stakeholder summary I can share with leadership before we build it." →
/plan-a-feature→/stakeholder-summary→/html-summary(optional, for a self-contained HTML version to hand off). - "Spec the discount engine, then build it test-first." →
/plan-a-feature→/tdd→/code-review. - "Research our options for background jobs, then spec the one you recommend." →
/research→/plan-a-feature. - "Compare the auth implementation to the auth spec, then plan how to close the gaps, finishing with splitting that work up into task-sized units." →
/gap-analysis→/plan-implementation→/plan-work-items. - "Compare the share v1 implementation to the share v2 spec, split the gaps into a phased rollout, then plan implementation for the first phase, finally laying out individual tasks based on that plan." →
/gap-analysis→/plan-a-phased-build→/plan-implementation→/plan-work-items.
The sizing-aware skills (/architectural-analysis, /code-review, /gap-analysis, /iterative-plan-review, /plan-a-feature, /plan-implementation, /research) classify the work as small, medium, or large before dispatching agents, default to small, and scale the team and iteration depth to the chosen band. Pass the size as the first positional argument to override (/code-review medium, /plan-a-feature large "describe the feature"). See Sizing for the full model.
Every planning, review, and standards skill applies an evidence-based YAGNI rule before committing items to its artifact. Items without acceptable evidence move to a ## Deferred (YAGNI) section with a named reopen-when trigger. Never silently dropped. If a skill says "deferred (YAGNI)," see YAGNI for the two gates, the acceptable-evidence list, and the override process.
- Pick a skill from the Skills Index.
- Follow a how-to guide from the How-to index when you want the full end-to-end recipe for one of the paths above.
- Skim the Agents Index to understand the specialists the skills dispatch.
- Read Concepts if the skill/agent split is still fuzzy.
- Read Sizing to understand how the swarming skills decide how many agents to dispatch.
- Read YAGNI to understand what survives a review and what gets deferred.