# 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

| 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 `--provider` |
| 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 `aiwg use sdlc --provider my-provider`
```

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

```json
{
  "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](https://github.com/jmagly/aiwg/blob/main/.aiwg/architecture/adr-identical-form-portability.md))
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:

```json
{
  "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:

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

- Bundle manifest schema: [`@src/extensions/types.ts`](../../src/extensions/types.ts), [`design-manifest-schema.md`](https://github.com/jmagly/aiwg/blob/main/.aiwg/architecture/design-manifest-schema.md)
- Identical-form ADR: [`adr-identical-form-portability.md`](https://github.com/jmagly/aiwg/blob/main/.aiwg/architecture/adr-identical-form-portability.md)
- Directory layout ADR: [`adr-aiwg-directory-layout.md`](https://github.com/jmagly/aiwg/blob/main/.aiwg/architecture/adr-aiwg-directory-layout.md)
- Override / shadow policy: [`adr-override-shadow-policy.md`](https://github.com/jmagly/aiwg/blob/main/.aiwg/architecture/adr-override-shadow-policy.md)
- Scaffolding CLI: `aiwg new-bundle <name> --type {extension|addon|framework|plugin|provider}`
- Lifecycle guide: [`project-local-lifecycle.md`](project-local-lifecycle.md)
- 5-minute quickstart: [`project-local-quickstart.md`](project-local-quickstart.md)