/**
 * Unified Extension Type System
 *
 * Provides a single schema for all AIWG extensions: agents, commands, skills,
 * hooks, tools, and MCP servers. Enables dynamic discovery, semantic search,
 * and unified help generation.
 *
 * @architecture @.aiwg/architecture/unified-extension-schema.md
 * @version 1.0.0
 */
/**
 * Extension type discriminator
 */
export type ExtensionType = 'agent' | 'command' | 'skill' | 'hook' | 'tool' | 'mcp-server' | 'framework' | 'addon' | 'template' | 'prompt' | 'soul' | 'behavior' | 'team';
/**
 * Types that are authored as source artifacts.
 *
 * Skills are the canonical source format for workflows. All new workflows
 * should be authored as skills, not commands.
 */
export type SourceExtensionType = Exclude<ExtensionType, 'command'>;
/**
 * Types that are generated at deploy time from source artifacts.
 *
 * Commands are generated from skills for providers that require command format
 * natively (Factory, OpenCode, Warp/Windsurf aggregation, legacy Codex).
 */
export type DeploymentExtensionType = 'command';
/**
 * Extension lifecycle status
 */
export type ExtensionStatus = 'stable' | 'beta' | 'experimental' | 'deprecated' | 'archived';
/**
 * Platform support level
 */
export type PlatformSupport = 'full' | 'partial' | 'experimental' | 'none';
/**
 * Platform compatibility matrix
 */
export interface PlatformCompatibility {
    /** Claude Code / Desktop */
    claude?: PlatformSupport;
    /** Factory AI */
    factory?: PlatformSupport;
    /** Cursor */
    cursor?: PlatformSupport;
    /** GitHub Copilot */
    copilot?: PlatformSupport;
    /** Windsurf */
    windsurf?: PlatformSupport;
    /** Codex / OpenAI */
    codex?: PlatformSupport;
    /** OpenCode */
    opencode?: PlatformSupport;
    /** Generic / Warp */
    generic?: PlatformSupport;
    /** OpenClaw */
    openclaw?: PlatformSupport;
}
/**
 * A single .aiwg/ path entry in a memory footprint declaration
 */
export interface MemoryPath {
    /** Path relative to project root — always under .aiwg/ */
    path: string;
    /** Human-readable description of what this path contains */
    description: string;
}
/**
 * Declares what .aiwg/ paths a component creates when deployed
 *
 * Skills and agents can safely reference any path listed in `creates` from
 * an installed component — those paths are guaranteed to exist after deployment.
 *
 * @see docs/development/aiwg-dir-reference-contract.md
 */
export interface MemoryFootprint {
    /**
     * Directories and files this component creates or populates in .aiwg/
     *
     * Skills may safely reference any path listed here.
     *
     * @example [{ "path": ".aiwg/requirements/", "description": "User stories, use cases, NFRs" }]
     */
    creates?: MemoryPath[];
    /**
     * Specific files with documented schemas that skills can depend on
     *
     * These are primary context injection points — they have a defined structure
     * that skills can rely on.
     *
     * @example [{ "path": ".aiwg/AIWG.md", "description": "Project context entry point" }]
     */
    normalizedFiles?: MemoryPath[];
    /**
     * Semantic memory topology declaration
     *
     * When present, this component declares a structured semantic memory that
     * kernel skills (memory-ingest, memory-lint, memory-query-capture) can
     * operate on. The kernel reads this contract to parameterize behavior.
     *
     * @see ADR-021 — Semantic memory kernel architecture
     */
    topology?: MemoryTopology;
}
/**
 * Cross-reference style used when linking between pages in semantic memory.
 *
 * Kernel skills write cross-references per the consumer's declared style.
 * AIWG internal tooling (mention-wire, mention-lint) uses at-mention exclusively.
 */
export type CrossRefStyle = 'at-mention' | 'wikilink' | 'markdown-link' | 'yaml-ref';
/**
 * Semantic memory topology contract
 *
 * Declares how a consumer's semantic memory is organized — where raw sources
 * live, where derived pages go, how pages cross-reference each other, and
 * what validation the kernel should apply during ingest and lint.
 *
 * Read by kernel skills in `agentic/code/addons/semantic-memory/` to
 * parameterize topology-agnostic operations.
 *
 * @see ADR-021 decisions D2 (interface) and D3 (schema location)
 * @see https://git.integrolabs.net/roctinam/aiwg/issues/825
 */
