AGENTS.md — Oficina

Entry point for harnesses that read AGENTS.md (Codex, Cursor, OpenCode, Gemini CLI and similar).

This repository is a lean harness of working patterns for the Node.js + TypeScript + Prisma stack — Express (manual Clean Architecture) in the production backends it was extracted from, NestJS kept for projects that explicitly pick it.

When working on any project that references this harness:

1. Follow the always-on rules in rules/:
   • rules/engineering-philosophy.md — how the team decides (pragmatism, no over-engineering)
   • rules/git-workflow.md — branches, commits, documentation from day 0
   • rules/security-baseline.md — security and multi-tenancy non-negotiables
   • rules/agent-workflow.md — how to direct the agent itself (plan before code, scoped sessions, early correction)

2. Consult the skills in skills/ before executing tasks in the covered areas. House patterns (extracted from repeated real usage — Path 1 in docs/HOW-TO-GROW.md):

   • express-prisma-pattern — creating any CRUD route/domain in an Express + Prisma backend (the house stack)
   • prisma-schema-conventions — creating/changing schema, planning migrations
   • rbac-design — permissions, roles, access control
   • clickup-task-breakdown — breaking scope into tasks
   • client-facing-docs — any material the client will read
   • token-efficiency — session setup, token/context limits, RTK
   • design-audit — read-only audit for the generated-UI look and design-system drift (static scan + rendered check, ranked report)
   • frontend-design — pick a deliberate visual direction (plan, review against brief, build) before writing UI; pair with design-audit to check the result
   • break-ui — feeds a component worst-case data (long names, empty states, huge counts, non-Latin text) behind a demo toggle and reports what breaks, with a fix for each
   • security-audit — read-only code security audit, source-to-sink tracing, HIGH-confidence findings only (Express/Prisma, web, Electron, Expo, LLM)
   • ai-news — daily AI news briefing in PT-BR (AlphaSignal + Hermes AI, new items only) and Shorts scripts from the best stories; output in ~/.oficina/news/, never in a repo

   Curated skills (audited external adoption closing a confirmed gap — Path 2 in docs/HOW-TO-GROW.md):

   • domain-modeling — building/sharpening CONTEXT.md glossary and ADRs
   • codebase-design — deep-module vocabulary when designing or reviewing an interface
   • improve-codebase-architecture — scanning a codebase for deepening opportunities
   • grilling — structured requirements interview to stress-test a plan or decision
   • diagnosing-bugs — hard bugs and performance regressions
   • tdd — test-first feature/bugfix work, red-green-refactor discipline
   • secrets-gitleaks — secret scanning, pre-commit and CI (operationalizes security-baseline.md)
   • ci-cd-and-automation — standing up CI/CD quality gates from scratch
   • redesign-existing-projects — auditing and upgrading the UI of an existing project without changing its stack
   • screenshot-to-code — rebuilding a UI from a screenshot, then comparing the render against it
   • web-design-guidelines — reviewing front-end code against Vercel Web Interface Guidelines (rules vendored, no network call)
   • playwright-cli — driving a real browser from the terminal to test a page at phone width (needs npm i -g @playwright/cli)
   • rag-architect — designing/evaluating a RAG pipeline
   • sentry-setup-ai-monitoring — instrumenting LLM call cost/latency/tokens

   Motion (experimental até o primeiro vídeo real que usar):

   • motion-dictionary — vocabulário de 25 efeitos (entradas, ritmo, texto, formas, transições e princípios de animação) com duração, easing e parâmetros padrão, gramática de spec ("peça assim"), 5 modelos de prompt em blocos e fx.js determinístico (função do tempo, sem dependências) para HTML-to-video, GSAP, Remotion, CSS ou Framer Motion

   Game projects only (experimental — not yet used in two real projects; load only when the project is a game, never in backends or web apps):

   • game-design-doc — building/reviewing a GDD (pillars, core loop, economy, scope); /oficina:gdd
   • game-assets — asset layout, naming and the AssetForge viewer/export scaffold for Unity, Electron and Roblox; /oficina:asset-forge, /oficina:asset
3. Documentary source of truth: data model and scope come from the project's documents. Divergence is a blocker to resolve with the tech lead, not a detail to ignore.