Overview

Extension architecture

Extension System Overview

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

AIWG's unified extension system provides a single schema for all extension types, enabling dynamic discovery, semantic search, and cross-platform deployment.

References:

  • @src/extensions/types.ts - Core type definitions
  • `@.aiwg/architecture/unified-extension-schema.md` - Complete schema documentation
  • @src/extensions/commands/definitions.ts - Example command extensions

What Are Extensions?

Extensions are the building blocks of AIWG frameworks and addons. They include:

TypePurposeExamples
agentSpecialized AI personasAPI Designer, Test Engineer
skillPrimary workflow extension — NL-triggered, deployed nativelyProject awareness, voice application, agent loop
commandDeployment artifact generated from skill sources; also CLI entry points`/mention-wire`, the agent-owned use operation
hookLifecycle event handlersPre-session setup, post-write validation
toolExternal utilitiesgit, jq, npm
mcp-serverMCP protocol serversAIWG MCP server
frameworkComplete workflowsSDLC Complete, Marketing Kit, Media Curator, Research Complete
addonFeature bundlesVoice Framework, Testing Quality
templateDocument templatesUse case template, ADR template
promptReusable promptsCode review, security audit
soulAgent identity and character (worldview, opinions, vocabulary)Project SOUL.md, agent-scoped `.soul.md`
behaviorReactive capabilities with hooks, scripts, and structured inputsBuild monitor, security sentinel, concierge
teamMulti-agent compositions with roles, dispatch mode, and handoffsAPI development, full-stack, security review

Skills are the canonical source type for agentic workflows. When you author a `SKILL.md`, AIWG deploys it natively for providers that support skills and generates a corresponding command file for providers that need it. Use the agent-owned add-skill operation to create new workflows; the agent-owned add-command operation is for advanced direct-command authoring only.

Unified Schema

All extensions share a common structure:

interface Extension {
  // Core identity
  id: string;                       // Unique identifier (kebab-case)
  type: ExtensionType;              // Extension type
  name: string;                     // Human-readable name
  description: string;              // Brief description
  version: string;                  // Semantic version

  // Discovery & classification
  capabilities: string[];           // What it can do
  keywords: string[];               // Search terms
  category?: string;                // Hierarchical category

  // Platform & deployment
  platforms: PlatformCompatibility; // Which platforms it supports
  deployment: DeploymentConfig;     // Where and how to deploy

  // Dependencies
  requires?: string[];              // Required extensions
  recommends?: string[];            // Optional enhancements
  conflicts?: string[];             // Incompatible extensions
  systemDependencies?: Record<string, string>; // CLI tools, etc.

  // Type-specific metadata
  metadata: ExtensionMetadata;      // Agent/Command/Skill/etc. specific data
}

Extension Types

Agent Extensions

Specialized AI personas with defined roles, tools, and workflows.

Metadata:

interface AgentMetadata {
  role: string;                     // e.g., "API Design and Contract Definition"
  model: {
    tier: 'haiku' | 'sonnet' | 'opus';
    override?: string;
  };
  tools: string[];                  // e.g., ["Read", "Write", "Bash"]
  workflow?: string[];              // Step-by-step process
  expertise?: string[];             // Areas of expertise
  responsibilities?: string[];      // What this agent does
}

Example:

{
  id: 'api-designer',
  type: 'agent',
  name: 'API Designer',
  description: 'Defines API styles, endpoints, and data contracts',
  capabilities: ['api-design', 'interface-contracts', 'rest'],
  metadata: {
    type: 'agent',
    role: 'API Design and Contract Definition',
    model: { tier: 'sonnet' },
    tools: ['Read', 'Write', 'Glob', 'Grep']
  }
}

Command Extensions

CLI and slash commands with argument parsing and execution logic.

Metadata:

interface CommandMetadata {
  template: 'utility' | 'transformation' | 'orchestration';
  arguments?: CommandArgument[];
  options?: CommandOption[];
  argumentHint?: string;            // e.g., "<file-path>"
  allowedTools?: string[];          // Tools this command uses
  executionSteps?: string[];        // What it does
}

Example:

{
  id: 'use',
  type: 'command',
  name: 'Use',
  description: 'Install and deploy framework',
  capabilities: ['cli', 'framework', 'deployment'],
  metadata: {
    type: 'command',
    template: 'orchestration',
    argumentHint: '<framework>',
    allowedTools: ['Read', 'Write', 'Bash', 'Glob']
  }
}

Skill Extensions

Natural language workflows triggered by phrases or conditions.

For portable third-party `SKILL.md` bundles, see Agent Skills import and deployment. That guide covers agentskills.io conformance, managed import, validation, strict provider projection, and the mapping between portable fields and AIWG extension metadata.

Metadata:

interface SkillMetadata {
  triggerPhrases: string[];         // e.g., ["what's next?", "project status"]
  autoTrigger?: boolean;            // Auto-activate on conditions
  autoTriggerConditions?: string[]; // e.g., ["session-start"]
  tools?: string[];
  references?: SkillReference[];
}

Example:

{
  id: 'project-awareness',
  type: 'skill',
  name: 'Project Awareness',
  description: 'Comprehensive project context detection',
  capabilities: ['context-awareness', 'project-detection'],
  metadata: {
    type: 'skill',
    triggerPhrases: ['what project is this', 'where are we?'],
    autoTrigger: true,
    autoTriggerConditions: ['session-start']
  }
}

Hook Extensions

Lifecycle event handlers for session, command, and tool events.

Metadata:

interface HookMetadata {
  event: HookEvent;                 // When to trigger
  priority?: number;                // Execution order (lower = earlier)
  canModify?: boolean;              // Can change execution
  canBlock?: boolean;               // Can prevent execution
}

type HookEvent =
  | 'pre-session' | 'post-session'
  | 'pre-command' | 'post-command'
  | 'pre-agent' | 'post-agent'
  | 'pre-write' | 'post-write'
  | 'pre-bash' | 'post-bash';

Tool Extensions

External CLI utilities with discovery and verification.

Metadata:

interface ToolMetadata {
  category: 'core' | 'languages' | 'utilities' | 'custom';
  executable: string;               // Command name
  aliases?: string[];               // Alternative names
  verificationStatus?: 'verified' | 'unverified';
  installHint?: string;             // How to install if missing
}

MCP Server Extensions

Model Context Protocol servers with capabilities and tools.

Metadata:

interface MCPServerMetadata {
  mcpVersion: string;               // e.g., "1.0"
  transport: 'stdio' | 'http';
  capabilities: {
    tools: boolean;
    resources: boolean;
    prompts: boolean;
  };
  tools?: MCPToolSummary[];
}

Framework Extensions

Complete workflows that bundle multiple extensions.

Metadata:

interface FrameworkMetadata {
  domain: string;                   // e.g., "sdlc", "marketing"
  includes: {
    agents?: string[];
    commands?: string[];
    skills?: string[];
    hooks?: string[];
    templates?: string[];
  };
}

Addon Extensions

Feature bundles that extend frameworks.

Metadata:

interface AddonMetadata {
  entry: {
    agents?: string;                // Path to agent definitions
    commands?: string;
    skills?: string;
  };
  provides: {
    agents?: string[];              // IDs of provided extensions
    commands?: string[];
    skills?: string[];
  };
}

Template Extensions

Document scaffolds with named variables and sections that produce SDLC artifacts (use cases, ADRs, test plans). Bundled inside frameworks.

Metadata:

interface TemplateMetadata {
  format: string;                   // "markdown" | "yaml" | "json" | "handlebars"
  variables?: TemplateVariable[];
  sections?: string[];
  targetArtifact?: string;          // e.g., "use-case", "test-plan"
}

Prompt Extensions

Reusable parameterized prompt fragments that agents and skills compose into larger workflows (review checklists, role primers, reliability reminders).

Metadata:

interface PromptMetadata {
  category: string;                 // "core" | "reliability" | "agents" | "review"
  purpose: string;
  useWhen: string[];
  variables?: string[];
  requiredContext?: string[];
}

Soul Extensions

Agent identity files (`SOUL.md`) declaring worldview, opinions, vocabulary, and boundaries. Soul defines who the agent is — distinct from voice (how it sounds) and skills (what it does). Scope is either project-wide or per-agent.

Metadata:

interface SoulMetadata {
  scope: 'project' | 'agent';
  targetAgent?: string;             // Required when scope is 'agent'
  sections: string[];               // who-i-am, worldview, opinions, vocabulary, boundaries
  companions?: { style?: string; memory?: string; examples?: string };
  estimatedTokens?: number;
}

Behavior Extensions

Reactive capabilities that combine NLP triggers with event hooks (`on_file_write`, `on_schedule`, `on_commit`) and shell scripts. Native on OpenClaw; emulated via the AIWG daemon on other providers. Behaviors degrade to skills on platforms without hook support.

Metadata:

interface BehaviorMetadata {
  triggerPhrases?: string[];
  inputs?: BehaviorInput[];
  hooks?: Partial<Record<BehaviorHookEvent, BehaviorHookAction[]>>;
  scripts?: Record<string, string>;
  manifest?: { category?: string; requires?: { bins?: string[] }; outputs?: Array<{type: string; path: string}> };
}

Team Extensions

Multi-agent compositions (2–8 agents) with assigned roles, an execution mode, and inter-agent handoffs. Native on Claude Code via the Task tool; emulated on other providers via the agent-owned mc operation Mission Control. Source format is JSON; schema lives in `agentic/code/frameworks/sdlc-complete/teams/schema.json`.

