feat(registry): automate component generation and migrate to OCX V2 schema (#315)

* feat(registry): migrate build-registry and registry.jsonc to OCX V2 schema

- Drop ocx: prefix from component types (skill, agent, bundle, profile, plugin)
- Add string shorthand support for file entries (path === target)
- Simplify resolveComponentFilePath to a uniform path.join(PROJECT_ROOT, file.path)
- Remove OCX_TARGET_REWRITES and normalizeTargetPath singularization
- Update schema URL to V2
- Migrate registry.jsonc V1 entries to V2 format

Build script now accepts both string shorthand and {path, target} object entries.
Generated entries (skills/agents) use string shorthand; profile entries keep
object form since their install target differs from source path.

* feat(registry): add generate-registry script with auto-population from filesystem

Generates skill and agent components in registry.jsonc from skills/ and agents/
directories. Bundles, profiles, and plugin entries stay hand-curated; bundles
named 'skills' or 'agents' get their dependencies arrays auto-populated with
all components of the matching type.

- Skill component name = directory basename (with underscores replaced by hyphens)
  to satisfy V2 schema pattern. generate_command -> generate-command.
- Agent component name = 'agent-' + filename stem.
- File entries use V2 string shorthand (path === target).
- Generator exits with error on any component with empty description.
- Excludes .DS_Store, .gitkeep, AGENTS.md, .bak/.tmp/~ files, and node_modules/
  __pycache__/.pytest_cache directories from skill file lists.
- Fresh header comment block written on each generation.

Skill validator updated to derive skill directory from SKILL.md path so unlisted-
file checks work even when component name differs from directory basename due to
sanitization.

Registry now contains 100 components (45 skills + 50 agents + 5 curated).

* feat(registry): remove unused skills and agents symlinks from registry/files/

The build script no longer uses these symlinks \u2014 file paths in registry.jsonc
now resolve directly from the repo root (V2 string shorthand). The symlinks
were left over from earlier path-resolution logic that prepended registry/files/
to component file paths.

registry/files/profiles/ stays untouched \u2014 those are real files that profile
components reference.

* feat(registry): add --check drift mode and wire into CI build job

The generator now supports --check that exits 0 if registry.jsonc matches what
would be generated, exit 1 otherwise. Trailing whitespace is normalized before
comparison to avoid false positives.

CI build job runs `bun scripts/generate-registry.ts --check` after the content-
integrity gate. Adding a new skill or agent without regenerating the registry
will now block the build automatically.

* test(registry): add 29-test suite for generator + match Biome JSON formatting

Tests cover:
- sanitizeComponentName underscore->hyphen transformation
- isExcludedFile (.DS_Store, .gitkeep, AGENTS.md, .bak/.tmp/~, node_modules)
- countComponents and normalizeForCompare helpers
- Skill discovery with files, references/, templates/ structure
- Agent discovery with agent- prefix
- Curated entry preservation (bundle/profile/plugin) with V1 to V2 type migration
- Bundle dependency auto-population for skills/agents bundles only
- Component sort order: generated alphabetical, then curated
- Fresh header comment block (does not preserve V1-era stale comments)
- Empty-description error path for skills and agents
- Idempotence and drift detection

Refactored the generator to accept rootDir as a parameter so tests can use
synthetic temp-dir fixtures without mocking the filesystem. main() guards
the script-only entry point with import.meta.main.

The generator now inlines single-element string arrays in its output to match
Biome's JSON formatter, keeping the drift check stable under bun run lint.

Also fixed a pre-existing useOptionalChain warning in skills/onboarding/scripts/
inventory.mjs that biome auto-fix surfaced.

* fix(registry): address Fro Bot review feedback on PR #315

Blocking:
- Replace GenerationError class with a tagged-error factory function and
  isGenerationError type guard. Keeps the codebase class-free per project
  convention.

Non-blocking improvements:
- Replace inlineSingleStringArrays regex with a real Biome subprocess call
  (`biome format --stdin-file-path`). Generator output now inherits any
  future Biome formatting changes for free instead of duplicating the
  inlining heuristic. Also drops the regex's brittleness if Biome's
  line-length threshold ever changes.
- normalizeForCompare now strips CRLF before trailing whitespace so the
  drift check works on Windows / git autocrlf checkouts.
- Add a regression test that round-trips generator output through Biome
  and asserts byte-identical equality, catching future Biome format
  changes before the drift check ever sees them.

Author: marcusrbrown

.github/workflows/main.yaml

@@ -62,6 +62,9 @@ jobs:
       - name: Content integrity gate
         run: bun scripts/content-integrity.ts
 
+      - name: Registry drift check
+        run: bun scripts/generate-registry.ts --check
+
   typecheck:
     name: Typecheck
     runs-on: ubuntu-latest

registry/files/agents

@@ -4,7 +4,14 @@ import { execSync } from 'node:child_process'
  * Build OCX Registry
  *
  * Reads registry/registry.jsonc, validates all referenced files exist,
- * and produces dist/registry/ output following OCX Registry Protocol v1.
+ * and produces dist/registry/ output following OCX Registry Protocol v2.
+ *
+ * V2 schema differences from V1:
+ *   - Component types are unprefixed (`skill`, `agent`, `bundle`, `profile`, `plugin`) — no `ocx:` prefix
+ *   - File entries are repo-root-relative paths
+ *   - File entries support string shorthand (path === target) in addition to {path, target} objects
+ *   - No `.opencode/` prefix on targets — OCX CLI auto-resolves install location by component type
+ *   - No singularization rewrites (V2 accepts plural target prefixes like `agents/`, `skills/`)
  *
  * Usage:
  *   bun scripts/build-registry.ts                    # Full build
@@ -30,16 +37,30 @@ interface RegistryFile {
   target: string
 }
 
+/**
+ * V2 file entries can be either:
+ *   - A {path, target} object when source and target paths differ (e.g., profiles)
+ *   - A string shorthand when source path equals target path (e.g., generated skills/agents)
+ */
+type RegistryFileEntry = RegistryFile | string
+
 interface RegistryComponent {
   name: string
   type: string
   version: string
   description?: string
-  files?: RegistryFile[]
+  files?: RegistryFileEntry[]
   dependencies?: string[]
   opencode?: Record<string, unknown>
 }
 
+function normalizeFileEntry(entry: RegistryFileEntry): RegistryFile {
+  if (typeof entry === 'string') {
+    return { path: entry, target: entry }
+  }
+  return entry
+}
+
 interface RegistrySource {
   $schema?: string
   name: string
@@ -175,32 +196,14 @@ function loadRegistrySource(): RegistrySource {
 }
 
 /**
- * Maps a component's file entry to its actual disk location.
- * Skills use paths relative to skills/{name}/, agents/commands use project-root-relative paths.
+ * Resolves a V2 file entry to its actual disk location.
+ * V2 file paths are always repo-root-relative regardless of component type.
  */
 function resolveComponentFilePath(
-  component: RegistryComponent,
+  _component: RegistryComponent,
   file: RegistryFile,
 ): string {
-  const type = component.type
-
-  if (type === 'ocx:skill') {
-    return path.join(PROJECT_ROOT, 'skills', component.name, file.path)
-  }
-
-  if (type === 'ocx:agent') {
-    return path.join(PROJECT_ROOT, file.path)
-  }
-
-  if (type === 'ocx:command') {
-    return path.join(PROJECT_ROOT, file.path)
-  }
-
-  if (type === 'ocx:profile') {
-    return path.join(PROJECT_ROOT, 'registry/files', file.path)
-  }
-
-  return path.join(PROJECT_ROOT, 'registry/files', file.path)
+  return path.join(PROJECT_ROOT, file.path)
 }
 
 function validateRegistry(source: RegistrySource): string[] {
@@ -211,13 +214,13 @@ function validateRegistry(source: RegistrySource): string[] {
     string,
     (component: RegistryComponent, errors: string[]) => void
   > = {
-    'ocx:skill': validateSkillComponent,
-    'ocx:agent': validateFileComponent,
-    'ocx:command': validateFileComponent,
-    'ocx:bundle': (component, currentErrors) =>
+    skill: validateSkillComponent,
+    agent: validateFileComponent,
+    command: validateFileComponent,
+    bundle: (component, currentErrors) =>
       validateBundleComponent(component, source, currentErrors),
-    'ocx:profile': validateProfileComponent,
-    'ocx:plugin': () => undefined,
+    profile: validateProfileComponent,
+    plugin: () => undefined,
   }
 
   for (const component of source.components) {
@@ -251,12 +254,15 @@ function validateSkillComponent(
     return
   }
 
-  const hasSkillMd = component.files.some((f) => f.path === 'SKILL.md')
-  if (!hasSkillMd) {
+  const normalizedFiles = component.files.map(normalizeFileEntry)
+  const skillMdFile = normalizedFiles.find(
+    (f) => f.path === 'SKILL.md' || f.path.endsWith('/SKILL.md'),
+  )
+  if (skillMdFile == null) {
     errors.push(`${prefix} Skill component missing SKILL.md`)
   }
 
-  for (const file of component.files) {
+  for (const file of normalizedFiles) {
     const diskPath = resolveComponentFilePath(component, file)
     if (!fs.existsSync(diskPath)) {
       errors.push(
@@ -265,15 +271,21 @@ function validateSkillComponent(
     }
   }
 
-  const skillDir = path.join(PROJECT_ROOT, 'skills', component.name)
+  // Derive the skill directory from the SKILL.md location so unlisted-file checks
+  // work regardless of any directory-name → component-name sanitization (e.g.,
+  // skills/generate_command/ → component name "generate-command").
+  if (skillMdFile == null) return
+  const skillDir = path.join(PROJECT_ROOT, path.dirname(skillMdFile.path))
   if (fs.existsSync(skillDir)) {
     const diskFiles = walkFiles(skillDir)
-    const declaredPaths = new Set(component.files.map((f) => f.path))
+    const declaredPaths = new Set(normalizedFiles.map((f) => f.path))
 
     for (const diskFile of diskFiles) {
-      const rel = path.relative(skillDir, diskFile)
-      if (!declaredPaths.has(rel)) {
-        errors.push(`${prefix} Unlisted file in skill directory: ${rel}`)
+      const repoRelative = path.relative(PROJECT_ROOT, diskFile)
+      if (!declaredPaths.has(repoRelative)) {
+        errors.push(
+          `${prefix} Unlisted file in skill directory: ${repoRelative}`,
+        )
       }
     }
   }
@@ -290,7 +302,8 @@ function validateFileComponent(
     return
   }
 
-  for (const file of component.files) {
+  const normalizedFiles = component.files.map(normalizeFileEntry)
+  for (const file of normalizedFiles) {
     if (!file.path.endsWith('.md')) {
       errors.push(`${prefix} File should be .md: ${file.path}`)
     }
@@ -315,7 +328,8 @@ function validateProfileComponent(
     return
   }
 
-  for (const file of component.files) {
+  const normalizedFiles = component.files.map(normalizeFileEntry)
+  for (const file of normalizedFiles) {
     const diskPath = resolveComponentFilePath(component, file)
     if (!fs.existsSync(diskPath)) {
       errors.push(
@@ -368,21 +382,6 @@ function walkFiles(dir: string): string[] {
   return results
 }
 
-/** OCX requires singular directory names for agent/command targets */
-const OCX_TARGET_REWRITES: ReadonlyArray<[RegExp, string]> = [
-  [/^\.opencode\/agents\//, '.opencode/agent/'],
-  [/^\.opencode\/commands\//, '.opencode/command/'],
-]
-
-function normalizeTargetPath(target: string): string {
-  for (const [pattern, replacement] of OCX_TARGET_REWRITES) {
-    if (pattern.test(target)) {
-      return target.replace(pattern, replacement)
-    }
-  }
-  return target
-}
-
 /** SHA-256 integrity: sha256-{base64(digest)} per OCX spec */
 function computeIntegrity(content: Buffer): string {
   const hash = createHash('sha256').update(content).digest('base64')
@@ -409,9 +408,9 @@ function buildRegistry(source: RegistrySource, version: string): void {
 
     if (Array.isArray(component.files) && component.files.length > 0) {
       buildPackument(component, version)
-    } else if (component.type === 'ocx:bundle') {
+    } else if (component.type === 'bundle') {
       buildBundlePackument(component, version)
-    } else if (component.type === 'ocx:plugin') {
+    } else if (component.type === 'plugin') {
       buildPluginPackument(component, version)
     }
   }
@@ -434,7 +433,8 @@ function buildPackument(component: RegistryComponent, version: string): void {
   const files = component.files ?? []
   const packumentFiles: PackumentFile[] = []
 
-  for (const file of files) {
+  for (const entry of files) {
+    const file = normalizeFileEntry(entry)
     const sourcePath = resolveComponentFilePath(component, file)
     let content: Buffer
     try {
@@ -446,7 +446,7 @@ function buildPackument(component: RegistryComponent, version: string): void {
 
     packumentFiles.push({
       path: file.path,
-      target: normalizeTargetPath(file.target),
+      target: file.target,
       integrity,
     })