AIWG Framework

You found a workflow that works. Now you want to share it.

Maybe you've written a custom slash command for your incident response process. A team-specific code review agent. A composite skill that chains your tooling pipeline. The first time you wrote it, it lived in .cursor/rules/ or ~/.claude/agents/. The next project needed it too. So did your colleague. Then your other team. Then your partner agency.

Now you have five copies in five repositories, drifting apart. The latest version is on someone's laptop. Updating one project means manually sync'ing the others. Forking AIWG to add your bits felt heavy — you'd own a fork forever, and you'd be a long way from upstream the moment AIWG ships its next release.

AIWG's customization model exists because this is the actual problem builders face. Build on AIWG, don't fork it.

The customization graduation ladder has three rungs. You usually only need the first.

Path A — Project-local

Drop a bundle into .aiwg/extensions/<name>/, .aiwg/addons/<name>/, .aiwg/frameworks/<name>/, or .aiwg/plugins/<name>/. AIWG auto-discovers it on the next aiwg use. Five minutes. No fork. Stays in your project's git history.

Path B — Fork

For changes that span projects or modify AIWG core. Run dev mode against your fork; contribute back upstream when the change is ready.

Path C — Corpus

Cross-project sharing without going public. A private corpus repo holds bundles your team uses across projects. Sync with aiwg use --corpus <path>.

Most builders live on Path A indefinitely. Path B opens up when you want to contribute back. Path C exists for agencies and platform teams sharing across projects without making the bundle public.

The shape of a bundle is byte-identical whether it lives in your project, your fork, or upstream. aiwg promote is a hash-verified copy — zero rewrite, zero translation step.

$ aiwg promote my-rule
[promote] checking source: .aiwg/extensions/my-rule/
[promote] sha256:c7a4...91e0  manifest.json
[promote] sha256:f02b...3d77  rules/my-rule.md
[promote] sha256:a138...88ab  README.md
[promote] target: ../aiwg/agentic/code/addons/my-rule/
[promote] copying 3 files (no rewrites)
[promote] verifying...
[promote] sha256 OK on all 3 files
[promote] manifest.json declares no overrides
[promote] graduation complete: project-local → upstream

No competitor we've audited ships this invariant. Spec Kit's layered overrides rewrite templates between layers. Claude Code is actively migrating its plugin format. The closest precedent is Homebrew taps — same artifact regardless of where it lives.

Why it matters: when you upgrade AIWG, your bundles don't break. When you contribute upstream, the diff is clean. When you graduate from Path A to B to C, nothing has to be rewritten.

# 1. Scaffold a bundle

# Bundle types: extension | addon | framework | plugin # Starters: rule | skill | agent | command | template

# 2. Edit the generated files

.aiwg/extensions/incident-runbook/
  manifest.json           ← name, version, dependencies, platforms
  README.md               ← what this does
  rules/incident-runbook.md  ← the rule itself

# 3. Deploy to your project

# 4. Inspect, validate, audit

Builder pain is well-documented in the Claude Code issue tracker. AIWG's design answers each one explicitly.

Non-atomic plugin installs — (Claude Code #49051, #40153)

Half-installed plugins leave users in an unrecoverable state. AIWG's aiwg use is transactional — either everything deploys, or nothing does, with rollback on partial failure.

No version visibility — (Claude Code #42424)

aiwg list reports installed-version, requires-version, and source for every component. aiwg activity-log show tracks what got deployed when.

No documented private-plugin path — (Claude Code #51348)

Path A (project-local) and Path C (corpus) are both private-by-default. Bundles never have to leave your repo or your team's corpus.

Sync wipes local plugins — (Claude Code #40773)

aiwg refresh never modifies project-local bundles. Source-preservation is an invariant: --force does not bypass it.

Name-collision overwrites — (Claude Code #44042)

Project-local bundles can shadow upstream cleanly — but shadowing safety-critical artifacts requires explicit declaration. See SAFETY below.

Project-local bundles can shadow upstream artifacts — that's how customization works. But silent shadowing of safety-critical components (security rules, audit log writers, gate enforcement) is how teams discover six months later that their compliance posture was different from what they thought.

AIWG enforces a denylist. Shadowing a safety-critical upstream artifact requires an explicit overrides: declaration in the bundle's manifest:

// .aiwg/extensions/my-relaxed-gates/manifest.json
{
  "name": "my-relaxed-gates",
  "version": "0.1.0",
  "overrides": [
    {
      "target": "sdlc-complete/rules/security-gate-mandatory.md",
      "justification": "Internal team has separate gate process documented in WIKI-1234",
      "approved_by": "security-team@"
    }
  ]
}

--force does not bypass this. The mechanism is comparable to Chrome's optional_permissions: extensions can request elevated capabilities, but the request is explicit and the user (or in our case, the manifest reviewer) has to authorize it.

Reference: the Claude Code MCP plugin security thread (#56119, "MCP Plugin Security: Systemic Risks") is the kind of discovery AIWG's design is meant to make impossible.

AIWG ships a Claude Code plugin marketplace.

Marketplace existence is now table stakes — Claude Code lists 2,000+ tagged repositories. We don't lead with it because the wedge is elsewhere.

A marketplace is one of three distribution paths:

1. Project-local — ship in your repo, no distribution at all. Most bundles live here.

2. Plugin marketplace — public discovery via jmagly/aiwg or your own marketplace.

3. Corpus — private cross-project sharing, no public publishing.

A note for MCP-community readers: AIWG bundles are composable atoms, not monolithic workflows. A bundle is a rule, a skill, an agent, a command, or a template — not a packaged 6-step process. Compose them as you need.

# 1. Install AIWG

# 2. Scaffold a bundle in your project

# 3. Edit, deploy, iterate

When you want to graduate to fork or corpus distribution, aiwg promote handles the move with hash verification. Your bundle's shape doesn't change.

> /loop — evaluating AIWG first? See the multi-week project narrative.

> /team — rolling this out at work? Governance, HITL, traceability.

> /docs/customization — full reference for bundle authoring, manifests, and the override policy.

> /h/extend — the alternate hero for this audience.