@architecture-rules.md @rules/conventions.md @rules/routes.md @rules/services.md @rules/hooks.md @rules/execution-model.md @rules/platform.md @rules/validation.md @references/official/current-docs-2026-06-02.md

Vite + TanStack Router 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>

Confirm a repository is a Vite + TanStack Router project before enforcing architecture rules.
Enforce safety boundaries for client-reachable loaders, route modules, service layers, env usage, generated route trees, and platform setup.
Apply Hypercore/repo-local conventions for route folders, hooks, services, naming, and nested shared folders such as src/lib/<domain>/ and src/services/<domain-or-provider>/.
Keep current Vite and TanStack Router facts in references/official/ so rapidly changing tool behavior can be refreshed without bloating the core skill.

</purpose>

<routing_rule>

Use this skill for architecture enforcement, implementation guidance, or review in existing Vite + TanStack Router projects. This includes route structure, route-local folders, loaders, validateSearch, service/query layers, custom hooks, Vite plugin setup, generated route tree handling, env/alias safety, and shared nested folder organization.

Do not use this skill when the project uses @tanstack/react-start / app.config.ts, when the project is generic Vite without TanStack Router, or when the task is a docs-only summary with no project audit or implementation guidance. For a Start project, return a boundary note that names the Start-only surfaces (createServerFn, useServerFn, Start middleware APIs, app.config.ts) and stops, instead of applying Vite route rules.

When official Vite/TanStack Router guidance and Hypercore conventions differ, enforce official and safety rules first, then apply Hypercore conventions only to touched architecture surfaces.

</routing_rule>

<instruction_contract>

| Field | Contract | |---|---| | Intent | Keep Vite + TanStack Router projects architecturally safe, maintainable, and aligned with official Vite/Router behavior plus labelled Hypercore conventions. | | Trigger | Existing Vite + TanStack Router project work involving routes, loaders, search params, services, hooks, Vite config, router setup, env/alias boundaries, or shared folder layout. | | Scope | Review and guide touched project architecture, topic rule files, official references, validation notes, and small reversible architecture fixes. | | Authority | User/project instructions outrank this skill. Official Vite and TanStack Router docs outrank Hypercore conventions for API facts. Safety policy blocks risky runtime/env/import-boundary changes. | | Evidence | Use project indicators, local package/config/router files, touched source paths, topic rules, official references, package checks, and validation command output. | | Tools | Use local search/read/edit/validation commands; use current official docs when API drift matters; gate broad route migrations, credential access, SSR adoption, and production side effects. | | Loop | No optimization loop. After an architecture pass, allow at most two verify-repair iterations against the touched-surface checks in rules/validation.md; keep a change only when it stays inside the touched scope and passes those checks, and stop when the Step 5 checklist passes or a blocker is reported. | | Output | Korean architecture decision or review with rule classifications, changed files if any, validation evidence, remaining risks, and official-doc ambiguity notes. | | Verification | Run rules/validation.md checks relevant to touched surfaces and scripts/validate-vite-architecture-skill.mjs when this skill folder changes. | | Stop condition | Stop after project mode is known, applicable safety gates pass, Hypercore conventions are applied or explicitly deferred, validation evidence is recorded, and unresolved API drift is dated and sourced. |

</instruction_contract>

Overview

Enforces hypercore Vite + TanStack Router architecture rules with strict validation before editing code.

This skill is RIGID. Follow exactly. No exceptions.

OPERATING MODE: This skill must stay self-contained. Do not block on external orchestration surfaces just to apply architecture rules. If a repo-local persistence loop is already active, carry these gates into that loop. Otherwise proceed directly with this skill.

NOTE: Some rules in this skill are stricter than TanStack Router defaults. Treat them as hypercore team conventions unless the user explicitly asks to follow official TanStack defaults instead.

<activation_examples>

Positive examples:

"Audit this Vite + TanStack Router app for route structure, validateSearch, and service boundaries before editing."
"Add a new route folder in a Vite + TanStack Router app and keep hooks/services compliant."
"Refactor a TanStack Router page so the UI stays in the route and logic moves into -hooks/."
"Vite Router 프로젝트에서 tanstackRouter plugin order와 routeTree.gen.ts 처리를 점검해줘."
"src/lib/utils.ts 말고 src/lib/auth/session.ts, src/services/billing/queries.ts처럼 nested folders로 묶어줘."