export interface MemoryTopology {
    /**
     * Root namespace for this consumer's memory under .aiwg/
     *
     * @example ".aiwg/research"
     * @example ".aiwg/wiki"
     */
    namespace: string;
    /**
     * Directory where raw/original sources are stored before processing
     *
     * @example ".aiwg/research/sources"
     */
    rawSources: string;
    /**
     * Map of derived page categories to their storage directories
     *
     * Keys are semantic roles (summary, entity, concept, synthesis, etc.).
     * Values are directory paths under the namespace.
     *
     * @example { "summary": ".aiwg/research/summaries", "entity": ".aiwg/research/knowledge/entities" }
     */
    derivedPages: Record<string, string>;
    /**
     * Path to the master index file for this memory
     *
     * @example ".aiwg/research/index.md"
     */
    index: string;
    /**
     * Path to the append-only JSON Lines event log
     *
     * @example ".aiwg/research/.log.jsonl"
     */
    log: string;
    /**
     * How cross-references between pages are written
     *
     * @default "at-mention"
     */
    crossRefStyle: CrossRefStyle;
    /**
     * Path to the page template used when creating new derived pages
     *
     * Relative to the consumer's addon/framework root.
     *
     * @example "templates/research-page.md"
     */
    pageTemplate?: string;
    /**
     * Capabilities required during ingest
     *
     * Kernel checks these and delegates to the named capability providers.
     * Common values: "provenance", "grade-quality", "citation-guard"
     *
     * @example ["provenance", "grade-quality"]
     */
    ingestRequires?: string[];
    /**
     * Lint rule IDs to apply during memory-lint
     *
     * References existing skill or rule IDs (e.g., "citation-guard", "link-check").
     * The kernel composes these with its own structural checks.
     *
     * @example ["citation-guard", "link-check", "mention-lint"]
     */
    lintRules?: string[];
}
/**
 * Deployment configuration
 */
export interface DeploymentConfig {
    /**
     * Base deployment path template
     *
     * Variables: {platform}, {id}, {type}
     *
     * @example ".{platform}/agents/{id}.md"
     * @example ".{platform}/commands/{id}.md"
     */
    pathTemplate: string;
    /**
     * Platform-specific path overrides
     *
     * @example { "claude": ".claude/agents/api-designer.md" }
     */
    pathOverrides?: Record<string, string>;
    /**
     * Additional files that are part of this extension
     *
     * @example ["references/api-patterns.md", "templates/openapi.yaml"]
     */
    additionalFiles?: string[];
    /**
     * Whether this extension auto-installs
     *
     * @default false
     */
    autoInstall?: boolean;
    /**
     * Whether this is a core extension
     *
     * Core extensions are always available.
     *
     * @default false
     */
    core?: boolean;
}
/**
 * Unified Extension Schema
 *
 * Represents any AIWG extension: agent, command, skill, hook, tool, or MCP server.
 *
 * @version 1.0.0
 */
