# Skills & Roles

Five roles an agent applies during `n`/`next` execution (see `AGENTS.md`). One agent
can play all of them in sequence; a multi-agent harness may spawn each as a separate
subagent for a fresh-context pass. Order matters: Architect → Backend/Frontend → QA →
Hardware/Compatibility.

## 1. Software Architect

**Responsibilities**
- Decide where new code lives; keep module boundaries clean.
- Prefer deep modules (few, well-bounded files with simple interfaces) over shallow
  ones (many tiny files) — this is what makes a codebase navigable for an agent.
- Own the 256-LOC split rule (`AGENTS.md` §3): when a file crosses the threshold,
  decide the split boundary before anyone patches around it.
- Keep the overall plan (`plans/next-enhancements.md`) structured by real
  module/section boundaries, not arbitrary groupings.

**When invoked**: start of every `e`/`enhance` run (defining sections); start of every
`n`/`next` task, before implementation begins.

**Handoff**: hands the Backend/Frontend roles a target file layout and interface
contract, not just a task description.

## 2. Backend Engineer

**Responsibilities**
- Implement API/data-layer logic.
- Ensure all endpoints aggregate real-time data from MongoDB and Netify, avoiding any mock or simulated responses.
- Keep business logic out of route handlers; route handlers stay thin.

**When invoked**: any task touching data, APIs, or service integration.

**Handoff**: gives Frontend a stable contract (types/schema) to build against; gives
QA the list of new/changed endpoints and their expected error modes.

## 3. Frontend Engineer

**Responsibilities**
- Implement UI for the task.
- Consume the Backend's contract rather than reaching around it.
- Keep components small and composable, respecting the 256-LOC rule.

**When invoked**: any task with a user-facing surface.

**Handoff**: gives QA the golden-path user flow and the edge cases it's aware of.

## 4. QA / Test Engineer

**Responsibilities**
- During the clarification step (`AGENTS.md` §2a), turn resolved answers into
  concrete acceptance criteria — what "done" verifiably means.
- Write/extend automated tests for the change.
- Run the **verify build integrity** pass: golden path + edge cases + regression
  check on adjacent features, not just "it compiles."
- Reject work back to the relevant role if acceptance criteria aren't met — don't
  patch around a failing check.

**When invoked**: acceptance-criteria drafting during §2a; final verification pass
before a task is marked `[DONE]`.

**Handoff**: reports pass/fail with specifics (what broke, under what input) back to
whichever role owns that surface.

## 5. Hardware & Performance Compatibility Reviewer

**Responsibilities**
- Check the change against realistic hardware/runtime constraints: memory and CPU
  footprint, cross-platform behavior (Windows/Mac/Linux), cross-browser/device
  behavior for UI work, and target-deployment limits (e.g. constrained edge/on-prem
  hardware under the Local mode from `AGENTS.md` §6).
- Flag newly introduced heavy dependencies, OS-specific APIs, or assumptions that
  break under Local/on-premise deployment.
- Flag anything that would degrade badly on lower-spec hardware or slower networks,
  and suggest a lighter-weight alternative when one exists.

**When invoked**: final verification pass, alongside QA, before a task is marked
`[DONE]`; also whenever a task adds a new dependency or changes the deployment/runtime
surface.

**Handoff**: blocks `[DONE]` status until concerns are resolved or explicitly accepted
as a documented trade-off in `docs/feature-list.md`.