@for-yeyu/evm-dapp-skills 0.1.0

package/README.md

@@ -0,0 +1,28 @@
+# @for-yeyu/evm-dapp-skills
+
+Standard skills package for the EVM DApp layered architecture.
+
+## Install
+
+```bash
+npm i @for-yeyu/evm-dapp-skills
+```
+
+## Use In Your Project
+
+Copy skills into your local agent skills directory:
+
+```bash
+rsync -a node_modules/@for-yeyu/evm-dapp-skills/skills/ .agents/skills/
+```
+
+## Included Skills
+
+- `evm-dapp-standard-coding`
+- `app-router-conventions`
+- `ui-conventions`
+- `api-conventions`
+- `hooks-conventions`
+- `configs-conventions`
+- `lib-infrastructure-conventions`
+- `styles-conventions`

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@for-yeyu/evm-dapp-skills",
+  "version": "0.1.0",
+  "description": "Standard AI coding skills for the EVM DApp layered architecture.",
+  "license": "MIT",
+  "private": false,
+  "files": [
+    "skills/**"
+  ],
+  "keywords": [
+    "skills",
+    "agents",
+    "ai",
+    "codex",
+    "evm",
+    "nextjs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/api-conventions/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: api-conventions
+description: Use when creating or updating src/api request functions, domain exports, query/mutation separation, and HTTP transport choices.
+---
+
+# API Conventions
+
+## Scope
+
+Applies to `src/api/**`.
+
+## Domain Structure
+
+Each domain follows:
+
+```text
+src/api/<domain>/
+  mutation/
+  query/
+  types/
+  index.ts
+```
+
+Use `index.ts` barrels at subfolder and domain level.
+
+## Hard Request Rules
+
+All request functions must use wrapped ky helpers from `@/lib/http/ky`:
+
+1. Use `apiRequest` for endpoints under `src/app/api/**`.
+2. Use `httpRequest` for non-`src/app/api/**` endpoints.
+3. Do not use direct `fetch`, raw `ky`, or ad-hoc transport logic.
+
+## Client Boundary Rule
+
+Client components must not call API endpoints directly.
+
+Required chain:
+
+`Client Component -> src/hooks -> src/api -> apiRequest/httpRequest`
+
+## Workflow
+
+1. Add function under `query/` or `mutation/` by behavior.
+2. Add/update shared contracts under `types/`.
+3. Export through local and domain `index.ts`.
+4. Ensure transport helper choice is correct (`apiRequest` vs `httpRequest`).
+
+## Review Checklist
+
+- Function is in correct `query` or `mutation` folder.
+- Shared contracts exist in `types`.
+- `index.ts` barrels are updated.
+- `apiRequest` is used for Next route handlers; `httpRequest` for others.
+- No direct client-side API requests are introduced.
+
+## References
+
+- `src/api/README.md`
+- `src/hooks/README.md`
+- `src/lib/README.md`

package/skills/app-router-conventions/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: app-router-conventions
+description: Use when creating or modifying src/app route entries, page/layout wrappers, route handlers, and app-to-ui route mapping.
+---
+
+# App Router Conventions
+
+## Scope
+
+Applies to `src/app/**`.
+
+## Hard Rules
+
+1. Keep `src/app` as a thin route-entry layer.
+2. Avoid page UI implementation details in route files.
+3. For non-static pages, do not write page-specific styles in `src/app`.
+4. Route entries export only `default function Page()` or `default function Layout()`.
+5. Route entries return named components imported from mirrored `src/ui/app` paths.
+
+Example:
+
+```tsx
+import { ServerTimePage } from '@/ui/app/examples/server-time'
+
+export default function Page() {
+  return <ServerTimePage />
+}
+```
+
+## Folder Mapping Rule
+
+Keep route path and UI path aligned:
+
+```text
+src/app/examples/server-time/page.tsx
+src/ui/app/examples/server-time/index.tsx
+```
+
+## Workflow
+
+1. Add route entry in `src/app/<route>/page.tsx` or `layout.tsx`.
+2. Add/update mirrored UI in `src/ui/app/<route>/index.tsx`.
+3. Keep route entry minimal: import + return.
+4. Keep shared layout pieces in `src/ui/app/layout` or route-local `layout/`.
+
+## Review Checklist
+
+- Route file uses `Page`/`Layout` export naming.
+- Route file returns route-named UI component from `@/ui/app/...`.
+- Non-static styles are not introduced in `src/app/**`.
+- `src/app` <-> `src/ui/app` mapping remains one-to-one.
+
+## References
+
+- `src/app/README.md`
+- `src/ui/README.md`

package/skills/configs-conventions/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: configs-conventions
+description: Use when adding or updating runtime configuration schemas and shared/server config modules in src/configs.
+---
+
+# Configs Conventions
+
+## Scope
+
+Applies to `src/configs/**`.
+
+## Structure Rules
+
+```text
+src/configs/
+  schema/   # schema + config types only
+  shared/   # non-secret runtime config (client+server safe)
+  server/   # secret runtime config (server-only)
+```
+
+## Hard Rules
+
+1. `schema/` defines schemas/types only and does not read `process.env`.
+2. `shared/` reads non-secret env values and validates via `schema`.
+3. `server/` reads secret env values and must include `import 'server-only'`.
+4. `shared` modules must not depend on `server` modules.
+5. `schema/index.ts` is the unified schema export entry.
+
+## Workflow
+
+1. Add schema in `schema/<name>.ts`.
+2. Export schema from `schema/index.ts`.
+3. Add runtime parser in `shared/<name>.ts` or `server/<name>.ts`.
+4. Use explicit imports from `@/configs/shared/*` or `@/configs/server/*`.
+
+## Review Checklist
+
+- New config has schema in `schema/`.
+- `schema/index.ts` is updated.
+- Secret config uses `server-only`.
+- Import boundaries remain explicit and safe.
+
+## References
+
+- `src/configs/README.md`

package/skills/evm-dapp-standard-coding/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: evm-dapp-standard-coding
+description: Use for any coding task in this repository to enforce layered architecture across src/app, src/ui, src/api, src/hooks, src/configs, src/lib, and src/styles.
+---
+
+# EVM DApp Standard Coding
+
+## When To Use This Skill
+
+Use this skill for any implementation, refactor, or review task in this repository.
+
+## Architecture Contract
+
+1. `src/app` is route-entry only.
+2. `src/ui` implements pages and reusable UI.
+3. `src/api` owns request functions.
+4. `src/hooks` is the only client-facing API call layer.
+5. Client components must not request APIs directly.
+6. `src/configs` owns runtime config schema/shared/server boundaries.
+7. `src/lib` is infrastructure and should remain stable.
+8. `src/styles` owns global style entry and CSS import wiring.
+
+## Skill Routing
+
+- `src/app/**` -> `app-router-conventions`
+- `src/ui/**` -> `ui-conventions`
+- `src/api/**` -> `api-conventions`
+- `src/hooks/**` -> `hooks-conventions`
+- `src/configs/**` -> `configs-conventions`
+- `src/lib/**` -> `lib-infrastructure-conventions`
+- `src/styles/**` -> `styles-conventions`
+
+## Standard Workflow
+
+1. Identify changed layer(s).
+2. Load matching layer skills and apply hard rules.
+3. Keep naming/export patterns consistent with conventions.
+4. Run checks relevant to the change (`pnpm lint`, `pnpm typecheck`, tests when needed).
+5. Verify no layer boundary violations are introduced.
+
+## Definition Of Done
+
+- Layer boundaries are preserved.
+- Import paths and file layout follow conventions.
+- No direct client-side network requests are introduced.
+- Infra edits outside `src/lib/utils` or `src/lib/abis` are explicitly justified.
+
+## References
+
+- `README.md`
+- `src/app/README.md`
+- `src/ui/README.md`
+- `src/api/README.md`
+- `src/hooks/README.md`
+- `src/configs/README.md`
+- `src/lib/README.md`
+- `src/styles/README.md`
+- `references/MIGRATION_GUIDE.md` (Detailed migration playbook for humans and AI tools)

package/skills/evm-dapp-standard-coding/references/MIGRATION_GUIDE.md

@@ -0,0 +1,220 @@
+# Migration Guide (To This Repository Architecture)
+
+This guide explains how to quickly migrate a messy project into the layered architecture used in this repository.  
+It is designed for both human developers and AI tools.
+
+Source of truth:
+- Root architecture doc: `README.md`
+- Layer docs: `src/*/README.md`
+- Executable skills: `.agents/skills/*/SKILL.md`
+
+---
+
+## 1. Target Architecture (Required)
+
+```text
+src/
+  app/        # Route entry layer (thin)
+  ui/         # Page and component implementation layer
+  api/        # Request function layer (query/mutation/types)
+  hooks/      # Client-only calling layer (React Query)
+  configs/    # Config layer (schema/shared/server)
+  lib/        # Infrastructure layer (errors/http/runtime/web3/utils)
+  styles/     # Global style entry layer
+```
+
+Hard boundaries:
+1. Client page components must not request APIs directly.
+2. Components can call data only through `src/hooks`.
+3. `src/hooks` calls `src/api`.
+4. `src/api` must use wrapped request functions only:
+   - `apiRequest` for `src/app/api/**`
+   - `httpRequest` for non-`src/app/api/**`
+5. `src/app` is route entry only, not page implementation.
+
+---
+
+## 2. Fast Migration Strategy (Recommended)
+
+Do not rewrite everything at once. Use **vertical-slice migration + dual track**:
+
+1. Build the target structure first, without deleting old logic.
+2. Migrate one business slice at a time (one route/page feature).
+3. New work must go to the new architecture only.
+4. Old code is migration-only (no new features), until fully removed.
+
+Benefits:
+- Controlled risk and continuous delivery.
+- Small change sets and clearer regression scope.
+- Consistent execution for both teams and AI tools.
+
+---
+
+## 3. Pre-Migration Setup (Day 0)
+
+1. Freeze architecture rules: treat `README.md + src/*/README.md + .agents/skills` as the only standard.
+2. Create target folders first: `src/app|ui|api|hooks|configs|lib|styles`.
+3. Enable quality gates in CI: lint/typecheck/test cannot be skipped.
+4. Define no-go zones:
+   - No direct client-side API requests.
+   - Do not modify `src/lib/common|http|runtime` by default (unless infra-level requirement).
+   - Do not manually edit `src/styles/shadcn.css`.
+
+---
+
+## 4. Single Slice Migration SOP (Core Template)
+
+For an old page `legacy/<feature>`, always use this order:
+
+1. Route entry migration (`src/app`)
+- Create `src/app/<route>/page.tsx`
+- Keep it as a thin wrapper only:
+  - `export default function Page() { return <FeaturePage /> }`
+
+2. UI implementation migration (`src/ui/app`)
+- Create `src/ui/app/<route>/index.tsx`
+- Move page UI, interaction, and child components here
+- Use kebab-case for child files (for example `filter-panel.tsx`)
+
+3. Request function migration (`src/api`)
+- Create `src/api/<domain>/{query,mutation,types}/`
+- Move request logic out of page/service into `query` or `mutation`
+- Use `@/lib/http/ky` only:
+  - `apiRequest` for Next route handlers
+  - `httpRequest` for external endpoints
+
+4. Hook wrapper migration (`src/hooks/api`)
+- Create `src/hooks/api/<domain>/{query,mutation,types}/`
+- Wrap `src/api` with React Query:
+  - `useQuery` for reads
+  - `useMutation` for writes
+- Pages call hooks only, never request functions directly
+
+5. Config and constants migration (`src/configs`)
+- Put config schema in `schema/`
+- Put client-safe config in `shared/`
+- Put secrets in `server/` with `import 'server-only'`
+
+6. Infrastructure dependency check (`src/lib`)
+- Reuse existing infra utilities whenever possible
+- Avoid editing `src/lib/common|http|runtime` unless strictly necessary
+
+7. Style migration (`src/styles` + `src/ui`)
+- Keep page styles in the corresponding `src/ui` module
+- Create dedicated global `.css` files and import from `src/styles/index.css`
+- Do not edit `src/styles/shadcn.css`
+
+---
+
+## 5. How AI Tools Should Execute
+
+### 5.1 Skill Entry
+
+Load the global skill first:
+- `.agents/skills/evm-dapp-standard-coding/SKILL.md`
+
+Then load layer skill(s) by changed path:
+- `src/app/**` -> `app-router-conventions`
+- `src/ui/**` -> `ui-conventions`
+- `src/api/**` -> `api-conventions`
+- `src/hooks/**` -> `hooks-conventions`
+- `src/configs/**` -> `configs-conventions`
+- `src/lib/**` -> `lib-infrastructure-conventions`
+- `src/styles/**` -> `styles-conventions`
+
+### 5.2 Standard Task Prompt For AI
+
+```text
+Follow .agents/skills/evm-dapp-standard-coding/SKILL.md.
+Changed paths: <fill paths>.
+You must enforce all corresponding sub-skill rules and keep layer boundaries intact.
+Migration target: move <old module/page> into the app/ui/api/hooks/configs/lib/styles architecture.
+Output:
+1) actual code changes
+2) migration mapping table (old path -> new path)
+3) verification results (lint/typecheck/test)
+```
+
+---
+
+## 6. Migration Scan Commands (Find Common Issues Fast)
+
+1. Find direct client requests:
+
+```bash
+rg -n "fetch\\(|axios\\(|ky\\(" src/ui src/app
+```
+
+2. Find pages using APIs without hooks:
+
+```bash
+rg -n "@/api/" src/ui src/app
+```
+
+3. Find overweight route files (line-count heuristic):
+
+```bash
+find src/app -type f \\( -name "page.tsx" -o -name "layout.tsx" \\) -print0 | xargs -0 wc -l | sort -nr
+```
+
+4. Find server-config boundary violations:
+
+```bash
+rg -n "@/configs/server/" src/ui src/hooks src/app
+```
+
+---
+
+## 7. Definition Of Done (DoD)
+
+A migrated business slice is complete only if all conditions are met:
+
+1. Route layer is thin and UI is in `src/ui/app`.
+2. Request functions are in `src/api` and organized by `query/mutation/types`.
+3. Pages use `src/hooks`; no direct client requests exist.
+4. Config is split by `schema/shared/server` with correct boundaries.
+5. No unnecessary infra-core changes in `src/lib`.
+6. Style changes follow `src/styles/index.css` import-entry rules.
+7. `pnpm lint`, `pnpm typecheck`, and required tests pass.
+
+---
+
+## 8. Common Failure Modes And Fixes
+
+1. Failure: business logic inside `src/app/page.tsx`
+- Fix: move it to `src/ui/app/<route>/index.tsx`; keep `src/app` as wrapper only.
+
+2. Failure: page directly uses `fetch`/`ky`
+- Fix: move request to `src/api`, then expose via `src/hooks`.
+
+3. Failure: `src/api` not split by `query/mutation/types`
+- Fix: reorganize by domain and add barrel exports (`index.ts`).
+
+4. Failure: secret config placed in `shared`
+- Fix: move to `src/configs/server` and add `server-only`.
+
+5. Failure: arbitrary edits in `src/lib/common|http|runtime`
+- Fix: revert to existing infra patterns; change only for explicit infra requirements.
+
+---
+
+## 9. Recommended Migration Order (Best Cost/Benefit)
+
+1. High-traffic pages (highest business impact)
+2. Highly reused components (reduce duplicate migration effort)
+3. Most chaotic data domains (clean boundaries earlier)
+4. Config and infra consolidation (last, lower risk)
+
+---
+
+## 10. References
+
+- `README.md`
+- `src/app/README.md`
+- `src/ui/README.md`
+- `src/api/README.md`
+- `src/hooks/README.md`
+- `src/configs/README.md`
+- `src/lib/README.md`
+- `src/styles/README.md`
+- `.agents/skills/*/SKILL.md`

package/skills/hooks-conventions/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: hooks-conventions
+description: Use when building src/hooks hooks, especially src/hooks/api React Query wrappers mapped to src/api domains.
+---
+
+# Hooks Conventions
+
+## Scope
+
+Applies to `src/hooks/**`.
+
+## Structure Rules
+
+1. `src/hooks/api` mirrors `src/api` domains and subfolders.
+2. Query hooks live in `query/` and use `useQuery`.
+3. Mutation hooks live in `mutation/` and use `useMutation`.
+4. Hook-level helper types live in `types/` when needed.
+5. Use `index.ts` barrels for folder and domain exports.
+
+## Hard Boundary Rule
+
+Client components must call APIs through hooks only.
+
+Not allowed:
+
+- Direct `fetch`/`ky` usage in client components.
+- Calling route handlers directly from components.
+
+## Non-API Hooks
+
+Other hooks should be grouped by function/business categories under `src/hooks`.
+Current base architecture does not provide non-API folder examples.
+
+## Workflow
+
+1. Confirm API function exists in `src/api/<domain>/query|mutation`.
+2. Create corresponding hook in `src/hooks/api/<domain>/query|mutation`.
+3. Use stable `queryKey` design for queries.
+4. Add invalidation/update behavior for mutations.
+5. Export through local and domain `index.ts`.
+
+## Review Checklist
+
+- Hook path mirrors API path.
+- Query and mutation hooks use proper React Query primitives.
+- `index.ts` barrels are updated.
+- Client code consumes hooks instead of direct request calls.
+- Non-API hooks (if added) are categorized clearly.
+
+## References
+
+- `src/hooks/README.md`
+- `src/api/README.md`

package/skills/lib-infrastructure-conventions/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: lib-infrastructure-conventions
+description: Use when modifying src/lib infrastructure modules, request/error/runtime wiring, utility helpers, or ABI assets.
+---
+
+# Lib Infrastructure Conventions
+
+## Scope
+
+Applies to `src/lib/**`.
+
+## Key Directories
+
+- `abis/`: contract ABI assets.
+- `common/errors`: error model and typed errors.
+- `common/web3`: wagmi config and EVM store.
+- `http`: `apiRequest/httpRequest`, `withResponse`, React Query client.
+- `runtime`: store/listener initialization.
+- `utils`: pure utility helpers.
+
+## Hard Modification Policy
+
+By default, only `src/lib/utils/**` and `src/lib/abis/**` should be modified.
+
+For `src/lib/common/**`, `src/lib/http/**`, and `src/lib/runtime/**`:
+
+- Treat as foundational infrastructure.
+- Change only for explicit new cross-layer business requirements.
+- Keep edits minimal and validate broad impact.
+
+## Usage Rules
+
+1. API layer transport should use `@/lib/http/ky` wrappers.
+2. Next route handlers should use `withResponse` from `@/lib/http/next`.
+3. Shared errors should prefer `BaseError` hierarchy.
+4. Runtime initialization should go through `runtime/*` initializers.
+
+## Workflow
+
+1. If change is utility-like, prefer `utils/`.
+2. If change is ABI-like, use `abis/`.
+3. If infra core must change, document reason and verify behavior across API/hooks/ui.
+4. Add or update tests for non-trivial utility logic.
+
+## Review Checklist
+
+- Edit location respects modification policy.
+- Transport/error/response wiring stays consistent.
+- Infra-core changes (if any) are justified and scoped.
+- Utility changes include tests when regression risk exists.
+
+## References
+
+- `src/lib/README.md`
+- `src/api/README.md`

package/skills/styles-conventions/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: styles-conventions
+description: Use when adding global styles, font setup, or CSS imports under src/styles.
+---
+
+# Styles Conventions
+
+## Scope
+
+Applies to `src/styles/**`.
+
+## Hard Rules
+
+1. Do not manually modify `src/styles/shadcn.css`.
+2. Configure fonts through `src/styles/fonts.ts`.
+3. For custom CSS, create a new `.css` file in `src/styles`.
+4. Import custom style files from `src/styles/index.css`.
+
+Example:
+
+```css
+@import "./scrollbar.css";
+```
+
+## Workflow
+
+1. Add dedicated style file for new global behavior.
+2. Keep style concerns separated by file purpose.
+3. Wire file through `index.css` import list.
+4. Avoid mixing framework base styles and custom app styles.
+
+## Review Checklist
+
+- `shadcn.css` is unchanged.
+- Font changes are in `fonts.ts`.
+- New CSS is added in a dedicated file.
+- New CSS file is imported by `index.css`.
+
+## References
+
+- `src/styles/README.md`

package/skills/ui-conventions/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: ui-conventions
+description: Use when implementing or refactoring src/ui page modules, shared components, providers, shadcn wrappers, or SVG components.
+---
+
+# UI Conventions
+
+## Scope
+
+Applies to `src/ui/**`.
+
+## Structure Rules
+
+1. `src/ui/app` mirrors `src/app` route structure.
+2. Page implementation entry file is `index.tsx` in each route folder.
+3. Internal child files use lowercase kebab-case (for example `server-config.tsx`).
+4. Shared route layout components live in `src/ui/app/layout`.
+5. Route-group-local layout components may live in route-local `layout/` folders.
+
+## Component Authoring Rules
+
+Default component declaration style:
+
+```tsx
+export const Loader: FC<ComponentProps<'div'>> = () => {}
+```
+
+Hard constraints:
+
+- Except `src/ui/svgs/**`, components should not consume `props`/`className` by default.
+- For non-`svgs` components, keep empty parameter signatures unless explicitly required.
+- Treat `src/ui/shadcn/**` as vendor-like primitives; avoid edits unless necessary.
+
+## Workflow
+
+1. Implement real pages under `src/ui/app/<route>/index.tsx`.
+2. Keep mapping with `src/app/<route>/page.tsx`.
+3. Put shared/global pieces under `components/providers` or `components/shared`.
+4. Place modal-specific code under `components/modal`.
+
+## Review Checklist
+
+- Route UI entry files use `index.tsx`.
+- Internal file names follow kebab-case.
+- Non-`svgs` components avoid `props`/`className` by default.
+- `shadcn` components are not modified without a clear reason.
+
+## References
+
+- `src/ui/README.md`
+- `src/app/README.md`