alpoxdev/hono-architecture

Hono Architecture Enforcement

<output_language>

Default all user-facing deliverables, saved artifacts, reports, plans, generated docs, summaries, handoff notes, commit/message drafts, and validation notes to Korean, even when this canonical skill file is written in English.

Preserve source code identifiers, CLI commands, file paths, schema keys, JSON/YAML field names, API names, package names, proper nouns, and quoted source excerpts in their required or original language.

Use a different language only when the user explicitly requests it, an existing target artifact must stay in another language for consistency, or a machine-readable contract requires exact English tokens. If a localized template or reference exists (for example *.ko.md or *.ko.json), prefer it for user-facing artifacts.

</output_language>

Overview

Enforces hypercore Hono architecture rules before code changes. Validate that the target is actually a Hono project, then apply strict rules for route composition, handlers, middleware, validation, error handling, platform entrypoints, and typed testing/RPC.

This skill is strict. Follow the rules exactly unless the user explicitly asks to prefer official Hono defaults over hypercore-specific conventions.

OPERATING MODE: This skill is self-contained. Do not block on global skills or external orchestration surfaces. If the user asks for exhaustive verification, keep verifying. Otherwise proceed directly with this skill's own validation flow.

IMPORTANT: Some rules in this skill are stricter than Hono itself. Treat those as hypercore conventions and label them clearly when reporting violations.

Trigger Examples

Positive

• Review this Hono app structure before I add more routes.
• Refactor a Hono API so routing, middleware, and validators follow one architecture.
• Add a new Hono route and make sure testClient and AppType inference still work.

Negative

• Create a generic Express middleware guide.
• Review a React SPA that does not use Hono.

Boundary

• Make a tiny copy-only response text change in a Hono handler. Direct editing can be enough if no architectural boundary is affected.

• Use official Hono defaults only, not the extra hypercore conventions. This skill still applies, but relax hypercore-only strictness that exceeds the official docs.

Step 1: Project Validation

Before doing any work, confirm the target is a Hono project:

rg -n '"hono"|@hono/' package.json
rg -n "from 'hono'|from \"hono\"" src app .
rg -n "new Hono\\(|createFactory\\(|testClient\\(|hc<" src app .

If none of those indicators exist, stop and route back to the normal implementation or review path instead of forcing Hono rules.

Step 2: Read Architecture Rules

Read the detailed rules before editing:

• architecture-rules.md
• rules/conventions.md
• rules/routes.md
• rules/handlers.md
• rules/middleware.md
• rules/validation.md
• rules/errors.md
• rules/testing-rpc.md
• rules/platform.md

When the change depends on current framework behavior or you need to justify a rule from the official docs, read:

• references/official/hono-docs.md

Task-to-Rule Routing

Use the next file based on the change you are making:

• For route composition, mount order, fallback placement, or sub-app structure, read rules/routes.md
• For handler extraction, createFactory(), createHandlers(), or typed context flow, read rules/handlers.md
• For shared request boundaries, auth/logging/request-id flow, or c.set() / c.get() usage, read rules/middleware.md
• For params/query/json/form validation choices, read rules/validation.md
• For HTTPException, app.onError(), or response-shaping problems, read rules/errors.md
• For testClient(), hc<typeof app>, AppType, or larger-app inference, read rules/testing-rpc.md
• For adapters, entrypoints, bindings, env/config typing, or basePath() boundaries, read rules/platform.md

Official-Defaults Override Mode

When the user explicitly asks for official Hono defaults instead of hypercore-only conventions:

• Start from references/official/hono-docs.md first
• Apply official Hono behavior as the default decision surface
• Treat stricter hypercore rules as optional overlays and only enforce them when the user did not opt out
• In findings and final reports, label which rules are official Hono behavior and which are hypercore-only conventions

Step 3: Pre-Change Validation Checklist

Validate planned changes against these gates.

Brownfield Adoption Rule

• Do not treat every legacy deviation as a project-wide failure.
• Safety, typing, and validation issues still block immediately, especially in touched files.
• Hypercore-specific structure drift in untouched legacy code can be recorded as migration backlog.
• Any file you touch should be brought into compliance unless that would require a materially risky migration.

Gate 1: Composition and Layers

| Check | Rule | |------|------| | Root app mixes transport, business logic, and persistence directly? | BLOCKED. Keep composition in app/route modules and move domain logic down. | | Route modules bypass services and talk to DB/SDK directly without a clear reason? | BLOCKED by hypercore convention. Prefer routes -> services -> repositories/clients. | | Controller-style class or giant controller file introduced for simple handlers? | BLOCKED. Hono best practices prefer smaller apps and route composition over controller-heavy structure. | | Large feature area mounted manually without sub-app composition? | WARNING. Prefer app.route() / basePath() composition. |

