agentic-team 0.0.0-stage → 6.2.0

package/template/skills/project-structure/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: project-structure
+description: "Where a new file goes — the three questions that decide it, and why third-party wrappers have a fixed home. Use whenever creating a module, component, hook or utility rather than editing an existing one."
+---
+
+# Skill: Project Structure
+
+## The fact everything else follows from
+
+**"Where does this go?" answered by judgement produces a different answer
+every time.**
+
+Nobody is wrong individually. One phase puts the Stripe call in the handler,
+the next puts it in `utils/`, a third writes a `PaymentService`. Six
+milestones later the same concern lives in four places, and no gate noticed —
+because none of it is a defect, it is drift.
+
+So the answer is a procedure, not a preference.
+
+## Three questions, in order
+
+Take the first one that is true.
+
+| Question | Where | What follows |
+|---|---|---|
+| **Does it call a third party's SDK or HTTP API?** | `src/integrations/<provider>/` | Coverage held at **100%** |
+| **Does more than one feature use it?** | `src/lib/` | Needs a doc comment with an example |
+| **Otherwise** | `src/features/<domain>/` | Nothing outside may import its internals |
+
+Feature-first, including on the backend. A layer-first tree — `controllers/`,
+`services/`, `models/` — spreads one change across four directories and gives
+you no place to draw a boundary: `services/` has no owner, so nothing stops
+one domain reaching into another. See
+`.claude/skills/architecture/SKILL.md` on what makes a boundary real.
+
+**Before creating anything, look in `src/lib/` and the feature you are in.**
+The duplicate that costs is the one written by someone who did not know the
+first existed.
+
+## Why integrations has a fixed home
+
+Two reasons, and neither of them is swappability.
+
+**The test suite needs something to hold.** The rule is that a function
+calling into a third-party library has a test, so that a dependency bump which
+changes behaviour turns the suite red — that is what makes a green Dependabot
+PR a merge signal. Called inline across a dozen handlers, there is no function
+to test and the bump goes green.
+
+**The policy is applied once.** Timeout, bounded retry, circuit breaker,
+mapping the provider's errors into ours, keeping the key out of the logs.
+Spread across a dozen call sites you will miss one, and the one you miss is
+the one that hangs.
+
+### It is a seam, not an abstraction
+
+| | Seam wrapper | Abstraction wrapper |
+|---|---|---|
+| Exists for | somewhere to test, one place for policy | pretending the vendor is interchangeable |
+| Shape | thin; this app's types, this app's needs | provider-neutral, lowest common denominator |
+| Justified by | the testing rule, today | a migration that may never happen |
+
+A seam wrapper is allowed to look obviously like the provider it wraps. It
+should. The abstraction version is what
+`.claude/rules/code-standards.orchestra.md` forbids — one implementation, and
+a guess about the future.
+
+**Migration is the secondary benefit, and it is version upgrades, not vendor
+swaps.** A major with a renamed method touches one file instead of twelve.
+That happens several times a year; a vendor swap mostly never does.
+
+### The 100% asks for exercise, not a test file
+
+An integration test that drives the wrapper through a faked HTTP boundary
+satisfies it completely. Do not add a unit test beside the wrapper to repeat
+what a route test already covers — that is writing a test to move a number,
+which the testing rule tells you to refuse rather than comply with.
+
+Fake the provider at the **network** boundary, never by mocking the wrapper.
+Mocking the wrapper means the wrapper is never tested, and the wrapper is the
+thing that breaks when the provider changes.
+
+## Components
+
+Two levels, not four. Atoms-elements-molecules-organisms sounds precise and
+is not: nobody places `FormField` the same way twice, and the folders drift
+into an argument.
+
+| Level | Contains | May import |
+|---|---|---|
+| **Primitives** — `src/design/` | Button, Input, Text. No business logic, no data fetching. | other primitives only |
+| **Compositions** — beside the feature that uses them | Anything that knows what the app does | primitives, and their own feature |
+
+The rule worth keeping from atomic design is the **import direction**: a
+primitive never imports a composition. That one is checkable by reading a
+diff. The taxonomy is not.
+
+A component used by a second feature moves up to shared — on the second use,
+not in anticipation of it.
+
+## Types live beside what they describe
+
+A global `types/` becomes a file everything imports, which is the opposite of
+a boundary. A type that describes a feature's data lives in that feature; a
+type crossing a boundary lives with the interface that defines it.
+
+## Signs the structure has stopped working
+
+- A change to one behaviour touches four directories.
+- Two features import each other.
+- `lib/` is the biggest directory in the app.
+- The same provider's SDK is imported in more than one place.
+- A file is named for a technical role — `helpers`, `managers`, `services` —
+  rather than for what it does.

