aios-core/.aios-core/core/registry/README.md

Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework

# AIOS Service Registry

The Service Registry is the central catalog of all workers, tasks, templates, scripts, and workflows in the AIOS framework. It enables service discovery, search, and reuse across the system.

## Overview

- **Total Workers:** 200+ cataloged services
- **Categories:** task, template, script, checklist, workflow, data
- **Performance:** < 500ms load time with caching
- **Format:** JSON with schema validation

## Files

| File | Description |
|------|-------------|
| `service-registry.json` | Main registry with all workers |
| `registry-schema.json` | JSON Schema for validation |
| `registry-loader.js` | Load and query registry (with caching) |
| `build-registry.js` | Build registry from source files |
| `validate-registry.js` | Validate registry and run smoke tests |

## Quick Start

### Loading the Registry

```javascript
const { getRegistry, loadRegistry } = require('.aios-core/core/registry/registry-loader');

// Quick load
const registry = await loadRegistry();
console.log(`Loaded ${registry.totalWorkers} workers`);

// Or use the class for more control
const reg = getRegistry();
await reg.load();
```

### Querying Workers

```javascript
const registry = getRegistry();

// Get by ID
const worker = await registry.getById('create-story');

// Get by category
const tasks = await registry.getByCategory('task');

// Get by tag
const devTasks = await registry.getByTag('development');

// Get by multiple tags (AND)
const qaDevTasks = await registry.getByTags(['testing', 'development']);

// Get workers for an agent
const devWorkers = await registry.getForAgent('dev');

// Search
const results = await registry.search('validate', { maxResults: 10 });
```

### Registry Info

```javascript
const registry = getRegistry();

// Get metadata
const info = await registry.getInfo();
// { version, generated, totalWorkers, categories }

// Get category summary
const categories = await registry.getCategories();

// Get all tags
const tags = await registry.getTags();

// Check worker count
const count = await registry.count();
```

## Building the Registry

Rebuild the registry after adding new workers:

```bash
node .aios-core/core/registry/build-registry.js
```

The builder scans:
- `.aios-core/development/tasks/**/*.md` → task
- `.aios-core/product/templates/**/*.md` → template
- `.aios-core/infrastructure/scripts/**/*.js` → script
- `.aios-core/product/checklists/**/*.md` → checklist
- `.aios-core/development/workflows/**/*.yaml` → workflow
- `.aios-core/core/data/**/*` → data

## Validating the Registry

Run validation and smoke tests:

```bash
node .aios-core/core/registry/validate-registry.js
```

### Smoke Tests

| Test | Priority | Description |
|------|----------|-------------|
| REG-01 | P0 | Registry loads without errors |
| REG-02 | P0 | Registry validates against schema |
| REG-03 | P0 | Registry has 97+ workers |
| REG-04 | P1 | All paths point to existing files |
| REG-05 | P1 | All IDs are unique |
| REG-06 | P1 | Registry loads in < 500ms |

## Worker Entry Schema

Each worker entry contains:

```json
{
  "id": "create-story",
  "name": "Create Story",
  "description": "Creates a new user story from template",
  "category": "task",
  "subcategory": "creation",
  "inputs": ["story-title", "epic-id"],
  "outputs": ["story-file-path"],
  "tags": ["task", "creation", "story", "product"],
  "path": ".aios-core/development/tasks/po-create-story.md",
  "taskFormat": "TASK-FORMAT-V1",
  "executorTypes": ["Agent", "Worker"],
  "performance": {
    "avgDuration": "1m",
    "cacheable": false,
    "parallelizable": false
  },
  "agents": ["po"],
  "metadata": {
    "source": "development",
    "addedVersion": "1.0.0"
  }
}
```

## Caching

The registry loader implements:
- **TTL Cache:** 5 minutes default
- **Indexed Lookups:** O(1) by ID, category, tag
- **Lazy Loading:** Registry loaded on first query
- **Manual Refresh:** `registry.load(true)` forces reload
- **Cache Clear:** `registry.clearCache()`

## Categories

| Category | Description | Count |
|----------|-------------|-------|
| task | Executable task workflows | ~115 |
| template | Document and code templates | ~19 |
| script | JavaScript utility scripts | ~54 |
| checklist | Quality validation checklists | ~6 |
| workflow | Multi-step workflow definitions | ~6 |
| data | Knowledge base and config | ~3 |

## Integration

The registry integrates with:
- **Discovery CLI** (Story 2.7-2.9): `aios search`, `aios info`, `aios list`
- **Manifest System** (Story 2.13): Worker dependencies
- **Agent Loading**: Worker assignment to agents

## Story Reference

Created in [Story 2.6 - Service Registry Creation](../../../../docs/stories/v4.0.4/sprint-2/story-2.6-service-registry.md)

---

*Generated by AIOS Framework v4.0.4*