The Mode System: Four Development Philosophies¶

Every addon exists on a spectrum between "safe and boring" and "powerful and fragile." The mode system lets you tell the AI exactly where on that spectrum you want to build.

A mode is a development philosophy preset that fundamentally changes how every AI agent behaves — from code generation and scaffolding to code review and architectural recommendations. When you set a mode, you're not just changing a config flag. You're changing the AI's entire mental model of what "good addon code" looks like.

What Are Modes?¶

Modes are stored as a single line in your project's .claude/modes/active-mode.md file. That one line — a canonical mode name — propagates to every agent, every command, and every review pass. When the Coder agent generates a frame hook, it checks the active mode. When the Reviewer agent flags a pattern, it checks the active mode. When the Scaffold agent creates boilerplate, it checks the active mode.

Switch modes with a single command:

/wow-mode enhancement-artist

The active mode affects:

• Code generation — Which APIs and patterns the Coder and Scaffold agents use
• Code review severity — What the Reviewer flags as violations vs. acceptable patterns
• Scaffolding boilerplate — Which standard patterns are included in new addon files
• Architectural recommendations — How the Generalist and Skin Designer agents approach problems

The default mode is Enhancement Artist — the philosophy behind the "BetterX" addon movement that dominates the Midnight ecosystem. Most developers never need to change it. But when you're building an ElvUI-class UI replacement or a zero-overhead raid tool, the right mode makes the AI a fundamentally better collaborator.

The Four Modes¶

Blizzard Faithful¶

"Official APIs only. If Blizzard didn't document it, we don't use it. Zero patch-day risk."

Blizzard Faithful is the most conservative mode. It constrains all code generation to documented, stable WoW APIs — the kind listed on warcraft.wiki.gg with official signatures and return values. Every pattern it produces has survived multiple patch cycles because it relies only on Blizzard's public API contract. When in doubt, the Faithful mode leaves it out.

Personality: Boring, safe, and bulletproof.

What It Allows¶

Best For¶

• First-time addon developers learning correct patterns from the start
• Guild tools and utility addons that must never break
• Corporate/competitive addons where reliability is non-negotiable
• Settings-only addons that configure but don't touch Blizzard UI
• Data display addons that create their own frames from scratch

Code Example: Settings-Only Addon¶

A minimal addon using only documented, stable APIs. This code will survive every patch without modification:

-- Mode: Blizzard Faithful | Safe across all patches
local addonName, ns = ...

ns.defaults = {
    enabled = true,
    scale = 1.0,
    showTooltips = true,
}

-- Safe initialization via documented EventUtil
EventUtil.ContinueOnAddOnLoaded(addonName, function()
    ns.db = MyAddonDB or CopyTable(ns.defaults)
    MyAddonDB = ns.db

    -- Settings panel via documented Settings API
    local category, layout = Settings.RegisterVerticalLayoutCategory(addonName)
    ns.categoryID = category:GetID()

    local enabledSetting = Settings.RegisterAddOnSetting(
        category, "enabled", "enabled",
        ns.db, type(true), "Enable Addon", true
    )
    Settings.CreateCheckbox(category, enabledSetting,
        "Toggle the addon on or off.")

    local scaleSetting = Settings.RegisterAddOnSetting(
        category, "scale", "scale",
        ns.db, type(1.0), "UI Scale", 1.0
    )
    local scaleOptions = Settings.CreateSliderOptions(0.5, 2.0, 0.1)
    Settings.CreateSlider(category, scaleSetting, scaleOptions,
        "Adjust the scale of addon frames.")

    Settings.RegisterAddOnCategory(category)
end)

-- Addon Compartment (minimap presence) — declared in TOC
function MyAddon_OnAddonCompartmentClick()
    Settings.OpenToCategory(ns.categoryID)
end

Enhancement Artist (DEFAULT)¶

"Skin, hook, extend — never replace. Make Blizzard's UI beautiful without breaking it."

Enhancement Artist is the default mode and the philosophy behind the "Better Addon" movement that defines the Midnight addon ecosystem. It lets you reach into Blizzard's own frames and make them look and work better — class-colored health bars, cleaner textures, repositioned elements — while preserving all of Blizzard's built-in functionality. Users keep their familiar layouts, Edit Mode settings, and muscle memory. You just make it all better.

Personality: Respectful, creative, and resilient.

Key Rules¶

Every piece of Enhancement Artist code follows these non-negotiable rules:

1. Always hooksecurefunc() — never pre-hook or override Blizzard functions
2. Always IsForbidden() checks — before modifying any hooked frame
3. Always recursion guards — when hooks trigger methods that fire hooks
4. Always store original state — save ogPoint, ogParent, ogWidth before modifying
5. Always defer out of combat — via the RunAfterCombat queue pattern
6. Always HookScript() — never SetScript() on Blizzard frames

Standard Patterns¶

The Enhancement Artist toolkit is built on a set of reusable patterns that form the foundation of every "BetterX" addon:

Best For¶

• "BetterX" addons that improve Blizzard UI without replacing it
• Frame skinning addons that add class colors, clean textures, or visual polish
• UI enhancement addons that reposition or resize Blizzard elements
• Quality-of-life addons that add functionality to existing Blizzard frames

Reference implementations: BetterBlizzFrames, BetterBlizzPlates, ActionBarsEnhanced, Platynator.

Code Example: Hook CompactUnitFrame for Class Colors¶

A simple enhancement that adds class-colored health bars to the default raid frames — the quintessential Enhancement Artist pattern:

-- Mode: Enhancement Artist | Enhance don't replace
local addonName, ns = ...

-- Recursion guard
local isProcessing = false

-- Hook the raid frame health bar update
hooksecurefunc("CompactUnitFrame_UpdateHealthColor", function(frame)
    if isProcessing then return end
    if frame:IsForbidden() then return end
    if not frame.healthBar then return end

    isProcessing = true

    local unit = frame.unit
    if unit and UnitExists(unit) and UnitIsPlayer(unit) then
        local _, class = UnitClass(unit)
        local color = RAID_CLASS_COLORS[class]
        if color then
            frame.healthBar:SetStatusBarColor(color.r, color.g, color.b)
        end
    end

    isProcessing = false
end)

Boundary Pusher¶

"Push WoW's addon API to its absolute limits. If the top addons do it, we do it better."

Boundary Pusher unlocks the aggressive, advanced techniques used by ElvUI, BetterBags, Cell, Plater, and OmniCD. Every technique in this mode is battle-tested in production addons with millions of downloads — but every technique also carries patch-day risk. This mode generates ElvUI/WeakAuras-class code that pushes the envelope, and it demands safety nets for every aggressive pattern.

Personality: Fearless, disciplined, and always prepared to fall back.

Unlocked Techniques¶

Best For¶

• Complete UI replacements (ElvUI-class)
• Nameplate addons (Plater/Platynator-class)
• Cooldown/ability trackers (OmniCD-class)
• Bag replacements (BetterBags-class)
• Raid frame addons (Cell-class)
• Boss mods (DBM/BigWigs-class)

Reference implementations: ElvUI, BetterBags, Cell, Plater, OmniCD, DBM, BigWigs.

Code Example: Metatable Hook with Safety¶

A Cooldown metatable hook that affects every Cooldown frame in the game — with full pcall safety and fallback:

-- Mode: Boundary Pusher | Push the limits
local addonName, ns = ...

-- BOUNDARY: May break if Blizzard changes Cooldown metatable
-- Fallback: per-frame hooksecurefunc on individual cooldown frames
local function SetupCooldownHook()
    local ok, cd = pcall(CreateFrame, "Cooldown", nil, nil, "CooldownFrameTemplate")
    if not ok or not cd then
        ns:PrintDebug("Cooldown metatable hook failed — using fallback")
        return false
    end

    local ok2, mt = pcall(getmetatable, cd)
    if not ok2 or not mt or not mt.__index then
        ns:PrintDebug("Cooldown metatable unavailable — using fallback")
        return false
    end

    local Cooldown_MT = mt.__index
    hooksecurefunc(Cooldown_MT, "SetCooldown", function(self, start, duration)
        if self:IsForbidden() then return end
        if not start or type(start) ~= "number" then return end  -- signature check
        if duration <= 1.5 then return end  -- ignore GCD

        -- Add custom cooldown text overlay to ALL cooldown frames
        if not self.myText then
            self.myText = self:CreateFontString(nil, "OVERLAY", "GameFontNormalLarge")
            self.myText:SetPoint("CENTER")
        end
        self.myText:SetText(math.ceil(duration))
        C_Timer.After(duration, function()
            if self.myText then self.myText:SetText("") end
        end)
    end)

    return true
end

-- Try aggressive hook, fall back to safe pattern
if not SetupCooldownHook() then
    ns:SetupPerFrameCooldownTracking()  -- Enhancement Artist fallback
end

Performance Zealot¶

"Every allocation counts. Zero waste. Your addon should be invisible to /eventtrace."

