commit

AGENTS.md

@@ -153,6 +153,51 @@ Before implementation, every non-trivial task must review:
 
 Implementation without this review is prohibited.
 
+### AI Workflow
+
+AI coding agents should follow this workflow for non-trivial work:
+
+1. Requirement analysis: restate the requested outcome, scope, and non-goals.
+2. Historical review: read the required standards, related ADRs, completed task notes, and relevant business/security docs.
+3. Architecture review: identify the approved foundations, service boundaries, route groups, permissions, audit events, and UI shells that already apply.
+4. Existing pattern discovery: search the codebase for similar components, hooks, utilities, dialogs, forms, tables, services, route handlers, layouts, providers, and tests before creating new ones.
+5. Implementation plan: choose the smallest change that extends existing architecture and document any justified exception.
+6. Implementation: make scoped changes in the owning feature/foundation area.
+7. Self review: check architecture, reuse, security, data freshness, UI states, accessibility, and maintainability before delivery.
+8. Validation: run the most relevant lint, typecheck, test, build, or manual verification available for the change.
+9. Delivery: summarize what changed, what was verified, and any residual risks or follow-up work.
+
+For small documentation-only or inspection tasks, agents may use a lighter version of this workflow, but they must still preserve project rules and avoid inventing new architecture.
+
+### Existing Pattern Discovery
+
+Before creating any new component, hook, utility, dialog, service, API, layout, table, form, provider, export flow, report dataset, permission helper, or audit event, agents must search for an existing implementation that can be reused or extended.
+
+Minimum discovery expectations:
+
+- search by domain name, route segment, entity name, and UI pattern
+- inspect neighboring features under `src/features/**`
+- inspect shared UI under `src/components/**`
+- inspect existing route handlers under `src/app/api/**`
+- inspect shared auth, permission, audit, report, PDF, approval, storage, and document foundations when the task touches those areas
+- prefer extending an existing module over introducing a parallel one
+
+If a new implementation is still required, document why the existing pattern could not be reused.
+
+### AI Skill Composition
+
+External AI skills, plugins, models, and assistant-specific workflows may help with implementation, but project standards always have the highest priority.
+
+Use this responsibility order:
+
+1. Project standards: `AGENTS.md`, `docs/standards/**`, ADRs, business docs, security docs, and implementation history.
+2. Architecture: approved Next.js, Auth.js, Drizzle, React Query, route-handler, service-layer, permission, and foundation patterns.
+3. Existing code pattern: local implementations already present in this repository.
+4. External skill: framework, UI, accessibility, performance, testing, documentation, or migration guidance.
+5. UI polish: visual refinement that preserves the established dashboard design language.
+
+AI-specific guidance must not override repository rules. When external advice conflicts with this document or the standards docs, follow the repository rule and note the conflict if it affects the deliverable.
+
 ---
 
 ## Technology Stack Details
@@ -388,6 +433,58 @@ Notes:
 
 - use `<Button isLoading={isPending}>` for loading states
 
+### Component Reuse Policy
+
+Before creating any new UI building block, search for an existing shared or feature-local pattern first.
+
+This applies to:
+
+- cards and summary cards
+- data tables, columns, filters, and toolbars
+- dialogs, sheets, drawers, destructive confirmations, and preview panels
+- forms, field wrappers, validation schemas, and submit buttons
+- status badges, labels, empty states, loading states, and error states
+- action bars, page headers, side panels, tabs, and navigation helpers
+
+Reuse order:
+
+1. shared app components under `src/components/**`
+2. foundation or CRM shared components under `src/features/foundation/**` and `src/features/crm/**`
+3. same-feature components under `src/features/<feature>/components/**`
+4. a new component only when reuse would create inappropriate coupling or unclear ownership
+
+New reusable components should follow the established shadcn/ui, Tailwind, `cn()`, icon registry, accessibility, and server/client boundary patterns.
+
+### Refactoring Policy
+
+Refactoring is encouraged when it reduces duplication, clarifies ownership, or makes the requested change safer.
+
+Preferred refactoring:
+
+- extend existing modules, services, schemas, query keys, mutations, and components
+- keep public contracts backward compatible unless the task explicitly requires a breaking change
+- move repeated business logic into the owning feature service or foundation
+- simplify local code while preserving established architecture and terminology
+- update documentation when a new rule, exception, or reusable pattern is introduced
+
+Avoid:
+
+- broad rewrites unrelated to the task
+- parallel helpers that duplicate foundation behavior
+- replacing working project patterns with a different library or architecture
+- cosmetic churn in files outside the requested scope
+- renaming domain concepts without a business or ADR-backed reason
+
+### Maintainability Expectations
+
+Code should be understandable to future agents and engineers without relying on hidden prompt context.
+
+- keep contracts explicit and close to their feature boundary
+- prefer clear names over comments for ordinary logic
+- add short comments only for non-obvious business rules, security decisions, or compatibility seams
+- avoid leaking implementation details from services into UI components
+- keep route handlers thin and move reusable logic into feature/foundation services
+
 ---
 
 ## Navigation & RBAC
@@ -552,6 +649,78 @@ Use:
 
 ---
 
