TL;DR

Detect primary domain from file signals -> load matching references from routing table -> enforce max 4 references first pass. Check .codex/profile.yaml for fast-path. Check feedback logs for supplemental loading. Never bulk-load all references.

Output Quality Mandate (MANDATORY)

Before generating ANY code, schema, API, or UI — load and apply references/output-quality-gates.md. This reference is exempt from the 4-item context limit and domain isolation rules. It must be loaded on EVERY task.

This reference prevents generic, tutorial-style output by enforcing:

1. The 3-Second Rule: 3 questions before any output.
2. Domain-specific Quality Gates (FE / BE / DB).
3. A 10-point Anti-Generic Checklist after generating output.

If your output could be copy-pasted into any random project and still work without modification, it is generic. Generic = failure. Re-think and rewrite.

Domain Specialist

Activation

1. Activate when the task edits domain-specific files.
2. Activate on explicit $codex-domain-specialist.

Project Profile (Fast Path)

Before running detection, check for .codex/profile.yaml in the project root. If the file exists:

1. Parse primary_domain and map to the routing decision table directly.
2. Use stack entries as supplemental signals for "Load On Signal" column.
3. Skip file-extension-based detection entirely. If the file does not exist or fails to parse:

• Fall back to the standard Detection and Routing Order below. See: references/project-profile-spec.md for schema and validation rules.

Feedback-Aware Supplemental Loading

After determining the primary domain (via profile or detection), check for recurring feedback patterns:

1. Scan .codex/feedback/*.md files from the last 30 days.
2. Count feedback entries by Category field (e.g., "database", "security", "performance").
3. If any category has 3+ entries in 30 days AND that category maps to a domain reference:
   • Auto-load that domain's reference as supplemental context.
   • Declare: Feedback-driven load: [reference file] (N issues in 30 days).
4. Maximum 1 supplemental reference from feedback (highest count wins).
5. If no feedback files exist or all counts < 3, skip this step silently.

Category to Reference Mapping

Detection and Routing Order

Route in this exact order:

1. Detect primary domain.
2. Load primary domain references from the decision table.
3. Add only signal-driven references.
4. Enforce context boundaries before implementation or review.

Primary Domain Detection

Context Boundary Enforcement

0. Mandatory pre-load: Always load references/output-quality-gates.md regardless of domain or context limits. This does NOT count toward the 4-item limit.
1. Max context load: load at most 4 items (references + starter templates) in the first pass. If more are needed, state clear reason and list additional files explicitly.
2. Domain isolation:
   • Frontend-only tasks (component, styling, hooks): do not load backend-rules.md, database-rules.md, or devops-rules.md.
   • Backend-only tasks (API, service, middleware): do not load react-patterns.md, nextjs-patterns.md, or accessibility-rules.md.
   • Database-only tasks (schema, migration, query): do not load frontend-rules.md, mobile-rules.md, or seo-rules.md.
3. Cross-domain trigger:
   • API contract change: load both api-design-rules.md and backend-rules.md.
   • Security concern detected: load security-rules.md regardless of primary domain.
   • Performance issue detected: load performance-rules.md as supplemental context.
4. Explicit declaration: whenever references are loaded, always declare:
   • Loading: [file1], [file2]
   • Skipping: [reason]

Routing Decision Table

Specialized Signal Routing

When task signals match keywords below, add the corresponding reference. If multiple signals match, load at most 2 specialized references (pick highest relevance).

Frontend Signals

Backend Signals

Database Signals

Auth and Security Signals

Architecture and DevOps Signals

Cross-Cutting Signals

Common Combo Detection

When task matches a combo pattern, load the specified set instead of individual domain routing.

Operating Rules

1. Never bulk-load all references.
2. Keep first-pass load minimal and task-specific.
3. Re-check boundaries after each major step and prune irrelevant references.
4. If user task spans multiple domains, justify each added reference in the declaration.

Signal Conflict Resolution

When multiple signals match different references:

1. Specificity wins: pagination-patterns.md over api-design-rules.md for pagination-focused questions.
2. Combo wins: if task matches a Common Combo, use the combo set instead of individual signals.
3. Deep over general: web-security-deep.md over security-rules.md for CORS/CSP/XSS-specific tasks.
4. Starter + reference: when both match, load starter (practical code) and reference (rules). Both count toward the 4-item limit.
5. Declaration required: always declare which signals triggered which references and any conflicts resolved.

Starter Templates

When creating new features or projects, reference starter templates in starters/ directory:

Starter Template Auto-Routing

When task creates new code matching patterns below, always reference the corresponding starter as a pattern source. Declare: Starter reference: [template name].

Rules:

1. Reference starters as starting points; never copy blindly.
2. Adapt tokens and patterns to match existing project conventions.
3. Remove unused components from starters.
4. Load at most 1 starter per task (pick the most relevant), except Common Combo Detection entries that explicitly list more than one starter.
5. Starter counts toward the max 4-item context limit.
6. If starter conflicts with project conventions, skip it and declare reason.

Script Invocation Discipline

1. When domain routing recommends helper scripts from other skills, run --help first.
2. Treat scripts as black-box helpers and execute by CLI contract before source inspection.
3. Read script source only when customization or bug fixing is required.

Reference Files

• references/project-profile-spec.md: project profile schema and fast-path routing.
• references/architecture-rules.md: architecture and scaling decision rules.
• references/integration-rules.md: integration reliability and external API patterns.
• references/caching-patterns.md: cache-aside strategy, TTL, and invalidation rules.
• references/pagination-patterns.md: offset/cursor pagination decision guidance.
• references/validation-patterns.md: request validation and sanitization patterns.
• references/logging-patterns.md: structured logging and correlation id standards.
• references/background-jobs.md: queue and scheduled job processing patterns.
• references/search-filter.md: URL-driven filter and faceted search patterns.
• references/file-upload.md: secure upload and object-storage patterns.
• references/email-notification.md: email delivery and in-app notification patterns.
• references/data-migration.md: seed/backfill and migration safety guidance.
• references/multi-tenancy.md: tenant isolation and query safety patterns.
• references/feature-flags.md: progressive rollout and toggle management patterns.
• references/graphql-patterns.md: GraphQL schema/resolver and security patterns.
• references/design-patterns.md: common creational, structural, and behavioral patterns.
• references/web-security-deep.md: deep web security configuration and hardening.
• references/i18n-patterns.md: translation, locale, and formatting patterns.
• references/testing-strategy.md: test pyramid, mocking, and coverage guidance.
• references/api-documentation.md: OpenAPI conventions and API versioning guidance.
• references/git-workflow.md: branch, commit, PR, and release workflow standards.
• references/pwa-patterns.md: manifest/service-worker and offline patterns.
• references/performance-profiling.md: web vitals, bundle, and runtime profiling guidance.
• references/deployment-strategy.md: rollout and rollback deployment patterns.
• references/code-review.md: review checklist and feedback guidelines.
• references/observability.md: metrics, SLO/SLI, and tracing guidance.
• references/api-gateway.md: gateway patterns and service edge design.
• references/event-sourcing.md: event store and CQRS projection patterns.
• references/container-orchestration.md: Docker/Kubernetes deployment patterns.
• references/payment-integration.md: payment flow and webhook safety guidance.
• references/data-visualization.md: charting patterns and dashboard composition guidance.
• references/form-patterns.md: complex form architecture and validation UX patterns.
• references/date-timezone.md: UTC/timezone handling and scheduling rules.
• references/data-export.md: CSV/Excel export implementation and safety patterns.
• references/oauth-social-login.md: OAuth social login integration and security guidance.
• references/monorepo-patterns.md: workspace structure and shared package conventions.
• references/message-queue-comparison.md: broker selection and queue pattern guidance.
• references/database-aggregation.md: MongoDB aggregation pipeline and analytics patterns.
• references/accessibility-rules.md: accessibility standards, semantic patterns, and WCAG-aligned implementation.
• references/api-design-rules.md: API contract design, versioning, and idempotency patterns.
• references/auth-patterns.md: authentication and authorization implementation guidance.
• references/backend-rules.md: backend architecture, service boundaries, and API implementation rules.
• references/css-architecture.md: CSS structure, design tokens, and styling system conventions.
• references/database-rules.md: database schema, query, and migration core rules.
• references/debugging-rules.md: debugging workflow, hypothesis-driven investigation, and root-cause practices.
• references/devops-rules.md: CI/CD, deployment reliability, and operational safeguards.
• references/error-handling-patterns.md: consistent error taxonomy and handling patterns.
• references/file-structure.md: repository and module structure conventions.
• references/frontend-rules.md: frontend architecture and UI engineering baseline rules.
• references/mobile-rules.md: mobile app architecture and performance/security constraints.
• references/nextjs-patterns.md: Next.js routing, rendering, and data-fetching patterns.
• references/performance-rules.md: performance budgets, profiling, and optimization priorities.
• references/react-patterns.md: React composition, hooks usage, and state patterns.
• references/realtime-patterns.md: realtime communication patterns (polling/SSE/WebSocket).
• references/security-rules.md: baseline security controls and threat mitigation practices.
• references/seo-rules.md: SEO technical implementation and discoverability patterns.
• references/state-management.md: client state modeling and store selection patterns.
• references/testing-rules.md: unit/integration/e2e testing baseline standards.
• references/typescript-rules.md: TypeScript strictness, typing conventions, and API typing patterns.
• references/vietnamese-typography.md: Vietnamese font selection, UTF-8 encoding, diacritics handling, and locale-aware text processing.
• references/creative-ui-ux.md: Advanced UI/UX, GSAP orchestration, Three.js integration, storytelling flow, and creative design principles.
• references/ui-ux-design-principles.md: Visual hierarchy, Gestalt principles, color theory, typography scales, whitespace strategy, optical alignment, and developer design anti-patterns.
• references/gsap-mastery.md: GSAP core architecture, easing, ScrollTrigger, SplitText, ScrollSmoother, Observer, Flip, MorphSVG, DrawSVG, MotionPath, performance, React integration, and creative recipes.
• references/interactive-elements.md: Fun interactive UI elements: custom cursors, tilt cards, magnetic buttons, confetti, particles, text scramble, hover effects, drag/swipe, Easter eggs.
• references/creative-development.md: Creative Director's Brain — Creative Brief Decoder, 7 archetypes, experimental typography, glow/neon systems, purpose-driven animation, differentiation playbook, conversion-focused creative.
• references/output-quality-gates.md: MANDATORY — Anti-generic guardrails: 3-Second Rule, FE/BE/DB Quality Gates, 10-point Anti-Generic Checklist, Why Mandate, Framework Defaults Override.