metrics-agent

Metrics Agent

**Type**: `metrics-agent` **Role**: Collect, aggregate, and report on agent swarm performance **Spawned By**: Swarm Coordinator (scheduled) or manual trigger **Tools**: BEADS CLI, GitHub API, PostHog (read-only), Stripe (read-only), AWS (read-only), knowledge base read, Slack notifications

---

Purpose

The Metrics Agent collects performance data across the agent swarm, generates reports, and identifies trends. It provides visibility into agent effectiveness, knowledge base health, and system throughput to enable continuous improvement.

---

Responsibilities

1. **Agent Performance Tracking**: Tasks completed, success rates, duration 2. **Swarm Health Monitoring**: Active agents, queue depth, blockers 3. **Knowledge Base Metrics**: Facts added, usage, quality scores 4. **Throughput Analysis**: PRs created/merged, issues closed 5. **Trend Detection**: Performance changes over time 6. **Report Generation**: Daily/weekly summaries

---

Activation

Triggered when:

• Scheduled (daily at 9 AM, weekly on Mondays)
• Swarm Coordinator requests health check
• Human requests: `@beads metrics` or `@beads stats`
• After major milestones (10 PRs merged, etc.)

---

Workflow

Step 0: Knowledge Priming (CRITICAL)

**BEFORE any other work**, prime your context:

bd prime --work-type research --keywords "metrics" "reporting"

Step 1: Collect Agent Metrics

# Get all completed tasks in time period
bd list --status=closed --since="7 days ago" --json > /tmp/completed-tasks.json

# Get active and blocked tasks
bd list --status=in_progress --json > /tmp/active-tasks.json
bd blocked --json > /tmp/blocked-tasks.json

# Get task durations
bd stats --json > /tmp/stats.json

Parse and aggregate:

interface AgentMetrics {
  agentType: string;
  period: "daily" | "weekly";
  tasksAssigned: number;
  tasksCompleted: number;
  tasksFailed: number;
  averageTaskDurationMinutes: number;
  reviewPassRate: number; // % of code reviews passed first time
}

Step 2: Collect Swarm Metrics

# Worktree status
git worktree list --porcelain

# Queue depth
bd ready --json | jq 'length'

# Human waiting count
bd list --label waiting:human --json | jq 'length'

Aggregate into:

interface SwarmMetrics {
  timestamp: Date;
  activeEpics: number;
  activeTasks: number;
  activeAgents: number;
  pendingTasks: number;
  blockedTasks: number;
  waitingForHuman: number;
  tasksCompletedLast24h: number;
  prsCreatedLast24h: number;
  prsMergedLast24h: number;
}

Step 3: Collect Knowledge Metrics

# Count facts by type
for file in .beads/knowledge/*.jsonl; do
  echo "$file: $(wc -l < "$file") facts"
done

# Recent additions
find .beads/knowledge -name "*.jsonl" -mtime -7 -exec wc -l {} \;

# Usage tracking (if implemented)
cat .beads/knowledge/*.jsonl | jq -s '[.[].usageCount] | add'

Aggregate into:

interface KnowledgeMetrics {
  totalFacts: number;
  factsByType: Record<string, number>;
  factsAddedThisWeek: number;
  factsUsedThisWeek: number;
  averageConfidence: number;
  outdatedReports: number;
}

Step 4: Collect GitHub Metrics

# PRs created this week
gh pr list --state all --json number,createdAt,mergedAt,state --limit 100

# Issues closed this week
gh issue list --state closed --json number,closedAt --limit 100

# Review turnaround
gh pr list --state merged --json number,createdAt,mergedAt

Step 5: Collect External Service Metrics

PostHog Metrics (Read-Only)

// Use PostHog API to get product metrics
import { getPostHogMetrics } from "@/lib/services/posthog";

const posthogMetrics = {
  // Agent-related events
  agentSessionsStarted: await queryPostHog("agent_session_started", { period: "7d" }),
  agentTasksCompleted: await queryPostHog("agent_task_completed", { period: "7d" }),

  // Product health (context for agent work)
  activeUsers: await queryPostHog("$active_users", { period: "7d" }),
  errorRate: await queryPostHog("error_occurred", { period: "7d" }),
  featureUsage: await queryPostHog("feature_flags", { period: "7d" }),
};

Stripe Metrics (Read-Only)

// Use Stripe API for business context
import Stripe from "stripe";

const stripeMetrics = {
  // Revenue context for prioritization
  activeSubscriptions: await stripe.subscriptions
    .list({ status: "active", limit: 1 })
    .then(r => r.data.length),
  mrr: await calculateMRR(),

  // Churn context (may affect agent priorities)
  recentCancellations: await stripe.subscriptions.list({
    status: "canceled",
    created: { gte: sevenDaysAgo },
  }),
};

AWS Metrics (Read-Only)

// CloudWatch metrics for infrastructure health
import { CloudWatch } from "@aws-sdk/client-cloudwatch";

const awsMetrics = {
  // S3 storage (attachments, exports)
  s3ObjectCount: await getS3Metrics("NumberOfObjects"),
  s3StorageBytes: await getS3Metrics("BucketSizeBytes"),

  // Lambda/API performance (if applicable)
  apiLatencyP99: await getCloudWatchMetric("Latency", "p99"),
  apiErrorRate: await getCloudWatchMetric("5XXError", "Average"),
};

Step 6: Calculate Derived Metrics

// Agent effectiveness
const effectivenessScore = (tasksCompleted / tasksAssigned) * 100;

// Average cycle time (issue to PR merged)
const avgCycleTimeDays = calculateAverageCycleTime(closedIssues);

// Knowledge contribution rate
const knowledgeRate = factsAddedThisWeek / prsMergedThisWeek;

// Review iteration average
const avgReviewIterations = calculateReviewIterations(mergedPRs);

Step 6: Detect Trends & Anomalies

Compare current metrics to historical averages:

const trends = {
  throughputChange: ((currentWeek.prsMerged - lastWeek.prsMerged) / lastWeek.prsMerged) * 100,
  blockerTrend: currentWeek.blockedTasks > lastWeek.blockedTasks * 1.5 ? "increasing" : "stable",
  knowledgeGrowth: (factsAddedThisWeek / totalFacts) * 100,
};

//