package/template/skills/push-notifications/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: push-notifications
+description: "Delivering push to iOS and Android — permission timing, token lifecycle, payload choice, deep links, and why none of it can be tested in a JS runner. Use for any phase that sends, receives, or routes a notification."
+---
+
+# Skill: Push Notifications
+
+## The fact everything else follows from
+
+**Nothing in the JS test suite can tell you push works.**
+
+`jest-expo` runs components in Node against mocked native modules, so the
+permission call, the token callback, the background handler and the deep link
+are all mocked into success. The suite is green and the notification never
+arrives.
+
+Push needs a build with your own credentials, on a real device, with the app
+in each of three states — foreground, background, terminated. Anything less
+tests the mock. This is the same reason the device layer is not optional in
+`.claude/skills/mobile-testing/SKILL.md`, on Expo.
+
+Resolve the SDK's current API and constraints from its own docs at
+implementation time. This area changes across SDK releases, and a handler
+signature written from memory compiles and silently never fires.
+
+## Permission is a product decision, not a setup step
+
+The prompt can be shown **once**. A denial is close to permanent — the system
+stops presenting the dialog, and the only route back is Settings.
+
+| When you ask | Roughly what you get |
+|---|---|
+| On first launch, cold | 15–20% |
+| After onboarding | 40–50% |
+| At the moment the user turns on a feature that needs it | 70–80% |
+
+So: explain the value, or better, ask at the moment the user does something
+that obviously requires it. Never on launch.
+
+- After a denial, do not re-prompt. Offer a route to Settings instead.
+- iOS provisional authorisation delivers quietly with no prompt at all —
+  worth considering when the value is not yet obvious to the user.
+- Android 13+ needs a runtime permission of its own. Treat it as a real
+  prompt with the same timing rules, not a manifest entry.
+
+## The token is a lifecycle, not a value
+
+The single most common defect: a token cached once and never refreshed, so
+delivery quietly stops for users who reinstalled.
+
+1. **Take it from the callback**, every launch. Never from storage as the
+   source of truth.
+2. **Refresh replaces it.** The refresh callback is not optional — the token
+   changes on reinstall, restore, and at the platform's discretion.
+3. **Key it by device, and associate a user.** One user has several devices;
+   one device may see several users. A token with no user cannot be targeted;
+   a token with no device id produces duplicates.
+4. **Delete on rejection.** When the provider says the device is not
+   registered, that token is dead. Keeping it means a growing share of your
+   sends fail, and your delivery rate becomes a number nobody trusts.
+5. **Treat it as opaque.** No parsing, no format assumptions.
+
+A push token identifies a device belonging to a person. It never goes in a
+log line, an error report, or an analytics property — see
+`.claude/rules/security.orchestra.md`.
+
+## Payload: visible or data-only
+
+This is the choice that decides whether your handler runs at all.
+
+| You want | Payload | Because |
+|---|---|---|
+| The user to see something now | **Visible** | Delivery is prioritised and the system displays it |
+| To sync in the background | **Data-only** | A visible payload is handled by the system, not your code |
+| Your own notification UI | **Data-only** | You build and post it |
+
+Two constraints that bite:
+
+- **Silent delivery is best-effort.** The OS may delay or drop it — battery,
+  Doze, Low Power Mode. Never carry something time-critical this way.
+- **The background handler has seconds, not minutes.** Enqueue the work and
+  return. Doing the work inline gets the process killed mid-write.
+
+On Android, a notification channel must exist before anything appears at all,
+and a notification icon must be white-on-transparent — a coloured one renders
+as a white square, which reads as a bug in your app.
+
+## Foreground, background, terminated
+
+Three states, three code paths, and they are handled in different places.
+A notification that works in the foreground and does nothing from terminated
+is the normal outcome of testing only one.
+
+Deep linking is where this shows up first: opening from a terminated state
+means the route is resolved **before** your navigation tree exists. Buffer
+the target and apply it once navigation is ready, rather than dropping it.
+
+Every one of the three gets tested by hand on a device before the phase
+closes. There is no substitute.
+
+## The send side
+
+Sending is a third-party seam, so it has a test —
+`.claude/rules/testing-standards.orchestra.md`. Fake the provider **at the
+HTTP boundary**, never by mocking your own `sendPush()`, because the wrapper
+is exactly what breaks when the provider changes.
+
+Treat it like any other outbound call: timeout, bounded retry with jitter on
+transient failures only, and a reported failure rather than a swallowed one.
+See `.claude/skills/architecture/SKILL.md`.
+
+- **A send is not a delivery.** Accepted by the provider means queued. Record
+  the two separately or your funnel is fiction.
+- **Batch and rate-limit your own sends.** A fan-out that hits the provider
+  as fast as it can is throttled, and the throttling arrives as partial
+  failure.
+- **Never send in a loop over users inside a request handler.** Queue it.
+
+## Measuring it
+
+Push is a feature with a funnel, so it is instrumented like one —
+`.claude/rules/analytics-kpi.orchestra.md`:
+
+- permission asked, granted, denied
+- token registered, refreshed, rejected
+- sent, delivered, opened
+- and the **failure** at each step, with a reason code
+
+Without the failure events you will know engagement dropped and never why.
+No PII in any of those properties, and the token is never a property.
+
+## Anti-patterns
+
+- **Asking on first launch.** You spend the one prompt you get on a user who
+  does not yet know what the app does.
+- **Re-prompting after denial.** The system ignores it; the user does not.
+- **Caching the token long-term.** Delivery stops silently for reinstalls.
+- **A visible payload when you needed the background handler.** The system
+  displays it and your code never runs.
+- **Relying on silent push for anything time-critical.** Delivery is not
+  guaranteed and you will not be told.
+- **Heavy work in the background handler.** The process is killed partway.
+- **Skipping the notification channel.** Nothing appears at all on modern
+  Android, with no error anywhere.
+- **Shipping without testing the terminated state.** It is the state most
+  users are actually in.

