#Agents System Fixes Summary

Date: 2025-12-16 Status: Complete

#Problem

The /agents system had overlapping owned_paths and unowned gaps that made routing ambiguous.

#Overlaps Found

Area	Agents Claiming	Severity
apps/worker-tracker/**	6 agents	High
packages/db/**	5 agents	High
apps/web/**	4 agents	Medium
packages/shared/**	3 agents	Medium
packages/queue/**	2 agents	Low

#Gaps Found

• apps/admin/** — no owner
• apps/storybook/** — no owner
• packages/config/** — no owner

#Solution

Applied 7 fixes to disambiguate ownership using file-level globs instead of directory-level claims.

#Fix 1: apps/worker-tracker/** → Subsystem Partitioning

Agent	New owned_paths
tracker-engineer	apps/worker-tracker/src/**, tests/**
diff-analyst	apps/worker-tracker/src/diff/**, src/meaningful-change/**
cron-scheduler	apps/worker-tracker/src/cron/**, src/scheduler/**
subscription-manager	apps/worker-tracker/src/subscription/**
summarization-safety	apps/worker-tracker/src/summarize/**
queue-sre	apps/worker-tracker/src/queue/**

#Fix 2: packages/db/** → Schema vs Queries

Agent	New owned_paths
db-migration-operator	packages/db/src/schema/**, migrations/**, client.ts, types.ts
render-engineer	packages/db/src/queries/render-*.ts
tracker-engineer	packages/db/src/queries/tracker-*.ts, url-*.ts
subscription-manager	packages/db/src/queries/subscription-*.ts
security-reviewer	packages/db/src/rls/**, policies/**

#Fix 3: apps/web/** → Feature Partitioning

Agent	New owned_paths
ux-page-card-designer	apps/web/src/components/**, app/(dashboard)/**
subscription-manager	apps/web/src/app/api/subscriptions/**, lib/subscriptions/**
security-reviewer	apps/web/src/app/api/**, middleware.ts, lib/auth/**
use-case-note-writer	apps/web/src/content/**, copy/**

#Fix 4: Gap Coverage

Gap	New Owner
apps/admin/**	architect-steward
apps/storybook/**	ci-quality-gatekeeper
packages/config/**	architect-steward

#Fix 5: observability-analyst Scope Alignment

Added paths to match stated mission:

• apps/**/src/logging/**
• apps/**/src/metrics/**

Added non_goal:

• "Modifying business logic to add logging (hand off to domain owner)"

#Fix 6: "How to Choose an Agent" Table

Added 18-row lookup table to README.md mapping file patterns to primary agents.

#Fix 7: Escalation Protocol

Added 4-step multi-agent handoff process:

1. Identify primary owner
2. Sequence secondary agents by dependency
3. Explicit handoff protocol
4. Final verification with architect-steward

#Files Modified

• 14 agent files (updated owned_paths)
• .claude/agents/README.md (added routing guide + escalation protocol)

#Verification

All overlaps resolved. Each repo area now has exactly one primary owner. The routing tests from the original assessment (scenarios A–H) can all be cleanly routed.

#Related

• Full analysis: agents-system-test-report.md