AIOX Service Discovery Guide

EN | PT | ES

How to discover, query, and use workers in the AIOX framework.

Version: 2.1.0 Last Updated: 2025-12-01

Overview

The Service Discovery system enables finding and using workers (tasks, templates, scripts, workflows) across the AIOX framework. The Service Registry is the central catalog containing metadata about all available workers.

Key Concepts

| Concept | Description | | -------------------- | -------------------------------------------------------------------------- | | Worker | Any executable unit: task, template, script, workflow | | Service Registry | Central catalog of all workers with metadata | | Category | Worker type: task, template, script, checklist, workflow, data | | Tag | Searchable label for grouping workers |

Service Registry API

Loading the Registry

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

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

// Full loader with methods
const reg = getRegistry();
await reg.load();

Querying Workers

Get by ID

const registry = getRegistry();
const worker = await registry.getById('create-story');

console.log(worker);
// {
//   id: 'create-story',
//   name: 'Create Story',
//   category: 'task',
//   path: '.aiox-core/development/tasks/po-create-story.md',
//   tags: ['task', 'creation', 'story', 'product'],
//   agents: ['po']
// }

Get by Category

// Get all tasks
const tasks = await registry.getByCategory('task');
console.log(`Found ${tasks.length} tasks`);

// Get all templates
const templates = await registry.getByCategory('template');

Get by Tag

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

// Multiple tags (AND logic)
const qaDevTasks = await registry.getByTags(['testing', 'development']);

Get Workers for Agent

// Get all workers assigned to the dev agent
const devWorkers = await registry.getForAgent('dev');

// Get workers for multiple agents
const teamWorkers = await registry.getForAgents(['dev', 'qa']);

Search

// Text search across worker names and descriptions
const results = await registry.search('validate', { maxResults: 10 });

// Search within category
const taskResults = await registry.search('story', {
  category: 'task',
  maxResults: 5,
});

Registry Information

const registry = getRegistry();

// Get metadata
const info = await registry.getInfo();
// { version: '1.0.0', generated: '2025-12-01', totalWorkers: 203 }

// Get category summary
const categories = await registry.getCategories();
// { task: 115, template: 52, script: 55, ... }

// Get all tags
const tags = await registry.getTags();
// ['task', 'creation', 'story', 'testing', ...]

// Count workers
const count = await registry.count();
// 203

CLI Commands

`aiox discover`

Search for workers in the registry.

# Search by text
aiox discover "create story"

# Search by category
aiox discover --category task

# Search by tag
aiox discover --tag testing

# Search for agent
aiox discover --agent dev

# Combine filters
aiox discover --category task --tag development --agent dev

Output:

Found 5 workers matching "create story":

  [task] po-create-story
         Path: .aiox-core/development/tasks/po-create-story.md
         Tags: task, creation, story, product
         Agents: po

  [task] dev-create-brownfield-story
         Path: .aiox-core/development/tasks/dev-create-brownfield-story.md
         Tags: task, creation, brownfield
         Agents: dev

  ...

`aiox info`

Get detailed information about a specific worker.

# Get worker info by ID
aiox info create-story

# Get worker info with full path
aiox info --path .aiox-core/development/tasks/po-create-story.md

Output:

Worker: create-story
========================
Name:        Create Story
Category:    task
Path:        .aiox-core/development/tasks/po-create-story.md

Description:
  Creates a new user story from template with proper formatting
  and acceptance criteria.

Inputs:
  - story-title (string, required)
  - epic-id (string, optional)
  - priority (string, optional)

Outputs:
  - story-file-path (string)

Tags:
  task, creation, story, product

Agents:
  po

Performance:
  Avg Duration: 1m
  Cacheable: No
  Parallelizable: No

`aiox list`

List workers by category or agent.

# List all tasks
aiox list tasks

# List all templates
aiox list templates

# List workers for agent
aiox list --agent dev

# List with pagination
aiox list tasks --page 1 --limit 20

Service Types

Tasks

Executable workflow definitions for agents.

# Example task structure
task:
  name: create-story
  version: 1.0.0
  description: 'Creates a new user story'

inputs:
  - name: story-title
    type: string
    required: true

outputs:
  - name: story-file-path
    type: string

steps:
  - name: gather-requirements
    action: elicit
  - name: generate-story
    action: template-render

Location: .aiox-core/development/tasks/

Templates

Document and code templates for generation.