package/template/skills/react-best-practices/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: react-best-practices
+description: "React and Next.js implementation patterns — data fetching, boundaries, imports, state. Use for any phase writing React components."
+---
+
+# Skill: React Best Practices
+
+## When to Use
+Phase involves React or Next.js frontend development.
+
+## Checklist
+- [ ] **No waterfall fetches:** use `Promise.all` for parallel data, `Suspense` boundaries for streaming
+- [ ] **Direct imports:** never import from barrel files (`index.ts`) — import from exact module path
+- [ ] **Server components by default:** only add `"use client"` when state/effects/browser APIs needed
+- [ ] **Lazy load heavy components:** `next/dynamic` or `React.lazy` for below-the-fold content
+- [ ] **Memoize expensive renders:** `React.memo` for components with stable props, `useMemo` for expensive computations
+- [ ] **Primitive dependencies in hooks:** avoid objects/arrays in `useEffect` deps — extract primitive values
+- [ ] **No duplicate serialization:** don't pass same data as both prop and context
+- [ ] **Parallel route fetching:** use `Promise.all` in `loader`/`getServerSideProps`, not sequential `await`
+- [ ] **SWR/React Query for client data:** deduplication, caching, revalidation built-in
+- [ ] **Passive event listeners:** `{ passive: true }` for scroll/touch handlers
+- [ ] **Hoist static JSX:** constant JSX outside component body to avoid re-creation on render
+- [ ] **Use `Map`/`Set` for lookups:** not `Array.find()` in render paths
+
+## Common Mistakes
+- Sequential `await` in data fetching → blocks waterfall, use `Promise.all`
+- Barrel file imports → prevents tree-shaking, entire module loaded
+- `"use client"` on everything → loses server component benefits (streaming, zero bundle)
+- Complex objects in `useEffect` dependencies → infinite re-render loop
+- Event listeners without cleanup → memory leak in `useEffect`
+- Fetching in `useEffect` without SWR/React Query → no dedup, no cache, race conditions

