Extensions vs Addons vs Frameworks vs Plugins

Choose the right bundle type

Extensions vs Addons vs Frameworks vs Plugins vs Providers

AIWG ships five overlapping bundle concepts. They sound similar and the boundaries are subtle, so this doc is the canonical reference for which one to author when. Project-local bundles can be any of the five.

One-sentence definitions

TypeWhat it isExample
ExtensionThe smallest deployable unit — a single capability (skill, agent, command, hook, rule) wrapped in a bundleA custom skill `my-team-naming-rules/`
AddonA focused feature pack — usually 2–10 related extensions delivered together`aiwg-utils` (rules + skills + agents working as a coherent set)
FrameworkA complete workflow domain — many addons + curated agents + templates`sdlc-complete` (93 agents, 116 skills, full SDLC)
PluginA delivery mechanism — packages any of the above for marketplace distributionA versioned `.zip` containing an addon for `/plugin install`
ProviderA deploy-target definition — selects an existing writer adapter for a custom provider id`.aiwg/providers/my-provider/` extending `claude`

The first three are content. The fourth is packaging. The fifth is provider metadata.

Comparison

PropertyExtensionAddonFrameworkPluginProvider
Granularity1 capability2-10 capabilities50+ capabilitieswraps any of the above1 provider id
Manifest`manifest.json` with `type: extension``type: addon` + `addonConfig``type: framework` + `frameworkConfig``type: plugin` + `pluginConfig``type: provider` + `providerConfig`
Lifecycleedit → deployedit → deployedit → deploypackage → installedit → select with `--provider`
Distributionbundled / project-local / marketplacebundled / project-local / marketplacebundled / project-local / marketplacemarketplace onlybundled / project-local / corpus
Override semanticsfollows shadow-resolution policy (#1041)samesameinherited from payload typeprovider id selection
Project-local?yes (`.aiwg/extensions/`)yes (`.aiwg/addons/`)yes (`.aiwg/frameworks/`)yes (`.aiwg/plugins/`)yes (`.aiwg/providers/`)
Identical-form portabilityyesyesyesyes (payload is byte-identical)yes
Graduation pathproject-local → upstreamsamesameunwrap payload, then graduateproject-local → `agentic/code/providers/`

Decision tree — "I want to add X"

What are you adding?
│
├─ A single workflow step or rule that helps one specific situation
│   └─→ Extension
│       Example: "skip the linter for files under vendor/"
│
├─ A small set of related capabilities that solve one problem
│   └─→ Addon
│       Example: "Postgres query helpers" (3 skills + 1 agent + 2 templates)
│
├─ A complete domain workflow with many specialized agents
│   └─→ Framework
│       Example: "Healthcare-specific SDLC with HIPAA reviewers"
│
└─ I want to publish my addon/framework so others can install it
    └─→ Plugin
        Example: a marketplace-distributed addon with versioning

└─ I want a custom provider id that reuses an existing writer adapter
    └─→ Provider
        Example: "my-provider" selected with `aiwg use sdlc --provider my-provider`

Common scenarios

You want to...AuthorLive under
Add a single rule the team always forgetsExtension`.aiwg/extensions/`
Add a custom voice profile + matching agentsAddon`.aiwg/addons/`
Build a regulated-industry SDLC variantFramework`.aiwg/frameworks/`
Distribute your addon publiclyPlugin (wraps your addon)marketplace
Select a custom provider id for an existing adapterProvider`.aiwg/providers/`
Override an upstream skill for your team onlyExtension`.aiwg/extensions/` (shadow w/ override)
Override a safety-critical upstream ruleExtension`.aiwg/extensions/` w/ explicit `overrides:`

Plugin vs the other three

Plugins are not "yet another content type." A plugin contains one of the other three as its payload. The manifest captures this:

{
  "type": "plugin",
  "pluginConfig": {
    "payloadType": "addon",
    "payloadPath": "payload/"
  }
}

When you run `/plugin install`, AIWG unpacks the payload and hands it to the addon/framework/extension deploy pipeline. The plugin layer adds versioning, packaging metadata, and marketplace integration — not new artifact semantics.

Graduation paths

.aiwg/extensions/foo/    ─┐
.aiwg/addons/foo/        ─┤
.aiwg/frameworks/foo/    ─┤── aiwg promote → upstream (agentic/code/{addons,frameworks}/)
.aiwg/plugins/foo/       ─┘                ↓
.aiwg/providers/foo/     ───── aiwg promote → upstream (agentic/code/providers/)
                                            corpus (your team's private tree)
                                            ↓
                                            marketplace (plugin-packaged)

The identical-form portability invariant (ADR #1038) means a project-local bundle is byte-identical to its upstream form. `aiwg promote` is therefore a copy + verify; no rewrite, no migration.

Provider phase-0 semantics

Project-local provider bundles are intentionally narrower than adding a new built-in provider writer. The manifest contains:

{
  "type": "provider",
  "providerConfig": {
    "extends": "claude",
    "displayName": "my-provider",
    "capabilities": {
      "nativeFeatures": {
        "cron": true
      },
      "emulation": {
        "mission_control": "aiwg-mc"
      }
    }
  }
}

`providerConfig.extends` delegates writing to an existing provider adapter. Optional `providerConfig.capabilities` values are data-only overrides for `aiwg steward capabilities --provider <custom>`; they do not create new deployment paths. Supported feature keys are `cron`, `agent_teams`, `tasks`, `mcp`, `behaviors`, `mission_control`, and `daemon`.

Use the custom id only as a selector:

aiwg use sdlc --provider my-provider

Do not expect `aiwg use my-provider` to deploy anything; provider bundles are metadata, not artifact-bearing targets.

Cross-references