export interface Extension {
    /**
     * Unique identifier (kebab-case)
     *
     * @example "api-designer"
     * @example "mention-wire"
     * @example "voice-apply"
     */
    id: string;
    /**
     * Previous ID for backward compatibility.
     * Existing deployments using this ID continue to resolve until users re-run `aiwg use`.
     */
    legacyId?: string;
    /**
     * Extension type discriminator
     *
     * Used for type-safe narrowing and dispatch.
     */
    type: ExtensionType;
    /**
     * Human-readable name
     *
     * @example "API Designer"
     * @example "Mention Wire Command"
     */
    name: string;
    /**
     * Brief description (1-2 sentences)
     *
     * Should be clear enough for search results and help listings.
     */
    description: string;
    /**
     * Semantic version (semver or CalVer)
     *
     * @example "1.0.0"
     * @example "2026.1.5"
     */
    version: string;
    /**
     * Capabilities this extension provides
     *
     * Used for capability-based discovery and semantic search.
     *
     * @example ["api-design", "interface-contracts", "rest"]
     * @example ["traceability", "@-mention", "validation"]
     */
    capabilities: string[];
    /**
     * Keywords for search and categorization
     *
     * @example ["sdlc", "architecture", "design"]
     * @example ["testing", "quality", "validation"]
     */
    keywords: string[];
    /**
     * Categorical classification
     *
     * Allows hierarchical organization.
     *
     * @example "sdlc/architecture"
     * @example "writing-quality/validation"
     */
    category?: string;
    /**
     * Platform compatibility
     *
     * Indicates which AI platforms this extension works with.
     */
    platforms: PlatformCompatibility;
    /**
     * Deployment configuration
     *
     * Where and how this extension is deployed.
     */
    deployment: DeploymentConfig;
    /**
     * Other extensions required by this extension
     *
     * @example ["sdlc-complete", "aiwg-utils"]
     */
    requires?: string[];
    /**
     * Optional extensions that enhance functionality
     *
     * @example ["voice-framework", "writing-quality"]
     */
    recommends?: string[];
    /**
     * Extensions that conflict with this one
     *
     * @example ["legacy-agent-v1"]
     */
    conflicts?: string[];
    /**
     * System dependencies (CLI tools, packages)
     *
     * @example { "gh": ">=2.0.0", "jq": "*" }
     */
    systemDependencies?: Record<string, string>;
    /**
     * Extension author
     *
     * @example "AIWG Contributors"
     * @example "John Magly <john@example.com>"
     */
    author?: string;
    /**
     * License identifier
     *
     * @example "MIT"
     * @example "Apache-2.0"
     */
    license?: string;
    /**
     * Repository URL
     *
     * @example "https://github.com/jmagly/aiwg"
     */
    repository?: string;
    /**
     * Homepage/documentation URL
     *
     * @example "https://aiwg.io/extensions/api-designer"
     */
    homepage?: string;
    /**
     * Bug tracker URL
     *
     * @example "https://github.com/jmagly/aiwg/issues"
     */
    bugs?: string;
    /**
     * Documentation paths relative to extension root
     *
     * @example { "readme": "README.md", "guide": "docs/guide.md" }
     */
    documentation?: Record<string, string>;
    /**
     * Research compliance metadata
     *
     * Links to research best practices and archetypes.
     */
    researchCompliance?: Record<string, string[]>;
    /**
     * .aiwg/ memory footprint declaration
     *
     * Declares what .aiwg/ paths this component creates when deployed.
     * Skills can safely @-reference any path declared in memory.creates.
     * Used by validate-component and dev-doctor to check link correctness.
     */
    memory?: MemoryFootprint;
    /**
     * Type-specific metadata
     *
     * The shape of this object depends on `type` field.
     * TypeScript will narrow this based on the discriminator.
     */
    metadata: ExtensionMetadata;
    /**
     * Extension status
     *
     * @default "stable"
     */
    status?: ExtensionStatus;
    /**
     * Deprecation information
     */
    deprecation?: {
        /** When this extension was deprecated (ISO 8601) */
        date: string;
        /** Replacement extension ID */
        successor?: string;
        /** Deprecation reason */
        reason: string;
    };
    /**
     * Installation state tracking
     *
     * Populated by the runtime, not in manifest files.
     */
    installation?: {
        /** Install timestamp (ISO 8601) */
        installedAt: string;
        /** Installation source */
        installedFrom: 'builtin' | 'registry' | 'local' | 'git';
        /** Installation path */
        installedPath: string;
        /** Enabled state */
        enabled: boolean;
    };
    /**
     * Extension checksum for integrity validation
     *
     * @example "sha256:abc123..."
     */
    checksum?: string;
    /**
     * Signature for authenticity verification
     */
    signature?: {
        algorithm: 'pgp' | 'ed25519';
        value: string;
        publicKey?: string;
    };
}
/**
 * Discriminated union of type-specific metadata
 */
export type ExtensionMetadata = AgentMetadata | CommandMetadata | SkillMetadata | HookMetadata | ToolMetadata | MCPServerMetadata | FrameworkMetadata | AddonMetadata | TemplateMetadata | PromptMetadata | SoulMetadata | BehaviorMetadata;
/**
 * Agent-specific metadata
 */
export interface AgentMetadata {
    type: 'agent';
    /**
     * Agent role/expertise area
     *
     * @example "API Design and Contract Definition"
     */
    role: string;
    /**
     * Model selection
     *
     * Tier-based selection or specific model override.
     */
    model: {
        /** Tier preference */
        tier: 'haiku' | 'sonnet' | 'opus';
        /** Specific model override (optional) */
        override?: string;
    };
    /**
     * Tools this agent can use
     *
     * @example ["Read", "Write", "Bash"]
     */
    tools: string[];
    /**
     * Agent complexity template
     *
     * @example "simple" | "complex" | "orchestrator"
     */
    template?: string;
    /**
     * Maximum tool count
     */
    maxTools?: number;
    /**
     * Can delegate to other agents
     */
    canDelegate?: boolean;
    /**
     * Read-only mode (no Write/Bash)
     */
    readOnly?: boolean;
    /**
     * Agent workflow steps
     */
    workflow?: string[];
    /**
     * Agent expertise areas
     */
    expertise?: string[];
    /**
     * Agent responsibilities
     */
    responsibilities?: string[];
}
/**
 * Command argument definition
 */
export interface CommandArgument {
    name: string;
    description: string;
    required: boolean;
    type: 'string' | 'number' | 'boolean';
    default?: string | number | boolean;
    position?: number;
}
/**
 * Command option definition
 */
