customerhub/AGENTS.md

AGENTS.md

Agent workflow and repo conventions. Role definitions live in SKILLS.md.

1. Workflow phases

Every n/next task runs through these phases in order:

1. Architect — define file layout and interface contracts before implementation starts.
2. Backend — implement API/data-layer logic; produce a stable contract for Frontend.
3. Frontend — implement UI against that contract.
4. QA — verify acceptance criteria, golden path, edge cases, and regression.
5. Hardware/Compatibility — check memory/CPU, cross-platform, and deployment constraints.

Each role hands off to the next. QA and H/W review can block [DONE] status.

2. Clarification step (§2a)

Before architecture begins, resolve ambiguity. Turn answers into concrete, verifiable acceptance criteria — what "done" means in terms of behavior and tests. QA extends these into the final checklist.

3. 256-LOC split rule (§3)

When a file exceeds 256 lines, the Architect decides the split boundary before anyone patches around it. No workaround commits on files that have already crossed the threshold.

4. Deep modules, thin handlers

• Prefer deep modules (few files with well-bounded, simple interfaces) over shallow ones (many tiny files).
• Keep business logic out of route handlers. Route handlers stay thin.

5. Demo/Live switch (§5)

The app supports a Demo (mock) mode and a Live mode. Both must resolve through the same contract — swapping the setting must never change calling code. The Backend wires this routing; Frontend provides the toggle control.

6. Cloud/Local switch (§6)

The app supports Cloud-hosted and Local/on-premise endpoints. Same rule as §5: both resolve through the same contract. Swapping the setting must never change calling code.

7. Key documents

• plans/next-enhancements.md — overall plan, structured by module/section boundaries.
• docs/feature-list.md — accepted trade-offs and feature documentation.

8. Commands

Command	Description
npm run dev	Vite dev server (http://localhost:5173)
npm run build	tsc -b && vite build
npm run lint	oxlint
npm run preview	Preview production build

Dev server starts on port 5173 by default (Vite convention). Build output goes to dist/. QA must verify build + lint before marking [DONE].