| 1 | # AGENTS.md |
| 2 | |
| 3 | This document defines how AI coding agents should operate in this repository. |
| 4 | |
| 5 | ## Scope |
| 6 | |
| 7 | - Applies to the entire monorepo rooted at `struxav2/`. |
| 8 | - If a nested directory later adds its own `AGENTS.md`, the nested one overrides this file for that subtree. |
| 9 | |
| 10 | ## Critical Rule |
| 11 | |
| 12 | - Do not run the project locally. |
| 13 | - Do not start dev servers (`bun run dev`, `next dev`, |
| 14 | - Do not run long-lived/watch processes. |
| 15 | |
| 16 | ## Project Overview |
| 17 | |
| 18 | - Monorepo managed with Bun workspaces and Turborepo. |
| 19 | - Apps: |
| 20 | - `apps/web`: Next.js fullstack app (port 3001 in local scripts). |
| 21 | - `apps/fumadocs`: Documentation site. |
| 22 | - Shared packages: |
| 23 | - `packages/ui`: shared UI primitives/styles (`@struxa/ui` |
| 24 | - `packages/api`: oRPC router and procedures (`@struxa/api` |
| 25 | - `packages/auth`: better-auth configuration (`@struxa/auth` |
| 26 | - `packages/db`: Drizzle ORM schema and database client (`@struxa/db` |
| 27 | - `packages/env`: environment schemas/helpers (`@struxa/env` |
| 28 | - `packages/config`: shared TypeScript config (`@struxa/config` |
| 29 | |
| 30 | ## Tech Stack |
| 31 | |
| 32 | - Bun (`packageManager: bun@1.3.5`) |
| 33 | - Turborepo |
| 34 | - Next.js 16 + React 19 |
| 35 | - Tailwind CSS 4 |
| 36 | - better-auth (authentication) |
| 37 | - Drizzle ORM + MySQL |
| 38 | - oRPC (type-safe API layer) |
| 39 | - TanStack Query (data fetching) |
| 40 | - shadcn/ui style component setup in shared UI package |
| 41 | |
| 42 | ## Workspace Commands (Reference Only) |
| 43 | |
| 44 | Use these as documentation for intent; avoid executing runtime/dev commands unless the user explicitly asks and confirms. |
| 45 | |
| 46 | - Root: |
| 47 | - `bun run dev` |
| 48 | - `bun run build` |
| 49 | - `bun run check-types` |
| 50 | - App scripts: |
| 51 | - `apps/web`: `dev` |
| 52 | - DB scripts (run from root or `packages/db`): |
| 53 | - `db:push`, `db:generate` |
| 54 | - `db:start`, `db:stop` |
| 55 | |
| 56 | ## Agent Working Agreement |
| 57 | |
| 58 | - Make minimal, targeted changes that satisfy the user request. |
| 59 | - Preserve existing architecture and naming conventions. |
| 60 | - Avoid broad refactors unless requested. |
| 61 | - Do not edit generated/lock files unless required by the task. |
| 62 | - Do not add new dependencies unless necessary and justified. |
| 63 | - Prefer shared package reuse over duplication in apps. |
| 64 | |
| 65 | ## Internationalization (i18n) |
| 66 | |
| 67 | This project uses **next-intl** for all user-visible strings in ` |
| 68 | |
| 69 | - **Never hardcode English strings** in React components - labels, placeholders, validation messages, toast messages, button text, and empty states all go in |
| 70 | - In server components (no `"use client"`), use `getTranslations` from |
| 71 | - Follow the existing namespace hierarchy: `auth.*`, `nav.*`, |
| 72 | - All new strings must be added to `en.json` in the same commit as the feature code. |
| 73 | - The locale is stored in the `NEXT_LOCALE` cookie (7-day) and synced to/from the `locale` column on the |
| 74 | |
| 75 | ## Editing Guidelines |
| 76 | |
| 77 | - Keep changes consistent with existing TypeScript/React style. |
| 78 | - For UI work, prefer composing from `@struxa/ui` components before adding app-local primitives. |
| 79 | - Put shared logic in `packages/*` when used by multiple apps. |
| 80 | - Keep environment parsing centralized in `packages/env`. |
| 81 | - Keep API contract/type updates synchronized across `packages/api`, `packages/auth`, and |
| 82 | - Auth is handled by better-auth via `packages/auth` - do not implement manual token management. |
| 83 | |
| 84 | ## Validation Strategy (No App Runtime) |
| 85 | |
| 86 | Because running the project is disallowed by default: |
| 87 | |
| 88 | - Prefer static checks only when needed and safe (lint/type/build commands are allowed only if user asks or task requires verification). |
| 89 | - If validation is skipped, clearly state what was not run and why. |
| 90 | - Provide a concise manual verification checklist for the user when useful. |
| 91 | |
| 92 | ## Data, Secrets, and Safety |
| 93 | |
| 94 | - Never commit secrets or real credentials. |
| 95 | - Treat `.env` files as sensitive; use `.env.example` patterns. |
| 96 | - Avoid destructive commands (`rm -rf`, hard resets, force pushes) unless explicitly requested. |
| 97 | |
| 98 | ## Paths and Conventions |
| 99 | |
| 100 | - Root task orchestration: `turbo.json`, `package.json`. |
| 101 | - Main docs: `README.md`. |
| 102 | - MCP settings: `.mcp.json`. |
| 103 | |
| 104 | ## Preferred Agent Response Shape |
| 105 | |
| 106 | - Start with what changed. |
| 107 | - List exact files touched. |
| 108 | - Note any commands run. |
| 109 | - Note what was not run (especially app runtime) and why. |
| 110 | - End with optional next steps. |