package/template/skills/realtime/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: realtime
+description: "Pushing updates to a connected client — choosing between polling, SSE and WebSocket, authenticating the connection, surviving reconnects, and what changes when there is more than one instance. Use for any phase adding live updates, presence, or a subscription."
+---
+
+# Skill: Realtime
+
+## The fact everything else follows from
+
+**A connection is state, and state is what makes a service hard to deploy.**
+
+A stateless service scales by adding an instance and deploys by replacing
+one. A connection breaks both: the client is pinned to an instance, a deploy
+drops every connection at once, and an event published on instance A never
+reaches a subscriber on instance B.
+
+None of that is a reason to avoid realtime. It is a reason to be sure you
+need it, and to decide the multi-instance answer **before** the second
+instance exists — retrofitting it is a rewrite.
+
+## Choose the cheapest thing that works
+
+Work down. Take the first row that is genuinely true.
+
+| If | Use | Why |
+|---|---|---|
+| Updates are seconds-stale-tolerant, or rare | **Polling** | No connection state, no deploy problem, works through every proxy |
+| Server → client only: feeds, progress, notifications, streamed output | **SSE** | Plain HTTP, reconnects and resumes by itself, no protocol to operate |
+| Genuinely bidirectional and low latency: collaboration, presence, games | **WebSocket** | Only case that pays for the state |
+
+Most "realtime" requirements are SSE requirements. A chat that only receives
+is server-to-client. Reaching for WebSocket first buys you connection
+management you did not need.
+
+**SSE's resume is the reason to prefer it.** The browser reconnects on its
+own and sends the last event id it saw; give every event an id and a client
+that missed a minute can be caught up. With WebSocket you write that
+yourself, and most implementations do not.
+
+## Authenticate the handshake
+
+The upgrade request is the only place authorisation happens. After it, you
+have a socket with no request cycle to check anything against.
+
+- Authenticate **during** the handshake, and reject before the upgrade
+  completes. Never accept first and check on the first message.
+- **The browser WebSocket API cannot set headers.** Pass a short-lived,
+  single-use ticket obtained over normal HTTP — never the session token in
+  the query string, which lands in every access log.
+- **A token that expires mid-connection matters.** Decide now: close and let
+  the client reconnect, or re-authenticate in-band. Both are fine. Neither
+  happening is a connection authorised by a credential that expired hours ago.
+- Authorise **per subscription**, not once at connect. Joining a room is an
+  authorisation decision, and it is the one most often forgotten.
+
+## Assume every connection dies
+
+Because they do — a tunnel closes, a phone changes network, a proxy times out
+an idle socket, or you deployed.
+
+- **Heartbeat both ways.** A TCP connection can be dead for minutes while
+  both sides believe it is open. Ping, expect a pong, close when it does not
+  arrive.
+- **The client reconnects with exponential backoff and jitter.** Without
+  jitter, a deploy disconnects everyone at once and they all return at once —
+  you knock over the instance that just came up.
+- **Reconnect is not resume.** State the recovery: replay from the last event
+  id, or refetch and replace. "The client will have missed some messages" is
+  a bug that reads as flakiness.
+- **Cap the retries, then say so.** A client that reconnects forever in the
+  background is a battery complaint. Surface a disconnected state and let the
+  user retry.
+
+## Bound everything
+
+An open socket is an invitation, and none of these have a safe default.
+
+- Maximum message size, enforced on receive.
+- Maximum messages per second, per connection — rate limiting at the socket,
+  not just at the HTTP edge.
+- Maximum connections per user, and per instance.
+- Maximum subscriptions per connection.
+- A send queue that **drops or disconnects** when the client stops reading,
+  rather than buffering until the process runs out of memory. This is the
+  failure that takes the service down, and it looks like a memory leak.
+
+Never do synchronous work per message on the event loop. One expensive
+handler stalls every other connection on that instance.
+
+## More than one instance
+
+The moment there are two, an event published on one has to reach subscribers
+on the other. Pick the mechanism deliberately:
+
+- **A pub/sub backplane** — every instance subscribes, every instance
+  forwards to its own connections. Simple, and the usual answer.
+- **A dedicated realtime service** — worth it when the connection count and
+  the request load have genuinely different shapes.
+
+Either way the backplane is now a dependency the service cannot serve
+without, so **it gets a readiness probe** — see
+`.claude/rules/observability.orchestra.md`. A service accepting connections
+it can never deliver to is worse than one refusing them.
+
+Sticky sessions are a workaround, not a design. They break on deploy, they
+unbalance load, and they hide the problem until the day you scale.
+
+## Deploys disconnect everybody
+
+This is normal and it is survivable, if it is designed:
+
+- Close connections **gracefully** on SIGTERM — send a close frame so clients
+  reconnect on purpose instead of timing out. The draining window exists for
+  this; see `.claude/skills/deployment/SKILL.md`.
+- Client backoff with jitter spreads the return.
+- The reconnect path is the same one used after a network drop, so it is
+  already tested.
+
+## Testing it
+
+- The **protocol** is a third-party seam: connect, authenticate, subscribe,
+  receive, reconnect — tested against a real server, not a mocked client.
+  `.claude/rules/testing-standards.orchestra.md`.
+- The **failure paths** are the point: rejected handshake, expired
+  credential, dropped connection mid-stream, a subscription the user is not
+  allowed to make.
+- **Never `sleep` and assert.** Wait for the event; a sleep is a flake with a
+  delay.
+- Instrument connect, disconnect with reason, reconnect, and messages
+  dropped. A realtime feature with no disconnect-reason metric cannot be
+  debugged from the outside.
+
+## Anti-patterns
+
+- **WebSocket where SSE would do.** You now operate a protocol for a feature
+  that only pushes.
+- **Authenticating after the upgrade.** The connection existed before anyone
+  checked.
+- **The session token in the query string.** It is in the access log of every
+  hop.
+- **No heartbeat.** Dead connections accumulate and are counted as users.
+- **Unbounded server-side buffering.** Reads as a memory leak, is actually a
+  slow client.
+- **Broadcasting to everyone and filtering on the client.** Every client
+  receives data it is not allowed to see; the filter is decoration.
+- **Assuming one instance.** Works perfectly until the day it matters.

