aiwg 2026.7.18 → 2026.7.20

package/agentic/code/addons/aiwg-utils/rules/subagent-scoping.md

@@ -13,7 +13,7 @@ enforcement: high
 
 Prevent context overload when delegating to subagents by enforcing focused, single-purpose invocations with minimal context and explicit output boundaries. Overloading causes context overflow/truncation, degraded output, premature termination, and expensive re-runs.
 
-**Core distinction**: These rules limit what goes INTO each subagent — NOT how many subagents an orchestrator spawns. Spawning 50 focused subagents (one per atomic subtask) is correct; giving one subagent 20 tasks is wrong. The anti-pattern is overload per subagent, never count.
+**Core distinction**: These rules primarily limit what goes INTO each subagent, while provider, project, context, framework, and natural-decomposition caps limit concurrent count. Focused delegation is useful only when its coordination cost and shared-state risk are lower than keeping the work local.
 
 ## Mandatory Rules
 
@@ -26,8 +26,17 @@ Include only context directly relevant to the task. **FORBIDDEN**: dumping full
 ### Rule 3: Task Decomposition Before Delegation
 Decompose complex tasks into atomic units before spawning. **FORBIDDEN**: "Implement the entire user registration flow." **REQUIRED**: split into atomic subagents (validate input, duplicate check, hash password, DB insert, send email, build response) — each succeeds/fails independently.
 
-### Rule 4: Parallel Over Sequential Overload
-When N related tasks exist, spawn N separate subagents in parallel. **FORBIDDEN**: one subagent "write tests for login, logout, refreshToken, validateSession." **REQUIRED**: 4 parallel test-writing subagents, one per function. If decomposition produces 20 atomic tasks, spawn 20 subagents — the limit is per-subagent input, not count.
+### Rule 4: Parallelize Independent Work Only
+When N independent tasks exist and delegation is beneficial, use separate focused subagents up to the effective cap. **FORBIDDEN**: parallel edits with serial dependencies or likely shared-state collisions. **REQUIRED**: keep tightly coupled work serial and retain integration in the primary agent.
+
+### Rule 4a: Select the Model Wrapper by Work Characteristics
+When the provider supports delegation, prefer AIWG's deployed wrappers instead of selecting the most capable model by default:
+
+- `aiwg-model-efficiency-worker` for discovery, inventory, focused edits, and bounded low-cost work.
+- `aiwg-model-coding-worker` for implementation, tests, debugging, and routine technical delivery.
+- `aiwg-model-reasoning-worker` for architecture, synthesis, difficult analysis, and high-consequence review.
+
+The primary agent remains responsible for orchestration, final integration, conflict resolution, validation, and the user-facing result. On global-only, compiled, inherited, or unsupported provider surfaces, describe actual enforcement honestly; never claim a per-worker pin that the provider cannot enforce.
 
 ### Rule 5: Output Scoping
 State exactly what format and scope to return. **FORBIDDEN**: "Analyze the auth system and provide recommendations" (output unspecified). **REQUIRED**: "Identify the top 3 security risks — list of exactly 3, each with name + severity + 1-sentence description, ≤300 words."