Negative examples:

"Create a new Codex skill for browser QA."
"Review a TanStack Start app that uses createServerFn and @tanstack/react-start."
"Review a generic Vite app that does not use TanStack Router."

Boundary examples:

"Make a tiny copy-only text change in a Vite route file." Direct editing can be enough if the change does not cross an architecture boundary, but touched files still need a quick compliance check.
"The repo actually uses @tanstack/react-start." Return a boundary note that names the Start-only surfaces to handle on a Start surface instead of forcing Vite rules onto a Start project.

</activation_examples>

<trigger_conditions>

| Situation | Mode | |---|---| | Existing Vite + TanStack Router project work touches routes, loaders, services, hooks, router setup, env, aliases, or shared folder layout | enforce | | @tanstack/react-start or app.config.ts is present | do not apply; return a Start-boundary note | | Generic Vite project without TanStack Router indicators | do not apply | | Copy-only text change in a route file | direct edit with quick compliance check |

</trigger_conditions>

<support_file_read_order>

Read architecture-rules.md before code changes or architecture findings.
Read the topic rule file that matches the touched surface: rules/routes.md, rules/services.md, rules/hooks.md, rules/execution-model.md, rules/platform.md, rules/conventions.md, or rules/validation.md.
Read the directly linked official current-docs reference only when Vite, TanStack Router, plugin, env, route tree, search, or loader behavior may be API-drift sensitive.
Run scripts/validate-vite-architecture-skill.mjs after editing this skill folder.

</support_file_read_order>

Step 1: Project Validation

Before any work, confirm a Vite + TanStack Router project:

# Check for Vite + TanStack Router indicators (ANY of these)
grep -r "@tanstack/react-router" package.json 2>/dev/null
grep -r "vite" package.json 2>/dev/null
ls vite.config.ts 2>/dev/null
ls src/routes/__root.tsx 2>/dev/null

If NONE found: STOP. This skill does not apply. Inform the user and return to the normal implementation or review path.

If @tanstack/react-start or app.config.ts is present: STOP. Return a Start-boundary note that names the Start-only surfaces instead of enforcing Vite route rules.

If the repo matches Vite + TanStack Router: proceed with architecture enforcement.

Step 2: Read Architecture Rules

Load the detailed rules reference:

REQUIRED: Read architecture-rules.md in this skill directory before writing any code. Read references/official/current-docs-2026-06-02.md when Vite config, env handling, TanStack Router plugin setup, routeTree generation, or search/load behavior may be API-drift sensitive.

For detailed patterns and examples, also read the relevant rule files:

rules/conventions.md - naming, TypeScript, imports, comments
rules/routes.md - route folder structure, route.tsx, loaders, search params
rules/services.md - public API services, query options, mutations, client boundaries
rules/hooks.md - custom hook separation and internal order
rules/execution-model.md - loader/runtime boundaries, SSR-aware caveats, env safety
rules/platform.md - vite.config.ts, router setup, generated files, env and alias rules
rules/validation.md - project/skill validation and readback checks

Step 3: Pre-Change Validation Checklist

Before writing ANY code, verify the planned change against these gates:

Brownfield Adoption Rule

Do not treat every untouched legacy deviation as an immediate project-wide failure.
Safety or boundary issues still block immediately, especially in touched files.
Hypercore-specific style or 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: Layer Violations

Routes -> Services -> External API

| Check | Rule | |-------|------| | Route calling fetch/axios directly? | BLOCKED. Must go through services | | Hook calling fetch/axios directly? | BLOCKED. Must go through services | | Service returning raw Response to routes/hooks? | BLOCKED. Return typed data | | createServerFn, useServerFn, or Start-only middleware APIs in a Vite app? | BLOCKED |

Gate 2: Route Structure

| Check | Rule | |-------|------| | Flat file route for a page that owns UI/logic? (routes/users.tsx) | BLOCKED. Use a folder route (routes/users/index.tsx) | | Missing -components/ folder? | BLOCKED. Every page needs it | | Missing -hooks/ folder? | BLOCKED. Every page needs it | | -functions/ folder present? | BLOCKED. Vite skill does not allow server functions | | const Route without export? | BLOCKED. Must be export const Route | | Logic in page component? | BLOCKED. Extract to -hooks/ | | Layout route missing route.tsx while it owns shared loader/beforeLoad/layout work? | BLOCKED | | Route with search params but no validateSearch? | BLOCKED. Use zodValidator | | Route with loader but no pendingComponent? | WARNING. Recommended |

