Codex Domain Specialist

TL;DR

Detect primary domain from file signals -> load matching references from routing table -> enforce max 4 references first pass. Check .codex/profile.json for fast-path. Check feedback logs for supplemental loading. Never bulk-load all references. Keep solutions project-specific without adding abstractions, dependencies, services, or architecture layers that the task does not justify.

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 and irresponsible overengineering by enforcing:

1. The 3-Second Rule: 3 questions before any output.
2. Domain-specific Quality Gates (FE / BE / DB).
3. A Scope Fit Gate before adding abstractions, dependencies, queues, caches, services, or framework layers.
4. 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.

If your solution adds architecture the current task does not need and cannot justify with repo evidence, it is overengineered. Overengineered = failure. Shrink the design.

Domain Specialist

Activation

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

Announce at start: "I'm using codex-domain-specialist to load domain-specific references."

Project Profile (Fast Path)

Before running detection, check for .codex/profile.json 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.

Tool-Aware Routing Overlay

Use this overlay after domain detection and before implementation. It does not replace domain routing; it records which tools are required to make the answer project-specific and evidence-backed.

Tool selection matrix

Rules:

1. Tool evidence must be concrete enough that another agent can repeat the same check; write this as explicit tool evidence in specs, plans, or final verification notes when it affects the decision.
2. Do not run heavyweight tools just to look rigorous; pick the smallest tool that can prove the routing decision.
3. Scripts remain black boxes unless customization or debugging requires source inspection.
4. Tool usage does not require full compliance work unless the task, repo evidence, or user request explicitly calls for it.

Security overlay

Apply security routing when the work changes a boundary, protected data path, privileged workflow, or externally reachable behavior. The overlay is proportional and does not require full compliance for every feature.

Security triggers:

• attacker-controlled input reaches parsing, query, file, template, network, shell, auth, authorization, or persistence logic
• secrets, tokens, credentials, session state, API keys, or CI/deployment privileges are touched
• auth, RBAC, OAuth, tenant isolation, admin behavior, or user identity changes
• public API, webhook, upload, export, package install, build pipeline, container, or deployment surface changes
• dependency, generated artifact, or tool execution path can influence runtime behavior

Security output requirements:

• identify assets and trust boundaries before recommending controls
• name the closest existing control and whether it is sufficient
• choose proportional controls; heavier controls need a stated risk, why the simpler control is insufficient, and a verification method
• record security validation or a clear no-security-surface rationale in the spec or final evidence

Implementation ticket trigger

Create or update spec tickets when any of these are true:

• more than one acceptance criterion is needed
• changes span more than one domain or role
• likely implementation touches multiple files or phases
• security validation, migration, deployment, or QA work must be tracked separately
• another agent or developer needs enough context to pick up one slice without rereading the whole conversation

Each ticket must include:

• TICKET-### ID
• title and domain/owner
• linked AC-### and security criteria when applicable
• intent and likely files or areas
• dependencies
• security notes
• validation command or manual check

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]
5. Scope-fit enforcement:
   • Prefer the smallest change that satisfies the task, tests, and existing project patterns.
   • Do not add a new dependency, service, worker, cache, queue, design system, abstraction layer, or cross-cutting framework unless the task has an explicit signal or repo evidence shows the simpler path fails.
   • If adding complexity, state: Why simpler option fails, What this complexity buys, and How we will verify it.

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

AI/LLM 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.
5. Avoid speculative architecture. Route to architecture/devops/security references only when the task changes a boundary, runtime, threat model, deployment path, or operational risk.
6. Use existing repo conventions before introducing new patterns. New patterns require evidence from the task, failing tests, scale constraints, or explicit user direction.

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.

Related Discipline Skills

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 and anti-overengineering guardrails: 3-Second Rule, Scope Fit Gate, FE/BE/DB Quality Gates, 12-point checklist, Why Mandate, Framework Defaults Override.
• references/ai-llm-patterns.md: AI/LLM integration patterns — prompt engineering, RAG pipelines, embeddings, vector DB selection, streaming, cost control, and security rules.