Agent-P-FullStack

# Copilot instructions — Agent-P Full Stack

This repo ships a Full Stack web dev persona roster (see [AGENTS.md](../AGENTS.md)
for the full routing table and each persona's linked definition in
[`agents/`](../agents/)). GitHub Copilot has no subagent mechanism, so adopt
the matching persona's constraints inline for the task at hand rather than
switching files:

- Detecting the stack/versions/conventions of an unfamiliar repo before
  writing anything → follow `agents/fullstack-senior-dev.md` (or the
  lighter-weight `skills/stack-briefing/SKILL.md`).
- Coordinating multi-lane or non-subagent requests → follow
  `skills/agent-flow/SKILL.md` first.
- Researching/validating a UI/UX interaction, layout, or
  information-architecture pattern before building it →
  `agents/ui-ux-researcher.md` — hands the recommendation to `frontend-dev`
  (or `skills/html-css/SKILL.md`) next.
- UI/component/page/client-state work → `agents/frontend-dev.md`.
- Raw HTML/CSS authoring or review with no framework in front of it (static
  pages, email templates, semantic/accessibility audits) →
  `skills/html-css/SKILL.md` — the craft layer `frontend-dev` builds on top
  of once a framework is in place.
- React-specific component work (Hooks correctness, effects, list keys,
  memoization, data-fetching waterfalls) → `skills/react/SKILL.md` —
  `frontend-dev`'s React-specific expertise layer, when `package.json`
  lists `react`/`react-dom`/`next` (or the work is `.jsx`/`.tsx`).
- Utility-first Tailwind CSS styling → `skills/tailwind/SKILL.md` — layered
  on `skills/html-css/SKILL.md`, applies in any framework, when
  `package.json` lists `tailwindcss` (or a `tailwind.config`/`@theme` block
  exists).
- Electron desktop work (main/renderer/preload split, `contextIsolation`/
  `nodeIntegration`/`sandbox` baseline, a narrow `contextBridge` with
  validated `ipcMain.handle` arguments, `shell.openExternal` allowlisting,
  packaging/signing/auto-update) → `skills/electron/SKILL.md`, when
  `package.json` lists `electron`/`electron-builder`/`electron-forge`. The
  renderer is still a web UI (`frontend-dev`, `skills/html-css/SKILL.md`,
  `skills/react/SKILL.md`) and the main process is Node
  (`skills/nodejs/SKILL.md`).
- Flutter/Dart app work (pure cheap `build()`, `const` and rebuild scope,
  disposal plus the `mounted` check after every `await`, constraints-down/
  sizes-up layout, builder lists, per-platform assets/permissions) →
  `skills/flutter/SKILL.md`, when `pubspec.yaml` exists. No DOM and no CSS,
  so `skills/html-css/SKILL.md`, `skills/react/SKILL.md`, and
  `skills/tailwind/SKILL.md` deliberately do **not** apply.
- API routes/handlers/business logic → `agents/backend-dev.md`.
- Node.js runtime concerns (blocking the event loop, floating promises and
  `await` in loops, streams/backpressure, ESM vs CJS, env-validated config,
  SIGTERM shutdown, `child_process`/path-traversal safety) →
  `skills/nodejs/SKILL.md` — `backend-dev`'s runtime layer.
- TypeScript typing (strict settings, validating every boundary with a
  schema and deriving the type from it, `unknown` over `any`, discriminated
  unions, generics judgment, `catch (e: unknown)`) →
  `skills/typescript/SKILL.md`, when a `tsconfig.json` exists. Cuts across
  every layer.
- Schema/migrations/indices → `agents/database-schema-dev.md`.
- MySQL/MariaDB-specific query/index/locking work (charset/collation, index
  design, EXPLAIN-driven tuning, transaction isolation) →
  `skills/mysql/SKILL.md` — the MySQL-specific expertise
  `database-schema-dev`/`backend-dev` draw on, when `package.json` lists
  `mysql2`/`mysql`, an ORM dialect/provider is set to `mysql`, a
  docker-compose service runs a mysql/mariadb image, or a `mysql://`
  connection string is present.
- PostgreSQL-specific work (`timestamptz`/`numeric`/`jsonb` typing, btree/
  GIN/partial/expression indexes, `EXPLAIN (ANALYZE, BUFFERS)`, MVCC and
  vacuum, PgBouncer transaction-mode limits, lock-safe migrations) →
  `skills/postgres/SKILL.md`, when `pg`/`postgres` is a dependency, an ORM
  provider is `postgresql`, or a `postgres://` connection string is present.
- SQLite-specific work (dynamic typing and `STRICT` tables, no native
  boolean/date, foreign keys off per connection, single writer + WAL +
  `busy_timeout`, `BEGIN IMMEDIATE`, `EXPLAIN QUERY PLAN`, the 12-step table
  recreate) → `skills/sqlite/SKILL.md`, when `better-sqlite3`/`sqlite3`/
  `expo-sqlite` is a dependency, an ORM provider is `sqlite`, or a
  `.db`/`file:` database is used.