Gate 3: Services

| Check | Rule | |-------|------| | POST/PUT/PATCH without schema validation? | BLOCKED. Validate with Zod before calling | | Direct fetch/axios in route or hook? | BLOCKED. Use service functions | | services/index.ts barrel export? | BLOCKED. Import directly from concrete files | | Missing explicit return type on service function? | BLOCKED |

Gate 4: Hooks

| Check | Rule | |-------|------| | Hook logic left inside page component? | BLOCKED. Move to -hooks/ | | Wrong hook order? | BLOCKED. State -> Global -> Query -> Handlers -> Memo -> Effect | | Missing exported return type interface? | BLOCKED | | camelCase hook filename? | BLOCKED. Use use-kebab-case.ts | | useServerFn in a Vite hook? | BLOCKED |

Gate 5: Conventions

| Check | Rule | |-------|------| | camelCase filename? | BLOCKED. Use kebab-case | | function keyword? | BLOCKED. Use const arrow functions | | any type? | BLOCKED. Use unknown | | Missing explicit return type? | BLOCKED | | Wrong import order? | BLOCKED. External -> @/ -> Relative -> Type | | Missing Korean block comments for grouped logic? | BLOCKED | | Using z.string().email()? | BLOCKED. Use z.email() in Zod 4 |

Gate 6: Execution Model

| Check | Rule | |-------|------| | Treating a route loader as a private server-only boundary? | BLOCKED. Loaders are client-reachable and may also participate in SSR/manual rendering | | Secret, DB, filesystem, or privileged SDK access inside a route module or loader? | BLOCKED. Keep it behind an actual backend/API boundary | | Browser-only APIs used at module scope or in shared route helpers without a client boundary? | BLOCKED | | Non-VITE_ env access in client-reachable code? | BLOCKED |

Gate 7: Platform Setup

| Check | Rule | |-------|------| | vite.config.ts missing tanstackRouter() or plugin order is wrong? | BLOCKED. Router plugin must stay explicit and precede react() | | routeTree.gen.ts hand-edited? | BLOCKED. Treat as generated output | | Router setup hidden or inconsistent with SSR/manual rendering needs? | WARNING. Keep src/router.tsx explicit; use a fresh router factory when SSR/manual rendering exists | | Path alias or env setup relies on implicit behavior only? | WARNING. Keep tsconfig/Vite config and runtime validation explicit |

Step 3.5: Auto-Remediation Policy

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

add missing validateSearch
move direct route/hook network access into services/
add missing pendingComponent or errorComponent
create missing -components/ or -hooks/ folders for touched pages
add or correct tanstackRouter() plugin setup, router scaffolding, or explicit env/alias wiring

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

mass route/file renames
sweeping route-tree restructures across many pages
introducing SSR/manual server rendering where the repo was SPA-only
large auth or API-client rewrites

Step 4: Implementation

Carry these acceptance criteria into the active task:

- [ ] Layer architecture respected (Routes -> Services -> External API)
- [ ] Route uses folder structure with -components/ and -hooks/
- [ ] export const Route = createFileRoute(...) used
- [ ] No Start-only server-function APIs in this Vite project
- [ ] Search params use zodValidator from @tanstack/zod-adapter
- [ ] Custom Hooks live in -hooks/ with correct internal order
- [ ] Loaders stay public-safe and SSR-safe
- [ ] Vite/router platform setup stays explicit (router plugin, router file, generated files)
- [ ] All filenames kebab-case
- [ ] Korean block comments present
- [ ] const arrow functions with explicit return types

</workflow>

<validation_checklist>

Step 5: Post-Change Verification

After writing code, verify:

Structure check: confirm each touched page still has -components/ and -hooks/ and no -functions/
Export check: grep for export const Route
Layer check: no direct fetch/axios in touched route or hook files
Convention check: no camelCase filenames, no function keyword declarations
Hook order check: read touched hooks and verify State -> Global -> Query -> Handlers -> Memo -> Effect
Execution check: loaders and route modules do not touch secrets, DB clients, or private env values directly
Platform check: vite.config.ts, src/router.tsx, env wiring, and generated router files remain coherent

</validation_checklist>