ai-job-hunter-app: Instructions file for Codex

AI Job Hunter: Agent Rules

Canonical rules for every AI coding agent on this repo. Enforced by ESLint, TypeScript, commitlint, and CI. Violations block commits and fail the build.

Cursor and Windsurf read this file natively; Copilot does too, but not in every feature, so the thin .github/copilot-instructions.md pointer stays. Claude Code reads it through the @AGENTS.md import at the top of CLAUDE.md, which adds Claude-only orchestration (subagent fleet, review gates, model tiering) on top. Cline reads it via the pointer in .clinerules.

IMPORTANT: edit rules here, never fork them into a tool-specific file. 13 parallel copies drifted badly enough to teach a stale UI-primitive set and hide a whole app; pnpm check:agent-system now guards against a repeat.

---

Path privacy

Never output absolute paths, usernames, home dirs, drive letters, or temp/IDE paths, anywhere (logs, PRs, commits, docs, screenshots, stack traces). Always repo-relative (apps/desktop/src-tauri/src/main.rs); the same rule applies to Git Bash-style paths (/c/Users/…).

Shell & tooling

Use Bash (never PowerShell). rg not grep · fd not find · bat not cat · pnpm not npm/yarn. Never find -exec.

---

Architecture

Local-first desktop app, pnpm monorepo. Tauri is the shell. Detail → docs/ARCHITECTURE.md, status → docs/ARCHITECTURE_STATUS.md, principles → docs/PATTERNS.md §13.

Workspaces: packages/{shared,ui,prompts,translations,test-ids} (contracts · design system · prompt templates · i18n · test IDs) and apps/{desktop,extension,landing} (Tauri app · MV3 extension · Next.js site). Boundaries are rule 12: they are enforced, not stylistic.

Renderer → shell only via AppClient (createTauriInvokeClient() in apps/desktop/src/tauri-client/index.ts). IPC contract: packages/shared/src/ipc/contracts/. Dev: pnpm dev.

---

Rules (enforced: full config in eslint.config.mjs)

1. PRs only, never push to main. Branch → commit → push → gh pr create → wait for approval.
2. No window.api in UI. Use service hooks from apps/desktop/src/renderer/services/ (React Query).
3. i18n from @ajh/translations, never react-i18next/i18next directly. Init shim: @/i18n.
4. No hardcoded brand colors. text-brand/bg-brand/… or var(--color-brand). [#RRGGBB] errors.
5. No inline transition objects. import { transition } from '@ajh/ui'.
6. Always @ajh/ui primitives: Button, Input, TextArea, NumberField, Dropdown, Switch, ModalShell, ConfirmModal, EmptyState, ErrorState, RowSkeleton/CardSkeleton, GlassCard, SettingsSection, OptionTile, StreamingText. Raw <button>/<select>/<textarea> error (except <input type=range|file|checkbox|radio|hidden>). PageShell from @/components/layout/PageShell; UpdateBanner from @/components/ui/UpdateBanner.
7. Package entrypoints, not deep paths. @ajh/ui directly; prefer React.ComponentProps<typeof X>.
8. Import order (blank line between): node:* → external → @ajh/* → @/* → relative. pnpm lint:fix.
9. import type for pure types (auto-fixed; never suppress).
10. File placement under renderer/: features/ (one route), components/ui/, components/layout/, services/ (IPC hooks), lib/ (pure utils + machines/), hooks/, providers/, store/. Never import across feature dirs.
11. State machines for 3+ states → lib/machines/ + useMachine from @/hooks/use-machine.
12. Remote data via React Query service hooks: no useState + useEffect fetching.
13. Package boundaries: shared no React/Node · ui no Zustand/IPC/routing · prompts no UI/window · translations no app/IPC imports.
14. Stale-branch check before work: git fetch origin && git branch -r | rg $(git branch --show-current).
15. New IPC capability (5 steps): ipc/contracts/ → commands/ → tauri-client/ → a services/ hook → query key in services/query-client/. Then pnpm gen:api — docs/API.md is generated from the contracts and CI fails on drift; document the method with TSDoc on the contract, never by editing that page.
16. Never bypass ESLint: no // eslint-disable, no @ts-ignore. Scoped override in eslint.config.mjs with a reason. CI runs lint:strict --max-warnings 0.
17. Backend work must survive navigation. A subscription only receives events while its component is mounted; the Rust work it describes does not unmount. Progress state kept in a route component is discarded on navigation, and the terminal event is dropped — so the UI shows idle for work still running. Mount subscriptions from routes/__root.tsx or a provider, and read in-flight truth from the backend (persisted status / the job registry), not from local state. Enforced: pnpm check:event-subscriptions fails until every subscribing file is declared with its mount lifetime.
18. Docs under docs/ are thin pointers, never copies. Describe shape and contracts and point at the owning source symbol; never paste drift-prone literals — weights, thresholds, counts, signatures, enum members, file lists. The test before you save: for every number or name on the page, ask "if someone changed this in the code tomorrow, would this page silently become a lie?" If yes, replace it with a pointer to where it lives. This is the most frequently-raised review finding on this repo. Generated pages are never hand-edited — a file opening with a GENERATED FILE banner (docs/API.md) is rendered by a script, so fix the TSDoc on the contract member and re-run its generator (pnpm gen:api); editing the page fails pnpm gen:api:check in CI.
19. Small Rust files, tests out of line. Every .rs file under apps/desktop/src-tauri/src (tests included) stays under the HARD_CAP_LOC in tests/architecture.rs (R8), counting code lines only — blank and comment lines are free; a file that genuinely reads worse split may go up to R8_EXCEPTION_CEILING if listed in R8_EXCEPTIONS with its reason. Split by responsibility (sub-modules), never arbitrary chunks — and shrink while you split: a split that only spreads the same lines over more files is incomplete; deduplicate (DRY), simplify (KISS), one responsibility per module/fn (SOLID), delete dead and speculative code (YAGNI), and trim restated-code comments, with behaviour and test assertions unchanged. Tests use Rust's standard out-of-line layout, never inline mod tests { … } and never #[path]: the tests of foo.rs live in foo/tests.rs, declared with #[cfg(test)] mod tests; (for dir/mod.rs, dir/tests.rs); a large suite becomes foo/tests/<topic>.rs (R8b). Existing offenders are ratcheted in tests/r8_baseline.txt / tests/r8b_inline_tests_baseline.txt: they may shrink, never grow; regenerate with R8_BLESS=1 cargo test --test architecture only after a split.
20. Small TS/TSX files. The same rule for every tracked .ts/.tsx file (tests included, .d.ts excluded): stay under the cap in scripts/check-ts-size.mjs, counting code lines only, and shrink while you split, exactly as rule 18 says. Split a component into sub-components and hooks inside its own feature dir (rule 9), a large suite into <name>/<topic>.test.ts(x) with shared fixtures. Existing offenders are ratcheted in scripts/data/ts-size-baseline.txt: they may shrink, never grow; regenerate with TS_SIZE_BLESS=1 pnpm check:ts-size only after a split. Tracked in #1323.