🎛️ OMP Control Board

graph TB
    %% Class Definitions
    classDef mainHeader fill:#1E293B,stroke:#38BDF8,stroke-width:2px,color:#F8FAFC,font-weight:bold;
    classDef colHeader fill:#334155,stroke:#94A3B8,stroke-width:1.5px,color:#F1F5F9,font-weight:bold;
    classDef itemNode fill:#0F172A,stroke:#475569,stroke-width:1px,color:#E2E8F0;

    %% Subgraphs for Columns
    subgraph Board ["📝 OMP SYNTHESIS CONTROL BOARD"]
        direction TB

        %% Column 1: Swarm & Agents
        subgraph Col1 ["🧼 SWARM & AGENTS"]
            direction TB
            A1["1. Python Evals"]
            A2["2. Testing Layers"]
            A3["3. Naming Rules"]
        end

        %% Column 2: Stack Reflection
        subgraph Col2 ["🧠 STACK REFLECTION"]
            direction TB
            B1["1. Core Integrations"]
            B2["2. Observability"]
            B3["3. CLI & Web Config"]
        end

        %% Column 3: Condensation & Formatting
        subgraph Col3 ["⚡ CONDENSATION & FORMATTING"]
            direction TB
            C1["1. High-density Tables"]
            C2["2. Visual Emojis Landmarks"]
            C3["3. Markdown Dashboards"]
        end
    end

    %% Apply Classes
    class Board mainHeader;
    class Col1,Col2,Col3 colHeader;
    class A1,A2,A3,B1,B2,B3,C1,C2,C3 itemNode;

🚀 Architecture & Infrastructure

• Ompycord Colocation: Run discord.py alongside FastAPI. Disable native signals on Uvicorn (server.install_signal_handlers = lambda: None).
• Telemetry Context: Carry context via Node/Bun AsyncLocalStorage. Use safe lazy dynamic imports (await import('langfuse').catch(...)).
• Environment Isolation: Keep a clean codebase. Distinguish test data from production traffic completely.
• Automated TTL: Automate dummy infrastructure cleanup via TTL (auto_ttl_days: 1).

📦 Swarm Orchestration & Agents

🛠️ Domain	💡 Implementation Standard
Agent Provisioning	Use agent_type="task" for filesystem writes. Reviewers are strictly read-only!
Persona Injection	Inject personas directly into the prompt string. The role kwarg is invalid for agent().
Output Scoring	Enforce JSON schemas when scoring outputs to avoid breaking diff-based exit conditions.
Validation Gates	Delegate pipeline validation to gatekeeper agents to halt loops with dummy configs.

🔧 Codebase Tooling & Commands

🛠️ Tool	✅ Action & Command
Prettier / ESLint	Ignore quartz/local-plugins in workspace configs to prevent overwrite loops.
Quartz UI	Strip emojis from Explorer using regex mapFn: /[\p{Emoji_Presentation}\p{Extended_Pictographic}\uFE0F]/gu.
Quartz Mermaids	Always wrap edge labels in double quotes (`—>
WordPress Builds	Edit JS/PHP inside src/. Always run npm run build from the plugin root directory.
WP-CLI Execution	Run sudo -u www-data wp in restricted /var/www/ directories to prevent permissions errors.
Secure Web Writes	Use sudo -u www-data tee path/to/file > /dev/null << 'EOF' instead of standard bash redirects.
OMP CLI	Execute debugging CLI commands strictly under a real PTY (pty: true).

💡 Best Practices & Testing

• Structured Naming: Replace generic placeholders (like test-topic-123) with namespaced formats: [env].[region].[service].[data-type]. Append versions (v1) and use strict lowercase.
• Local Verification: Use dummy placeholders strictly for rapid local verification, never in shared environments.
• Test Independence: Assert strictly on behavioral outcomes. Tests must run independently without relying on shared state.
• Lifecycle Policy: Enforce a strict lifecycle management policy for all test topics to ensure immediate cleanup.

🚨 Gotchas / Traps / Warnings

• Generic Placeholders (test-topic-123): NEVER deploy generic strings in shared/production environments. They obscure observability, pollute metrics, and introduce collision risks.
• Read-Only Reviewers: Agents tagged agent_type="reviewer" cannot write to the filesystem. NEVER attempt I/O with them.
• Brittle Tests: Over-reliance on internal implementation details breaks tests during refactoring.
• Direct Build Edits: Modifying build/ files in WordPress directly is an anti-pattern and will be overwritten by builds.
• Shared Test State: Designing tests that rely on shared state from previous tests guarantees cascading failures.
• Signal Overlap: Never allow signal handlers to clash when co-locating asynchronous frameworks like Uvicorn and Discord.py.