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
Extensions are the building blocks of AIWG frameworks and addons. They include:
| Type | Purpose | Examples |
|---|---|---|
| agent | Specialized AI personas | API Designer, Test Engineer |
| skill | Primary workflow extension — NL-triggered, deployed natively | Project awareness, voice application, agent loop |
| command | Deployment artifact generated from skill sources; also CLI entry points | /mention-wire, aiwg use sdlc |
| hook | Lifecycle event handlers | Pre-session setup, post-write validation |
| tool | External utilities | git, jq, npm |
| mcp-server | MCP protocol servers | AIWG MCP server |
| framework | Complete workflows | SDLC Complete, Marketing Kit, Media Curator, Research Complete |
| addon | Feature bundles | Voice Framework, Testing Quality |
| template | Document templates | Use case template, ADR template |
| prompt | Reusable prompts | Code review, security audit |
| soul | Agent identity and character (worldview, opinions, vocabulary) | Project SOUL.md, agent-scoped .soul.md |
| behavior | Reactive capabilities with hooks, scripts, and structured inputs | Build monitor, security sentinel, concierge |
| team | Multi-agent compositions with roles, dispatch mode, and handoffs | API 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. Useaiwg add-skillto create new workflows;aiwg add-commandis for advanced direct-command authoring only.
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
}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']
}
}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']
}
}Natural language workflows triggered by phrases or conditions.
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']
}
}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';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
}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[];
}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[];
};
}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[];
};
}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"
}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[];
}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;
}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}> };
}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 aiwg mc 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;
}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 toCLAUDE.md) - Cursor:
.cursor/rules/,.cursor/agents/
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' });Extensions are discovered from:
- Built-in directories (
agentic/code/frameworks/,agentic/code/addons/) - Installed packages (
node_modules/@aiwg/*/) - Local directories (
.aiwg/frameworks/)
const registry = new ExtensionRegistry();
await registry.discover([
'agentic/code/frameworks',
'agentic/code/addons',
]);# Deploy to target platform
aiwg use sdlc --provider claude
# Extension system:
# 1. Resolves dependencies
# 2. Validates platform compatibility
# 3. Copies files to platform paths
# 4. Updates registryconst result = await validateExtension(extension);
if (!result.valid) {
console.error('Validation errors:', result.errors);
}Extensions can declare dependencies:
{
requires: ['sdlc-complete', 'aiwg-utils'],
recommends: ['voice-framework'],
conflicts: ['legacy-agent-v1'],
systemDependencies: {
'git': '>=2.0.0',
'jq': '*'
}
}Dependency resolution:
- Check required extensions are installed
- Install recommended extensions if available
- Verify no conflicts exist
- Check system dependencies present
See:
- Creating Extensions Guide
- Extension Types Reference
- @docs/development/agent-template.md
- @agentic/code/frameworks/sdlc-complete/agents/README.md
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
- Single source of truth for all extension metadata
- Type-safe TypeScript definitions
- Consistent validation rules
- Extensions found automatically
- Capability-based search
- Platform-aware filtering
- Deploy to any supported platform
- Platform-specific path overrides
- Compatibility declarations
- Automatic dependency resolution
- Conflict detection
- Version constraints
- Dynamic help from metadata
- Always in sync with extensions
- Rich examples and descriptions
Existing formats automatically migrate to unified schema:
| Source Format | Migration Function |
|---|---|
| Agent frontmatter | migrateAgentFrontmatter() |
| Command frontmatter | migrateCommandFrontmatter() |
| Skill YAML | migrateSkillYAML() |
| manifest.json v1 | migrateManifestV1() |
Backward compatibility maintained during transition.
- Creating Extensions - How to create your own
- Extension Types Reference - Detailed type definitions
- Graph Backends - Artifact index graph storage tiers and configuration
- @src/extensions/types.ts - Source code
- @.aiwg/architecture/unified-extension-schema.md - Full specification
- @docs/cli-reference.md - CLI command reference