trackgo-fe/.agents/skills/project-guidelines-example/SKILL.md

name, description

name	description
project-guidelines-example	Frontend monorepo guidelines for this pnpm + Turborepo React/Vite/Electron workspace. Use when scaffolding features, reviewing structure, or aligning code with this repo's conventions.

Project Guidelines

Project skill for this frontend monorepo. Architecture, file layout, patterns, testing, and scripts as they exist in the repo today.

When to Use

Reference this skill when working on this project. It contains:

• Architecture overview
• File structure
• Code patterns
• Testing requirements
• Related skills

---

Architecture Overview

Stack:

• Apps: React 19 + Vite (apps/web, apps/showcase, apps/landing) + Electron (apps/desktop) + VitePress (apps/docs-dev)
• Packages: @repo/ui (Mantine), @repo/core-api, @repo/core-storage, @repo/core-i18n, @repo/core-events, @repo/utils, @repo/brand, packages/configs
• Testing: Vitest; Testing Library in packages/ui and packages/core-events
• Package manager: pnpm 8.15.6 + Turbo

Where to work: product in apps/web; copy UI/API usage from apps/showcase; concepts from apps/docs-dev. Do not invent a parallel UI kit.

---

File Structure

.
├── apps/
│   ├── web/                 # Product app
│   ├── showcase/            # Living cookbook for @repo/*
│   ├── docs-dev/            # VitePress
│   ├── desktop/             # Electron wrapper of apps/web
│   └── landing/             # Marketing SPA
├── packages/
│   ├── ui/                  # @repo/ui — components, form, foundations
│   ├── core-api/            # HTTP client + remote data services
│   ├── core-storage/
│   ├── core-i18n/
│   ├── core-events/
│   ├── utils/
│   ├── brand/
│   └── configs/
└── package.json             # Root scripts

Web module (copy example/full-page)

apps/web/src/apps/main/modules/<group>/<feature>/
  data/                      # *RemoteDataServices
  domain/
    constants/               # ModuleConfigEntity
    entities/
    factories/               # apiClient + service + transformer
    transformers/
    validators/              # Zod factories
  presentation/
    factory/                 # registerModuleNamespace + EnterpriseModuleProvider + routes
    pages/                   # index | form | detail
    components/
    store/                   # optional zustand
    languages/{en,id}/

Auth lives under src/apps/auth/. Shared-across-modules code lives in src/core/.

---

Code Patterns

Module config + factory

import { ModuleConfigEntity } from '@repo/ui/foundations';

export const fullPageModuleConfig: ModuleConfigEntity = {
  moduleKey: 'EXAMPLE_FULL_PAGE',
  translationNamespace: 'EXAMPLE_FULL_PAGE',
  apiUrl: '/full-page',
  webUrl: '/app/example/full-page',
  moduleCategory: 'FULL_PAGE',
  moduleType: 'MASTER_DATA',
};

import { EnterpriseModuleProvider } from '@repo/ui/foundations';
import { registerModuleNamespace } from '@repo/core-i18n';
import { apiClient } from '../../../../../../../core/lib/api-client';

registerModuleNamespace(fullPageModuleConfig.translationNamespace, { id, en });

Validators (Zod)

import { z } from 'zod';
import { compose, required, rangeLength } from '@repo/ui/validators';

export const createFullPageSchema = (t: (key: string) => string) =>
  z.object({
    code: compose(z.string(), required(t('common:fields.code'))),
    name: compose(z.string(), required(t('common:fields.name')), rangeLength(3, 50, t('common:fields.name'))),
  });

Forms and HTTP

• Form fields: FieldTextInput and other Field* from @repo/ui/form
• HTTP: apiClient from src/core/lib/api-client (built with createHttpClient). Never raw axios.
• Env: ENV from src/core/environment. Files only in apps/web/.env*.

---

Testing Requirements

pnpm test
pnpm --filter web test
pnpm --filter @repo/ui test
pnpm typecheck:web
pnpm check:all

• Unit tests colocated as *.test.ts(x)
• Component tests with Testing Library in packages that already have it
• App journeys: browser-verify login and FULL_PAGE index / form / detail
• Minimum 80% coverage; TDD (red → green → refactor)

---

Scripts

pnpm dev:web
pnpm dev:showcase
pnpm dev:docs-dev
pnpm lint
pnpm typecheck:web
pnpm test
pnpm check:all

Env (apps/web)

See apps/web/.env.example. Typical VITE_* keys: VITE_APP_ENV, VITE_API_BASE_URL, telemetry URLs. All VITE_* values are public to the client.

---

Critical Rules

1. No emojis in code, comments, or documentation
2. Immutability — never mutate objects or arrays
3. TDD — tests before implementation
4. 80% coverage minimum
5. Many small files — 200–400 lines typical, 800 max
6. No console.log in production code
7. No raw Mantine/axios — use @repo/ui and apiClient
8. Input validation with Zod + @repo/ui/validators
9. Copy example/full-page; do not invent a third layout

---

Related Skills

• .agents/skills/coding-standards/ — TypeScript/React practices
• .agents/skills/form-layout/ — form layout
• .agents/skills/detail-layout/ — detail page layout
• .agents/skills/index-layout/ — index / list table layout
• .agents/skills/tdd-workflow/ — TDD
• .agents/skills/security-review/ — frontend/Electron security