pfm-ocr/AGENTS.md

# Agent Instructions

This is the authoritative rules file for any AI coding agent (Claude Code, Cursor,
GitHub Copilot, Aider, etc.) working in a project that uses this starter kit. Agents
that don't read AGENTS.md natively should be pointed at it via their own config file
— see `docs/vibe-coding/` for per-tool instructions. `CLAUDE.md` imports this file.

## Scope: excludes `backend/`

This kit's automated behaviors — the `e`/`enhance` and `n`/`next` triggers, the §3
file-size threshold as an *enforcement action* (splitting a file because this kit
says so), and the §5 Demo/Live and §6 Cloud/Local switches — govern the **Flutter
app at the repo root** (`lib/`, `test/`, root-level config/docs) only.

**`backend/` is out of scope for this kit.** It is a separately governed subtree
with its own pre-existing rules files — `backend/CLAUDE.md` (project-specific
architecture/history/confidentiality notes) and `backend/AGENTS.md` (carried over
near-unchanged from `ai-ocr-pfm-2026`: uv conventions, issue-recording workflow,
karpathy coding guidelines) — that predate this kit's adoption and are tuned to
that codebase's own conventions. Do not let this kit's generic rules override or
be conflated with them:
- Don't run `e`/`enhance` against `backend/` modules, and don't let `n`/`next`
  auto-seed or pick up backend-section tasks, unless the user explicitly asks for
  a backend-scoped run for that specific invocation.
- Don't apply §3's 256-line split as a repo-wide mandate inside `backend/` — that
  subtree already documents its own pre-existing large files as accepted debt (see
  `backend/CLAUDE.md`) and has its own change conventions.
- §5 (Demo/Live) and §6 (Cloud/Local) describe app-level UX switches for the
  Flutter client; they are not a mandate to add mock-data layers or deployment
  switches inside the Next.js backend.
- If asked to work inside `backend/`, defer entirely to `backend/CLAUDE.md` and
  `backend/AGENTS.md` (and `backend/plans/next-enhancements.md` for feature-level
  status — `backend/next-implementation.md` was deleted 2026-07-08, its content
  folded into that plan) instead of this file.

See **Adaptation Notes** at the end of this file for how `plans/next-enhancements.md`
reconciles this after an earlier adoption pass mistakenly seeded backend sections.

## 0. Adopting Into an Existing Project

This kit auto-detects whether it's landing in a new or existing codebase — no
separate trigger is required. You can also type "i" / "init" at any time to force a
re-audit (e.g. after a large refactor or reorg).

**Auto-detection**: the first time "e"/"enhance" or "n"/"next" runs, if
`plans/next-enhancements.md` is still the empty seed template (or missing) AND the
repo already contains files/history beyond this kit's own files, treat it as an
existing project and run the audit below first. Skip it on a genuinely empty/new
project — there's nothing to audit.

**The audit** (owned by the Software Architect role, see `SKILLS.md`):
- **Don't overwrite silently.** If the repo already has its own README.md/AGENTS.md/
  CLAUDE.md, merge additively — append a clearly-marked section pointing at this
  kit's files rather than deleting existing project-specific instructions.
- **Discover reality before writing anything**:
  - Detect the tech stack and real build/test/lint commands (package.json, Makefile,
    pyproject.toml, etc.).
  - Map the actual existing folder/module structure — this becomes the section list
    `e`/`enhance` uses, replacing invented sections.
  - Scan for files already over the 256-line threshold (§3) and list them as
    **pre-existing debt**, not a blocker — the rule binds new/touched files going
    forward, it does not retroactively force-refactor untouched legacy code.
  - Check for existing equivalents of Demo/Live (§5) or Cloud/Local (§6) patterns;
    adapt to what's already there instead of introducing a redundant second switch.
- Seed `plans/next-enhancements.md` sections from the real discovered modules (not
  blank placeholders); optionally backfill `docs/feature-list.md` with a short
  "Existing Features (pre-kit)" summary so the log doesn't start misleadingly empty.
- Record any deviation from this kit's defaults (because the project already does it
  differently) as a short **Adaptation Notes** subsection appended to the end of this
  file — so future `e`/`n` runs see local reality, not just the template's
  assumptions.
- Once the audit (and any merge/adaptation) is done, `e`/`enhance` and `n`/`next`
  behave exactly as described below.

## 1. Trigger "e" or "enhance"

If the user types "e", "enhance", or requests an enhancement plan:
- Read `/plans/next-enhancements.md` to understand the current platform structure, history, and active tasks.
- Overwrite or update the active tasks list inside `/plans/next-enhancements.md`.
- The plan must cover each main section/module of the application.
- Inside the tasks list, define **exactly 3 new enhancements per section** with:
  1. A unique number (e.g., `1.1`, `1.2`, `1.3`).
  2. A clear, specific description of the functional change.
  3. A status (initially set to `[TODO]`).
