social-app/apps/AGENTS.md

# Flutter Mobile Development Constraints

This document defines **hard constraints** for Flutter mobile development. Treat all items as **non-negotiable** unless explicitly overridden.

## 0) Scope and Precedence (MUST)

- This file applies to all changes under `apps/**`.
- It extends root routing rules in `AGENTS.md` and workspace global runtime rules.
- If rules conflict, apply the stricter requirement.
- Keep Flutter-specific constraints in this file; avoid duplicating them in root `AGENTS.md`.

## 1) Design Tokens (MUST)

- **MUST** use design tokens from `apps/lib/core/theme/design_tokens.dart`:
  - Colors: `AppColors.*`
  - Spacing: `AppSpacing.*`
  - Radius: `AppRadius.*`
- **MUST NOT** hardcode any visual values, including (but not limited to): colors, font sizes, spacing, padding/margins, widths/heights, radii, shadows, opacity, or “magic numbers”.
  - Examples that are **NOT allowed**: `Color(0xFF...)`, `SizedBox(height: 12)`, `EdgeInsets.all(16)`, `Radius.circular(8)`.

## 2) Component Reuse (MUST)

- **MUST** prefer existing components and established page patterns over creating new UI components.
- **MUST** use:
  - Buttons: `AppButton` from `apps/lib/shared/widgets/app_button.dart`
- **MUST NOT** introduce parallel UI systems (custom buttons, custom loading systems, custom input wrappers) unless explicitly required and approved.

## 3) Layout Mapping & Alignment (MUST)

- **MUST** explicitly set `crossAxisAlignment` for every `Row` / `Column` (do not rely on defaults).
- **MUST** preserve layout semantics from root to leaf:
  - alignment/justification intent must be explicitly represented in Flutter widgets.
- **MUST NOT** skip necessary container layers if doing so loses layout meaning or makes mapping non-traceable.

## 4) Centering & Visual Balance (MUST)

- **MUST** evaluate centering within `SafeArea` usable bounds (not full-screen bounds).
- **MUST NOT** rely on `Spacer` / proportional flex as the only centering mechanism for critical content.
- If persistent header/footer regions exist, **MUST** center primary content within the remaining usable region.
- **MUST** prioritize *visual centering* over purely geometric centering when they differ.

## 5) Testing Strategy (MUST)

Follow lightweight testing strategy - prioritize value over coverage:

**Write tests for:**
- Model / DTO parsing (json → model)
- Service layer logic (business rules, API call handling)
- Complex custom widgets with rich interactions

**Skip for:**
- Simple UI pages, regular buttons, basic layouts

## 6) UI Feedback System (MUST)

- All user-facing feedback **MUST** use the Toast system.
  - Transient notifications: `Toast.show(...)`
  - Persistent inline form errors: `AppBanner`
- **MUST NOT** create custom SnackBar/Dialog/Banner feedback components.
- **MUST NOT** use raw `ScaffoldMessenger` for feedback messaging.

## 7) Agent Chat (AG-UI Protocol) (MUST)

Agent chat functionality **MUST** follow the AG-UI protocol. **Use the `ag-ui` skill** for protocol reference and implementation guidance.

- **MUST** use Server-Sent Events (SSE) for streaming.
- **MUST** emit required lifecycle events:
  - `RUN_STARTED` is required for every run
  - End with exactly one of: `RUN_FINISHED` or `RUN_ERROR`
- **MUST** follow standard text streaming flow:
  - `TEXT_MESSAGE_START` → `TEXT_MESSAGE_CONTENT` (delta) → `TEXT_MESSAGE_END`
- **MUST** support the standard AG-UI event type set as defined in the spec.
- **MUST NOT** return non-streaming responses for agent chat.
- **MUST NOT** omit required lifecycle events.
- **MUST NOT** use non-AG-UI event formats (except where the spec explicitly allows).