Repository Guidelines

Project Structure & Module Organization

ForgeApps is a private TypeScript-first pnpm monorepo. Deployable products live in apps/<name>/; reusable libraries live in packages/. Put repository tools in scripts/, scheduled automation in crons/, durable documentation in docs/ or references/, and shared static files in assets/. Most workspace code belongs under src/. Keep tests beside the code as *.test.ts(x) or in __tests__/ or tests/. .forgebot/skills/ is the canonical skill library; runtime-specific skill folders are linked views and must not contain copies.

Build, Test, and Development Commands

Use Node.js 24.x and pnpm 11.10.0 through Corepack.

• corepack pnpm install --frozen-lockfile installs the locked workspace.
• corepack pnpm --filter ./apps/example dev starts one app; replace the path with the workspace you are changing.
• corepack pnpm check runs the required checks for changed workspaces.
• corepack pnpm -r --if-present typecheck type-checks all applicable packages.
• corepack pnpm -r --if-present test runs workspace test suites.
• corepack pnpm -r --if-present build verifies production builds.

Coding Style & Naming Conventions

Use TypeScript for scripts, automation, utilities, and examples; do not add Python tooling or .py files. Prettier enforces two-space indentation, single quotes, no semicolons, trailing ES5 commas, and an 80-column target. Run the workspace's ESLint script before review. Name React components and pages in PascalCase, hooks as useCamelCase, other symbols in camelCase, and workspace directories in lowercase. Prefer shared @forgeapps/* packages over duplicated helpers.

Testing Guidelines

Vitest is the primary test runner; React work commonly uses Testing Library. Name tests *.test.ts or *.test.tsx and keep them close to the behavior they cover. Add a regression test for bug fixes and focused tests for new branches. No global numeric coverage threshold is configured, so favor meaningful behavior coverage. Verify visible UI changes in a browser and include before and after screenshots.

Commit & Pull Request Guidelines

Follow the existing Conventional Commit pattern: feat(forgerail): add meeting filters, test(ui): cover status fallback, or chore(metro): refresh data. Keep commits focused and subjects imperative. Pull requests should explain the problem and solution, link the issue, list affected workspaces and validation commands, and include screenshots for visual changes. Call out migrations, configuration, or deployment impact. Rebase on main and never discard unrelated working-tree changes.

Security & Configuration

Load secrets through Doppler project/config forgeapps/prd; never commit .env files, tokens, or credentials. Production deploys flow through git push, not direct local deployment commands.