export interface CommandOption {
    name: string;
    description: string;
    type: 'string' | 'boolean' | 'number' | 'array';
    default?: string | boolean | number;
    short?: string;
    long?: string;
}
/**
 * Command-specific metadata
 *
 * @deprecated As a source format. Commands are now generated from skills at deploy time.
 * This type is retained for providers that require command format natively
 * (Factory, OpenCode, Warp/Windsurf aggregation, legacy Codex).
 * New workflows should use `type: 'skill'` with `commandHint` for translation metadata.
 *
 * @see SkillMetadata.commandHint
 */
export interface CommandMetadata {
    type: 'command';
    /**
     * Command template type
     */
    template: 'utility' | 'transformation' | 'orchestration';
    /**
     * Command arguments
     */
    arguments?: CommandArgument[];
    /**
     * Command options/flags
     */
    options?: CommandOption[];
    /**
     * Argument hint for help display
     *
     * @example "<file-path>"
     * @example "[options] <input>"
     */
    argumentHint?: string;
    /**
     * Allowed tools for this command
     *
     * @example ["Read", "Write", "Grep"]
     */
    allowedTools?: string[];
    /**
     * Model preference
     *
     * @example "sonnet"
     */
    model?: string;
    /**
     * Execution steps
     */
    executionSteps?: string[];
    /**
     * Success criteria
     */
    successCriteria?: string[];
    /**
     * When true, this command is slash-command-only and has no CLI handler.
     * Exempts it from handler coverage checks.
     */
    cliDisabled?: boolean;
    /**
     * Skill ID that produced this command (set at generation time by the translation layer).
     * Present only on commands generated from skills, not hand-authored commands.
     */
    generatedFrom?: string;
}
/**
 * Skill reference material
 */
export interface SkillReference {
    /** Reference filename */
    filename: string;
    /** Reference description */
    description: string;
    /** Reference content path */
    path: string;
}
/**
 * Command translation hints for generating command artifacts from skills.
 *
 * Used by the skill→command translation layer when deploying to providers
 * that require command format natively (Factory, OpenCode, Warp/Windsurf, legacy Codex).
 */
export interface CommandHint {
    /**
     * Argument hint for help display
     *
     * @example "<file-path>"
     * @example "[options] <input>"
     */
    argumentHint?: string;
    /**
     * Allowed tools to declare in the generated command
     *
     * @example ["Read", "Write", "Grep"]
     */
    allowedTools?: string[];
    /**
     * Command template type for generated commands
     */
    template?: 'utility' | 'transformation' | 'orchestration';
    /**
     * Command arguments for generated command files
     */
    arguments?: CommandArgument[];
    /**
     * Command options/flags for generated command files
     */
    options?: CommandOption[];
    /**
     * Execution steps for generated command documentation
     */
    executionSteps?: string[];
    /**
     * Success criteria for generated command documentation
     */
    successCriteria?: string[];
    /**
     * Model preference for the generated command
     *
     * @example "sonnet"
     */
    model?: string;
    /**
     * When true, this skill has no CLI handler (slash-command-only).
     * Exempts it from handler coverage checks.
     */
    cliDisabled?: boolean;
    /**
     * When true, this skill is executed via `aiwg skills run` (provider dispatch)
     * rather than a bespoke TypeScript handler.
     * Exempts it from handler coverage checks.
     */
    executedViaSkillRunner?: boolean;
}
/**
 * Skill-specific metadata
 */
export interface SkillMetadata {
    type: 'skill';
    /**
     * Namespace prefix for collision avoidance (e.g., 'aiwg').
     * Canonical invocation slug: '{namespace}-{name}'
     *
     * @see adr-skill-namespace-strategy.md
     */
    namespace?: string;
    /**
     * Natural language trigger phrases
     *
     * @example ["what's next?", "project status", "where are we?"]
     */
    triggerPhrases: string[];
    /**
     * Whether this skill is auto-triggered
     *
     * @default false
     */
    autoTrigger?: boolean;
    /**
     * Auto-trigger conditions
     */
    autoTriggerConditions?: string[];
    /**
     * Tools this skill uses
     */
    tools?: string[];
    /**
     * Reference materials
     */
    references?: SkillReference[];
    /**
     * Input requirements
     */
    inputRequirements?: string[];
    /**
     * Output format description
     */
    outputFormat?: string;
    /**
     * Model effort override (1=low, 2=medium, 3=high)
     *
     * Controls reasoning effort when the skill is invoked.
     */
    effort?: 1 | 2 | 3;
    /**
     * Whether this skill can be invoked by the user via slash command.
     *
     * @default true
     */
    userInvocable?: boolean;
    /**
     * When true, prevents model from auto-invoking this skill.
     * The skill can only be triggered explicitly by the user.
     *
     * @default false
     */
    disableModelInvocation?: boolean;
    /**
     * Execution context isolation mode.
     *
     * - 'fork': Skill runs in an isolated context (new conversation)
     * - 'inherit': Skill runs in the current conversation context
     */
    context?: 'fork' | 'inherit';
    /**
     * Tool access restriction for this skill when invoked in Claude Code.
     *
     * Note: Distinct from `commandHint.allowedTools` which describes tools
     * declared in generated command files for legacy providers.
     */
    allowedTools?: string[];
    /**
     * Command translation hints for generating command artifacts.
     *
     * Used by the skill→command translation layer when deploying to providers
     * that require command format natively. Skills without `commandHint` will
     * still be translated using defaults derived from the skill's own fields.
     */
    commandHint?: CommandHint;
}
/**
 * Hook lifecycle events
 */
