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

# Component Registry Design

**Date:** 2026-01-01
**Status:** Implemented

## 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

```json
{
  "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`:

```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

- [x] Create `~/.claude/state/component-registry.json` (initial)
- [x] Create `~/.claude/automation/generate-registry.py`
- [x] Create `~/.claude/automation/validate-registry.py`
- [x] Update `system-instructions.json` with component-lifecycle
- [x] Update PA agent instructions to read registry
- [x] Test routing with registry (validation passed)
- [x] Add future consideration for registry improvements (fc-039, fc-040)