Add component registry design

Design for session-aware component registry: - PA reads registry at session start for routing awareness - Auto-generation script scans directories for components - Validation script checks for drift - Manual triggers/hints for intelligent routing - Component lifecycle process in system-instructions.json 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-31 23:58:30 -08:00
parent 0e1e47d577
commit 2772a6e512
1 changed files with 193 additions and 0 deletions
--- a/plans/2026-01-01-component-registry-design.md
+++ b/plans/2026-01-01-component-registry-design.md
@@ -0,0 +1,193 @@
+# 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
+
+```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
+
+- [ ] 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