export type HookEvent = 'pre-session' | 'post-session' | 'pre-command' | 'post-command' | 'pre-agent' | 'post-agent' | 'pre-write' | 'post-write' | 'pre-bash' | 'post-bash';
/**
 * Hook-specific metadata
 */
export interface HookMetadata {
    type: 'hook';
    /**
     * Hook lifecycle event
     *
     * @example "pre-session" | "post-session" | "pre-command" | "post-command"
     */
    event: HookEvent;
    /**
     * Hook priority (lower = earlier execution)
     *
     * @default 100
     */
    priority?: number;
    /**
     * Whether this hook can modify execution
     *
     * @default false
     */
    canModify?: boolean;
    /**
     * Whether this hook can block execution
     *
     * @default false
     */
    canBlock?: boolean;
    /**
     * Hook configuration schema
     */
    configSchema?: Record<string, unknown>;
}
/**
 * Tool-specific metadata
 */
export interface ToolMetadata {
    type: 'tool';
    /**
     * Tool category
     */
    category: 'core' | 'languages' | 'utilities' | 'custom';
    /**
     * Executable path or command
     */
    executable: string;
    /**
     * Tool verification status
     */
    verificationStatus?: 'verified' | 'unverified';
    /**
     * Last verified date (ISO 8601)
     */
    lastVerified?: string;
    /**
     * Manual page content
     */
    manPage?: string;
    /**
     * Tool aliases
     *
     * @example ["rg", "ripgrep"]
     */
    aliases?: string[];
    /**
     * Related tools
     *
     * @example ["grep", "ag", "ack"]
     */
    relatedTools?: string[];
    /**
     * Platform-specific notes
     */
    platformNotes?: Record<string, string>;
    /**
     * Installation hint
     */
    installHint?: string;
}
/**
 * MCP tool summary
 */
export interface MCPToolSummary {
    name: string;
    description: string;
    dangerous: boolean;
}
/**
 * MCP Server-specific metadata
 */
export interface MCPServerMetadata {
    type: 'mcp-server';
    /**
     * MCP protocol version
     *
     * @example "1.0"
     */
    mcpVersion: string;
    /**
     * Server transport type
     */
    transport: 'stdio' | 'http';
    /**
     * Server port (for HTTP transport)
     */
    port?: number;
    /**
     * Server capabilities
     */
    capabilities: {
        tools: boolean;
        resources: boolean;
        prompts: boolean;
        sampling: boolean;
        logging: boolean;
    };
    /**
     * Source type
     */
    sourceType: 'cli' | 'api' | 'catalog' | 'nl' | 'extension';
    /**
     * Base command (for CLI source)
     */
    sourceCommand?: string;
    /**
     * API base URL (for API source)
     */
    sourceBaseUrl?: string;
    /**
     * Working directory
     */
    workingDirectory?: string;
    /**
     * Environment variables
     */
    environment?: Record<string, string>;
    /**
     * Tool definitions
     */
    tools?: MCPToolSummary[];
    /**
     * Resource patterns
     */
    resources?: string[];
    /**
     * Available prompts
     */
    prompts?: string[];
}
/**
 * Framework-specific metadata
 */
/**
 * CI workflow artifacts declared by a framework.
 * Source files live under `{framework}/ci/{forge}/workflows/`.
 * Deployed to `.github/workflows/` or `.gitea/workflows/` when
 * `aiwg use <framework> --ci-hooks-enabled` is run.
 *
 * @implements #661
 */
export interface ManifestCiSpec {
    /** Paths relative to `ci/github/` to deploy to `.github/workflows/` */
    github?: string[];
    /** Paths relative to `ci/gitea/` to deploy to `.gitea/workflows/` */
    gitea?: string[];
}
export interface FrameworkMetadata {
    type: 'framework';
    /**
     * Framework domain
     *
     * @example "sdlc" | "marketing" | "security"
     */
    domain: string;
    /**
     * Included extension IDs
     */
    includes: {
        agents?: string[];
        commands?: string[];
        skills?: string[];
        hooks?: string[];
        templates?: string[];
        prompts?: string[];
    };
    /**
     * CI workflow artifacts for opt-in deployment via --ci-hooks-enabled.
     * @implements #661
     */
    ci?: ManifestCiSpec;
    /**
     * Framework configuration schema
     */
    configSchema?: Record<string, unknown>;
    /**
     * Default configuration
     */
    defaultConfig?: Record<string, unknown>;
}
/**
 * Addon-specific metadata
 */
