Skip to content

quickstart.md

Latest commit

 

History

History
116 lines (75 loc) · 13.1 KB

quickstart.md

File metadata and controls

116 lines (75 loc) · 13.1 KB

Quickstart

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 · Skills · Agents · Sizing · YAGNI

Which path are you on?

Not sure which? Start with the Concepts page, then come back.

Path A: Plan a new feature

You have a feature idea and want a specification grounded in evidence, then a plan for how to build it.

  1. /plan-a-feature. Run a relentless, evidence-based interview that walks the design tree, dispatches specialist reviewers, and produces feature-specification.md plus a decision log and team findings.
  2. /stakeholder-summary (optional). When the spec needs sign-off from non-technical stakeholders (leadership, product, customer-facing reviewers) before the team commits to building it, turn the spec into a plain-language summary with Mermaid diagrams and share that.
  3. /plan-a-phased-build (optional). When the feature is large enough to ship in slices rather than all at once, split the spec into a numbered sequence of vertical-slice phases, each independently demoable to a real person.
  4. /plan-implementation. Turn the specification (or a single phase from the phased build) into an implementation plan through a project-manager-led team conversation.
  5. /iterative-plan-review (optional). Stress-test either plan through multiple codebase-grounded review passes before committing to it.
  6. /plan-work-items (optional). Divide an implementation plan into individual, independently-grabbable work items.
  7. /tdd (when you build it). Implement the plan test-first through a BDD-framed red-green-refactor loop. The specification becomes the behavior test list; the skill enforces an observed-failure gate and applies your coding standards and ADRs in green and refactor.

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.

Path B: Investigate a bug or failure

Something is broken. You want a root cause, not a guess.

  1. /issue-triage (as needed). If the report is vague or incomplete, classify the issue, identify missing information, and capture the next step before you investigate.
  2. /investigate. Evidence-based investigation: file paths, line numbers, git history, test coverage. Produces an investigation report with the root cause and a proposed fix that an adversarial-validator has already tried to falsify.
  3. /iterative-plan-review (optional). If the investigation produced a fix plan you do not trust, iterate on it before writing code.

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.

Path C: Review code or architecture

You want feedback on something that is already written.

Start with the scope that matches:

  • A branch or a few files → /code-review. Always dispatches junior-developer and adversarial-security-analyst. Conditionally adds test-engineer, edge-case-explorer, structural-analyst, behavioral-analyst, concurrency-analyst, data-engineer, or devops-engineer when 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 → /gh-pr-review. Everything /code-review does, plus a junior-developer clarity 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 of structural-analyst, behavioral-analyst, risk-analyst, and software-architect to examine coupling, data flow, risk, and SOLID alignment. Conditionally adds concurrency-analyst, adversarial-security-analyst, data-engineer, devops-engineer, codebase-explorer, or system-architect when the focus area's signals call for them. The roster scales with the size, defaulting to small. For cross-service topology when system-architect is not auto-included, dispatch it separately.
  • Tests you want to plan, not review → /test-planning. Dispatches test-engineer and edge-case-explorer, plus concurrency-analyst or adversarial-security-analyst when 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 stable G-NNN gap IDs. Dispatches gap-analyzer for the primary analysis, then runs a validator-and-augmenter swarm by default — including junior-developer's actor-perspective sweep across human users, API callers, AI agents, and other actor types. Opt out with no swarm for 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. Dispatches information-architect against the rendered outline.

You are done when: you have a review artifact you trust, with findings tied to specific files, lines, and severity levels.

Path D: Set up a project for everything else

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.

  1. /project-discovery. Scans the repository and writes a static reference (languages, frameworks, build tools, documentation structure). Other skills consume this automatically.
  2. /project-documentation (as needed). Document features, systems, and components. /code-review and /architectural-decision-record read these docs as context.
  3. /coding-standard (as needed). Formalize coding conventions, either from existing patterns or from research. /code-review checks these automatically.
  4. /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.

Path E: Research your options before you commit

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.

  1. /research. Research the open-ended question across the codebase, the open web, and any material you provide. Produces a report: the framed question, numbered evidence each with a checkable source, an options landscape with trade-offs, a recommended option, and adversarial-validator findings that already tried to break the recommendation. Scales with size, defaulting to small.
  2. /plan-a-feature (optional). Once /research recommends an option, turn that decision into a behavioral specification.

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. 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.

Combining paths

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:

A note on sizing

Seven 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.

A note on YAGNI

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.

Where to go next

  • Pick a skill from the Skills Index.
  • 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.