+## Enterprise UI / UX Standards
+
+Enterprise dashboard work should feel consistent, calm, scannable, and production-ready. New UI must reuse the existing dashboard shell, shadcn/ui primitives, Tailwind tokens, app icon registry, and CRM terminology rules before introducing new visual patterns.
+
+### Visual Hierarchy
+
+- make the primary task, primary data, and primary action clear without relying on explanatory text blocks
+- use `PageContainer` for dashboard page framing and keep action placement predictable
+- group related filters, metrics, tables, forms, and detail panels by task flow
+- keep typography hierarchy restrained inside cards, tables, dialogs, and side panels
+- avoid visual clutter, decorative-only UI, and competing emphasis
+
+### Layout And Responsiveness
+
+- design for desktop dashboard density while keeping mobile and tablet layouts usable
+- preserve spacing consistency with existing dashboard, CRM, report, and table pages
+- use stable dimensions for toolbars, action buttons, status badges, cards, table controls, and loading placeholders
+- avoid layouts where text, controls, sticky panels, or table actions overlap at common breakpoints
+- verify horizontal scrolling only where it is deliberate, such as wide data tables
+
+### States And Feedback
+
+Every user-facing data surface should account for:
+
+- loading states, preferably skeletons that preserve layout stability
+- empty states with a clear next action or explanation
+- error states with actionable copy and no leaked backend internals
+- disabled and pending states for actions and submit buttons
+- successful mutation completion only after cache invalidation or refresh behavior is triggered
+
+### Accessibility And Interaction
+
+- preserve semantic HTML and accessible names for interactive controls
+- keep keyboard navigation usable for menus, dialogs, forms, tabs, and tables
+- ensure focus behavior is predictable when opening and closing dialogs or sheets
+- maintain readable contrast in light and dark modes
+- do not rely on color alone to communicate status or required action
+
+### Enterprise Dashboard Standards
+
+Dashboard and CRM pages should prefer:
+
+- clear information hierarchy from summary to detail
+- summary cards only when they answer a real operational question
+- balanced table, filter, chart, and detail panel composition
+- grouped actions with the most common action in the most predictable location
+- sticky action panels or footers when they improve long-form completion
+- consistent empty/loading/error states across sibling pages
+- restrained whitespace that improves scanning without hiding dense operational data
+
+Avoid:
+
+- one-off visual systems inside dashboard pages
+- oversized marketing-style hero sections for operational tools
+- unnecessary nested cards
+- duplicating table, filter, export, report, approval, PDF, or permission UI patterns already owned by a foundation
+
+### Design Review Checklist
+
+Before considering UI work complete, agents must verify:
+
+- readability: labels, values, and actions are clear
+- consistency: spacing, typography, radius, borders, icons, and controls match nearby screens
+- responsiveness: mobile, tablet, and desktop layouts remain usable
+- accessibility: keyboard, focus, contrast, semantics, and non-color status cues are covered
+- component reuse: shared app, CRM, table, form, and foundation components were reused where appropriate
+- visual balance: dense data remains scannable without decorative clutter
+- state coverage: loading, empty, error, disabled, and success states are represented
+- maintainability: UI logic, business rules, and server-state behavior remain in the correct layers
+
+---
+
 ## Current Migration Guidance
 
 Use the migrated `products` feature as the main reference for new CRUD work.
@@ -659,6 +828,36 @@ Ensure these are set:
 23. Do not create duplicate report/export/PDF/approval/security plumbing when a project foundation already exists.
 24. CRM authorization must flow through resolved access helpers such as `resolveCrmMembershipAccess()`, `buildCrmSecurityContext()`, or report-context builders; do not authorize with raw role strings alone.
 
+### AI Self Review Checklist
+
+Before declaring implementation complete, verify:
+
+- architecture follows the project standards and approved foundations
+- historical review was completed for non-trivial work
+- existing services, APIs, components, query keys, mutations, and UI shells were reused or extension rationale is documented
+- no duplicated business logic, permission checks, export/report flows, PDF flows, approval flows, or audit plumbing was introduced
+- server-side auth, organization access, CRM scope, pricing visibility, and audit behavior are enforced where applicable
+- route handlers remain thin and business logic remains in feature/foundation services
+- React Query invalidation covers list, detail, child-resource, counts, previews, approval panels, and related cross-feature data affected by mutations
+- UI is consistent with dashboard and CRM standards
+- loading, empty, error, disabled, pending, and success states are handled where user-facing behavior requires them
+- accessibility, keyboard navigation, focus behavior, contrast, and responsive layout were considered
+- date/time rendering uses `src/lib/date-format.ts` and remains deterministic
+- code remains maintainable, scoped, and free of unrelated rewrites
+- relevant lint, typecheck, tests, build, or manual checks were run or explicitly noted as not run
+
+### Future Compatibility
+
+This guide is AI-agent agnostic. It applies to Codex, Claude Code, Gemini CLI, Cursor, Windsurf, Cline, and future coding assistants.
+
+Agents may use their own planning, tool, or skill systems, but must preserve these repository priorities:
+
+1. project governance and standards
+2. accepted ADRs and business/security documents
+3. existing foundations and feature implementations
+4. local code patterns
+5. external framework or assistant-specific recommendations
+
 Before implementing any task, review:
 - AGENTS.md
 - docs/standards/*