Skip to content

CLAUDE.md

Latest commit

 

History

History
80 lines (59 loc) · 4.08 KB

CLAUDE.md

File metadata and controls

80 lines (59 loc) · 4.08 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Repo Is

Lumen is a Claude AI agent framework — a Product Management AI co-pilot system that runs as a Claude Code plugin. It is NOT a traditional web application. The core artifacts are Markdown agent definition files (in agents/), not source code. Node.js scripts exist only for validation and simulation.

Commands

npm install                         # Install dependencies (js-yaml, glob, @anthropic-ai/sdk)
npm run validate                    # Static validation of all agents/*.md frontmatter + sections
npm run simulate                    # Smoke test: run W1 orchestrator against fixture data
node scripts/run_with_claude.js     # Live API call against Anthropic (requires ANTHROPIC_API_KEY)
node scripts/list_anthropic_models.js  # List available models via API

Prerequisites for simulation:

  • lumen-setup.json must exist (copy from lumen-setup.example.json) and have mcp_connections.posthog set
  • tests/fixtures/eventiq_output.json must exist (already in repo)

There is no linter or formatter configured.

Architecture

Agent-as-Markdown Pattern

Each agent is a .md file in agents/ with:

  • YAML frontmatter: name, display_name, model, layer, tier_gate, oversight_level, mcp_servers
  • Markdown sections: behavior instructions, required/optional context slots, output format, evidence quality logic

The scripts/validate_agents.js script checks all agent files for required frontmatter fields and sections.

Context Slot System

Agents communicate exclusively through named "context slots" — 51 canonical slots defined in schemas/context-slots.md. Each agent declares which slots it requires (blocks if absent) and which it optionally reads (improves output quality). Agents also write new slots that downstream agents consume.

Orchestrator Pattern

agents/orchestrator.md is the runtime entry point for all workflows. It:

  1. Sequences sub-agents based on workflow type (W1–W6)
  2. Enforces tier gates and human approval at oversight_level 2+
  3. Aggregates evidence_quality across agents (lowest rating wins)
  4. Detects cross-agent conflicts and generates final reports

Six Workflows

ID Workflow Key Constraint
W1 PMF Discovery PostHog required for PMF scoring; runs PARTIAL without it (v2.3)
W2 PMF Recovery / Churn Crisis —
W3 Strategy —
W4 Feature Validation DataLayer ethics checkpoint required
W5 Launch —
W6 Churn —

MCP Integration

Agents declare required MCP servers in frontmatter. When a server is unavailable, agents degrade gracefully (skip KG writes, use lower evidence quality).

MCP servers: posthog, supabase, hubspot, upstash, slack, stripe, figma, github, sentry, postman

PostHog enables PMF scoring in W1; W1 runs in PARTIAL mode without it (v2.3 — not a hard block).

Knowledge Graph

Analytical results are persisted to Supabase as 15 entity types (UserSegment, Opportunity, Persona, Experiment, Feature, Decision, Metric, etc.). All KG writes are silently skipped when Supabase is not connected.

Model Assignment

  • claude-sonnet-4-6: Orchestrator, DataLayer, and all Growth/Scale/Enterprise-tier agents (complex reasoning)
  • claude-haiku-4-5: EventIQ, SignalMonitor, DiscoveryOS, NorthStar, SetupGuide (high-frequency Starter workers)

Key Files

Path Purpose
agents/orchestrator.md Master agent — sequences all workflows
agents/*.md Individual sub-agents (one per analytical domain)
schemas/context-slots.md Canonical table of all 51 context slots
lumen-setup.example.json Project config template (copy to lumen-setup.json, fill in credentials)
skills/*.md Reusable knowledge modules loaded by agents
scripts/validate_agents.js CI validation script
.env.example Required environment variable template

See reports/findings_summary.md for historical findings (all resolved as of 2026-03-12).