Performance Zealot prioritizes absolute minimum overhead. Every table creation, every global lookup, every unthrottled handler is a tax on the player's framerate. Code generated in this mode is lean, pre-allocated, and event-driven. If it can be cached, it is cached. If it can be pooled, it is pooled. If it can be avoided, it is avoided.

Personality: Ruthlessly efficient, measurement-obsessed.

Key Rules¶

1. Never create tables inside functions called more than once per second
2. Always cache globals as locals at file scope (local GetTime = GetTime)
3. Always throttle OnUpdate with elapsed accumulator (minimum 0.1s interval)
4. Always use events over polling — register for specific events only
5. Always unregister events when data is no longer needed
6. Always use wipe(t) over t = {} for table reuse
7. Prefer RegisterUnitEvent("EVENT", "unit") over RegisterEvent("EVENT")
8. Require a /perf diagnostic slash command in every addon

The 10 Anti-Patterns¶

Any of these in generated code is an automatic rejection during review:

Best For¶

• Raid environments (20+ players, dozens of auras, high event throughput)
• Low-spec machines where every KB and every ms matters
• Always-on addons (damage meters, nameplates, unit frames)
• High-frequency processing (combat parsing, health tracking, nameplate updates)

Code Example: Object Pool with Diagnostics¶

The canonical Performance Zealot pattern — an object pool that eliminates CreateFrame() calls in hot paths, with the required /perf diagnostic:

-- Mode: Performance Zealot | Zero-waste addon
local addonName, ns = ...

-- Performance: cached globals
local tremove, wipe = table.remove, table.wipe
local CreateFrame = CreateFrame
local format = string.format
local GetAddOnMemoryUsage = GetAddOnMemoryUsage
local UpdateAddOnMemoryUsage = UpdateAddOnMemoryUsage

-- Object pool: never CreateFrame() in a hot path
local pool = {}
local activeCount = 0

local function Acquire()
    local obj = tremove(pool)
    if not obj then
        obj = CreateFrame("Frame", nil, UIParent)
        obj:SetSize(24, 24)
        obj.icon = obj:CreateTexture(nil, "ARTWORK")
        obj.icon:SetAllPoints()
    end
    obj:Show()
    activeCount = activeCount + 1
    return obj
end

