ARSVINE DOCS
  • English

      • Agent workflow

      Realm is an "AI coding agent friendly" project. Maintainers (humans) and coding agents follow the role split below.

      Documentation split

      FileRoleWho can change it
      CLAUDE.mdEntry index; must stay shortMaintainers only
      AGENTS.mdHard rules and "common danger zones"Maintainers only
      docs/DEVELOPMENT.mdLocal commands, COS Referer, fonts, mediaMaintainer / agent collaboration
      docs/ARCHITECTURE.mdRoutes / content / protected posts / API / transitions / styling / 3DMaintainer / agent collaboration
      docs/OPERATIONS.mdDeploy / env / CDN / COS / ISR / Upstash / SEOMaintainer / agent collaboration
      docs/PERFORMANCE.mdAdaptive performance tiersMaintainer / agent collaboration
      docs/ASSETS.mdCOS publishing pipelineMaintainer / agent collaboration
      docs/GOTCHAS.md27 historical regressionsMaintainer / agent collaboration
      docs/superpowers/specs/...Design specs (output during design phase)Agents can write during spec phase
      tests/<area>/Test codeAgents can write

      Hard rules (agents must obey)

      1. Pages Router; do not switch to App Router
      2. Do not replace server.js
      3. Internal navigation uses useTransition().navigateTo()
      4. Do not infer language from IP / country
      5. Do not dynamically require locale data
      6. Do not reintroduce reading-time
      7. Do not attach --font-display to translated / user content
      8. coscli uses only temporary env-injected credentials
      9. Protected MDX does not enter static products
      10. Preserve the reducer / effect race fixes in useBlogPostState.ts / lib/blog-post-state.ts

      Read the corresponding docs/GOTCHAS.md entry before changing related code.

      Decision boundaries

      Agents can do these directly:

      • Edit data/<topic>/<locale>.ts content
      • Edit locales/<locale>.json copy
      • Edit data/site.ts SEO / fonts / social
      • Add tests/<area>/<name>.test.ts
      • Modify components/... internals (without changing external interfaces)
      • Modify scripts/... internals
      • Modify docs/... content (without restructuring)

      Agents must report first before:

      • Adding / removing env vars
      • Changing package.json dependencies / devDependencies
      • Changing next.config.js / server.js / proxy.ts / i18n/config.ts
      • Changing pages/[locale]/_app.tsx / _document.tsx
      • Changing hooks/useBlogPostState.ts / lib/blog-post-state.ts (protected-post state machine)
      • Changing scripts/assets-publish.mjs (involves coscli credentials and pointer flip)
      • Changing data/site.ts fonts.googleStylesheet (requires re-fetch and upload)

      Agents must never do these:

      • Commit COS secrets, GitHub PATs, TOTP secrets, or access-grant secrets anywhere
      • Remove the corresponding fixes for fragile conventions recorded in GOTCHAS.md
      • Change the locale resolution order
      • Bypass enforceRateLimit() to expose revalidate / protected-verify as unlimited endpoints
      • Place protected post bodies in _next/data/... JSON (even encrypted)

      PR template

      Every change PR must describe:

      1. Intent (one sentence)
      2. Impact (which files / routes / locales)
      3. Manual verification (dev side + desktop / mobile)
      4. Related issue (if any)
      5. CI pass proof (pnpm check output + four SSR paths returning 200)
      6. Rollback steps (in case a post-release revert is needed)

      CI gates

      pnpm check

      = pnpm lint + pnpm typecheck + pnpm test + pnpm build. All four must pass before merging.

      Vercel deployment auto-runs SSG pre-rendering; any SSG error (missing getStaticPaths, locale mismatch, circular import) fails at the build step.

      Design specs

      Complex changes (multi-file / multi-day / multi-locale impact) must first produce docs/superpowers/specs/<date>-<topic>-design.md. A spec includes:

      • Current state (reference current implementation plus existing docs)
      • Goal (the user-visible or maintenance-visible problem being solved)
      • Design (API shape, data flow, key decisions)
      • Verification (dev side, prod side, rollback)

      Agents may draft specs, but final sign-off is the maintainer's call.