- Present this plan to the user in your final summary response.

## 2. Trigger "n", "next", or "n{x}"

If the user types "n", "next", "n{x}" (where `{x}` is a positive integer), or requests execution of the next enhancement task(s):
- Read `/plans/next-enhancements.md` to check the status of tasks.
- If all tasks are `[DONE]` (or none are `[TODO]`), automatically run the **"e" / "enhance"** workflow first.
- Otherwise, select the most impactful `[TODO]` task(s) by strategic value, functional impact, or UX contribution — not just the first in order. If `{x}` is given, select the top `{x}` tasks and execute them sequentially.

### 2a. Clarify before building ("Grill Me" step)

Before implementing a task, check whether its scope or acceptance criteria are
genuinely ambiguous (multiple valid interpretations, unspecified UI/data behavior,
no clear "done" condition). If so:
- Ask clarifying questions **one at a time** until the task is unambiguous — use
  your tool's native mechanism (e.g. Claude Code's `AskUserQuestion`) where available,
  otherwise ask inline and wait for the answer before continuing.
- Record the resolved acceptance criteria as a short 1-3 line note next to the task
  entry in `/plans/next-enhancements.md` before writing any code.
- Skip this step entirely when the task is already unambiguous — don't grill the
  user on obvious work.

### 2b. TDD Workflow (Test First)

- **Write Tests First**: Before implementing the actual feature code for a task, write automated tests defining the expected behavior.
- **Iterate Until Green**: Run the tests to confirm they fail, then write the implementation until all tests pass perfectly.
- **Browser Testing**: If the enhancement involves web UI or visual components, use browser tools (e.g., Chrome) to test the app visually and functionally if necessary.

- Implement the selected task(s) fully in the codebase, applying the relevant role(s)
  from `SKILLS.md` (Architect, Backend, Frontend, QA, Hardware/Compatibility).
- Once complete:
  1. Update the task's status in `/plans/next-enhancements.md` to `[DONE]`.
  2. Document the new/updated feature in `/docs/feature-list.md` under the right section heading.
  3. **Create an Iteration Log**: Perform a code review and audit of the tasks just completed. Document this audit in `/docs/iteration-log.md` (or append to it) to ensure all functions work perfectly.
- **Verify build integrity** — this is not just "it compiles and runs":
  - QA pass: exercise the golden path and edge cases; run/extend automated tests.
  - Hardware/Compatibility pass: check cross-platform, cross-browser, and resource
    (memory/CPU) assumptions per `SKILLS.md`.
- In your final response, state which task(s) were completed and the exact menu/navigation path to see the new feature.

## 3. File Size, Refactoring & SOLID Rules

- **SOLID Principles**: Always design, implement, and refactor code adhering to SOLID programming principles (Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion). This ensures code is modular, testable, and maintainable.
- **256-line threshold**: any code/script file — new, modified, or pre-existing —
  that exceeds 256 lines of code must be split into smaller, modular, logical files.
  This is a repo-wide rule, not just for new work; if you touch a file over the
  threshold, split it as part of that change.
- **Why**: an agent reading a file spends its context budget parsing it before it can
  reason about the task. Small, single-purpose files keep that cost low and keep the
  agent's understanding accurate (see the "smart zone / dumb zone" problem — models
  reason worse as context fills up).
- This applies to AGENTS.md, CLAUDE.md, and SKILLS.md too: keep each under ~250 lines.
  Push detail into linked docs (`docs/`) rather than growing the root files.

## 4. Roles

Every implementation task should be viewed through the lens of the relevant role(s)
defined in `SKILLS.md`: Software Architect, Backend Engineer, Frontend Engineer,
QA/Test Engineer, and Hardware & Performance Compatibility Reviewer. A single agent
plays all roles in sequence unless the harness supports spawning role-specific
subagents (see `CLAUDE.md`).

## 5. Mockup Data & Demo/Live Mode

- Store all mock/sample data in `/data/mockup/` — keep it separate from UI components and styling.
- Provide a mock API layer that reads from `/data/mockup/` and mirrors the real backend contract.
- Add a switcher control (icon) in the UI to toggle **Demo** (mock API + mock data) and **Live** (real API + real data).

## 6. Cloud vs Local (On-Premise)

- Provide a setting to choose **Cloud** or **Local (on-premise)** deployment.
- **Cloud**: use remote/cloud-hosted API endpoints and services.
- **Local**: use on-premise/self-hosted API endpoints and services.
- Persist the selection and route all backend/service calls to the chosen environment.