local function Release(obj)
    obj:Hide()
    obj:ClearAllPoints()
    obj.icon:SetTexture(nil)
    activeCount = activeCount - 1
    pool[#pool + 1] = obj
end

local function ReleaseAll()
    -- Caller provides the active list, we drain it
    -- No table allocation: caller wipes their own reference table
end

-- Required: /perf diagnostic
SLASH_MYADDON_PERF1 = "/myaddonperf"
SlashCmdList["MYADDON_PERF"] = function()
    UpdateAddOnMemoryUsage()
    local mem = GetAddOnMemoryUsage(addonName)
    print(format(
        "|cff00ff00%s|r: %.1f KB | %d active | %d pooled",
        addonName, mem, activeCount, #pool
    ))
end

Choosing Your Mode¶

Decision Matrix¶

Choosing by Question¶

Ask yourself these questions in order:

1. Does this addon touch Blizzard frames at all?

• No Blizzard Faithful. You're building your own UI from scratch with documented APIs.

2. Do you need to replace Blizzard frames, or just improve them?

• Improve them Enhancement Artist. Hook, skin, extend.
• Replace them Boundary Pusher. You need the aggressive toolbox.

3. Is this addon performance-critical? (Raid frames, nameplates, combat processing)

• Yes Performance Zealot. Every allocation counts.
• No Stay with your choice from step 2.

Mode in Action: Same Addon, Four Ways¶

To see how modes change real code, let's implement the same feature four different ways: add class color to the target frame's name text.

-- Mode: Blizzard Faithful | Safe across all patches
-- Cannot access TargetFrame name text directly.
-- Alternative: create our own class-colored name display.
local addonName, ns = ...

local nameFrame = CreateFrame("Frame", nil, UIParent)
nameFrame:SetSize(200, 20)
nameFrame:SetPoint("TOP", UIParent, "TOP", 0, -20)

local nameText = nameFrame:CreateFontString(nil, "OVERLAY",
    "GameFontNormalLarge")
nameText:SetPoint("CENTER")

local events = {}

function events:PLAYER_TARGET_CHANGED()
    if not UnitExists("target") then
        nameFrame:Hide()
        return
    end
    local name = UnitName("target")
    if UnitIsPlayer("target") then
        local _, class = UnitClass("target")
        local color = RAID_CLASS_COLORS[class]
        if color then
            nameText:SetText(color:WrapTextInColorCode(name))
        else
            nameText:SetText(name)
        end
    else
        nameText:SetText(name)
    end
    nameFrame:Show()
end

local eventFrame = CreateFrame("Frame")
eventFrame:SetScript("OnEvent", function(self, event, ...)
    local handler = events[event]
    if handler then handler(self, ...) end
end)
for event in pairs(events) do
    eventFrame:RegisterEvent(event)
end

-- Mode: Enhancement Artist | Enhance don't replace
local addonName, ns = ...

local isProcessing = false

hooksecurefunc("TargetFrame_UpdateName", function(self)
    if isProcessing then return end
    if self:IsForbidden() then return end

    local name = self.name
    if not name then return end

    isProcessing = true

    local unit = self.unit
    if unit and UnitExists(unit) and UnitIsPlayer(unit) then
        local _, class = UnitClass(unit)
        local color = RAID_CLASS_COLORS[class]
        if color then
            name:SetTextColor(color.r, color.g, color.b)
        end
    end

    isProcessing = false
end)

-- Mode: Boundary Pusher | Push the limits
local addonName, ns = ...

-- BOUNDARY: May break if TargetFrame metatable changes
-- Fallback: hooksecurefunc on TargetFrame_UpdateName
local function SetupTargetNameHook()
    local targetFrame = TargetFrame
    if not targetFrame then return false end

    local ok, mt = pcall(getmetatable, targetFrame)
    if not ok or not mt or not mt.__index then
        return false
    end

    -- Hook at the frame method level for maximum control
    hooksecurefunc(mt.__index, "UpdateName", function(self)
        if self:IsForbidden() then return end
        local name = self.name
        if not name then return end

        local unit = self.unit
        if not unit or not UnitExists(unit) then return end

        if UnitIsPlayer(unit) then
            local _, class = UnitClass(unit)
            local color = RAID_CLASS_COLORS[class]
            if color then
                name:SetTextColor(color.r, color.g, color.b)
            end
        else
            -- Color NPCs by reaction
            local reaction = UnitReaction(unit, "player")
            if reaction then
                local color = FACTION_BAR_COLORS[reaction]
                if color then
                    name:SetTextColor(color.r, color.g, color.b)
                end
            end
        end
    end)

    return true
end

if not SetupTargetNameHook() then
    -- Fallback to Enhancement Artist approach
    hooksecurefunc("TargetFrame_UpdateName", function(self)
        if self:IsForbidden() then return end
        if not self.name or not self.unit then return end
        if UnitIsPlayer(self.unit) then
            local _, class = UnitClass(self.unit)
            local color = RAID_CLASS_COLORS[class]
            if color then
                self.name:SetTextColor(color.r, color.g, color.b)
            end
        end
    end)
end

-- Mode: Performance Zealot | Zero-waste addon
local addonName, ns = ...

-- Performance: cached globals
local UnitExists = UnitExists
local UnitIsPlayer = UnitIsPlayer
local UnitClass = UnitClass
local RAID_CLASS_COLORS = RAID_CLASS_COLORS

-- Pre-cache class colors as simple r,g,b to avoid table lookups
local classColorCache = {}
for class, color in pairs(RAID_CLASS_COLORS) do
    classColorCache[class] = { color.r, color.g, color.b }
end

-- Throttle: don't recolor on every micro-update
local lastUnit = nil
local lastClass = nil

hooksecurefunc("TargetFrame_UpdateName", function(self)
    if self:IsForbidden() then return end

    local unit = self.unit
    if not unit or not UnitExists(unit) then return end

    -- Skip if same target, same class (no work needed)
    if unit == lastUnit then return end
    lastUnit = unit

    local name = self.name
    if not name then return end

    if UnitIsPlayer(unit) then
        local _, class = UnitClass(unit)
        if class == lastClass then return end  -- same class, skip
        lastClass = class

        local c = classColorCache[class]
        if c then
            name:SetTextColor(c[1], c[2], c[3])
        end
    else
        lastClass = nil
    end
end)

Switching Modes¶

Commands¶

/wow-mode blizzard-faithful    # Full name
/wow-mode faithful             # Alias
/wow-mode safe                 # Another alias
/wow-mode status               # Show current mode
/wow-mode                      # Same as status

All Aliases¶

What Happens When You Switch¶

1. active-mode.md is overwritten with the canonical mode name
2. All subsequent agent interactions use the new mode's rules
3. Code generation patterns change immediately
4. Review criteria adjust to the new mode's standards

The switch is instant and affects the current project only. No restart needed — the next time any agent reads the active mode file, it picks up the change.