Gate 2: Route Modules

| Check | Rule | |------|------| | Route registration scattered across unrelated files? | BLOCKED. Keep one obvious composition path. | | Larger route module missing a dedicated folder with local schemas/handlers? | BLOCKED by hypercore convention. | | Catch-all or fallback route registered before specific routes? | BLOCKED. Registration order matters in Hono. | | Route module cannot be mounted cleanly with app.route() or a typed sub-app? | BLOCKED. |

Gate 3: Handlers and Context Typing

| Check | Rule | |------|------| | Extracted handlers lose route typing or context typing? | BLOCKED. Use inline chaining or createFactory() / factory.createHandlers(). | | Untyped c.set() / c.get() values used across middleware/handlers? | BLOCKED. Type Variables on the app/factory. | | Request parsing and domain work mixed into a single long handler? | WARNING. Split validator, service, and response shaping. |

Gate 4: Validation

| Check | Rule | |------|------| | Non-trivial request data consumed without validator middleware? | BLOCKED. | | Raw await c.req.json() or manual parsing repeated inside handlers? | BLOCKED unless the payload is trivial and tightly scoped. | | Validation strategy is inconsistent across params/query/json/form in the same feature? | WARNING. Normalize it. | | New validation library added without need? | BLOCKED unless explicitly requested. Prefer built-in validator(), @hono/zod-validator, or @hono/standard-validator. |

Gate 5: Middleware

| Check | Rule | |------|------| | Middleware order assumed incorrectly? | BLOCKED. Registration order matters. | | Shared auth/logging/request-id logic duplicated across handlers? | WARNING. Prefer middleware. | | Context values survive across requests by assumption? | BLOCKED. Context is request-scoped only. | | Runtime-specific concerns leak from middleware into domain layers? | BLOCKED. |

Gate 6: Errors and Responses

| Check | Rule | |------|------| | Handler throws raw generic errors for expected HTTP failures everywhere? | WARNING. Prefer HTTPException or one centralized translation policy. | | app.onError() missing in a non-trivial API? | WARNING. Add a central error boundary. | | Code relies on HTTPException.getResponse() while forgetting existing Context headers? | BLOCKED. Preserve context-set headers when rebuilding responses. | | Typed RPC client is exported but the app still depends on c.notFound() behavior? | BLOCKED. Avoid patterns the Hono RPC docs call out as incompatible. |

Gate 7: Testing and RPC

| Check | Rule | |------|------| | testClient() or hc<typeof app> type inference broken by non-chained route definition? | BLOCKED. Keep route types flowing through the exported app. | | App type not exported where typed client/test usage is expected? | BLOCKED. Export AppType. | | Large app split loses typed inference across sub-apps? | BLOCKED. Follow the larger-app chaining pattern from the Hono RPC docs. |

Gate 8: Platform Entry

| Check | Rule | |------|------| | Runtime adapter code mixed into route modules? | BLOCKED. Keep adapter/bootstrap code at the edge. | | Environment bindings/vars used without a typed Bindings/config boundary? | BLOCKED. | | Debug helpers like showRoutes() enabled outside explicit dev-only setup? | WARNING. |

Step 3.5: Auto-Remediation Policy

Auto-fix directly when the issue is local, reversible, and low-risk.

• Add missing validator middleware to a touched route
• Add typed AppType export
• Move route mounting into a single composition file
• Convert extracted untyped handlers to createFactory() / factory.createHandlers()
• Add app.onError() or improve HTTP exception translation
• Move runtime adapter imports out of handlers and route modules

Do not auto-apply broad or potentially breaking migrations without explicit justification.

• Mass route/module renames
• Whole-app layer rewrites
• Validation library swaps across the entire repository
• RPC shape changes that break existing clients
• Runtime adapter swaps

Step 4: Implementation

When changing Hono code, prefer this order:

1. Validate current structure and rule breaches.
2. Fix route composition and typing boundaries first.
3. Fix validation and middleware ordering.
4. Fix error handling and response shaping.
5. Fix testing/RPC inference regressions.
6. Run verification.

Verification Checklist

• Hono project detection confirmed
• Relevant rule files read
• Official override mode applied when the user requested official Hono defaults
• Touched files follow kebab-case naming
• Route composition is obvious and mountable
• Middleware order verified
• Validation enforced on non-trivial inputs
• Error handling policy is explicit
• testClient / hc / AppType inference still works when applicable
• Runtime adapter code stays at the edge
• Final findings distinguish official Hono rules from hypercore-only conventions