package/template/skills/review/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: review
+description: "Reviewing a diff — as the reviewer role, or self-review before submitting. Use for any phase that reviews code rather than writing it."
+---
+
+# Skill: Review
+
+## Review what the gate cannot
+
+By the time a diff exists, a great deal has already been decided
+mechanically. Re-checking any of it spends the only thing a reader has that
+a script does not.
+
+**Already enforced. Do not spend attention here:**
+
+| Concern | Enforced by |
+|---|---|
+| Secrets, in the diff or anywhere in history | gitleaks |
+| String-built SQL | `scripts/policy-check.mjs` |
+| Empty or unreported `catch` | `scripts/policy-check.mjs` |
+| `getByTestId` in a test | `scripts/policy-check.mjs` |
+| A mocked database | `scripts/policy-check.mjs` |
+| Unused imports, dead code, `console.log` | biome |
+| Contrast, ARIA, missing labels | axe, in component tests and e2e |
+| Coverage of the lines this change touched | the diff gate |
+| Anything wrapping a dependency, at 100% | the seam gate |
+| Bundle growth | the bundle ratchet |
+| It compiles, bundles, boots | typecheck, build, e2e |
+| A known critical vulnerability | `yarn npm audit` in CI |
+
+If one of those is wrong the commit does not exist — the gate blocked it.
+Reporting it anyway tells the author you did not know that.
+
+## Yours alone
+
+Every item here needs a reader.
+
+- [ ] **It does what the phase asked.** Re-read the acceptance criteria
+      against the diff. Working code that solves a different problem is the
+      most expensive defect there is, and no gate detects it.
+- [ ] **The error handling is meaningful, not merely present.** A check
+      proves the `catch` is not empty. Only a reader can tell whether the
+      user gets a correct outcome or the failure was made invisible.
+- [ ] **The tests assert behaviour.** Coverage proves a line ran. Read the
+      assertions: a test that calls a function and checks nothing about what
+      it did passes every gate we have.
+- [ ] **Authorization is on the route**, not in a helper a future route can
+      forget to call. Named as unmechanizable in
+      `.claude/rules/security.orchestra.md` — so it is yours.
+- [ ] **No PII in logs, errors or analytics.** Redaction covers known keys;
+      a new field carrying a person's name is invisible to it.
+- [ ] **Query shape.** N+1, a missing index, a transaction that should exist
+      and does not.
+- [ ] **Readiness probes what it claims.** A new dependency without a probe
+      is a broken release that gets promoted.
+- [ ] **The abstraction earns itself.** Extracted after the second
+      duplication, not before. Was a simpler alternative available?
+- [ ] **Loading, empty and failure states exist** for anything a user waits
+      on.
+- [ ] **Anything that will be wrong later.** A pinned version with no reason
+      written beside it, a TODO with no owner, a workaround presented as a
+      fix.
+
+## Severity
+
+Defined once, in `.claude/agents/reviewer.md` under Severity — Blocking,
+Important, Suggestion, and which of them hold the pull request. Read it
+there; a second copy here drifted from it before.
+
+## Common mistakes
+
+- Reviewing the diff without opening the file. Context-dependent bugs live
+  in the lines that did not change.
+- Re-reporting something a gate already decided.
+- Nitpicking style a formatter owns.
+- A vague finding. Say what, where, and why.
+
+## Never ask for a test to be loosened
+
+Nor a threshold lowered, nor an ignore added. If a gate is wrong, that is a
+finding **about the gate** — a change to `.orchestra/stacks/`, not to the
+project under review.