@@ -85,7 +94,7 @@ Override for higher-tier plans: `aiwg config set --project parallelism.max_paral
 
 ## Orchestrator Fan-Out
 
-Spawn many subagents when subtasks are independent (large multi-component feature 10-20+; one per file/function/service/endpoint/doc-section). The decision per subtask: atomic? context minimal (<20% of window)? output scoped? — if yes to all, spawn one subagent per subtask and execute in parallel (in sequential waves if `AIWG_CONTEXT_WINDOW` budget requires), then aggregate. Spawning 50 focused subagents beats 5 overloaded ones.
+Consider subagents when non-trivial work decomposes into independent, bounded units. The decision per subtask is: atomic, context minimal (<20% of window), output scoped, independent, collision-safe, and worth the coordination cost? If yes, dispatch up to the effective cap and aggregate in the primary agent. If no—especially for trivial, tightly coupled, inherently serial, or shared-state-sensitive work—keep it local.
 
 ## Integration with Other Rules
 
@@ -104,12 +113,15 @@ Before spawning a subagent:
 - [ ] Context is only what's directly relevant (<20% of window)
 - [ ] Output format/scope explicit
 - [ ] Task is atomic
+- [ ] Task is independent and collision-safe
+- [ ] Delegation benefit exceeds coordination cost
+- [ ] Efficiency, coding, or reasoning wrapper matches the task and consequence
 - [ ] Similar tasks → separate subagents, not bundled
 - [ ] Delegation depth ≤ 2 levels
 - [ ] Budget estimated <50% of window; if `AIWG_CONTEXT_WINDOW` set, parallel count within budget AND provider cap (Rule 8)
 
 Before giving one subagent multiple tasks: **STOP** — can these be separate subagents? Document why only if truly inseparable.
-Before limiting subagent count: **STOP** — the rules limit per-subagent input, not count; if each is atomic, many subagents is correct.
+Before setting concurrency: take the minimum of provider, project, context, framework, and natural-decomposition caps.
 
 ## References
 

package/agentic/code/addons/aiwg-utils/skills/new-bundle/SKILL.md

@@ -0,0 +1,53 @@
+---
+namespace: aiwg
+name: new-bundle
+platforms: [all]
+description: Scaffold a project-local extension, addon, framework, plugin, or provider bundle under the configured AIWG artifact root.
+triggers:
+  - new-bundle
+  - new bundle
+  - scaffold project-local
+  - create project-local bundle
+  - project-local bundle
+  - new extension
+  - new addon
+  - new provider
+---
+
+# New Bundle
+
+Create a version-controlled project-local bundle under `.aiwg/`.
+
+## Behavior
+
+1. Determine the bundle name and type.
+2. Select an optional starter artifact.
+3. Preview when requested, then run:
+
+   ```bash
+   aiwg new-bundle <name> \
+     [--type extension|addon|framework|plugin|provider] \
+     [--starter skill|rule|agent|minimal] \
+     [--description "..."] \
+     [--dry-run]
+   ```
+
+4. Deploy the completed bundle with `aiwg use <name>`.
+5. Validate project-local health with `aiwg doctor`.
+6. When the bundle is ready to graduate, use `aiwg promote <name> --dry-run`.
+
+The default type is `extension`; the default starter is `skill`. The aliases
+`new-extension`, `new-addon`, `new-framework`, `new-plugin`, and `new-provider`
+select their corresponding type.
+
+## Safety
+
+- Use `--dry-run` before scaffolding when the target or layout is uncertain.
+- Refuse to overwrite an existing bundle.
+- Keep project-local source in version control; provider deployment copies are
+  generated artifacts.
+
+## References
+
+- @$AIWG_ROOT/src/cli/handlers/subcommands.ts — `new-bundle` command handler
+- @$AIWG_ROOT/agentic/code/addons/aiwg-utils/skills/steward-quickref/SKILL.md

package/agentic/code/addons/aiwg-utils/skills/package-all-plugins/SKILL.md

@@ -17,7 +17,6 @@ Alternate expressions and non-obvious activations (primary phrases are matched a
 - "build all plugin archives" → batch package all plugins
 - "bundle all plugins" → batch package all plugins
 - "batch package the plugins" → batch package all plugins
-- "publish all plugins" → batch package all plugins (with --publish)
 
 ## Trigger Patterns Reference
 
@@ -25,18 +24,16 @@ Alternate expressions and non-obvious activations (primary phrases are matched a
 |---------|---------|--------|
 | Package all | "package all plugins" | Run `aiwg package-all-plugins` |
 | Bundle all | "bundle all plugins" | Run `aiwg package-all-plugins` |
-| Publish all | "publish all plugins" | Run `aiwg package-all-plugins --publish` |
 | Batch package | "batch package plugins" | Run `aiwg package-all-plugins` |
 | Dry run all | "validate all plugins before packaging" | Run `aiwg package-all-plugins --dry-run` |
-| Skip failures | "package all, skip broken ones" | Run `aiwg package-all-plugins --continue-on-error` |
 
 ## Behavior
 
 When triggered:
 
 1. **Extract intent**:
-   - Should packages be published after creation, or archived locally only?
-   - Should the batch abort on first failure, or continue and report all failures?
+   - Which provider wrappers should be generated?
+   - Should existing generated output be cleaned first?
    - Is this a dry run (validate only)?
 
 2. **Run the appropriate command**:
@@ -48,17 +45,11 @@ When triggered:
    # Validate all plugins — no archives created
    aiwg package-all-plugins --dry-run
 
-   # Package and publish all to marketplace
-   aiwg package-all-plugins --publish
+   # Package all Codex wrappers
+   aiwg package-all-plugins --provider codex
 
-   # Continue on individual failures, report all at end
-   aiwg package-all-plugins --continue-on-error
-
-   # Specify output directory for all archives
-   aiwg package-all-plugins --output dist/plugins/
-
-   # Bump all versions before packaging
-   aiwg package-all-plugins --bump patch
+   # Clean generated output before rebuilding
+   aiwg package-all-plugins --clean
    ```
 
 3. **Report the result** — list each marketplace wrapper with its status (packaged, failed, skipped), total count, and any errors.