export interface AddonMetadata {
    type: 'addon';
    /**
     * Addon entry points
     */
    entry: {
        agents?: string;
        commands?: string;
        skills?: string;
        hooks?: string;
        templates?: string;
        prompts?: string;
    };
    /**
     * Extensions this addon provides
     */
    provides: {
        agents?: string[];
        commands?: string[];
        skills?: string[];
        hooks?: string[];
        templates?: string[];
        prompts?: string[];
    };
    /**
     * CLI commands contributed to the `aiwg` binary
     *
     * Addon-contributed commands are dispatched as `aiwg <namespace> <subcommand>`.
     * Each subcommand maps to an mjs file that exports a default async function.
     * The `hook_event` field enables automatic Claude Code hook registration on deploy.
     *
     * @example
     * ```json
     * {
     *   "namespace": "my-addon",
     *   "description": "My addon lifecycle operations",
     *   "entry": "commands/",
     *   "subcommands": {
     *     "check": { "file": "commands/my-check.mjs", "description": "Validate completion" }
     *   }
     * }
     * ```
     */
    cli_commands?: {
        namespace: string;
        description: string;
        entry: string;
        subcommands: Record<string, {
            file: string;
            description: string;
            hook_event?: string;
        }>;
    };
}
/**
 * Template variable definition
 */
export interface TemplateVariable {
    name: string;
    description: string;
    type: 'string' | 'number' | 'boolean' | 'array' | 'object';
    required: boolean;
    default?: unknown;
}
/**
 * Template-specific metadata
 */
export interface TemplateMetadata {
    type: 'template';
    /**
     * Template language/format
     *
     * @example "markdown" | "yaml" | "json" | "handlebars"
     */
    format: string;
    /**
     * Template variables
     */
    variables?: TemplateVariable[];
    /**
     * Template sections
     */
    sections?: string[];
    /**
     * Target artifact type
     *
     * @example "use-case" | "architecture-doc" | "test-plan"
     */
    targetArtifact?: string;
}
/**
 * Prompt-specific metadata
 */
export interface PromptMetadata {
    type: 'prompt';
    /**
     * Prompt category
     *
     * @example "core" | "reliability" | "agents"
     */
    category: string;
    /**
     * Prompt purpose
     */
    purpose: string;
    /**
     * When to use this prompt
     */
    useWhen: string[];
    /**
     * Prompt variables
     */
    variables?: string[];
    /**
     * Expected context
     */
    requiredContext?: string[];
}
/**
 * Soul-specific metadata
 *
 * Defines an AI agent's identity, worldview, and character.
 * Distinct from voice profiles (how content sounds) — soul defines
 * who the agent is.
 *
 * @see https://github.com/aaronjmars/soul.md
 */
export interface SoulMetadata {
    type: 'soul';
    /**
     * Soul scope
     *
     * @example "project" — applies to all agents in the project
     * @example "agent" — applies to a specific agent
     */
    scope: 'project' | 'agent';
    /**
     * Target agent name (required when scope is 'agent')
     *
     * @example "test-engineer"
     */
    targetAgent?: string;
    /**
     * Sections present in the soul file
     *
     * @example ["who-i-am", "worldview", "opinions", "vocabulary", "boundaries"]
     */
    sections: string[];
    /**
     * Companion files
     *
     * Optional related files in the soul ecosystem
     */
    companions?: {
        /** STYLE.md — writing style companion */
        style?: string;
        /** MEMORY.md — session memory */
        memory?: string;
        /** examples/ — calibration examples */
        examples?: string;
    };
    /**
     * Context budget estimate in tokens
     */
    estimatedTokens?: number;
}
/**
 * Behavior hook event types
 *
 * Events that behaviors can subscribe to on platforms with hook support.
 * Platforms without hook support ignore the hooks section and degrade
 * the behavior to a skill (NLP triggers only).
 */
export type BehaviorHookEvent = 'on_file_write' | 'on_tool_complete' | 'on_schedule' | 'on_commit' | 'on_pr_open' | 'on_deploy' | 'on_session_start' | 'on_session_end';
/**
 * Behavior hook action configuration
 */
