playbooks

home / skills / falkicon / mechanic / k-ecosystem

k-ecosystem skill

/.agent/skills/k-ecosystem

This skill helps WoW addon developers master the Fen ecosystem, coordinating Mechanic, FenCore, FenUI, and MechanicLib for faster, reliable debugging.

npx playbooks add skill falkicon/mechanic --skill k-ecosystem

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
3.8 KB
---
name: k-ecosystem
description: >
  Context for the Mechanic/Fen WoW addon development ecosystem. Covers all
  components (Mechanic, FenCore, FenUI, MechanicLib), their relationships,
  and AFD principles. Load this at the start of addon work.
  Triggers: ecosystem, fen, fencore, fenui, mechanic, addon, context.
---

# Fen Ecosystem

The Mechanic/Fen ecosystem is a unified platform for WoW addon development.

## The Reload Loop (MANDATORY)

After ANY addon code change, you MUST verify the changes in-game:

1. **Ask** the user to `/reload` in WoW (or trigger via keybinding CTRL+SHIFT+R)
2. **Wait** for the user to confirm the reload is complete
3. **Then** use the `addon.output` MCP tool (agent_mode=true) to get errors, tests, and console logs

> **CRITICAL**: Do NOT call `addon.output` immediately after changes. The timing between reload and SavedVariables sync is unpredictable. Always wait for user confirmation.

## Ecosystem Components

| Component | Purpose | Key Tools |
|-----------|---------|-----------|
| **Mechanic** | Development hub (CLI, MCP, Dashboard) | `env.status`, `addon.output`, `addon.lint`, `addon.test` |
| **FenCore** | Pure logic library (no UI dependencies) | `fencore.catalog`, `fencore.search`, `fencore.info` |
| **FenUI** | UI widget library (frames, layouts) | `Layout`, `Panel`, `Tabs`, `Grid`, `Buttons` |
| **MechanicLib** | Bridge library (addon ↔ Mechanic) | `RegisterAddon`, `Print`, `RegisterTest` |

## Component Relationships

```
┌─────────────────────────────────────────────────────┐
│                    Your Addon                        │
├─────────────────────────────────────────────────────┤
│  Core Layer     │  Bridge Layer   │  View Layer     │
│  (Pure Logic)   │  (Events/Data)  │  (UI Frames)    │
│                 │                 │                 │
│  Uses: FenCore  │  Uses: Ace3     │  Uses: FenUI    │
└─────────────────────────────────────────────────────┘
         │                 │                 │
         └────────────┬────┴─────────────────┘
                      │
              ┌───────▼───────┐
              │  MechanicLib  │  (Registers addon with Mechanic)
              └───────┬───────┘
                      │
              ┌───────▼───────┐
              │   Mechanic    │  (Development hub)
              └───────────────┘
```

## Essential MCP Tools

| Task | MCP Tool |
|------|----------|
| Get Addon Output | `addon.output(agent_mode=true)` |
| Lint Code | `addon.lint(addon="MyAddon")` |
| Run Tests | `addon.test(addon="MyAddon")` |
| Search APIs | `api.search(query="*Spell*")` |
| Search FenCore | `fencore.search(query="clamp")` |
| Env Status | `env.status()` |

## AFD Core Principles

Mechanic follows **Agent-First Development (AFD)** — [github.com/Falkicon/afd](https://github.com/Falkicon/afd)

1. **Tool-First**: All functionality exists as an MCP tool before any UI
2. **Structured Results**: Tools return predictable JSON with `success`, `data`, `error`
3. **Agent Mode**: Use `agent_mode=true` for AI-optimized output

## Related Knowledge

- [k-mechanic](../k-mechanic/SKILL.md) - Deep dive into Mechanic tools
- [k-fencore](../k-fencore/SKILL.md) - FenCore library details
- [k-fenui](../k-fenui/SKILL.md) - FenUI widget library

Overview

This skill provides the Fen/Mechanic ecosystem context for World of Warcraft addon development. It summarizes components (Mechanic, FenCore, FenUI, MechanicLib), their relationships, essential MCP tools, and Agent-First Development (AFD) principles. Load it at the start of any addon work to ensure consistent workflow and tooling.

How this skill works

It teaches the required reload loop workflow and explains when and how to call MCP tools safely. It describes each ecosystem component, how your addon layers map to them, and which tools to use for output, linting, testing, and API searches. It also clarifies AFD expectations: tool-first design, structured JSON results, and agent_mode usage for AI-optimized output.

When to use it

  • At the start of any addon development session to load shared context
  • Immediately after making code changes—follow the mandatory reload loop before collecting output
  • Before running tests or linting to ensure you use the correct MCP calls
  • When adding or refactoring core logic, UI, or the bridge layer to map to Fen components
  • Whenever you need consistent, predictable MCP outputs for automation or agents

Best practices

  • Always perform the reload loop: ask user to /reload, wait for confirmation, then call addon.output(agent_mode=true)
  • Keep pure logic in FenCore, UI in FenUI, and event/bridge code in MechanicLib to preserve separation of concerns
  • Use MCP tools first (tool-first): implement CLI/tool behavior before adding any UI layer
  • Pass agent_mode=true to tools when you need AI-optimized, structured JSON responses
  • Rely on env.status() to confirm runtime environment before invoking other tools

Example use cases

  • Verifying a bug fix: modify code, follow reload loop, run addon.output to capture errors and logs
  • Integrating a new feature: place algorithms in FenCore, expose events via MechanicLib, build UI with FenUI components
  • Automated testing: run addon.lint and addon.test via MCP to collect structured results for CI or agents
  • API exploration: use api.search and fencore.search to find functions or utilities to reuse

FAQ

Why must I wait after /reload before calling addon.output?

SavedVariables sync timing is unpredictable. Waiting for user confirmation ensures the game has fully reloaded and the MCP tool will return complete, reliable output.

When should I use agent_mode=true?

Use agent_mode=true whenever you want consistent, AI-friendly JSON results from MCP tools—this enables structured success/data/error responses suited for automation and agents.