boilerplate-be/mds/learned_protocols.md

Learned Protocols & Standards

This document serves as the persistent memory of the protocols, standards, and personas learned from the skript-be and skript-ui repositories.

1. Frontend Standards (skript-ui)

Design & Aesthetics (frontend-design)

• Anti-AI Slop: Avoid generic, cookie-cutter "AI" aesthetics (e.g., standard purple gradients, predictable layouts).
• Boldness: Commit to a specific aesthetic direction (Minimalist, Brutalist, Magazine, etc.).
• Typography: Use distinctive fonts; avoid system defaults like Arial/Inter unless intentional.
• Micro-interactions: Prioritize one or two high-impact animations over scattered noise.
• Creativity: Use noise textures, gradient meshes, asymmetry, and overlapping elements.

Architecture (senior-frontend & nextjs-architecture-expert)

• Next.js App Router: STRICT adherence to App Router patterns (layouts, error.tsx, loading.tsx).
• Server Components (RSC): Default to Server Components. Use Client Components ('use client') only when interactivity is required.
• State Management: component-first thinking; use Context/Zustand for global state, local state for UI.
• Performance: Aim for sub-3s load times. Use next/image, code splitting, and lazy loading.
• Tailwind CSS: Use correctly; avoid long string pollution where possible (use utils/cva).

Quality Assurance (senior-qa)

• E2E Testing: Critical flows must be tested.
• Coverage: High unit test coverage for utilities and complex logic.

2. Backend Standards (skript-be)

Code Quality (code-reviewer)

• Review: Verify BEFORE implementing.
• Simplicity: No over-engineering.
• Security: No secrets in code. Input validation is mandatory.
• YAGNI: "You Aren't Gonna Need It" - don't build features "just in case".

Security (security-engineer & api-security-audit)

• Zero Trust: Verify every request.
• OWASP: Check against Top 10 (Injection, Broken Auth, etc.).
• Data: Validate all inputs using libraries (e.g., Zod, Joi).
• Logging: Sanitize logs (no PII/secrets).

Database (database-optimizer)

• N+1: Watch out for N+1 queries in loops/ORMs.
• Indexing: Index foreign keys and search columns.
• Explain: Check execution plans for complex queries.

General Engineering

• TypeScript: Strict mode enabled. No any. Use generics and utility types (typescript-pro).
• Feedback: "Receive Code Review" protocol – technical correctness > polite agreement. Verify suggestions before applying.

TypeScript Expertise (typescript-pro)

• Seniority: I write Senior-level code. This means focusing on maintainability, scalability, and robustness, not just "making it work".
• Modern Techniques: I utilize the latest TypeScript features:
  • Advanced Types: Conditional types, Template Literal Types, Mapped Types.
  • Utility Types: Pick, Omit, Partial, Readonly, ReturnType, Parameters, etc.
  • Generics: Proper constraints (T extends ...) and defaults.
  • Type Inference: Leveraging inference where clean, explicit typing where necessary for clarity.
• Strictness:
  • noImplicitAny is law.
  • Avoid any at all costs; use unknown with type narrowing/guards if dynamic typing is truly needed.
  • Strict null checks always on.
• Architecture: Value objects, opaque types, and branded types for domain safety.

3. Operational Protocols

• Agent Persona: I act as the specific specialist required for the task (e.g., if debugging, I am debugger; if designing, I am frontend-developer).
• Proactiveness: I do not wait for permission to fix obvious bugs or improve clear performace bottlenecks if they are within scope.
• Persistence: These rules apply to ALL future tasks in this session.