From ccb24b26062d657312bc3566e652157dcee34999 Mon Sep 17 00:00:00 2001 From: beatzaplenty Date: Fri, 21 Nov 2025 15:12:12 +1000 Subject: [PATCH] modified: Agents.md --- Agents.md | 375 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 355 insertions(+), 20 deletions(-) diff --git a/Agents.md b/Agents.md index 53a9d6a..e7e1480 100644 --- a/Agents.md +++ b/Agents.md @@ -1,31 +1,366 @@ -Purpose +# AGENTS.md --- StockFill -StockFill is an offline-first Progressive Web App (PWA) designed to help service station staff create pick lists used to restock various store areas (drinks fridge, chips, chocolate, dairy, deli, etc.). -It uses IndexedDB (Dexie) for local storage, no backend, and runs fully offline. +## Purpose -All code generated must follow the architecture, conventions, and rules below. +StockFill is an offline-first Progressive Web App (PWA) designed to help +service station staff create pick lists used to restock various store +areas (drinks fridge, chips, chocolate, dairy, deli, etc.).\ +It uses **IndexedDB (Dexie)** for local storage, has **no backend**, and +runs fully offline. -1. Core Architecture +All code generated must follow the architecture, conventions, and rules +below. + +------------------------------------------------------------------------ + +## 1. Core Architecture StockFill is: -🟩 React + Vite +- React + Vite\ +- PWA (service worker + manifest)\ +- Dexie.js for local DB (IndexedDB)\ +- React Router\ +- Context + Hooks\ +- Mobile-first UI\ +- Hosted via Docker using Nginx -🟩 PWA (service worker + manifest) - -🟩 Dexie.js for local DB (IndexedDB) - -🟩 React Router for navigation - -🟩 Context + Hooks for app logic - -🟩 Mobile-first UI - -🟩 Hosted via Docker using Nginx - -There is no remote API. +There is **no remote API**.\ All data stays local to the device. -2. Directory Structure +------------------------------------------------------------------------ + +## 2. Directory Structure Codex must always generate files within this structure: + + /app + /src + /components + /screens + /hooks + /db + index.ts + migrations.ts + seed.ts + /models + Product.ts + Area.ts + PickList.ts + PickItem.ts + /context + DBProvider.tsx + /utils + barcode.ts + longPress.ts + swipe.ts + /pwa + service-worker.js + manifest.json + App.tsx + main.tsx + Dockerfile + docker-compose.yml + vite.config.ts + AGENTS.md + +Codex must not introduce alternative or conflicting structures. + +------------------------------------------------------------------------ + +## 3. Data Model Specification + +Dexie tables must be implemented exactly as follows: + +### Products + + id: string (UUID) + name: string + category: string + unit_type: string + bulk_name?: string + units_per_bulk?: number + barcode?: string + archived: boolean + created_at: number + updated_at: number + +### Areas + + id: string + name: string + created_at: number + updated_at: number + +### PickLists + + id: string + area_id: string + created_at: number + completed_at?: number + notes?: string + +### PickItems + + id: string + pick_list_id: string + product_id: string + quantity_units: number + quantity_bulk: number + status: "pending" | "picked" | "skipped" + created_at: number + updated_at: number + +------------------------------------------------------------------------ + +## 4. UI & UX Rules + +- Mobile-first screens\ +- Large touch targets\ +- Clean, minimal UI\ +- Use MUI components\ +- Follow workflow conventions\ +- Avoid excessive modal dialogs\ +- Ensure barcode scanning is fast\ +- Ensure gesture operations are smooth + +------------------------------------------------------------------------ + +## 5. Core Screens + +### HomeScreen + +- Start New Pick List\ +- View Pick Lists\ +- Manage Products\ +- Manage Areas\ +- Scan Barcode (quick add) + +### StartPickListScreen + +- Choose Area\ +- Start button + +### ActivePickListScreen + +- List of PickItems\ +- Tap = +1 unit\ +- Long-press = +1 bulk\ +- Swipe left = mark picked\ +- Swipe right = delete\ +- Add Item button\ +- Complete List button + +### AddItemScreen + +- Search\ +- Category filter\ +- Scan barcode\ +- Increment units & bulk\ +- Add to pick list + +### ManageProductsScreen + +- List\ +- Search\ +- Filters\ +- Edit product\ +- Add product + +### ManageAreasScreen + +- Add\ +- Edit\ +- Delete + +### BarcodeScannerScreen + +- Live camera preview\ +- On detection → resolve product or prompt creation + +------------------------------------------------------------------------ + +## 6. Gestures & Interaction Rules + +### Tap + +Increase `quantity_units` by **1**. + +### Long Press + +Increase `quantity_bulk` by **1** using a shared `useLongPress()` hook. + +### Swipe Left + +Mark item as `"picked"`. + +### Swipe Right + +Delete item. + +### Barcode Scanning + +- Use `@zxing/browser`\ +- Fallback to native `BarcodeDetector` + +------------------------------------------------------------------------ + +## 7. Hooks Requirements + +### Database Hooks + +- `useProducts()`\ +- `useProduct(id)`\ +- `usePickList(id)`\ +- `usePickLists()`\ +- `usePickItems(pickListId)`\ +- `useAreas()` + +### Interaction Hooks + +- `useLongPress()`\ +- `useSwipe()`\ +- `useBarcodeScanner()` + +### PWA Hooks + +- `useServiceWorker()` + +------------------------------------------------------------------------ + +## 8. Component Requirements + +- ProductRow\ +- PickItemRow\ +- NumericStepper\ +- BarcodeScannerView\ +- LongPressButton + +All components must use TypeScript and be reusable. + +------------------------------------------------------------------------ + +## 9. State Management Rules + +- Use Context for DB provider\ +- No Redux\ +- Long-lived data must come from Dexie\ +- No external APIs\ +- Full offline functionality + +------------------------------------------------------------------------ + +## 10. PWA Requirements + +### manifest.json + +- name\ +- short_name\ +- icons\ +- display: standalone\ +- background_color\ +- theme_color + +### service-worker.js + +- Precache static assets\ +- Cache index.html\ +- Cache route requests\ +- Provide offline fallback + +Must NOT break Dexie. + +------------------------------------------------------------------------ + +## 11. Docker Requirements + +### Dockerfile + +- Node build stage\ +- Nginx serve stage\ +- Copy build to `/var/www/html`\ +- Must include service worker + PWA files + +### docker-compose.yml + +Expose port 8080: + + ports: + - "8080:80" + +------------------------------------------------------------------------ + +## 12. Code Style Rules + +- TypeScript only\ +- Strict mode\ +- Prettier formatting\ +- Named exports unless default is clearer\ +- No files larger than 300--400 lines\ +- Keep architecture consistent + +------------------------------------------------------------------------ + +## 13. UX Workflow Requirements + +- Minimise taps\ +- Prioritise mobile experience\ +- Search must be instant\ +- Barcode scanning must be quick\ +- Product creation must be minimal friction\ +- Auto-save pick lists\ +- Smooth animations on long press + +------------------------------------------------------------------------ + +## 14. Testing and Validation + +Codex must generate: + +- Unit tests for hooks\ +- Component tests with React Testing Library\ +- e2e tests only if explicitly requested + +Must support offline mode. + +------------------------------------------------------------------------ + +## 15. Things Codex Must NOT Do + +Codex must **never**: + +- Create a backend\ +- Use remote APIs\ +- Break PWA functionality\ +- Change Dexie schema without migrations\ +- Introduce Redux\ +- Modify directory structure\ +- Remove offline support\ +- Add multi-user logic + +------------------------------------------------------------------------ + +## 16. Output Rules for Codex + +- Include file paths at top of each snippet\ +- No placeholder TODOs\ +- Code must be runnable\ +- Must follow existing patterns\ +- Must ensure offline correctness + +------------------------------------------------------------------------ + +## 17. Project Evolution Rules + +- New features must follow these patterns\ +- DB changes must use migrations\ +- Schema must remain forward-compatible + +------------------------------------------------------------------------ + +## 18. Summary + +This document defines how Codex must generate, modify, and maintain the +StockFill codebase.\ +Codex must follow this specification **exactly**, ensuring consistency +and maintainability across all future changes.