@@ -68,10 +59,10 @@ When triggered:
 ```
 Packaging all plugins (4)...
 
-  sdlc       ✓ packaged   dist/plugins/sdlc-2026.4.0.aiwg-plugin.tar.gz
-  voice      ✓ packaged   dist/plugins/voice-2026.4.0.aiwg-plugin.tar.gz
-  marketing  ✓ packaged   dist/plugins/marketing-2026.4.0.aiwg-plugin.tar.gz
-  utils      ✗ failed     validate-metadata: 1 error in soul-blend/SKILL.md
+  sdlc       ✓ generated   agentic/code/plugins/sdlc
+  voice      ✓ generated   agentic/code/plugins/voice
+  marketing  ✓ generated   agentic/code/plugins/marketing
+  utils      ✗ failed      source validation error
 
 Packaged: 3 / 4
 Failed:   1 (utils)
@@ -79,11 +70,11 @@ Failed:   1 (utils)
 
 ## Failure Behavior
 
-By default (`--abort-on-error`), the batch stops at the first failure and reports the error. Use `--continue-on-error` to package all plugins and collect all errors for a single remediation pass.
+The batch reports an error and exits non-zero when packaging cannot complete.
 
 ## Relationship to `package-plugin`
 
-`package-all-plugins` is a thin loop over `package-plugin`. Each marketplace wrapper runs through the same validation and packaging logic as a single `package-plugin` call. Flags like `--dry-run`, `--publish`, and `--bump` are forwarded to each invocation.
+`package-all-plugins` uses the same packager as `package-plugin`. Supported shared flags are `--provider`, `--clean`, and `--dry-run`.
 
 ## Examples
 
@@ -98,7 +89,7 @@ By default (`--abort-on-error`), the batch stops at the first failure and report
 aiwg package-all-plugins
 ```
 
-**Response**: "Packaged 4/4 plugins. Archives in dist/plugins/: sdlc-2026.4.0, voice-2026.4.0, marketing-2026.4.0, utils-2026.4.0. All metadata validation passed."
+**Response**: "Generated 4/4 wrappers under `agentic/code/plugins/`."
 
 ### Example 2: Validate everything before tagging
 
@@ -113,34 +104,38 @@ aiwg package-all-plugins --dry-run
 
 **Response**: "Dry run: 4 plugins validated. 3 passed. 1 error: utils plugin — soul-blend/SKILL.md missing required field `id`. Fix and re-run."
 
-### Example 3: Package and publish in one step
+### Example 3: Package every Codex wrapper
 
