Hono Architecture Enforcement

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:

bash

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:

Validate current structure and rule breaches.
Fix route composition and typing boundaries first.
Fix validation and middleware ordering.
Fix error handling and response shaping.
Fix testing/RPC inference regressions.
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

hono-architecture

NPX Install

Tags

SKILL.md Content