CLAUDE

agents/ — Agent Definitions

Agent definitions are data, not code. Each JSON file in this directory defines an AI agent's identity, what data it watches, and what reports it produces. The seed script (pnpm seed) reads all .json files from this directory and inserts them into D1.

Agent Definition Schema

Every agent JSON file must have these fields:

{
  // Identity
  "id": string,           // Unique kebab-case ID (matches filename without .json)
  "name": string,          // Human-readable display name
  "description": string,   // What this agent watches and does (shown in dashboard)

  // Data Sources
  "subscriptions": [       // Which events this agent receives
    {
      "source": string,        // Must match a connector source: "github", "slack", etc.
      "eventTypes": string[],  // Wildcard patterns: "pr.*", "message.*", "*"
      "scopeFilter"?: {        // Optional narrowing (AND logic)
        "org"?: string,
        "project"?: string,
        "team"?: string
      }
    }
  ],

  // Claude's Identity
  "persona": {
    "role": string,            // System prompt identity (1 sentence)
    "instructions": string,    // Detailed analysis guidelines (Markdown, can be long)
    "watchPatterns": string[], // Specific things to flag/escalate
    "outputStyle": string,     // How to format and tone the output
    "voice"?: string,          // Communication style and vocabulary
    "personality"?: string     // Temperament, values, quirks
  },

  // Report Configuration
  "outputs": {
    "reports": [
      {
        "reportType": string,    // Unique type ID: "daily-standup", "daily-metrics-brief"
        "cadence": "daily",
        "sections": string[]     // Section names Claude must include
      }
    ]
  },

  // Capabilities
  "enabled": boolean,          // Whether the agent actively generates reports
  "tools"?: string[],          // Optional: ["query_events", "github_file", "github_search"]

  // Access Control
  "visibility"?: "public" | "exec"  // Default: "public". See "Exec Visibility" below.
}