-**User**: "Package and publish everything for the release"
+**User**: "Package every plugin for Codex"
 
-**Extraction**: Batch package and publish
+**Extraction**: Batch package for Codex
 
 **Action**:
 ```bash
-aiwg package-all-plugins --publish
+aiwg package-all-plugins --provider codex
 ```
 
-**Response**: "Packaged and published 4/4 plugins to the AIWG marketplace. sdlc, voice, marketing, utils — all at v2026.4.0."
+**Response**: "Generated every supported Codex plugin wrapper."
 
-### Example 4: Continue through failures
+### Example 4: Clean rebuild
 
-**User**: "Package all plugins but don't stop if one fails — I want to see all the errors at once"
+**User**: "Clean and rebuild all plugin wrappers"
 
-**Extraction**: Batch with `--continue-on-error`
+**Extraction**: Clean existing generated output and rebuild
 
 **Action**:
 ```bash
-aiwg package-all-plugins --continue-on-error
+aiwg package-all-plugins --clean
 ```
 
-**Response**: "Packaged 3/4 plugins. 1 failure: utils — validate-metadata error in soul-blend/SKILL.md line 4 (missing `id`). All other packages created in dist/plugins/."
+**Response**: "Cleaned and regenerated all supported plugin wrappers."
+
+## Unsupported legacy examples
+
+Earlier skill revisions documented `--publish`, `--bump`, `--output`, `--continue-on-error`, and `--abort-on-error`; the packager never implemented those flags. They are intentionally removed from the command contract. Use the repository release workflow for publication and update authoritative manifests separately before packaging.
 
 ## References
 
-- @$AIWG_ROOT/src/cli/handlers/utilities.ts — Command handler
+- @$AIWG_ROOT/src/cli/handlers/subcommands.ts — Command handler
 - @$AIWG_ROOT/docs/cli-reference.md — CLI reference
 - @$AIWG_ROOT/agentic/code/addons/aiwg-utils/skills/package-plugin/SKILL.md — Single-plugin packaging

package/agentic/code/addons/aiwg-utils/skills/package-plugin/SKILL.md

@@ -2,12 +2,19 @@
 namespace: aiwg
 name: package-plugin
 platforms: [all]
-description: Bundle a single marketplace delivery wrapper into a distributable archive, validating metadata and optionally publishing
+description: Package a built-in or standalone project-local AIWG plugin wrapper for marketplace distribution
+triggers:
+  - standalone plugin repository
+  - publish project-local plugin
+  - package project-local plugin
+  - community plugin repository
 ---
 
 # Package Plugin
 
-You bundle a single marketplace delivery wrapper for the AIWG marketplace. In AIWG vocabulary, the plugin layer packages an extension, addon, or framework payload for distribution. You validate metadata, create the package archive, and optionally publish to the registry.
+You validate and package either a built-in marketplace wrapper or a standalone
+project-local wrapper. Standalone wrappers are auto-discovered under
+`.aiwg/plugins/<name>/` and emitted as deterministic provider archives.
 
 ## Triggers
 
