# 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/`.