export interface BehaviorHookAction {
    /** Glob filter for file-based events */
    filter?: string;
    /** Tool name filter for on_tool_complete events */
    tool?: string;
    /** Cron expression for on_schedule events */
    cron?: string;
    /** Action to take when the hook fires */
    action: 'run_script' | 'notify' | 'log';
    /** Script to execute (relative to behavior directory) */
    script?: string;
}
/**
 * Behavior structured input definition
 */
export interface BehaviorInput {
    /** Input parameter name */
    name: string;
    /** Input type */
    type: 'string' | 'number' | 'boolean' | 'enum' | 'path';
    /** Whether this input is required */
    required?: boolean;
    /** Description of the input */
    description?: string;
    /** Default value */
    default?: string | number | boolean;
    /** Allowed values (for enum type) */
    values?: string[];
}
/**
 * Behavior-specific metadata
 *
 * Behaviors are reactive capabilities with scripts + hooks + structured inputs.
 * They extend beyond skills by subscribing to system events via hooks.
 * On platforms without hook support, behaviors degrade to skills gracefully.
 */
export interface BehaviorMetadata {
    type: 'behavior';
    /**
     * Natural language trigger phrases (invocation path — same as skills)
     *
     * @example ["run security scan", "check for vulnerabilities"]
     */
    triggerPhrases?: string[];
    /**
     * Structured input parameters
     */
    inputs?: BehaviorInput[];
    /**
     * Event hook subscriptions (reactive path — what makes it a behavior)
     *
     * Keyed by hook event type, each containing an array of hook actions.
     */
    hooks?: Partial<Record<BehaviorHookEvent, BehaviorHookAction[]>>;
    /**
     * Scripts associated with this behavior
     *
     * Keyed by logical name, value is the relative path from the behavior directory.
     *
     * @example { "main": "scripts/main.sh", "lint": "scripts/lint-on-write.sh" }
     */
    scripts?: Record<string, string>;
    /**
     * Behavior manifest — richer metadata than skills
     */
    manifest?: {
        /** Category for discovery */
        category?: string;
        /** Runtime requirements */
        requires?: {
            /** Required binaries */
            bins?: string[];
            /** Required environment variables */
            env?: string[];
        };
        /** Output descriptions */
        outputs?: Array<{
            type: string;
            path: string;
        }>;
        /** Behaviors this composes with */
        composable_with?: string[];
    };
}
/**
 * Capability index for semantic search
 *
 * This index enables fast capability-based discovery.
 */
export interface CapabilityIndex {
    /**
     * Index version
     */
    version: string;
    /**
     * Index generation timestamp (ISO 8601)
     */
    generated: string;
    /**
     * Capability to extensions mapping
     *
     * Key: capability name
     * Value: list of extension IDs that provide it
     */
    capabilities: Record<string, string[]>;
    /**
     * Keyword to extensions mapping
     *
     * Key: keyword
     * Value: list of extension IDs tagged with it
     */
    keywords: Record<string, string[]>;
    /**
     * Category to extensions mapping
     *
     * Key: category path
     * Value: list of extension IDs in that category
     */
    categories: Record<string, string[]>;
    /**
     * Type to extensions mapping
     *
     * Key: extension type
     * Value: list of extension IDs of that type
     */
    types: Record<ExtensionType, string[]>;
    /**
     * Platform to extensions mapping
     *
     * Key: platform name
     * Value: list of extension IDs supporting that platform
     */
    platforms: Record<string, string[]>;
    /**
     * Full-text search index (inverted index)
     *
     * Key: term (lowercased)
     * Value: list of extension IDs containing that term
     */
    searchIndex: Record<string, string[]>;
}
/**
 * Capability search query
 */
export interface CapabilityQuery {
    /**
     * Required capabilities (AND)
     */
    requires?: string[];
    /**
     * Optional capabilities (OR)
     */
    prefers?: string[];
    /**
     * Extension type filter
     */
    type?: ExtensionType | ExtensionType[];
    /**
     * Platform filter
     */
    platform?: string;
    /**
     * Keyword filter
     */
    keywords?: string[];
    /**
     * Category filter
     */
    category?: string;
    /**
     * Full-text search
     */
    search?: string;
    /**
     * Status filter
     */
    status?: ExtensionStatus[];
}
/**
 * Capability search result
 */
export interface CapabilitySearchResult {
    /**
     * Matching extensions
     */
    extensions: Extension[];
    /**
     * Result count
     */
    count: number;
    /**
     * Match scores (0-1, higher is better)
     *
     * Key: extension ID
     * Value: relevance score
     */
    scores: Record<string, number>;
    /**
     * Search metadata
     */
    metadata: {
        query: CapabilityQuery;
        executedAt: string;
        executionTimeMs: number;
    };
}
/**
 * Field constraint definition
 */
