Extensions vs Addons vs Frameworks vs Plugins

Choose the right bundle type

Extensions vs Addons vs Frameworks vs Plugins vs Providers

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 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

Type	What it is	Example
Extension	The smallest deployable unit — a single capability (skill, agent, command, hook, rule) wrapped in a bundle	A custom skill `my-team-naming-rules/`
Addon	A focused feature pack — usually 2–10 related extensions delivered together	`aiwg-utils` (rules + skills + agents working as a coherent set)
Framework	A complete workflow domain — many addons + curated agents + templates	`sdlc-complete` (93 agents, 116 skills, full SDLC)
Plugin	A delivery mechanism — packages any of the above for marketplace distribution	A versioned `.zip` containing an addon for `/plugin install`
Provider	A 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

Property	Extension	Addon	Framework	Plugin	Provider
Granularity	1 capability	2-10 capabilities	50+ capabilities	wraps any of the above	1 provider id
Manifest	`manifest.json` with `type: extension`	`type: addon` + `addonConfig`	`type: framework` + `frameworkConfig`	`type: plugin` + `pluginConfig`	`type: provider` + `providerConfig`
Lifecycle	edit → deploy	edit → deploy	edit → deploy	package → install	edit → select with the provider option
Distribution	bundled / project-local / marketplace	bundled / project-local / marketplace	bundled / project-local / marketplace	marketplace only	bundled / project-local / corpus
Override semantics	follows shadow-resolution policy (#1041)	same	same	inherited from payload type	provider id selection
Project-local?	yes (`.aiwg/extensions/`)	yes (`.aiwg/addons/`)	yes (`.aiwg/frameworks/`)	yes (`.aiwg/plugins/`)	yes (`.aiwg/providers/`)
Identical-form portability	yes	yes	yes	yes (payload is byte-identical)	yes
Graduation path	project-local → upstream	same	same	unwrap payload, then graduate	project-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 the agent-owned use operation

Common scenarios

You want to...	Author	Live under
Add a single rule the team always forgets	Extension	`.aiwg/extensions/`
Add a custom voice profile + matching agents	Addon	`.aiwg/addons/`
Build a regulated-industry SDLC variant	Framework	`.aiwg/frameworks/`
Distribute your addon publicly	Plugin (wraps your addon)	marketplace
Select a custom provider id for an existing adapter	Provider	`.aiwg/providers/`
Override an upstream skill for your team only	Extension	`.aiwg/extensions/` (shadow w/ override)
Override a safety-critical upstream rule	Extension	`.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/    ─┤── the agent-owned promote operation → upstream (agentic/code/{addons,frameworks}/)
.aiwg/plugins/foo/       ─┘                ↓
.aiwg/providers/foo/     ───── the agent-owned promote operation → 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. the agent-owned promote operation 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 the agent-owned steward operation; 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:

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

Do not expect the agent-owned use operation to deploy anything; provider bundles are metadata, not artifact-bearing targets.

Cross-references

Bundle manifest schema: `@src/extensions/types.ts`, `design-manifest-schema.md`
Identical-form ADR: `adr-identical-form-portability.md`
Directory layout ADR: `adr-aiwg-directory-layout.md`
Override / shadow policy: `adr-override-shadow-policy.md`
Scaffolding CLI: the agent-owned new-bundle operation
Lifecycle guide: `project-local-lifecycle.md`
5-minute quickstart: `project-local-quickstart.md`