Definition (not in `metadata` — teams use a top-level JSON schema):

interface TeamDefinition {
  name: string;
  slug: string;
  description: string;
  dispatch?: 'parallel' | 'sequential' | 'consensus';
  agents: TeamMember[];             // 2–8 entries
  handoffs?: TeamHandoff[];
  sdlc_phases?: string[];
  max_context_agents?: number;
}

Platform Compatibility

Extensions declare which platforms they support:

interface PlatformCompatibility {
  claude?: PlatformSupport;
  factory?: PlatformSupport;
  cursor?: PlatformSupport;
  copilot?: PlatformSupport;
  windsurf?: PlatformSupport;
  codex?: PlatformSupport;
  opencode?: PlatformSupport;
  generic?: PlatformSupport;
}

type PlatformSupport = 'full' | 'partial' | 'experimental' | 'none';

Deployment paths are platform-specific:

{
  deployment: {
    pathTemplate: '.{platform}/agents/{id}.md',
    pathOverrides: {
      'claude': '.claude/agents/api-designer.md'
    }
  }
}

Platform examples:

  • Claude Code: `.claude/agents/`, `.claude/commands/`
  • GitHub Copilot: `.github/agents/`, `.github/commands/`
  • Warp: `WARP.md` (symlinked to `CLAUDE.md`)
  • Cursor: `.cursor/rules/`, `.cursor/agents/`

Capability-Based Discovery

Extensions are indexed by capabilities for semantic search:

interface CapabilityIndex {
  capabilities: Record<string, string[]>;  // capability → extension IDs
  keywords: Record<string, string[]>;      // keyword → extension IDs
  categories: Record<string, string[]>;    // category → extension IDs
  types: Record<ExtensionType, string[]>;  // type → extension IDs
  platforms: Record<string, string[]>;     // platform → extension IDs
  searchIndex: Record<string, string[]>;   // term → extension IDs
}

Search examples:

// Find all API-related extensions
registry.search({ capabilities: ['api-design'] });

// Find agents that can write code
registry.search({ type: 'agent', capabilities: ['code-generation'] });

// Find commands for Cursor platform
registry.search({ type: 'command', platform: 'cursor' });

// Full-text search
registry.search({ search: 'authentication' });

Extension Lifecycle

Discovery

Extensions are discovered from:

  • Built-in directories (`agentic/code/frameworks/`, `agentic/code/addons/`)
  • Installed packages (`node_modules/@aiwg/*/`)
  • Local directories (`.aiwg/frameworks/`)

Registration

const registry = new ExtensionRegistry();
await registry.discover([
  'agentic/code/frameworks',
  'agentic/code/addons',
]);

Deployment

Use AIWG to complete this documented outcome: Deployment
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Validation

const result = await validateExtension(extension);
if (!result.valid) {
  console.error('Validation errors:', result.errors);
}

Dependencies

Extensions can declare dependencies:

{
  requires: ['sdlc-complete', 'aiwg-utils'],
  recommends: ['voice-framework'],
  conflicts: ['legacy-agent-v1'],
  systemDependencies: {
    'git': '>=2.0.0',
    'jq': '*'
  }
}

Dependency resolution:

1. Check required extensions are installed 2. Install recommended extensions if available 3. Verify no conflicts exist 4. Check system dependencies present

Creating Extensions

See:

Extension Registry

The central registry manages all extensions:

class ExtensionRegistry {
  // Discovery
  async discover(paths: string[]): Promise<Extension[]>;

  // CRUD
  async register(ext: Extension): Promise<void>;
  async unregister(id: string): Promise<void>;
  async get(id: string): Promise<Extension | null>;
  async list(filter?: ExtensionFilter): Promise<Extension[]>;

  // Search
  async search(query: CapabilityQuery): Promise<CapabilitySearchResult>;

  // Index
  async rebuildIndex(): Promise<void>;
  getIndex(): CapabilityIndex;
}

Registry file: `.aiwg/frameworks/registry.json`

Benefits

Unified Schema

  • Single source of truth for all extension metadata
  • Type-safe TypeScript definitions
  • Consistent validation rules

Dynamic Discovery

  • Extensions found automatically
  • Capability-based search
  • Platform-aware filtering

Multi-Platform Support

  • Deploy to any supported platform
  • Platform-specific path overrides
  • Compatibility declarations

Dependency Management

  • Automatic dependency resolution
  • Conflict detection
  • Version constraints

Help Generation

  • Dynamic help from metadata
  • Always in sync with extensions
  • Rich examples and descriptions

Migration

Existing formats automatically migrate to unified schema:

Source FormatMigration Function
Agent frontmatter`migrateAgentFrontmatter()`
Command frontmatter`migrateCommandFrontmatter()`
Skill YAML`migrateSkillYAML()`
manifest.json v1`migrateManifestV1()`

Backward compatibility maintained during transition.

See Also