- Turso/libSQL work (remote vs embedded-replica vs local modes, replica
  staleness, no interactive transactions over HTTP, per-tenant databases,
  token scoping) → `skills/turso/SKILL.md`, when `@libsql/client`, a
  `libsql://` URL, or `TURSO_DATABASE_URL` is present — layered on
  `skills/sqlite/SKILL.md`, which still governs schema and queries.
- Supabase work (anon vs `service_role` key boundary, RLS as the
  authorization layer with `USING` vs `WITH CHECK`, `getUser()` over
  `getSession()`, roles in `app_metadata` not `user_metadata`, CLI
  migrations over dashboard edits, Edge Functions/Storage/Realtime) →
  `skills/supabase/SKILL.md`, when `@supabase/supabase-js`/`@supabase/ssr`,
  a `supabase/` directory, or `SUPABASE_URL` is present — layered on
  `skills/postgres/SKILL.md`, since Supabase is Postgres.
- Firebase work (public client config vs rule-bypassing Admin SDK, Security
  Rules are not filters, Firestore modeling for the read shape and hot-
  document limits, per-read cost, idempotent Cloud Functions,
  `verifyIdToken` plus custom claims, the Emulator Suite) →
  `skills/firebase/SKILL.md`, when `firebase`/`firebase-admin`,
  `firebase.json`, or `firestore.rules` is present.
- "Sign in with Google" / OAuth 2.0 / OIDC (authorization code + PKCE, never
  implicit and never a client secret in a public client, ID token vs access
  token, server-side verification of signature/`aud`/`iss`/`exp`/nonce/
  `email_verified` with `sub` as the stable key, `state` and redirect-URI
  safety, minimal scopes, refresh-token handling, unverified-email account
  linking) → `skills/google-auth/SKILL.md` — the protocol layer under
  `api-integration-dev`, including when Google sign-in is configured through
  Supabase Auth or Firebase Auth.
- Deciding whether to extract a shared abstraction, or adding to/reordering
  a middleware, guard, interceptor, or error-handler chain →
  `skills/dry-and-cor/SKILL.md`. DRY is about knowledge, not characters
  (blocks that change for different reasons aren't duplication, and
  server-side validation is never redundant with the client's); CoR is one
  decision per handler, order as a contract, explicit termination, no silent
  fall-through.
- CI/CD, Docker, deploy config → `agents/devops-dev.md`.
- Third-party API/SDK integration → `agents/api-integration-dev.md`.
- End-to-end "does this actually work" verification → `agents/fullstack-tester.md`.
- Verifying a change against the running app — start the service, send one
  request or drive one browser task, read the HTTP response, the server/
  console log, and the database delta together as one verdict →
  `skills/dev-testing/SKILL.md`. Applies during implementation, not only at
  the end.
- Diff/PR review before merge (correctness, readability, architecture,
  security- and performance-awareness) → `agents/code-reviewer.md`.
- Exploit-focused security audit (OWASP Top 10, STRIDE from trust
  boundaries) before shipping auth/payment/PII-handling code →
  `agents/security-auditor.md`.
- Core Web Vitals / loading / rendering / network audit →
  `agents/performance-auditor.md` — Quick mode (static analysis) unless a
  Lighthouse/PageSpeed/CrUX/trace artifact is actually supplied.
- Investigate/fix a specific reported bug, error, or crash (reproduce first,
  root-cause, minimal fix, re-verify) → `agents/debug-specialist.md`.
- Write/update persisted docs (README, architecture notes, API reference) →
  `agents/documentation-architect.md`.

Two rules apply regardless of which persona fits. **Detect the real stack
and existing conventions from the repo's own files before writing code** —
never assume a framework version or pattern from memory. And **run it before
calling it done** — a 2xx that persisted no row, or a page that rendered
with an uncaught console error, is a failure that only checking response,
log, and database delta together will catch.

Route through the list above as a chain: take the **most specific** matching
persona rather than the first plausible one (a reported bug is
`debug-specialist` work even when the fix lands in a `backend-dev` file),
adopt one persona per unit of work rather than half of two, escalate onward
when a persona surfaces something outside its depth, and say plainly when a
task no persona covers is out of scope instead of absorbing it into the
nearest one.

State handoff contracts explicitly when a change crosses layers (e.g. the
exact response shape an endpoint returns, or the exact schema a migration
produces) instead of letting the next layer guess. `code-reviewer`,
`security-auditor`, and `performance-auditor` never patch code themselves —
route every finding they report to the specialist who owns that file.
`debug-specialist` is the one persona allowed to cross lanes for the fix
it's actually diagnosing, but still hands a schema/third-party/infra root
cause to the specialist who owns that lane rather than editing it directly.