61 lines
2.9 KiB
Markdown
61 lines
2.9 KiB
Markdown
# Family Hub development agents
|
|
|
|
Three roles coordinate so features stay usable on phones and desktops, data stays consistent, and releases are verifiable without adding Composer or npm tooling.
|
|
|
|
## Roles
|
|
|
|
### UI agent
|
|
|
|
**Owns**
|
|
|
|
- Responsive layout (Bootstrap breakpoints), readable typography, and spacing consistent with [assets/css/style.css](assets/css/style.css).
|
|
- Touch targets (about 44px minimum where practical) and hover/keyboard affordances on desktop.
|
|
- Empty states, loading/error feedback for API actions, and color contrast when applying per-person `favoriteColor` theming.
|
|
- Information architecture for tabs (e.g. store sub-nav in groceries): scannable labels, scroll behavior on small screens.
|
|
|
|
**Definition of done**
|
|
|
|
- No horizontal overflow on a 320px-wide viewport for primary flows.
|
|
- Primary actions visible without reliance on hover-only tooltips.
|
|
|
|
### Engineering agent
|
|
|
|
**Owns**
|
|
|
|
- JSON schemas in `data/`, [`includes/db.php`](includes/db.php) read/write patterns (including locking), and `api/*.php` contracts.
|
|
- Session and persona rules: who can switch to Head of Household (PIN), how PINs are stored (`password_hash` only), and never exposing secrets in HTML or JSON responses.
|
|
- Migrations from older flat JSON shapes when fields are added; documenting new filenames in export/cron if applicable.
|
|
|
|
**Definition of done**
|
|
|
|
- Writes use exclusive file locks; reads that must be consistent use shared locks where implemented.
|
|
- Invalid `tab=` values cannot include arbitrary files ([`index.php`](index.php)).
|
|
- API errors return JSON with a stable `error` string; success responses are predictable for the UI agent.
|
|
|
|
### Testing agent
|
|
|
|
**Owns**
|
|
|
|
- Manual test matrices per feature (happy path, validation failures, mobile width).
|
|
- Optional plain-PHP smoke scripts under `scripts/` (no PHPUnit dependency).
|
|
- Browser checks for critical flows: persona switch, HoH PIN failure/success, settings save.
|
|
|
|
**Definition of done**
|
|
|
|
- Every feature merged with a short checklist in the PR description or a linked note (until automated smoke tests exist).
|
|
- Regression entries added when bugs are fixed.
|
|
|
|
## How the agents work together
|
|
|
|
1. **Engineering** lands data model and API first (or in the same PR as minimal UI).
|
|
2. **UI** wires the flow against real endpoints; adjusts copy and layout.
|
|
3. **Testing** runs the matrix; block merge on open P0/P1 gaps.
|
|
|
|
**Conflict resolution:** If a shortcut breaks responsive or locking rules, Engineering revises the approach; if the API is awkward for users, UI and Engineering agree on a small contract change before adding UI polish.
|
|
|
|
## Conventions
|
|
|
|
- PHP: naming per [.cursor/rules/naming-conventions.mdc](.cursor/rules/naming-conventions.mdc).
|
|
- Front-end libraries: Bootstrap, Font Awesome, and jQuery from CDN only (project rule).
|
|
- Runtime data lives in gitignored `data/`; committed examples belong under `fixtures/` or `docs/samples/`, not `data/`.
|