--- name: audit-realworld description: > Read-only conformance audit of a full-stack app against RealWorld ("Conduit"): API spec, shared E2E suite, closest-stack reference. Use when "audit against RealWorld", "Conduit conformance", or "is my full-stack app complete?". license: MIT effort: high --- # audit-realworld — Full-Stack Gap Audit vs the RealWorld Reference **Degree of freedom: MIXED** — Mode, parity, and routing `[HIGH freedom]`; Phase 4 contract-suite run `[LOW freedom — run exactly]` when a server or suite exists. Read-only. Findings and a prioritized gap report only — no code changes. Remediation goes to the skill named per finding. RealWorld ("Conduit") is an objectively testable full-stack benchmark: formal API spec, shared E2E suite, shared CSS theme, hosted API at `api.realworld.show`. > **The RealWorld API spec and its E2E suite are the source of truth — not any > single community implementation.** Reference repos vary; the spec and the > passing suite do not. > **RealWorld is a demo spec, not a production bar.** It omits rate limiting, > observability, caching, CI/CD, secrets, and deployment. Report *feature/ > pattern parity*, then delegate hardening to `audit-security`, > `plan-security-audit`, `plan-perf-audit`, `plan-rls-audit`, and > `full-stack-ship-discipline`. ## How to reason — Observe → Interpret → Classify → Severity 1. **Observe** — quote the spec contract (or pattern) and the repo's `file:line` (or suite result) 2. **Interpret** — does this layer implement the contract, or only the UI/route? 3. **Classify** — Implemented / Partial / Missing / Diverges — or Bow-out if the repo is not a web CRUD+auth app 4. **Severity** — core Conduit / authz / list-contract gaps = High; production-omitted concerns are routed, not scored as RealWorld misses ## Worked example > **Observe:** Conformance mode. `GET /api/articles` returns `{ articles }` > with no `articlesCount` and no `limit`/`offset` (`app/api/articles/route.ts`). > Bruno list request fails the count assertion. Auth header is `Token `. > **Interpret:** the list contract is partial; clients cannot paginate. Auth > scheme matches the spec. > **Classify:** Partial (pagination / `articlesCount`); auth Implemented. > **Severity:** High — feed is a core Conduit surface. > **Finding:** Article list | no pagination / articlesCount | High | complete-everything --- ## Phase 0 — Detect the stack and gate applicability [HIGH freedom] Read the dependency manifest and source before comparing anything (reuse the `audit-fe-api` detection approach). ### 0a. Classify the stack - **Frontend:** framework (React/Next/Vue/Nuxt/Svelte/Angular/Solid), router, state/data layer (TanStack Query, SWR, RTK, Pinia), HTTP client. - **Backend:** framework (Express/Hono/Fastify/Nitro/NestJS/Django/Rails/Go/ Laravel/Spring), routing style, auth mechanism. - **Data layer:** database + ORM/query builder (Prisma/Drizzle/TypeORM/Sequelize/ SQLAlchemy/ActiveRecord/Supabase), migration tool. - **Tests:** unit runner, and any API/E2E harness (Bruno, Hurl, Postman/Newman, Playwright, Cypress). ### 0b. Applicability gate Decide the mode — state which one and why, out loud: | Condition | Mode | |---|---| | Repo is a RealWorld/Conduit build (articles, profiles, favorites/follow, tags, JWT `Token` scheme) | **Conformance** | | Web full-stack CRUD app with auth + owned resources, but a different domain | **Benchmark** | | Not a web app, no HTTP API, no auth/resources (CLI, library, static site, pure ML) | **Bow out** | **If you bow out, say so plainly** and recommend the fitting skills instead (`audit-security`, `audit-performance`, `plan-perf-audit`, `audit-code-quality`, `audit-fe-api`). Do not force a RealWorld comparison onto a repo it does not fit. ### 0c. Record the discovery ``` STACK: FE=<...> · BE=<...> · DB/ORM=<...> · tests=<...> MODE: Conformance | Benchmark | Bow-out (reason) RealWorld reference chosen: (spec-compliant? maintained?) ``` --- ## Phase 1 — Pull the reference (current) [HIGH freedom] ### 1a. Spec + test suite (source of truth) - API spec and shared E2E suite live in the `realworld-apps/realworld` repo (`specs/`, Bruno `.bru`, Hurl `.hurl`) with a Postman collection for endpoint testing. The hosted API at `api.realworld.show` needs no keys. - Fetch the current spec and note the exact endpoint/response/error contracts (summarized in Phase 2). Recognizing RealWorld is not knowing its current endpoint contracts — read the spec as published, not from memory. ### 1b. Closest-stack reference implementation - Find the nearest implementation on `codebase.show/projects/realworld`, filter by the detected FE/BE stack. **Prefer spec-compliant, recently maintained implementations** (only a subset are verified spec-compliant at any time). - Treat the reference as a *pattern* yardstick (folder structure, auth wiring, validation, error mapping) — not as gospel. When the reference and the spec disagree, the spec wins. ### 1c. Research current best practices Follow the `/research` protocol for the detected stack (Context7 for library docs; Firecrawl for current patterns, dated to now). Anchor recommendations to the versions actually installed in the repo. --- ## Phase 2 — Parity / pattern matrix [HIGH freedom] ### Conformance mode — audit against the RealWorld contract Enumerate the spec surface and mark each **Implemented / Partial / Missing / Diverges**, with `file:line` evidence: **Auth & users** - `POST /api/users` (register), `POST /api/users/login` - `GET /api/user`, `PUT /api/user` (current user) - Auth header scheme: `Authorization: Token ` (not `Bearer`) **Profiles** - `GET /api/profiles/:username` - `POST` / `DELETE /api/profiles/:username/follow` **Articles** - `GET /api/articles` (filters: `tag`, `author`, `favorited`, `limit`, `offset`) - `GET /api/articles/feed` (auth, followed authors) - `GET` / `POST` / `PUT` / `DELETE /api/articles/:slug` - `POST` / `DELETE /api/articles/:slug/favorite` **Comments & tags** - `GET` / `POST /api/articles/:slug/comments`, `DELETE .../comments/:id` - `GET /api/tags` **Cross-cutting contracts** - Response envelopes: `{ user }`, `{ profile }`, `{ article }`, `{ articles, articlesCount }`, `{ comment(s) }`, `{ tags }` - Validation errors: `422` with `{ "errors": { "body": [ ... ] } }` - Auth failures: `401`; missing resources: `404` - Pagination: `limit` / `offset`, with `articlesCount` for lists - Slug generation, `favoritesCount`, `following`/`favorited` booleans reflect the requesting user ### Benchmark mode — map the patterns onto the repo's own domain The repo isn't Conduit, so audit whether it exhibits the same *production- relevant patterns* RealWorld demonstrates, for its own resources: | Pattern | What to check in this repo | |---|---| | Auth flow | Register/login/current-user; token issue + attach + refresh; protected routes | | Owned resources + authz | CRUD on user-owned entities; ownership enforced server-side, not just UI | | List semantics | Pagination, filtering, total counts, empty states | | Relations | Follow/favorite-style join semantics done correctly (no N+1, correct counts) | | Consistent envelopes | Uniform response + error shape across endpoints | | Validation | Server-side validation with structured field errors | | Contract tests | An API/E2E suite that proves the contract, not just unit tests | --- ## Phase 3 — Full-stack coverage sweep [HIGH freedom] Audit all three layers, not just whichever is easiest to read: - **Frontend:** routes for each resource; auth flow (login/register/logout, token persistence, guarded routes); data layer (caching, error/loading/empty states); forms with validation and server-error surfacing. - **Backend:** every spec/pattern endpoint present; auth middleware; input validation; consistent error mapping; pagination; correct status codes. - **Data layer:** schema covers the entities and relations; migrations exist and are current; indexes on foreign keys and hot query paths; constraints (unique, not-null, FK) enforce integrity. Verify live via Supabase MCP when applicable. - **Tests:** unit coverage on core logic, plus the RealWorld contract suite (or the repo's equivalent E2E harness). - **Build/config:** app builds; env contract documented (names only). --- ## Phase 4 — Live conformance test (optional but decisive) [LOW freedom — run exactly] If a server is running or the E2E suite is present, run the objective proof: - Run the RealWorld Bruno collection (`bru run`), the Hurl files (`hurl --test`), or the Postman collection (`newman run`) against the local API base URL. Report pass/fail per endpoint. - If no server is available, state exactly how to run it (base URL, seed/demo credentials) rather than guessing conformance from code alone. A passing contract suite is stronger evidence than any static reading. Save any run artifacts under `.playwright-mcp/` if using playwright-cli. --- ## Phase 5 — Production layering (the honest part) [HIGH freedom] RealWorld parity is necessary breadth, not sufficient depth. Enumerate what RealWorld does **not** cover and route each to the right skill — do not imply parity means production-ready: | Concern RealWorld omits | Route to | |---|---| | AuthN/AuthZ hardening, secrets, injection, OWASP | `audit-security`, `plan-security-audit` | | Row-level security / access control (Supabase) | `plan-rls-audit` | | Performance, Core Web Vitals, query cost | `plan-perf-audit`, `audit-performance`, `backend-db-performance` | | FE↔BE contract drift and runtime errors | `audit-fe-api`, `debug-fe-be-integration` | | Rate limiting, observability, error handling | `backend-observability`, `backend-error-handling` | | Deploy + migration/edge-function verification | `full-stack-ship-discipline`, `deploy-verify` | --- ## Phase 6 — Report (read-only) [HIGH freedom] ```markdown ## RealWorld Full-Stack Audit — [repo] — [date] **Mode:** Conformance | Benchmark **Stack:** FE [..] · BE [..] · DB/ORM [..] · tests [..] **Reference:** [closest-stack impl] (spec-compliant: yes/no) **Live contract suite:** ran (N/M passed) | not run — [how to run] ### Implemented correctly - [feature/pattern] — [file:line] ### Partial (works but incomplete or diverges) | Feature/Pattern | Gap | file:line | Severity | Fix via | |---|---|---|---|---| | Article feed | No pagination / articlesCount | ... | High | complete-everything | ### Missing | Feature/Pattern | file:line (where it should live) | Severity | Fix via | |---|---|---|---| | DELETE comment authz | ... | High | workflow-fix-and-ship | ### Diverges from spec (Conformance mode) | Endpoint | Spec says | Repo does | file:line | |---|---|---|---| | Auth header | `Token ` | `Bearer ` | ... | ### Production gaps (NOT covered by RealWorld — separate hardening) - Security → `audit-security` · Perf → `plan-perf-audit` · RLS → `plan-rls-audit` · ... ### Recommended order 1. [Critical conformance/parity gaps] → complete-everything / workflow-fix-and-ship 2. [Production hardening] → audit-security → plan-perf-audit → ... ``` **Forbidden:** claiming production-readiness from RealWorld parity alone; inventing conformance without running or precisely describing the contract test; silently skipping a layer (FE, BE, or DB). --- ## Self-critique before reporting [LOW freedom — do not skip] 1. **Evidenced** — `file:line` or suite pass/fail, not "looks like Conduit" 2. **Mode honest** — Bow-out if no HTTP API + auth + owned resources; do not force a comparison 3. **Suite honesty** — ran N/M or stated exactly how to run; never invent conformance 4. **All three layers** — FE, BE, and data; skipping one is a failed audit 5. **Not production-ready** — RealWorld parity is never a security / perf / RLS pass 6. **Nothing changed** until approved ## Related - `audit-fe-api` — FE↔BE contract detail once endpoints are inventoried - `debug-fe-be-integration` — reactive debugging of contract mismatches - `audit-security` / `plan-security-audit` — the security depth RealWorld omits - `plan-rls-audit` — Supabase access control - `plan-perf-audit` / `audit-performance` — the performance depth RealWorld omits - `test-unit` / `test-playwright` — write the coverage this audit finds missing - `complete-everything` — close the parity + hardening gaps to done - `workflow-fix-and-ship` — fix a single missing endpoint/feature and ship it - `full-stack-ship-discipline` (rule) — migrations/functions must actually deploy