familyHub/AGENTS.md

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.
• 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 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).
• 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.
• 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/.