chore: add AGENTS.md with engineer task handoff instructions

Engineers were not properly picking up and completing delegated tasks.
This adds structured instructions for Paperclip task lifecycle,
git workflow, and handoff expectations.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

AGENTS.md

@@ -0,0 +1,43 @@
+# GroomBook — Agent Instructions
+
+## Repo Layout
+
+- `apps/api` — NestJS backend API
+- `apps/web` — React frontend (Vite)
+- `apps/e2e` — Playwright E2E tests
+- `apps/groombook` — CLI / meta package
+- `packages/` — shared libraries
+- `charts/` — Helm charts
+- `infra/` — infrastructure config
+
+## Development
+
+- Package manager: `pnpm` (workspace monorepo)
+- Run E2E tests: `pnpm --filter @groombook/e2e test`
+- Run API: `pnpm --filter @groombook/api dev`
+- Run web: `pnpm --filter @groombook/web dev`
+
+## Git Workflow
+
+- Branch from `main` using the pattern `fix/<issue-id>-<short-desc>` or `feat/<issue-id>-<short-desc>`
+- Push to origin and open a PR against `main`
+- If the issue specifies an existing PR/branch, push to that branch instead of creating a new one
+- Commit messages: short imperative summary, reference the issue ID
+
+## Task Handoff (Paperclip)
+
+When you receive an assigned task from Paperclip:
+
+1. **Checkout the task** immediately using `POST /api/issues/{issueId}/checkout`
+2. **Read the full issue description** and any comments for context
+3. **Do the work** — implement the fix/feature as described
+4. **Test your changes** — run relevant tests, lint, type-check
+5. **Commit and push** your changes to the appropriate branch
+6. **Update the task** with status `in_review` and a comment summarizing what you did, including the commit SHA and PR link
+7. **Never leave a task in `in_progress` without posting a comment** explaining current state before exiting your heartbeat
+
+If you cannot complete the work (missing info, blocked by another task, environment issue):
+- Set the task to `blocked` with a comment explaining what's blocking you
+- Tag your manager in the comment if escalation is needed
+
+Do NOT silently drop tasks. Every assigned task must get a status update and comment before your heartbeat ends.

apps/e2e/tests/navigation.spec.ts

@@ -44,10 +44,7 @@ test.beforeEach(async ({ page }) => {
         json: { newClients: [], activeInPeriodCount: 0, churnRisk: [], churnRiskTotal: 0 },
       });
     }
-    if (url.includes("/api/invoices")) {
-      return route.fulfill({ json: { data: [], total: 0 } });
-    }
-    // Appointments, clients, services, staff, book, etc.
+    // Appointments, clients, services, staff, invoices, book, etc.
     return route.fulfill({ json: [] });
   });
 });
@@ -85,7 +82,6 @@ test("admin staff page loads", async ({ page }) => {
 
 test("admin invoices page loads", async ({ page }) => {
   await page.goto("/admin/invoices");
-  await page.waitForLoadState("domcontentloaded");
   await expect(page.getByText("GroomBook")).toBeVisible();
   await expect(page.getByRole("link", { name: "Invoices" })).toBeVisible();
 });