## 7. Ad-hoc Feature Requests

For direct feature requests not using "e"/"n", implement the feature and document it in `/docs/feature-list.md`.

## Adaptation Notes (this project)

Recorded 2026-07-08, from adopting this kit into the existing `app-pfm-ocr-v2` repo.

- **Tech stack**: Flutter mobile app at the repo root (`lib/`) is the field client;
  `backend/` runs a Next.js API gateway + Python PaddleOCR/vLLM OCR pipeline +
  Postgres. See root `CLAUDE.md` and `backend/CLAUDE.md` for full architecture.
- **Real commands**: `flutter test`, `flutter analyze lib`, `flutter build apk --release`
  (Flutter, repo root); `npm run dev`/`build`/`lint` inside `backend/pfm-web-app`
  (Next.js) — see `backend/CLAUDE.md` for the OCR accuracy regression harness and the
  uv/vLLM Python service commands. There is no single unified test runner across both
  halves; Flutter and backend are tested independently.
- **Real module boundaries** (seeded into `plans/next-enhancements.md`): Flutter —
  Auth & Splash, Camera Capture & Geotagging, Pending Documents Queue, Document
  Editor & PDF Receipt; Backend — Next.js API Gateway, OCR Pipeline & Accuracy,
  Postgres Data Layer, DevOps/Docker & Dev Tunnel.
- **Scope correction (2026-07-08, later same day)**: an early `e`/`enhance` run
  seeded and executed against the four Backend sections above (5-8) before the
  **Scope: excludes `backend/`** rule at the top of this file was written. Those
  sections were first frozen as archival, then removed outright from
  `plans/next-enhancements.md` (2026-07-08) once `backend/` got its own independent
  kit copy — the already-shipped 7.1 DB-transaction fix stays recorded in
  `docs/feature-list.md`, but the task itself no longer has an entry in this file's
  plan. `plans/next-enhancements.md` now tracks only the Flutter sections (1-4).
  Backend enhancement tracking lives entirely in `backend/`'s own copy of this kit
  (`backend/plans/next-enhancements.md`, driven by `backend/AGENTS.md` Part B).
- **Pre-existing files over the 256-line threshold** (§3 debt, not a blocker — split
  only if/when touched going forward), **Flutter only** now that `backend/` is out of
  scope for this kit (see §Scope above; backend's own debt list, re-verified
  2026-07-08, lives in `backend/AGENTS.md`'s Adaptation Notes instead):
  `lib/features/camera/image_preview_screen.dart` (380), `lib/features/camera/camera_screen.dart`
  (376). (`editor_screen.dart` was split 2026-07-10 when task 6.3 touched it —
  see root `plans/next-enhancements.md` §6.3 and `docs/iteration-log.md`;
  `documents_screen.dart` and `pending_documents_provider.dart` were already
  split down by earlier iterations and are no longer over threshold — this
  line was stale.)
- **No Demo/Live or Cloud/Local switch exists yet** (§5, §6). The closest existing
  analogue is `AppConfig.initializeApiBaseUrl()` in `lib/config/app_config.dart`,
  which dynamically resolves a *real* backend endpoint (ngrok tunnel, falling back to
  a LAN IP) — it always talks to the live backend with real data, never mock data, so
  it is not a Demo/Live switch. Building an actual mock-data Demo mode and a
  Cloud/Local deployment switch remain open `n`/`next` work, not something this
  adoption pass implemented.
- **Naming collision to watch for**: `docker-compose.demo.yml` at the repo root
  already uses "demo" for an unrelated concept — a **production-mode** Compose
  override (`npm start` instead of `npm run dev`), not a mock-data mode. Don't
  conflate it with §5's Demo/Live data switch when that feature is eventually built.
- **Pre-existing, unrelated governance files left as-is** (not part of this kit, not
  touched by this adoption):
  - `.agents/AGENTS.md` — a short set of OCR post-processing/parsing rules (table
    column-shift correction, date normalization). Different purpose and path from
    this kit's root `AGENTS.md`; both coexist.
  - `plans/next-enhancement-plan.md` (singular) — a pre-existing, fully `[DONE]` QA
    verification checklist auto-managed by "QE guidelines," unrelated to the `e`/`n`
    workflow's `plans/next-enhancements.md` (plural, added by this kit). Kept side by
    side, not merged or migrated.
- **CLAUDE.md**: the repo already had a substantial project-specific root
  `CLAUDE.md`. Per this section's "merge additively" rule, this kit's import and
  Claude-specific notes were appended as a new, clearly-marked section rather than
  replacing the file.