@@ -15,8 +22,9 @@ Alternate expressions and non-obvious activations (primary phrases are matched a
 
 - "bundle the voice plugin for release" → package voice plugin
 - "prepare the SDLC plugin for distribution" → package sdlc plugin
-- "I want to publish my plugin" → package and optionally publish
-- "create the plugin archive" → package without publishing
+- "create the plugin wrapper" → package the generated provider wrapper
+- "publish project-local plugin" → validate and package the repository-local wrapper
+- "standalone plugin repository" → use the community/team repository workflow
 
 ## Trigger Patterns Reference
 
@@ -24,10 +32,10 @@ Alternate expressions and non-obvious activations (primary phrases are matched a
 |---------|---------|--------|
 | Package plugin | "package plugin sdlc" | Run `aiwg package-plugin sdlc` |
 | Bundle plugin | "bundle plugin voice" | Run `aiwg package-plugin voice` |
-| Publish plugin | "publish plugin marketing" | Run `aiwg package-plugin marketing --publish` |
 | Create package | "create plugin package utils" | Run `aiwg package-plugin utils` |
 | Dry run | "validate sdlc plugin before packaging" | Run `aiwg package-plugin sdlc --dry-run` |
-| With version bump | "package voice with new version" | Run `aiwg package-plugin voice --bump patch` |
+| Standalone wrapper | "package project-local plugin team-tools" | Run `aiwg package-plugin team-tools --dry-run` |
+| Explicit source | "package wrapper from wrappers/team-tools" | Run `aiwg package-plugin team-tools --source wrappers/team-tools` |
 
 ## Behavior
 
@@ -35,8 +43,8 @@ When triggered:
 
 1. **Extract intent**:
    - Which delivery wrapper is being packaged?
-   - Should it be published after packaging, or just archived locally?
-   - Is a version bump needed?
+   - Which provider wrapper is needed?
+   - Should existing generated output be cleaned first?
    - Is this a validation dry run?
 
 2. **Run the appropriate command**:
@@ -50,22 +58,24 @@ When triggered:
    # Validate only — no archive created
    aiwg package-plugin sdlc --dry-run
 
-   # Package and publish to marketplace
-   aiwg package-plugin sdlc --publish
+   # Build one provider-specific wrapper
+   aiwg package-plugin sdlc --provider codex
 
-   # Bump version before packaging
-   aiwg package-plugin voice --bump patch
-   aiwg package-plugin voice --bump minor
+   # Clean generated output before rebuilding
+   aiwg package-plugin sdlc --clean
 
-   # Specify output directory
-   aiwg package-plugin sdlc --output dist/plugins/
+   # Standalone/project-local wrapper (auto-discovered)
+   aiwg package-plugin team-tools --provider all --output dist/plugins
+
+   # Explicit in-repository source
+   aiwg package-plugin team-tools --source wrappers/team-tools --provider codex
    ```
 
-3. **Report the result** — confirm archive path, included file count, and publish status.
+3. **Report the result** — confirm generated wrapper path and included file counts.
 
 ## What the Package Contains
 
-A plugin package archive (`.aiwg-plugin.tar.gz`) is a delivery wrapper. It includes the manifest plus the payload files being distributed:
+A generated plugin wrapper includes provider metadata plus the selected payload files:
 
 | Contents | Path in Archive |
 |----------|----------------|
@@ -101,7 +111,7 @@ Packaging fails if any validation step fails.
 aiwg package-plugin voice
 ```
 
-**Response**: "Packaged voice@aiwg v2026.4.0. Archive: dist/plugins/voice-2026.4.0.aiwg-plugin.tar.gz (42 files, 1.2MB). Metadata validation passed. Ready to publish with `aiwg package-plugin voice --publish`."
+**Response**: "Generated the voice marketplace wrapper under `agentic/code/plugins/voice`."
 
 ### Example 2: Validate before packaging
 
@@ -116,34 +126,53 @@ aiwg package-plugin sdlc --dry-run
 
 **Response**: "Dry run: sdlc plugin metadata passed (58 agents, 42 commands, 12 skills, 33 rules validated). Ready to package. 1 warning: CHANGELOG.md not found — package will be created without it."
 
-### Example 3: Package and publish in one step
+### Example 3: Package for Codex
 
-**User**: "Publish the marketing plugin to the marketplace"
+**User**: "Build the marketing plugin for Codex"
 
-**Extraction**: Package and publish marketing plugin
+**Extraction**: Package marketing for the Codex provider
 
 **Action**:
 ```bash
-aiwg package-plugin marketing --publish
+aiwg package-plugin marketing --provider codex
 ```
 
-**Response**: "Packaged and published marketing@aiwg v2026.4.0 to the AIWG marketplace. Archive: dist/plugins/marketing-2026.4.0.aiwg-plugin.tar.gz. Registry updated."
+**Response**: "Generated the Codex marketing wrapper under `agentic/code/plugins/marketing`."
 
-### Example 4: Package with version bump
+### Example 4: Clean rebuild
 
-**User**: "Bump and package the utils plugin with a patch version"
+**User**: "Clean and rebuild the utils plugin"
 
-**Extraction**: Bump patch version then package
+**Extraction**: Remove prior generated output, then package
 
 **Action**:
 ```bash
-aiwg package-plugin utils --bump patch
+aiwg package-plugin utils --clean
 ```
 
-**Response**: "Bumped utils version 2026.3.5 → 2026.4.0. Packaged. Archive: dist/plugins/utils-2026.4.0.aiwg-plugin.tar.gz."
+**Response**: "Cleaned and regenerated the utils wrapper."
+
+## Standalone repository contract
+
+The wrapper must contain `manifest.json` with `type: plugin` and a
+`pluginConfig` declaring `payloadType` and traversal-safe `payloadPath`. The
+payload requires its own matching manifest. Sources must remain inside the
+current repository; symlink escapes and output collisions are rejected.
+Payload files are copied byte-for-byte into deterministic Claude and/or Codex
+archives.
+
+See `docs/customization/standalone-plugin-repository.md` for the complete
+scaffold, validation, install-smoke, versioning, licensing, and publication
+workflow.
+
+## Unsupported legacy examples
+
+`--publish` and `--bump` remain intentionally unsupported. Publish generated
+archives through the repository's release workflow and change versions in the
+authoritative wrapper/payload manifests before packaging.
 
 ## References
 
-- @$AIWG_ROOT/src/cli/handlers/utilities.ts — Command handler
+- @$AIWG_ROOT/src/cli/handlers/subcommands.ts — Command handler
 - @$AIWG_ROOT/docs/cli-reference.md — CLI reference
 - @$AIWG_ROOT/docs/contributing/versioning.md — CalVer versioning rules

package/agentic/code/addons/aiwg-utils/skills/promote/SKILL.md

@@ -0,0 +1,48 @@
+---
+namespace: aiwg
+name: promote
+platforms: [all]
+description: Promote or graduate a project-local bundle to its upstream AIWG location or to a private corpus path.
+triggers:
+  - promote bundle
+  - promote project-local
+  - graduate project-local bundle
+  - graduate to upstream
+  - project-local bundle
+---
+
+# Promote Project-Local Bundle
+
+Graduate a proven project-local bundle without losing its source provenance.
+
+## Behavior
+
+1. Identify the project-local bundle and its intended destination.
+2. Preview the copy and registry transition:
+
+   ```bash
+   aiwg promote <name> --dry-run
+   ```
+
+3. Promote to the declared upstream location or a private corpus:
+
+   ```bash
+   aiwg promote <name> --to upstream
+   aiwg promote <name> --to corpus <path>
+   ```
+
+4. Use `--cleanup` only when the project-local source should be removed after
+   successful promotion. Use `--force` only after reviewing a destination
+   conflict.
+
+## Safety
+
+- Run `aiwg doctor` and a dry run before promotion.
+- Promotion verifies the bundle manifest and destination before copying.
+- Omit `--cleanup` to retain the project-local source.
+
+## References
+
+- @$AIWG_ROOT/src/cli/handlers/subcommands.ts — `promote` command handler
+- @$AIWG_ROOT/src/extensions/project-local-promote.ts — promotion implementation
+- @$AIWG_ROOT/agentic/code/addons/aiwg-utils/skills/steward-quickref/SKILL.md

package/agentic/code/addons/aiwg-utils/skills/steward-quickref/SKILL.md

@@ -51,6 +51,7 @@ command output.
 | Create an addon | `aiwg discover "create an addon"` | `scaffold-addon` |
 | Build a framework | `aiwg discover "scaffold a framework"` | `scaffold-framework` |
 | Pilot then graduate a project-local bundle | `aiwg discover "project-local bundle"` | `new-bundle`, `promote` |
+| Package a standalone/community plugin repository | `aiwg discover "standalone plugin repository"` | `package-plugin` |
 
 ## Domain 2 — Persona / SOUL identity (author **and** select)
 

package/agentic/code/addons/aiwg-utils/skills/update/SKILL.md

@@ -2,13 +2,13 @@
 namespace: aiwg
 name: update
 platforms: [all]
-description: Update AIWG to the latest stable version and re-deploy all installed frameworks from the registry
+description: Update AIWG through its install-aware updater and re-deploy all installed frameworks from the registry
 
 ---
 
 # AIWG Update
 
-You update AIWG to the latest stable version and re-deploy all installed frameworks from the registry.
+You update AIWG through its canonical install-aware command and re-deploy all installed frameworks from the registry.
 
 ## Triggers
 
@@ -64,7 +64,10 @@ When triggered:
    ```
 
    Execution sequence:
-   1. Check npm/git for a newer version (unless `--skip-check`)
+   1. Detect the active distribution and update safely (unless `--skip-check`)
+      - full `aiwg` npm package: preserve `stable`, `next`, or `nightly`
+      - lightweight `@aiwg/cli`: follow its signed web resource channel without replacing it with the full package
+      - source/dev checkout: print the supported Git/build workflow without overwriting the checkout
    2. Read `.aiwg/frameworks/registry.json` to find installed frameworks
    3. Re-deploy each installed framework via `aiwg use <framework> [--provider <name>]`
    4. Print update summary with per-framework pass/fail status
@@ -77,7 +80,7 @@ When triggered:
 
 | | `aiwg update` | `aiwg sync` |
 |---|---|---|
-| Target channel | Stable only (default) | Follows configured channel |
+| Target channel | Preserves configured channel | Preserves or explicitly switches configured channel |
 | Scope | Installed frameworks only (default) | All deployed frameworks |
 | Typical use | "Get the latest stable release" | "Keep this session current" |
 
@@ -159,5 +162,5 @@ If the request is ambiguous between update and sync:
 ## References
 
 - @$AIWG_ROOT/src/cli/handlers/utilities.ts — Update command handler (updateHandler)
-- @$AIWG_ROOT/src/update/checker.mjs — npm/git update check logic
+- @$AIWG_ROOT/src/update/service.mjs — install-aware update dispatch
 - @$AIWG_ROOT/docs/cli-reference.md — CLI reference

package/agentic/code/frameworks/media-curator/README.md

@@ -29,6 +29,9 @@ aiwg use media-curator
 # Create a research-grade transcript sidecar
 /transcribe-media /path/to/acquired-media.wav --source-url https://example.invalid/source
 
+# Create a diarized transcript sidecar with anonymous speaker clusters
+/diarize-media /path/to/acquired-media.wav --min-speakers 2 --max-speakers 2
+
 # Hand acquired media and transcript metadata to research-complete
 /induct-media metadata.json --transcript media.transcript.json --source-url https://example.invalid/source --storage hash-only
 
@@ -51,6 +54,7 @@ aiwg use media-curator
 | Multi-platform format export | (integrated) | `/export` |
 | SHA-256 integrity verification | (integrated) | `/verify-archive` |
 | Timestamped transcript sidecars | (integrated) | `/transcribe-media` |
+| Speaker diarization sidecars | (integrated) | `/diarize-media` |
 | Research media handoff | (research-complete) | `/induct-media` |
 
 ## Architecture
@@ -88,6 +92,7 @@ media-curator/
 │   ├── cover-art-embedding.md      # Artwork embedding
 │   ├── integrity-verification.md   # SHA-256 manifests
 │   ├── transcribe-media.md         # Transcript sidecars for research handoff
+│   ├── diarize-media.md            # Anonymous speaker-cluster diarization
 │   ├── gap-documentation.md        # GAP-NOTE.md pattern
 │   └── provenance-tracking.md      # W3C PROV-O for media
 ├── config/

package/agentic/code/frameworks/media-curator/skills/diarize-media/SKILL.md

@@ -0,0 +1,92 @@
+---
+namespace: aiwg
+platforms: [all]
+name: diarize-media
+description: Run local speaker diarization for acquired audio/video with WhisperX and pyannote, preserving anonymous speaker clusters in canonical transcript sidecars
+script:
+  entrypoint: scripts/diarize_media.mjs
+  runtime: node
+  cwd: project-root
+  argsHint: "run --media <file> --output <sidecar.json> --credential-provider env:HF_TOKEN [--min-speakers N] [--max-speakers N]"
+triggers:
+  - "speaker diarization audio"
+  - "diarize media"
+  - "diarize audio speakers"
+  - "diarize video speakers"
+  - "transcribe and diarize media speakers"
+  - "speaker clustering media"
+category: media-curator
+---
+
+# Diarize Media
+
+Run local speaker diarization for acquired audio/video and write a canonical
+`aiwg.media.transcript.v1` sidecar. This is a dedicated routing skill for the
+diarization part of the media-curator transcript workflow.
+
+## What Diarization Means
+
+Speaker diarization is anonymous clustering: it answers "which portions sound
+like the same speaker?" with labels such as `SPEAKER_00` and `SPEAKER_01`.
+
+Speaker identification is different: it maps an anonymous cluster to a verified
+person. Do not replace anonymous labels with names unless acquisition metadata,
+a human transcript, or explicit review evidence supports that mapping.
+
+## Executable Adapter
+
+The bundled adapter uses WhisperX plus pyannote Community-1:
+
+```bash
+HF_TOKEN="$TOKEN_FROM_OPERATOR_OR_VAULT" \
+aiwg run skill diarize-media -- run \
+  --media /path/to/interview.wav \
+  --output .aiwg/media/transcripts/interview.transcript.json \
+  --credential-provider env:HF_TOKEN \
+  --min-speakers 2 \
+  --max-speakers 2
+```
+
+The credential provider is a reference, not a token value. The adapter checks
+the referenced environment variable before transcription starts, injects it into
+the local WhisperX process environment, and never writes token values to argv,
+disk, logs, state, provenance, or manifests.
+
+## Preflight
+
+```bash
+aiwg run skill diarize-media -- preflight \
+  --media /path/to/interview.wav \
+  --output .aiwg/media/transcripts/interview.transcript.json \
+  --credential-provider env:HF_TOKEN \
+  --min-speakers 2 \
+  --max-speakers 2 \
+  --format json
+```
+
+Preflight checks:
+- media readability and source SHA-256
+- output directory writability
+- `whisperx` availability
+- `ffmpeg` availability warning
+- CPU/GPU capability reporting
+- gated-model authorization through the named credential provider
+
+Missing authorization emits `aiwg.media.transcript-plan.v1` with
+`status: blocked-credential-missing` before the expensive STT stage.
+
+## Output And Degraded Mode
+
+Successful runs produce the same canonical sidecar as `transcribe-media`, with
+stable segment IDs, source and transcript hashes, tool provenance, anonymous
+speaker labels, and quality limitations.
+
+If WhisperX writes transcription/alignment JSON and then exits non-zero during
+diarization, the adapter preserves the completed output as a valid sidecar with
+`transcript.quality.status: degraded-diarization-failed`. If no native JSON is
+available, it writes an actionable transcript plan instead of fabricating text.
+
+## References
+
+- @$AIWG_ROOT/agentic/code/frameworks/media-curator/skills/transcribe-media/SKILL.md — Shared transcript sidecar schema and WhisperX adapter
+- @$AIWG_ROOT/agentic/code/frameworks/media-curator/skills/provenance-tracking/SKILL.md — Provenance model for derived media artifacts

package/agentic/code/frameworks/media-curator/skills/diarize-media/scripts/diarize_media.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { main } from '../../transcribe-media/scripts/transcribe_media.mjs';
+
+const code = await main(process.argv.slice(2), {
+  defaultDiarize: true,
+  activity: 'diarize-media',
+});
+process.exitCode = code;