| Template | Purpose | | -------------------------- | ------------------------- | | story-tmpl.yaml | Story document template | | prd-tmpl.yaml | PRD template | | architecture-tmpl.yaml | Architecture doc template | | component-react-tmpl.tsx | React component template | | ide-rules/*.md | IDE-specific rules |

Location: .aiox-core/product/templates/

Scripts

JavaScript utilities for automation.

| Script | Purpose | | --------------------- | ------------------------- | | backup-manager.js | Backup/restore operations | | template-engine.js | Template processing | | git-wrapper.js | Git operations | | security-checker.js | Security validation |

Location: .aiox-core/infrastructure/scripts/

Workflows

Multi-step development processes.

| Workflow | Use Case | | --------------------------- | ----------------------------- | | greenfield-fullstack.yaml | New full-stack project | | brownfield-fullstack.yaml | Existing project enhancement | | greenfield-service.yaml | New backend service | | brownfield-ui.yaml | Existing frontend enhancement |

Location: .aiox-core/development/workflows/

Checklists

Quality validation checklists.

| Checklist | Purpose | | ------------------------ | ------------------------ | | story-dod-checklist.md | Story Definition of Done | | pre-push-checklist.md | Pre-push validation | | architect-checklist.md | Architecture review | | release-checklist.md | Release validation |

Location: .aiox-core/product/checklists/

Worker Registration

Automatic Registration

Workers are automatically registered when the registry is built:

# Rebuild registry
node .aiox-core/core/registry/build-registry.js

The builder scans:

.aiox-core/development/tasks/**/*.md
.aiox-core/product/templates/**/*
.aiox-core/infrastructure/scripts/**/*.js
.aiox-core/product/checklists/**/*.md
.aiox-core/development/workflows/**/*.yaml
.aiox-core/core/data/**/*

Worker Entry Schema

{
  "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": ".aiox-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 intelligent caching:

| Feature | Description | | ------------------- | --------------------------------------- | | TTL Cache | 5 minutes default expiration | | Indexed Lookups | O(1) by ID, category, tag | | Lazy Loading | Registry loaded on first query | | Manual Refresh | Force reload with registry.load(true) |

Cache Operations

const registry = getRegistry();

// Force reload (bypass cache)
await registry.load(true);

// Clear cache
registry.clearCache();

// Check if cached
const isCached = registry.isCached();

Code Examples

Find All Tasks for an Agent

const { getRegistry } = require('./.aiox-core/core/registry/registry-loader');

async function getAgentTasks(agentId) {
  const registry = getRegistry();
  const tasks = await registry.getForAgent(agentId);

  return tasks.filter((w) => w.category === 'task');
}

// Usage
const devTasks = await getAgentTasks('dev');
console.log(`Dev agent has ${devTasks.length} tasks`);

Search and Execute Task

const { getRegistry } = require('./.aiox-core/core/registry/registry-loader');
const { TaskExecutor } = require('./.aiox-core/development/scripts/task-executor');

async function findAndExecute(searchTerm, inputs) {
  const registry = getRegistry();
  const results = await registry.search(searchTerm, {
    category: 'task',
    maxResults: 1,
  });

  if (results.length === 0) {
    throw new Error(`No task found for: ${searchTerm}`);
  }

  const task = results[0];
  const executor = new TaskExecutor(task.path);
  return executor.execute(inputs);
}

// Usage
await findAndExecute('create story', {
  'story-title': 'Implement user authentication',
  'epic-id': 'EPIC-001',
});

List Workers by Category

const { getRegistry } = require('./.aiox-core/core/registry/registry-loader');

async function listByCategory() {
  const registry = getRegistry();
  const categories = await registry.getCategories();

  for (const [category, count] of Object.entries(categories)) {
    console.log(`${category}: ${count} workers`);
  }
}

// Output:
// task: 115 workers
// template: 52 workers
// script: 55 workers
// checklist: 11 workers
// workflow: 7 workers
// data: 3 workers

Troubleshooting

Registry Not Loading

# Verify registry file exists
ls .aiox-core/core/registry/service-registry.json

# Rebuild registry
node .aiox-core/core/registry/build-registry.js

# Validate registry
node .aiox-core/core/registry/validate-registry.js

Worker Not Found

Check worker file exists in expected location
Verify file has proper YAML frontmatter
Rebuild registry to include new workers
Check category and tags in search query

Performance Issues

// Check cache status
const registry = getRegistry();
console.log('Cached:', registry.isCached());

// Clear cache if stale
registry.clearCache();
await registry.load(true);