export interface Constraint {
    /** Minimum value (for numbers/lengths) */
    min?: number;
    /** Maximum value (for numbers/lengths) */
    max?: number;
    /** Allowed values (enum) */
    enum?: unknown[];
    /** Custom validation function */
    validate?: (value: unknown) => boolean;
    /** Error message */
    message: string;
}
/**
 * Cross-field validation rule
 */
export interface CrossFieldRule {
    /** Rule description */
    description: string;
    /** Fields involved */
    fields: string[];
    /** Validation function */
    validate: (extension: Extension) => boolean;
    /** Error message */
    message: string;
}
/**
 * Extension validation rules
 */
export interface ValidationRules {
    /**
     * Required fields for all extensions
     */
    required: string[];
    /**
     * Field type constraints
     */
    types: Record<string, string>;
    /**
     * Field format patterns (regex)
     */
    patterns: Record<string, string>;
    /**
     * Field value constraints
     */
    constraints: Record<string, Constraint>;
    /**
     * Cross-field validation rules
     */
    crossFieldRules: CrossFieldRule[];
    /**
     * Type-specific validation rules
     */
    typeSpecificRules: Record<ExtensionType, ValidationRules>;
}
/**
 * Validation error
 */
export interface ValidationError {
    /** Error type */
    type: 'required' | 'type' | 'format' | 'constraint' | 'cross-field';
    /** Field path */
    field: string;
    /** Error message */
    message: string;
    /** Current value */
    value?: unknown;
    /** Expected value/format */
    expected?: unknown;
    /** Suggestion for fix */
    suggestion?: string;
}
/**
 * Validation warning
 */
export interface ValidationWarning {
    /** Warning type */
    type: 'deprecated' | 'missing-optional' | 'best-practice';
    /** Field path */
    field: string;
    /** Warning message */
    message: string;
    /** Recommendation */
    recommendation?: string;
}
/**
 * Validation result
 */
export interface ExtensionValidationResult {
    /** Whether extension is valid */
    valid: boolean;
    /** Validation errors */
    errors: ValidationError[];
    /** Validation warnings */
    warnings: ValidationWarning[];
    /** Extension being validated */
    extension: Extension;
}
/**
 * Migration mapping from existing formats to unified schema
 */
export interface MigrationMapping {
    /**
     * Source format identifier
     */
    sourceFormat: string;
    /**
     * Target schema version
     */
    targetVersion: string;
    /**
     * Field mappings
     *
     * Key: target field path (dot-notation)
     * Value: source field path or transform function name
     */
    fieldMappings: Record<string, string>;
    /**
     * Default values for new fields
     */
    defaults: Record<string, unknown>;
    /**
     * Custom transform functions
     */
    transforms?: Record<string, (value: unknown) => unknown>;
}
/**
 * Type guard for agent extensions
 */
export declare function isAgentExtension(ext: Extension): ext is Extension & {
    metadata: AgentMetadata;
};
/**
 * Type guard for command extensions
 */
export declare function isCommandExtension(ext: Extension): ext is Extension & {
    metadata: CommandMetadata;
};
/**
 * Type guard for skill extensions
 */
export declare function isSkillExtension(ext: Extension): ext is Extension & {
    metadata: SkillMetadata;
};
/**
 * Type guard for hook extensions
 */
export declare function isHookExtension(ext: Extension): ext is Extension & {
    metadata: HookMetadata;
};
/**
 * Type guard for tool extensions
 */
export declare function isToolExtension(ext: Extension): ext is Extension & {
    metadata: ToolMetadata;
};
/**
 * Type guard for MCP server extensions
 */
export declare function isMCPServerExtension(ext: Extension): ext is Extension & {
    metadata: MCPServerMetadata;
};
/**
 * Type guard for framework extensions
 */
export declare function isFrameworkExtension(ext: Extension): ext is Extension & {
    metadata: FrameworkMetadata;
};
/**
 * Type guard for addon extensions
 */
export declare function isAddonExtension(ext: Extension): ext is Extension & {
    metadata: AddonMetadata;
};
/**
 * Type guard for template extensions
 */
export declare function isTemplateExtension(ext: Extension): ext is Extension & {
    metadata: TemplateMetadata;
};
/**
 * Type guard for prompt extensions
 */
export declare function isPromptExtension(ext: Extension): ext is Extension & {
    metadata: PromptMetadata;
};
/**
 * Type guard for soul extensions
 */
export declare function isSoulExtension(ext: Extension): ext is Extension & {
    metadata: SoulMetadata;
};
/**
 * Type guard for behavior extensions
 */
export declare function isBehaviorExtension(ext: Extension): ext is Extension & {
    metadata: BehaviorMetadata;
};
//# sourceMappingURL=types.d.ts.map