backend-integration

What this skill does

# Backend Integration

Use this skill for the full backend-integration workflow. This skill is intentionally self-contained.

## Core Rules

- Follow this skill from top to bottom.
- Treat this as the canonical workflow for `Wire backend integration`.
- Do not improvise a new backend stack.
- Do not rely on unrelated skills for backend architecture, testing strategy, or migration planning unless higher-priority instructions explicitly require that.
- The one explicitly allowed companion skill for this workflow is `playwright-interactive-sandbox`, and only for baseline/final interactive QA passes.
- Keep existing product behavior working while changing the persistence and transport layer underneath it.
- Preserve the current implemented app behavior and scope. Do not add new product features, new domain workflows, or speculative capabilities.
- Do not do anything less than the current app already does.
- Do not do anything more than the current app already does, unless higher-priority instructions explicitly require it.
- Re-read this skill and the current `plan.md` on every compaction before continuing.

## Fixed Target Stack

Convert the app toward the Customware reference stack:

- React Router SPA
- Hono server
- tRPC transport/router
- Zod runtime contracts
- neverthrow `Result` / `ResultAsync`
- SQLite via `better-sqlite3`
- Drizzle ORM + migrations

The backend reference repo is:

- Canonical git remote: `[email protected]:customware-ai/template-be-setup.git`
- HTTPS fallback: `https://github.com/customware-ai/template-be-setup.git`

Use the same clone pattern/runtime approach already known to work for Customware repos in the execution environment.

## Minimum Package And Setup Delta From `client-only-spa`

When migrating from the standard `client-only-spa` starter toward the backend-enabled stack, treat the following as the minimum baseline delta that must be accounted for.

### Must-Add Runtime Packages

- `hono`
- `@hono/node-server`
- `@hono/trpc-server`
- `@trpc/server`
- `@trpc/client`
- `@trpc/react-query`
- `@tanstack/react-query`
- `better-sqlite3`
- `drizzle-orm`
- `dotenv`

### Must-Add Dev/Test/Tooling Packages

- `vitest`
- `jsdom`
- `@playwright/test`
- `@testing-library/dom`
- `@testing-library/jest-dom`
- `@testing-library/react`
- `@testing-library/user-event`
- `drizzle-kit`
- `tsx`
- `typescript`
- `@types/better-sqlite3`

### Must-Add Or Align Scripts

- `build:client`
- `build:server`
- `test`
- `e2e:install`
- `e2e`
- `db:generate`
- `db:migrate`

### Must-Add Or Align Files

- `.env.example`
- `drizzle.config.ts`
- `playwright.config.ts`
- `vitest.config.ts`
- `server/tsconfig.json`
- `server/index.ts`
- `server/start.ts`
- `server/utils/env.ts`
- `server/db/index.ts`
- `server/db/schemas.ts`
- `server/db/migrate.ts`
- `server/trpc/router.ts`
- `tests/e2e/database.ts`
- `tests/e2e/global-setup.ts`
- `tests/unit/setup.ts`
- `tests/unit/helpers.ts`

### Important Rule

- This list is the minimum baseline, not the full migration.
- If other packages, files, configs, or helpers are needed to complete the backend integration correctly, add them too.
- Do not treat this list as permission to skip unlisted required setup.
- Do not omit a listed item unless the migrated app has an explicit higher-priority reason not to use it.
- For backend/runtime/testing dependencies and setup, prefer the backend reference repo's versions and conventions.
- Use the same backend/runtime/testing package versions as the backend reference repo unless there is an explicit approved reason to differ.
- Do not install `latest`, `next`, floating ranges, or ad hoc newer versions for Playwright or any other backend/runtime/testing package during this task.
- When adding packages from the backend reference repo, copy the template's pinned version choice instead of guessing or upgrading.
- Do not churn unrelated frontend package versions unless the migration genuinely requires it.

## Required Step Order

1. Read project instructions first.
2. Read this skill fully.
3. Create `plan.md` in the project root using the exact section contract in this skill.
4. Clone or refresh the backend reference repo into a temporary location if needed.
5. Replace the current project `AGENTS.md` with the `AGENTS.md` from the backend reference repo.
6. Immediately re-read the newly replaced project `AGENTS.md` before continuing.
7. Use `playwright-interactive-sandbox` for a baseline interactive audit of the current app behavior and record the findings in `plan.md`.
8. Audit the current project and map it against the reference repo.
9. Replace the frontend-only runtime/build/startup flow with the backend reference repo's runtime/build/startup flow while keeping the top-level package commands `npm run build` and `npm run start`.
10. Adapt the backend stack and test setup using this skill's template map.
11. Migrate storage-backed flows to backend-backed flows and track every migration in `plan.md`.
12. Create or update automated tests using this skill's testing and verification rules.
13. Use `playwright-interactive-sandbox` again for final interactive verification of behavior parity after backend migration.
14. Run final verification.
15. Remove temporary assets and `plan.md` as the final successful step.

Do not skip a prerequisite step because the later action seems obvious.

## Scope Rule

The purpose of backend integration is:

- take the current front-end-only implementation
- make it backend and SQLite/Drizzle based
- keep the existing app behavior intact
- add backend-focused tests and end-to-end coverage

This task does not need domain knowledge files to decide scope.

- Do not read `DOMAIN.md` / `domain.md` to redefine the product.
- Use the current implemented app behavior as the source of truth for scope.
- Preserve what the app already does and make it persistent and tested.

## Required `AGENTS.md` Replacement

- Replacing the current project `AGENTS.md` with the `AGENTS.md` from the backend reference repo is a required step.
- Do not partially merge them.
- Do not keep the frontend-only `AGENTS.md` in place.
- The backend reference `AGENTS.md` becomes the new governing repo instructions for the migrated app.
- Perform this replacement early in the workflow so all later work follows the backend-capable instructions.
- Immediately re-read the replaced `AGENTS.md` before continuing any migration work.

## Required Runtime Script And Startup Replacement

- Replace the frontend-only runtime/build/start flow with the backend reference repo's flow.
- Keep the top-level package commands named `npm run build` and `npm run start`.
- What those commands do should follow the backend reference repo's behavior, not the old client-only starter behavior.
- Remove or adapt obsolete frontend-only startup entrypoints such as `start.js` or any old startup-script path once the backend server startup flow takes over.
- Do not keep conflicting old startup behavior alongside the new backend-capable startup path.

## Output Contract While Working

- `plan.md` must exist for the duration of the backend integration task.
- `plan.md` must use the exact top-level section headings defined in this skill.
- Every section must contain markdown checkboxes.
- Every migrated browser-storage path must be accounted for in the `Storage Migration Inventory` section.
- Every significant route/page/flow touched by backend integration must be accounted for in the `Coverage Mapping` section.

## Planning Rules

- `plan.md` is a working checklist, not a narrative document.
- Keep each checkbox concrete and verifiable.
- Update `plan.md` continuously as work progresses.
- If you discover a new required migration or test surface, add it to the checklist before implementing it.
- Optional sections from the template should be added only when the current app actually needs them.

## Playwright Interactive QA Rule

- Use `playwright-interactive-sandbox` in exactly two intentional passes unless a special failure re