Add Events Agent with Figma MCP integration

[Daniel Beer (DanielB945)]

Summary

Created comprehensive Events Agent with two main workflows for discovering, mapping, and validating analytics events.

Structure

agents/events-agent/
├── SKILL.md                                     - Main router
├── map-events/                                  - Event discovery & mapping
│   ├── SKILL.md (362 lines)
│   └── map-events-skill/                        - 🎨 Figma MCP Integration
│       ├── SKILL.md (491 lines)
│       ├── IMPLEMENTATION_RULES.md (276 lines)
│       └── TEMPLATE.md (425 lines)
└── validate-events/                             - Event validation
    ├── SKILL.md (463 lines)
    └── validate-analytics-schemas/
        └── SKILL.md (901 lines)

---

Map Events Agent

General Workflow (map-events/SKILL.md)

• Multi-source event discovery (Figma, code, registry, PRDs)
• Event registry YAML generation
• Routes to specialized Figma workflow when URL provided

Figma MCP Integration (map-events/map-events-skill/)

Two modes:

1. V3 Schema Specification - Full event spec documents

   • Comprehensive FE + BE event documentation
   • Follows LTX Studio V3 schema patterns
   • Outputs to resources/docs/analytics-global-web-v3/

2. Figma Annotation - Quick event mapping

   • Reads Figma designs via MCP
   • Maps UI elements to events
   • Writes event comments directly to Figma (linked to node IDs)
   • Generates event registry YAML

Key Features:

• ✅ Figma MCP integration (ListMcpResourcesTool, read files, post comments)
• ✅ Parses UI elements (buttons, modals, inputs, flows)
• ✅ Maps to V3 events (ui_interacted, flow_started, process_started, be_flow_*)
• ✅ Documents FE→BE event linking (fe_process_id, generation_id)
• ✅ Annotates Figma with 📊 EVENT comments
• ✅ Follows IMPLEMENTATION_RULES.md and TEMPLATE.md

Support Files:

• IMPLEMENTATION_RULES.md - V3 event types, ID linking, required fields
• TEMPLATE.md - V3 specification document template structure

---

Validate Events Agent

Production Validation (validate-events/SKILL.md)

Validates LTX Studio production events:

• Registry vs Production - Compares documented vs firing events
• Data Quality - NULL checks, invalid data, schema issues
• Volume Sanity - Reasonable event counts
• Recency - When events last fired
• Coverage - Missing or undocumented events

Output: Validation report with ✓ OK / ⚠️ Warning / ❌ Critical

V3 Schema Validation (validate-events/validate-analytics-schemas/)

Validates V3 analytics in integration environment:

• Frontend + Backend event validation
• FE↔BE Correlation - fe_process_id linking, generation_id matching
• ID Pairing - flow_started↔flow_ended, process_started↔process_ended
• Required Fields - Non-nullable schema validation
• Recommended Values - ENUM compliance
• Spec-driven - Validates against Event Spec Documents

---

Usage Examples

Map Events from Figma (V3 Spec)

User: "Create V3 analytics spec from https://figma.com/design/ABC123/Camera-Angle"

Flow:
  → Routes to map-events-skill
  → Checks Figma MCP available
  → Reads Figma file via MCP
  → Maps UI elements to V3 events
  → Generates spec following TEMPLATE.md
  → Posts comments to Figma with event docs

Quick Mapping with Figma Annotation

User: "Map events and annotate Figma: https://figma.com/design/XYZ789/New-Feature"

Flow:
  → Uses Figma MCP to read design
  → Identifies trackable elements
  → Creates event registry YAML
  → Posts 📊 EVENT comments to Figma (linked to node IDs)

Validate Production Events

User: "Validate timeline events are firing correctly"

Flow:
  → Queries ltxstudio_user_all_actions table
  → Compares registry vs production
  → Checks data quality, volume, recency
  → Generates validation report

---

Files Changed

New Files (10)

• agents/events-agent/SKILL.md - Main router
• agents/events-agent/map-events/SKILL.md - Event mapping workflow
• agents/events-agent/map-events/map-events-skill/SKILL.md - Figma MCP integration
• agents/events-agent/map-events/map-events-skill/IMPLEMENTATION_RULES.md - V3 rules
• agents/events-agent/map-events/map-events-skill/TEMPLATE.md - V3 spec template
• agents/events-agent/validate-events/SKILL.md - Production validation
• agents/events-agent/validate-events/validate-analytics-schemas/SKILL.md - V3 validation

Updated Files (2)

• CLAUDE.md - Added events-agent routing
• README.md - Added Events Agent documentation

Total: 3,371 insertions

---

Key Features

✅ Figma MCP Integration - Read designs, write annotations, link to node IDs
✅ V3 Analytics Schema - Full spec generation with FE↔BE linking
✅ Event Registry YAML - LTX Studio production event documentation
✅ Multi-source Discovery - Figma, code, registry, PRDs, production
✅ Production Validation - Data quality, volume, recency checks
✅ Integration Testing - V3 schema validation in integration environment
✅ Spec-driven Validation - Test against Event Spec Documents

---

🤖 Generated with Claude Code