claude-code/plans/2026-01-01-component-registry-design.md

Component Registry Design

Date: 2026-01-01 Status: Approved

Overview

Build a component registry that PA reads at session start for routing awareness. Ensures PA knows all skills, commands, agents, and workflows immediately without discovery latency.

Goals

• Session awareness — PA knows all components at session start
• Accurate routing — Match user requests to correct components via triggers
• Maintenance discipline — Auto-generation + validation keeps registry in sync

Architecture

Component directories          Registry                    PA Session
─────────────────────         ─────────                   ──────────
skills/*/SKILL.md      ──┐
commands/**/*.md       ──┼──► generate-registry.py ──► component-registry.json
agents/*.md            ──┤                                    │
workflows/**/*.yaml    ──┘                                    ▼
                              validate-registry.py       Read at init
                                     │                        │
                                     ▼                        ▼
                              Warns on drift             Route requests

Components

File	Purpose
~/.claude/state/component-registry.json	Registry (read at session start)
~/.claude/automation/generate-registry.py	Auto-generate skeleton
~/.claude/automation/validate-registry.py	Check for drift
system-instructions.json	Component lifecycle rules

Registry Format

{
  "version": "1.0",
  "generated": "2026-01-01T22:30:00-08:00",
  "skills": {
    "gmail": {
      "description": "Email read access",
      "triggers": ["email", "gmail", "inbox", "unread"]
    },
    "gcal": {
      "description": "Calendar read access",
      "triggers": ["calendar", "schedule", "meeting", "event"]
    }
  },
  "commands": {
    "/gcal": {
      "description": "Google Calendar access",
      "aliases": ["/calendar", "/cal"]
    },
    "/usage": {
      "description": "View usage statistics",
      "aliases": ["/stats"]
    }
  },
  "agents": {
    "linux-sysadmin": {
      "description": "Workstation management",
      "triggers": ["system", "linux", "package", "service"]
    }
  },
  "workflows": {
    "health/cluster-health-check": {
      "description": "K8s cluster health check",
      "triggers": ["cluster health", "k8s status"]
    }
  }
}

Field Definitions

Field	Purpose
description	One-liner for context
triggers	Keywords that suggest this component (routing)
aliases	Alternate command names
status	Optional: "removed" for stale entries

Auto-Generation Script

~/.claude/automation/generate-registry.py:

• Scans component directories
• Extracts names and descriptions from frontmatter
• Preserves existing manual hints (triggers)
• Adds "triggers": ["TODO"] for new components
• Marks removed components as "status": "removed"

Scan Paths

Directory	Component Type
~/.claude/skills/*/SKILL.md	skills
~/.claude/commands/**/*.md	commands
~/.claude/agents/*.md	agents
~/.claude/workflows/**/*.yaml	workflows

Validation Script

~/.claude/automation/validate-registry.py:

Checks

1. All components in directories are in registry
2. All registry entries still exist on disk
3. No "TODO" placeholders remaining
4. Warns on stale entries (status: removed)

Output Example

Registry Validation
✓ 6 skills: all present
✓ 10 commands: all present
✗ 1 agent missing: new-agent (add to registry)
⚠ 1 stale entry: old-agent (marked removed)

Component Lifecycle

Add to system-instructions.json:

{
  "component-lifecycle": {
    "add": [
      "Create component file",
      "Run generate-registry.py",
      "Add triggers/hints to registry",
      "Commit both files"
    ],
    "remove": [
      "Remove component file",
      "Run generate-registry.py (marks as removed)",
      "Commit updated registry"
    ],
    "validate": [
      "Run validate-registry.py",
      "Fix any warnings before commit"
    ]
  }
}

PA Session Initialization

Update PA agent to read registry at session start:

Read these state files before executing tasks:
...
~/.claude/state/component-registry.json    # Component index for routing

Routing Logic

1. User request received
2. Scan registry triggers for keyword matches
3. Match found → invoke corresponding component
4. No match → ask for clarification or use general reasoning

Example

User: "what's on my calendar tomorrow?"
       │
       ▼
Scan triggers: "calendar" matches gcal.triggers
       │
       ▼
Invoke skill:gcal with context "tomorrow"

Implementation Checklist

• Create ~/.claude/state/component-registry.json (initial)
• Create ~/.claude/automation/generate-registry.py
• Create ~/.claude/automation/validate-registry.py
• Update system-instructions.json with component-lifecycle
• Update PA agent instructions to read registry
• Test routing with registry
• Add future consideration for registry improvements