Imported from tiwariabishek44/abishek_fewa (fewaoms_saas_tenant_002/AGENTS.md). Install upstream with npx skills add tiwariabishek44/abishek_fewa --skill fewaoms_saas_tenant_002. Copyright stays with the author.

AGENTS.md

Lak Project — Flutter Engineering Agent Playbook (BLoC + Strong CLI + Test-First)

Goal

Ship mobile features with discipline: read → analyze → PROBE APIs → write findings → plan → implement → test → document.
BLoC for state management everywhere. No Frankenstein mixes.
Admin is web-only. App consumes user-facing /api/v1/* only, with the standard envelope and cursor pagination from /docs.
App must be responsive, localized (en/ne), and follow the Design System.

Repo Map (relevant)

/docs ← canonical product/architecture (read-only for agent)
/web ← Laravel app (API source of truth)
/app ← Flutter app
- /docs
  - /findings ← agent writes API probes + analysis (one file per task)
  - /plan ← agent writes a single plan.md (overwritten per approved task)
  - /implementations ← agent writes what shipped per task
- /lib (current)
  - app/ ← app shell
  - counter/ ← sample (will be replaced by feature scaffolds)
  - l10n/ ← localization (will switch to en/ne)
  - main_*.dart ← flavors
- /test, /integration_test, pubspec.yaml

Workflow (strict)

Important

1) READ (in this order)

a) /docs/00-foundation/project_overview.md
b) /docs/00-foundation/information_architecture.md
c) /docs/10-design/design_system.md
d) /docs/20-architecture/api_conventions.md
e) /docs/20-architecture/tech_blueprint.md
f) /docs/20-architecture/notifications_messaging.md
g) /docs/30-modules/<module>.md
h) /docs/40-quality/non_functional_requirements.md
i) /docs/40-quality/security_privacy_compliance.md
j) /docs/40-quality/test_plan.md, /docs/40-quality/acceptance_criteria.md

2) PROBE APIs (must do before findings/plan)

Purpose: confirm real response shapes, envelope, cursors, error codes.

Obtain APP_BASE_URL and a Bearer token (test user) or login creds.
Run quick probes and capture payloads:
- GET /api/v1/meta/config
- One list with cursor (e.g., GET /api/v1/notices?publish_status=published&page_size=3)
- One detail read (e.g., GET /api/v1/notices/{id})
- One POST happy-path (e.g., /api/v1/payments with mocked input if possible)
- One failure case to record error.code + message
Save raw JSON excerpts in the Findings file.

CLI examples:

curl -H "Authorization: Bearer <TOKEN>" "$APP_BASE_URL/api/v1/meta/config"
curl -H "Authorization: Bearer <TOKEN>" "$APP_BASE_URL/api/v1/notices?publish_status=published&page_size=3"

3) FINDINGS (write)

Create one file in /app/docs/findings/: findings-YYYYMMDD-HHMM-<task-slug>.md

Must include:

Summary of requested change
What exists now (routes/nav, screens/widgets, blocs, repos, API client, models, l10n, theming)
API PROBE RESULTS (raw snippets) and gaps vs. /docs (envelope, fields, cursor keys, errors)
Api responses of tests must be at the file like :
- API : api url
- Response of this
- Response of this
- if you get continus error , stop docs and ask for fix and i will inform with updated api and continue again.
- that means actual api results observation and testing is compulsor , for testing otp is 123456.
Proposed BLoC design (events/states), repository interfaces, models/DTOs
UI deltas (screens/widgets, loaders/empty/error, responsive behavior)
Localization keys to add (en/ne)
Risks & unknowns
Tokens needed (see “Tokens & Secrets”)

4) PLAN (after owner approval)

Write a single /app/docs/plan/plan.md (overwrite per cycle). Must be exact:

Scope, acceptance criteria mapping
Routing: named routes, deep links
BLoC: event/state diagrams, bloc/repo/provider wiring
Data layer: repositories, DTOs, envelope parsing, cursor helpers
Networking: interceptors (bearer, Accept-Language, retry/backoff, redaction)
Screens & Widgets: file paths, skeletons, empty/error, aspect ratios (4:1 banners, 4:3 cards, 1:1 gallery, 3:4 board)
Responsive spec: sm ≥ 480, md ≥ 768, lg ≥ 1024, xl ≥ 1280; layout changes at md/lg
Theming: read /api/v1/meta/config and apply tokens to ThemeData
Localization: ARB keys for en/ne
Notifications: FCM registration (if in scope), device token POST
Tests (MANDATORY):
- Unit: models parsing, repositories (mocked client)
- Widget: golden tests at sm/md/lg breakpoints, with truncation/ellipsis assertions
- Integration: login/token + one end-to-end list with cursor + one POST with failure path
Build flavors & dart-defines
Rollback and out-of-scope

5) IMPLEMENT

Branch: feature/<module>-<slug>-<issueNo>
Commit style:
- feat(membership): add membership_status screen + bloc + repo
- test(api): add envelope & cursor parsing tests
- fix(ui): clamp card title to 2 lines
Code rules:
- Use flutter_bloc + bloc_test
- One ApiClient (dio or http wrapper) with interceptors
- Repository pattern between client and blocs
- CursorPage helper reused across lists
- Design tokens for spacing/radius/colors; no inline magic numbers

6) TEST (Expectations — no tests, no merge)

API tests (unit): envelope success/failure parsing; error code mapping; cursor advancement
Widget tests: at least one golden per new screen at sm/md/lg; asserts for skeleton, empty, error, loaded; asserts text truncation
Integration tests: happy path + one failure (network 500 or 401 → refresh → retry)

7) DOCUMENT

Create /app/docs/implementations/impl-YYYYMMDD-HHMM-<task-slug>.md:

What shipped: screens, blocs, repos, models
Endpoints used
Files changed
Test summary (counts, coverage)
Screenshots/recording
Flags/config
Follow-ups

8) PR / REVIEW

Link findings + plan + implementation docs
Show green unit + widget + integration tests
Demo screens with responsive layouts
Reject if envelope/cursor/localization/design-tokens violated

Tokens & Secrets (ask at end of Findings)

APP_BASE_URL for dev/stage/prod
Auth:
- Test member login (email/password) for token flow, OR
- A Bearer token valid on staging to run integration tests
FCM configs (google-services files) if push is in scope
Deep link scheme (e.g., app://), if applicable

Do NOT request server or DB secrets.

Project Guardrails (BLoC + CLI)

Packages (recommended)

flutter_bloc, bloc_test, equatable
dio (or http + interceptors), mocktail
json_annotation + build_runner (+ freezed optional)
go_router (or your choice) for routing
intl for i18n
golden_toolkit for responsive goldens
device_frame (for preview in tests)

CLI scaffolding (write simple scripts under `/app/tool/cli`)

tool/cli/new_feature.dart → generates:
- lib/features/<name>/bloc/<name>_bloc.dart
- lib/features/<name>/repo/<name>_repository.dart
- lib/features/<name>/view/<name>_page.dart
- test/features/<name>/bloc/<name>_bloc_test.dart
- test/features/<name>/view/<name>_page_test.dart
Wire it in pubspec.yaml as a dart run executable.
Enforce folder schema:


/lib
/core
api/ (client, interceptors, envelope, cursor)
theme/ (tokens: colors, radius 8/12, spacing 4pt)
i18n/
/features
/membership
bloc/, repo/, view/
/documents
/notices
/news
/prices
/media
/downloads
/notifications
app/app.dart
main_development.dart | main_staging.dart | main_production.dart

Testing Matrix (must)

Unit

Envelope parsing: success {data, meta, error:null} and failure {data:null, meta:{request_id}, error:{code,message}}
Cursor helpers: next/prev cursor propagation
Repository: translates API errors to domain failures

Widget (goldens at sm=375x812, md=834x1112, lg=1280x800)

Dashboard and new list/detail screens
States: loading skeleton, empty, error (with retry), loaded
Typography: Poppins/Inter applied
Truncation: titles 2 lines, body 3 lines
Ratio enforcement (4:1, 4:3, 1:1, 3:4)

Integration (`integration_test/`)

Auth: login or token injection
GET /api/v1/meta/config → ThemeData updated
One cursor list: fetch → next → prev
One POST: success + error (simulate 500/422)

CI example

flutter pub get
flutter analyze
flutter test --coverage
flutter test test/features/..._test.dart
flutter drive --driver=test_driver/integration_test.dart --target=integration_test/main_test.dart --dart-define=APP_BASE_URL=$APP_BASE_URL

Definition of Done (DoD) — App

BLoC everywhere for new features
API probes captured in Findings before Plan
Uses /api/v1 envelope + cursor correctly
Responsive at sm/md/lg per design system
en/ne localization present for new strings
Unit + widget + integration tests green
Plan and Implementation docs updated

Findings — YYYY-MM-DD HH:MM — (Flutter)

Summary

Requested change:

What exists now

Navigation/routes:
Screens/widgets:
BLoCs:
Repositories/models:
API client/interceptors:
Localization keys (en/ne status):
Theming (meta/config usage):
Tests (unit/widget/integration):

API Probe Results (raw snippets)

GET /api/v1/meta/config →
LIST (cursor) →
DETAIL →
POST success →
POST failure → <error.code, message>

Spec vs Current Gaps

<bullets mapped to /docs>

Proposed Architecture

BLoC: events → states diagram
Repository interface + DTOs
Envelope/cursor handling

UI Changes

Screens/widgets, loaders/empty/error, responsive adjustments (sm/md/lg)
Image ratios (4:1, 4:3, 1:1, 3:4)

Risks/Unknowns

Tokens needed

APP_BASE_URL (dev/stage)
Auth (login creds or staging Bearer token)
FCM config (if push)
Deep link scheme (if needed)

Plan — (Flutter)

Scope & AC

Modules/specs:
Acceptance criteria:

Routing

Named routes & deep links:

State & Data

BLoCs (events/states), Repositories, Models
Envelope + cursor helpers reuse

Networking

Endpoints (method/path), requests/responses, interceptors

Screens & Widgets

Files, loaders/empty/error, truncation, image ratios
Responsive behavior at md/lg

Localization

ARB keys to add (en/ne)

Theming

Apply /api/v1/meta/config → ThemeData

Notifications

Device token POST (if in scope)

Tests

Unit cases:
Widget goldens (sm/md/lg):
Integration scenarios:

Build & Config

dart-defines:
Feature flags:

Rollback & Out-of-Scope

Implementation — YYYY-MM-DD HH:MM — (Flutter)

Changes

Files added/modified (paths)
Routes changed
BLoCs/Repositories/Models added
Theme/meta-config updated
L10n keys added

Endpoints Used

METHOD /api/v1/… (notes)

Tests

Unit: pass count
Widget: pass count (goldens)
Integration: scenarios pass

Screenshots/Recording

Config

dart-defines used

Post-Deploy Checks

Token persistence, theme apply, locale switch, cursor lists

Follow-ups

fewaoms_saas_tenant_002

About

AGENTS.md

Workflow (strict)

1) READ (in this order)

2) PROBE APIs (must do before findings/plan)

3) FINDINGS (write)

4) PLAN (after owner approval)

5) IMPLEMENT

6) TEST (Expectations — no tests, no merge)

7) DOCUMENT

8) PR / REVIEW

Tokens & Secrets (ask at end of Findings)

Project Guardrails (BLoC + CLI)

Packages (recommended)

CLI scaffolding (write simple scripts under `/app/tool/cli`)

Testing Matrix (must)

Unit

Widget (goldens at sm=375x812, md=834x1112, lg=1280x800)

Integration (`integration_test/`)

Definition of Done (DoD) — App

Findings — YYYY-MM-DD HH:MM — (Flutter)

Plan — (Flutter)

Implementation — YYYY-MM-DD HH:MM — (Flutter)

Use it

Manifest

Reviews

About

AGENTS.md

Workflow (strict)

1) READ (in this order)

2) PROBE APIs (must do before findings/plan)

3) FINDINGS (write)

4) PLAN (after owner approval)

5) IMPLEMENT

6) TEST (Expectations — no tests, no merge)

7) DOCUMENT

8) PR / REVIEW

Tokens & Secrets (ask at end of Findings)

Project Guardrails (BLoC + CLI)

Packages (recommended)

CLI scaffolding (write simple scripts under /app/tool/cli)

Testing Matrix (must)

Unit

Widget (goldens at sm=375x812, md=834x1112, lg=1280x800)

Integration (integration_test/)

Definition of Done (DoD) — App

Findings — YYYY-MM-DD HH:MM — (Flutter)

Plan — (Flutter)

Implementation — YYYY-MM-DD HH:MM — (Flutter)

Use it

Manifest

Reviews

CLI scaffolding (write simple scripts under `/app/tool/cli`)

Integration (`integration_test/`)