package/template/skills/testing/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: testing
+description: "The working checklist for writing tests. Strategy lives in the testing-standards rule; each platform has its own skill. Use for any phase that writes or changes tests."
+---
+
+# Skill: Testing
+
+## When to Use
+Phase involves writing tests or improving coverage. The strategy lives in
+`.claude/rules/testing-standards.orchestra.md`; this is the working checklist.
+
+## Checklist
+- [ ] **Detect framework:** check package.json for vitest, jest, pytest — use the project's
+- [ ] **Read existing tests:** match style, naming, and file organisation
+- [ ] **Pick the right layer:** pure logic → unit. Anything touching I/O → integration through the real entry point
+- [ ] **Real database, never a mocked driver:** a fake repository returns what you told it to and cannot tell you the query is wrong
+- [ ] **Fake external services at the network boundary** (MSW or a stub server), never by mocking our own wrapper — the wrapper is the thing that breaks on a provider change
+- [ ] **Happy path, edge cases, and failures:** empty, null, boundary values, and the error branch with its reason
+- [ ] **Async behaviour:** resolve and reject, timeouts, ordering
+- [ ] **One assertion per concept:** the test name states the scenario
+- [ ] **Run them, then break the code and confirm they fail** — a test that has never failed has not been tested
+- [ ] **Isolation:** each test creates its own data; no shared seed fixture, no ordering dependency
+
+## Common Mistakes
+- Mocking the database → you test the mock. Use a real one in a container.
+- Mocking your own module instead of the network → the seam goes untested.
+- Snapshot tests as coverage → a snapshot passes while a handler stops firing.
+- Writing tests to move the coverage number → the gate has started doing harm; say so.
+- Testing implementation details → assert behaviour, not internal calls.
+- Imposing a new style on an existing project → match what is there.
+
+## Related
+
+Each platform has a different shape, and the differences are not stylistic —
+they come from what the test runner can and cannot see. Only the skills for
+this project's `project.platforms` are installed.
+
+- Web: `.claude/skills/web-testing/SKILL.md` — jsdom has no layout engine, so
+  component tests run in real Chromium.
+- Mobile: `.claude/skills/mobile-testing/SKILL.md` — jest does not run React
+  Native; the device layer is not optional.
+- iOS: `.claude/skills/ios-testing/SKILL.md` — a green unit suite does not
+  prove the app launches.
+- Android: `.claude/skills/android-testing/SKILL.md` — a passing debug build
+  proves little about the release build.

package/template/skills/web-quality-audit/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: web-quality-audit
+description: "End-to-end quality review of a web app — performance, accessibility, SEO, best practices. Use when auditing an existing app rather than building a feature."
+---
+
+# Skill: Web Quality Audit
+
+## When to Use
+Phase involves comprehensive quality review of a web application — performance, accessibility, SEO, and best practices.
+
+## Checklist
+
+### Performance
+- [ ] Core Web Vitals pass (LCP <= 2.5s, INP <= 200ms, CLS <= 0.1)
+- [ ] Images compressed and properly sized (WebP/AVIF preferred)
+- [ ] JavaScript minified and tree-shaken
+- [ ] Critical CSS inlined, non-critical deferred
+- [ ] Lazy loading for below-the-fold images and components
+- [ ] Caching headers set for static assets (Cache-Control, ETag)
+
+### Accessibility
+- [ ] WCAG 2.1 AA compliant (run axe or similar audit)
+- [ ] Keyboard navigation works for all interactive elements
+- [ ] Screen reader tested (proper headings, landmarks, alt text)
+- [ ] Color contrast ratios meet minimums
+
+### SEO
+- [ ] Unique `<title>` and `<meta name="description">` per page
+- [ ] `robots.txt` present and correct
+- [ ] Sitemap.xml generated and submitted
+- [ ] Structured data (JSON-LD) for key content types
+- [ ] Canonical URLs set for duplicate content
+- [ ] Open Graph and Twitter Card meta tags present
+
+### Best Practices
+- [ ] HTTPS everywhere, no mixed content
+- [ ] No vulnerable dependencies (`npm audit`)
+- [ ] Error pages (404, 500) are user-friendly
+- [ ] Console has no errors or warnings in production
+- [ ] No deprecated APIs used
+
+## Common Mistakes
+- Optimizing only one metric → all four areas matter for real quality
+- Ignoring SEO on SPAs → search engines need server-rendered content or prerendering
+- No structured data → misses rich snippets in search results
+- Performance testing only on fast networks → test on 3G/slow 4G too
+- Missing error pages → users see raw error messages