@event4u/agent-config 2.21.0 → 2.24.0

package/docs/guidelines/prompt-templates.md

@@ -0,0 +1,166 @@
+# Prompt Templates
+
+Reference catalogue of prompt structures the [`prompt-optimizer`](../../.agent-src.uncompressed/skills/prompt-optimizer/SKILL.md)
+skill picks from during the **Develop** step of the 4-D methodology.
+Cited by the [`refine-prompt`](../../.agent-src.uncompressed/skills/refine-prompt/SKILL.md)
+skill in `mini` mode for stack-aware shaping.
+
+Templates are tools, not dogma. Pick by request type, not by upstream
+whitelist — see the [Rejection note](#rejection-note) at the bottom.
+
+## When-to-pick rubric
+
+| Request shape | First-choice template | Fallback |
+|---|---|---|
+| One-shot technical change (refactor, lint fix) | **RTF** | File-Scope |
+| Multi-file refactor across a codebase | **File-Scope** | RTF |
+| Marketing / brand / tone-heavy copy | **CO-STAR** | CRISPE |
+| Mixed-audience explainer (technical + lay) | **CRISPE** | CO-STAR |
+| Step-by-step explainer / tutorial | **RISEN** | Few-Shot |
+| Pattern-heavy task (classification, extraction) | **Few-Shot** | RISEN |
+| Multi-step reasoning or math | **CoT** | ReAct |
+| Tool-using agent (web search, file ops) | **ReAct** | CoT |
+| Image AI (Midjourney, SD, DALL·E) | **Visual Descriptor** | Reference-Image-Edit |
+| Image edit from a source image | **Reference-Image-Edit** | Visual Descriptor |
+| ComfyUI / node-graph image workflows | **ComfyUI** | Visual Descriptor |
+| Reverse-engineer an existing good prompt | **Prompt Decompiler** | — |
+| Honest critical feedback on a finished artifact (post, design, naming, proposal) — any domain | **Honest Sparring Partner** | CRISPE |
+
+## Text templates
+
+### RTF — Role · Task · Format
+Smallest viable structure. Three lines: who the AI is, what to do,
+how the output should look. Best for one-shot technical asks.
+
+### CO-STAR — Context · Objective · Style · Tone · Audience · Response
+Six-slot structure originally from the Singapore GovTech prompt
+study. Best for copy where audience and tone carry the message.
+
+### RISEN — Role · Input · Steps · Expectation · Narrowing
+Step-explicit shape. Best for tutorials, walkthroughs, and any
+output where the reader follows the prompt's structure.
+
+### CRISPE — Capacity · Role · Insight · Statement · Personality · Experiment
+Six-slot, persona-heavy. Best when the *voice* matters more than
+the structure (creative writing, explainers with a strong narrator).
+
+### CoT — Chain-of-Thought
+Append "Think step by step" or "Reason aloud before answering" to
+any base template. Best for multi-step reasoning, math, planning.
+Pairs well with RTF or RISEN.
+
+### Few-Shot
+Two to five worked examples inline before the actual ask. Best for
+classification, extraction, format-mimicking. Costs tokens — keep
+examples minimal and representative.
+
+### File-Scope
+Codebase-aware variant of RTF. Names the files in scope, the
+allowed-edit list, and the "do not touch" list explicitly. Best for
+agent-driven refactors where blast radius matters.
+
+```
+Role: senior TypeScript engineer
+Files in scope: src/auth/*.ts, tests/auth/*.ts
+Do not modify: src/db/*, package.json, tsconfig.json
+Task: migrate from jsonwebtoken to jose; keep the exported API stable
+Format: unified diff
+```
+
+### ReAct — Reason + Act
+Interleaved thought / action / observation loop. Best for agents
+with tools — web search, file ops, shell. Each cycle:
+
+```
+Thought: <why I need this next step>
+Action: <tool call>
+Observation: <result>
+... repeat ...
+Final Answer: <synthesis>
+```
+
+### Honest Sparring Partner
+Domain-agnostic stance template for getting honest critical feedback on
+a finished artifact — blog post, design draft, naming decision, business
+proposal, care-plan, marketing copy. Works for any role (engineer,
+graphic designer, nurse, founder) because the role slot is filled by
+the user's actual profession, not hard-coded.
+
+Five-slot shape:
+
+```
+Role: <user's domain> — e.g. graphic designer, geriatric nurse, founder
+Stance: honest sparring partner, not yes-man. Push back when something
+        is weak; acknowledge when something is solid; stay silent when
+        there is nothing substantive to add. No flattery openings, no
+        artificial criticism for its own sake.
+Context-fit: ask ONE clarifying question only if real context is missing
+             (role, audience, constraint). Otherwise answer directly.
+Artifact: <the finished thing — paste, link, or describe>
+Ask: <what kind of reaction the user wants — "does the argument hold?",
+     "is the naming clear?", "would this land with audience X?">
+```
+
+**Anti-pattern this rejects:** "what do you honestly think?" prompts that
+either default to praise ("looks great!") or default to manufactured
+criticism ("here are 5 problems...") regardless of whether the work
+warrants either reaction. The stance slot makes the honest-when-warranted
+contract explicit.
+
+**Package equivalents** — inside this agent-config, the
+[`adversarial-review`](../../.agent-src.uncompressed/skills/adversarial-review/SKILL.md)
+skill implements the same stance via an Attack-Defend-Revise loop and is
+the right tool when the user submits finished work for a critical take.
+This template is for **end-users prompting their own LLM** (ChatGPT,
+Claude, Gemini) outside this package.
+
+## Image templates
+
+### Visual Descriptor
+Subject · style · composition · lighting · medium · mood · technical
+parameters (aspect ratio, resolution). Best for Midjourney, Stable
+Diffusion, DALL·E from a blank canvas.
+
+### Reference-Image-Edit
+Source image reference + change set + preservation set. Names what
+to change, what to keep, and the desired output framing. Best for
+inpainting, style transfer, character consistency.
+
+### ComfyUI
+Node-graph-aware. Names the workflow nodes (KSampler, CLIPTextEncode,
+VAEDecode) and the parameter intent per node rather than the
+parameter values. Best for advanced SD pipelines.
+
+## Reverse template
+
+### Prompt Decompiler
+Given an existing good output, reconstruct the prompt that would
+produce it. Used to mine prompts from public LLM artifacts. Not a
+shaping template — a forensic one.
+
+## Rejection note
+
+Upstream `nidhinjs/prompt-master` claims that only five techniques
+are "safe" for production prompting:
+
+- few-shot
+- role assignment
+- structured output
+- constraint-based
+- chain-of-thought
+
+This package **rejects** that whitelist. CO-STAR, RISEN, CRISPE,
+ReAct, and the image-AI templates above are first-class. The
+"5 safe" framing came from a single benchmark on a single LLM
+generation — it does not generalise. See AI Council session
+`agents/council-responses/prompt-master-mini.json` (2026-05-17) for the analysis behind this rejection. <!-- council-ref-allowed: ADR decision trace -->
+
+The right gate is request-type fit, not technique-whitelist
+membership.
+
+## See also
+
+- [`prompt-optimizer`](../../.agent-src.uncompressed/skills/prompt-optimizer/SKILL.md) — engine-outbound; cites this catalogue in its Develop step
+- [`refine-prompt`](../../.agent-src.uncompressed/skills/refine-prompt/SKILL.md) — engine-inbound; uses templates in `mini` mode for stack-aware shaping
+- [`prompt-engineering-patterns`](../../.agent-src.uncompressed/skills/prompt-engineering-patterns/SKILL.md) — production-LLM prompt patterns (sibling skill, not a catalogue)
+- AI Council session: `agents/council-responses/prompt-master-mini.json` (2026-05-17) <!-- council-ref-allowed: ADR decision trace -->

package/docs/parity/ruflo.md

@@ -2,7 +2,7 @@
 
 > Per-row verdict against the eight Ruflo measurement-governance patterns
 > catalogued in
-> [`external-findings.md § 2`](../../agents/audit-2026-05-14-north-star/external-findings.md).
+> [`external-findings.md § 2`](../../agents/council-sessions/audit-2026-05-14-north-star/external-findings.md).
 > Owner roadmap: [`step-11-ruflo-parity.md`](../../agents/roadmaps/step-11-ruflo-parity.md)
 > (Phase 6 Step 1). Cross-index lives at
 > [`step-99-north-star-restructure.md`](../../agents/roadmaps/step-99-north-star-restructure.md)
@@ -10,7 +10,7 @@
 >
 > **Verdict legend:** `[x] covered by <file:line>` · `[~] superseded by <approach>` · `[!] gap`.
 > **Acceptance:** zero `[!]` rows. Closure flips the corresponding cell in the
-> [composite scorecard](../../agents/audit-2026-05-14-north-star/external-findings.md#5-composite-scorecard--agent-config-vs-the-field)
+> [composite scorecard](../../agents/council-sessions/audit-2026-05-14-north-star/external-findings.md#5-composite-scorecard--agent-config-vs-the-field)
 > `vs Ruflo` column from `–` to `=` or `+`.
 
 **Measured-vs-claimed disclaimer:** Each row cites the **mechanism** that
@@ -41,6 +41,6 @@ mechanisms remain claimed until [`bench.json`](bench.json) soak completes
 
 ## Cross-references
 
-- Composite scorecard refresh: owned by [`step-99-north-star-restructure.md`](../../agents/roadmaps/step-99-north-star-restructure.md) Phase 5 Step 4 (replaces [`external-findings.md § 5`](../../agents/audit-2026-05-14-north-star/external-findings.md)).
+- Composite scorecard refresh: owned by [`step-99-north-star-restructure.md`](../../agents/roadmaps/step-99-north-star-restructure.md) Phase 5 Step 4 (replaces [`external-findings.md § 5`](../../agents/council-sessions/audit-2026-05-14-north-star/external-findings.md)).
 - Bench-ruflo redundancy verdict: [`bench-ruflo.json`](bench-ruflo.json) (step-11 Phase 6 Step 2).
 - G5 redundancy gate cite: step-99 Acceptance Criteria row "G5 — external redundancy (Domination Mandate)".

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "2.21.0",
+    "version": "2.24.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/ai-video/adapters/gemini-veo.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# gemini-veo.sh — Google Gemini Veo video generation adapter.
+#
+# Capability: audio=native. Veo accepts dialogue + ambient sound blocks
+# and returns a muxed MP4. Async API: submit → poll (predictLongRunning)
+# → fetch. The orchestrator drives all three subcommands; this script
+# never auto-retries.
+#
+# Contract: scripts/ai-video/lib/adapter-contract.md
+# Provider: top-level <provider id="gemini-veo" kind="video"> in
+# agents/.ai-video.xml.
+
+set -euo pipefail
+
+# shellcheck source=../lib/adapter-common.sh
+. "$(dirname "$0")/../lib/adapter-common.sh"
+
+ADAPTER_ID="gemini-veo"
+
+# Submit: read contract JSON from stdin, return {job_id, status:"queued"}.
+aiv_cmd_submit() {
+  aiv_assert_dryrun
+  aiv_require_cmd curl jq
+  aiv_load_provider "${ADAPTER_ID}"
+  [ "$(aiv_key_status)" = "present" ] \
+    || aiv_die 6 "${ADAPTER_ID}: api key missing in agents/.ai-video.xml"
+
+  local stdin_json
+  stdin_json="$(cat)"
+  # Validate required prompt blocks early so a bad blueprint fails
+  # before any network call would happen.
+  printf '%s' "${stdin_json}" | jq -e '.prompt.subject and .prompt.action' >/dev/null \
+    || aiv_die 3 "${ADAPTER_ID}: stdin JSON missing required prompt.subject / prompt.action"
+
+  aiv_die 9 "${ADAPTER_ID}: live submit not yet wired (predictLongRunning endpoint requires per-key wiring)"
+}
+
+# Poll: check long-running operation status. Stub returns "done" so the
+# stitcher path is exercisable end-to-end in dry-run; live mode is
+# wired by the orchestrator once a real job_id exists.
+aiv_cmd_poll() {
+  local job_id="${1:-}"
+  [ -n "${job_id}" ] || aiv_die 2 "${ADAPTER_ID}: poll <job_id> required"
+  aiv_assert_dryrun
+  aiv_die 9 "${ADAPTER_ID}: live poll not yet wired (job=${job_id})"
+}
+
+# Fetch: download the muxed MP4. Live mode is stubbed; dry-run returns
+# the fixture path with audio_embedded=true.
+aiv_cmd_fetch() {
+  local job_id="${1:-}"
+  [ -n "${job_id}" ] || aiv_die 2 "${ADAPTER_ID}: fetch <job_id> required"
+  aiv_assert_dryrun
+  aiv_die 9 "${ADAPTER_ID}: live fetch not yet wired (job=${job_id})"
+}
+
+aiv_dispatch "${ADAPTER_ID}" "native" "$@"

package/scripts/ai-video/adapters/higgsfield.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# higgsfield.sh — Higgsfield motion-preset video adapter.
+#
+# Capability: per-model. The provider exposes named motion presets
+# (e.g. Mix, Burst, DVD) each with its own audio behaviour. Capability
+# discovery via `capability --preset <name>` so the orchestrator can
+# pick the right mux path.
+#
+# Contract: scripts/ai-video/lib/adapter-contract.md
+# Provider: top-level <provider id="higgsfield" kind="video"> in
+# agents/.ai-video.xml. Preset → motion-choreographer profile mapping
+# is documented in agents/ai-video/prompts/motion-choreography.md
+# (Phase 6).
+
+set -euo pipefail
+
+# shellcheck source=../lib/adapter-common.sh
+. "$(dirname "$0")/../lib/adapter-common.sh"
+
+ADAPTER_ID="higgsfield"
+
+# Map preset → audio capability. Conservative defaults; tuning table
+# lives alongside the prompt library so creators can extend without
+# touching this adapter.
+higgsfield_audio_for_preset() {
+  case "${1:-}" in
+    mix|burst|dvd) printf 'none' ;;
+    cinematic|talk) printf 'native' ;;
+    *) printf 'none' ;;
+  esac
+}
+
+# Override capability handling so `capability --preset <name>` answers
+# per-preset before falling through to the generic helper.
+aiv_higgsfield_capability() {
+  local preset=""
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --preset) preset="${2:-}"; shift 2 ;;
+      *) shift ;;
+    esac
+  done
+  if [ -n "${preset}" ]; then
+    printf '{"audio":"%s","preset":"%s"}\n' \
+      "$(higgsfield_audio_for_preset "${preset}")" "${preset}"
+    return 0
+  fi
+  printf '{"audio":"per-model","presets":["mix","burst","dvd","cinematic","talk"]}\n'
+}
+
+aiv_cmd_submit() {
+  aiv_assert_dryrun
+  aiv_require_cmd curl jq
+  aiv_load_provider "${ADAPTER_ID}"
+  [ "$(aiv_key_status)" = "present" ] \
+    || aiv_die 6 "${ADAPTER_ID}: api key missing in agents/.ai-video.xml"
+  aiv_die 9 "${ADAPTER_ID}: live submit not yet wired"
+}
+
+aiv_cmd_poll() {
+  local job_id="${1:-}"
+  [ -n "${job_id}" ] || aiv_die 2 "${ADAPTER_ID}: poll <job_id> required"
+  aiv_assert_dryrun
+  aiv_die 9 "${ADAPTER_ID}: live poll not yet wired (job=${job_id})"
+}
+
+aiv_cmd_fetch() {
+  local job_id="${1:-}"
+  [ -n "${job_id}" ] || aiv_die 2 "${ADAPTER_ID}: fetch <job_id> required"
+  aiv_assert_dryrun
+  aiv_die 9 "${ADAPTER_ID}: live fetch not yet wired (job=${job_id})"
+}
+
+# Custom dispatch with capability override; falls back to the common
+# router for every other subcommand.
+sub="${1:-}"
+if [ "${sub}" = "capability" ]; then
+  shift
+  aiv_higgsfield_capability "$@"
+  exit 0
+fi
+aiv_dispatch "${ADAPTER_ID}" "per-model" "$@"

package/scripts/ai-video/adapters/kling.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# kling.sh — Kuaishou Kling motion-tuned video generation adapter.
+#
+# Capability: audio=none by default (Kling current generation does not
+# emit native audio); the orchestrator muxes operator-supplied dialogue
+# / ambient at stitch time. Max duration is model-dependent; clip-time
+# clamping happens in motion-choreographer (it tunes the prompt to fit).
+#
+# Contract: scripts/ai-video/lib/adapter-contract.md
+# Provider: top-level <provider id="kling" kind="video"> in
+# agents/.ai-video.xml.
+
+set -euo pipefail
+
+# shellcheck source=../lib/adapter-common.sh
+. "$(dirname "$0")/../lib/adapter-common.sh"
+
+ADAPTER_ID="kling"
+KLING_MAX_DURATION="${KLING_MAX_DURATION:-10}"
+
+aiv_cmd_submit() {
+  aiv_assert_dryrun
+  aiv_require_cmd curl jq
+  aiv_load_provider "${ADAPTER_ID}"
+  [ "$(aiv_key_status)" = "present" ] \
+    || aiv_die 6 "${ADAPTER_ID}: api key missing in agents/.ai-video.xml"
+
+  local stdin_json duration
+  stdin_json="$(cat)"
+  duration="$(printf '%s' "${stdin_json}" | jq -r '.duration // empty')"
+  if [ -n "${duration}" ]; then
+    awk -v d="${duration}" -v m="${KLING_MAX_DURATION}" \
+      'BEGIN { if (d+0 > m+0) exit 1; exit 0 }' \
+      || aiv_die 3 "${ADAPTER_ID}: duration ${duration}s exceeds model max ${KLING_MAX_DURATION}s"
+  fi
+
+  aiv_die 9 "${ADAPTER_ID}: live submit not yet wired (max duration ${KLING_MAX_DURATION}s honored)"
+}
+
+aiv_cmd_poll() {
+  local job_id="${1:-}"
+  [ -n "${job_id}" ] || aiv_die 2 "${ADAPTER_ID}: poll <job_id> required"
+  aiv_assert_dryrun
+  aiv_die 9 "${ADAPTER_ID}: live poll not yet wired (job=${job_id})"
+}
+
+aiv_cmd_fetch() {
+  local job_id="${1:-}"
+  [ -n "${job_id}" ] || aiv_die 2 "${ADAPTER_ID}: fetch <job_id> required"
+  aiv_assert_dryrun
+  aiv_die 9 "${ADAPTER_ID}: live fetch not yet wired (job=${job_id})"
+}
+
+aiv_dispatch "${ADAPTER_ID}" "none" "$@"

package/scripts/ai-video/adapters/openai-images.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# openai-images.sh — image generation adapter (DALL-E / gpt-image-1).
+#
+# Capability: audio=none (still images only — motion handled by a
+# downstream video adapter). Ref-image and seed reuse are passed
+# through verbatim so character-consistency can lock a face across
+# scenes by reusing the same seed.
+#
+# Contract: scripts/ai-video/lib/adapter-contract.md
+# Provider: top-level <provider id="openai-images" kind="image"> in
+# agents/.ai-video.xml.
+
+set -euo pipefail
+
+# shellcheck source=../lib/adapter-common.sh
+. "$(dirname "$0")/../lib/adapter-common.sh"
+
+ADAPTER_ID="openai-images"
+
+aiv_cmd_run() {
+  aiv_assert_dryrun
+  aiv_require_cmd curl jq
+  aiv_load_provider "${ADAPTER_ID}"
+  [ "$(aiv_key_status)" = "present" ] \
+    || aiv_die 6 "${ADAPTER_ID}: api key missing in agents/.ai-video.xml"
+
+  # Read contract stdin JSON; compose a single text prompt from the
+  # eight prose blocks. Ref-image + seed are passed verbatim.
+  local stdin_json prompt seed ref_first
+  stdin_json="$(cat)"
+  prompt="$(printf '%s' "${stdin_json}" | jq -r '
+    [.prompt.style, .prompt.subject, .prompt.environment, .prompt.action,
+     .prompt.camera, .prompt.lens, .prompt.lighting, .prompt.mood]
+    | map(select(. != null and . != ""))
+    | join(". ")
+  ')"
+  seed="$(printf '%s' "${stdin_json}" | jq -r '.seed // empty')"
+  ref_first="$(printf '%s' "${stdin_json}" | jq -r '.ref_images[0] // empty')"
+
+  # Live mode is implementation-scaffolded: we do NOT yet POST to the
+  # OpenAI Images API from inside this adapter. The cost-floor gate
+  # (Phase 5 Step 6) refuses live mode unless the operator explicitly
+  # confirms in-turn; this branch surfaces a clear stub error so the
+  # contract surface stays stable while the live path is wired later.
+  aiv_die 9 "${ADAPTER_ID}: live mode not yet wired (prompt=${#prompt} chars, seed=${seed:-unset}, ref=${ref_first:-none})"
+}
+
+aiv_cmd_submit() { aiv_cmd_run "$@"; }
+aiv_cmd_fetch()  { aiv_cmd_run "$@"; }
+aiv_cmd_poll()   { printf '{"status":"done"}\n'; }
+
+aiv_dispatch "${ADAPTER_ID}" "none" "$@"

package/scripts/ai-video/adapters/sora.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# sora.sh — OpenAI Sora structural-prompt video adapter.
+#
+# Capability: audio=native. Sora-class models produce muxed MP4 with
+# dialogue + ambient sound; we pass the audio block straight through.
+# Structural-prompt path informed by upstream `awesome-sora-prompts`
+# (attribution in agents/ai-video/prompts/cinematic-blueprint.md).
+#
+# Contract: scripts/ai-video/lib/adapter-contract.md
+# Provider: top-level <provider id="sora" kind="video"> in
+# agents/.ai-video.xml.
+
+set -euo pipefail
+
+# shellcheck source=../lib/adapter-common.sh
+. "$(dirname "$0")/../lib/adapter-common.sh"
+
+ADAPTER_ID="sora"
+
+aiv_cmd_submit() {
+  aiv_assert_dryrun
+  aiv_require_cmd curl jq
+  aiv_load_provider "${ADAPTER_ID}"
+  [ "$(aiv_key_status)" = "present" ] \
+    || aiv_die 6 "${ADAPTER_ID}: api key missing in agents/.ai-video.xml"
+
+  local stdin_json
+  stdin_json="$(cat)"
+  # Sora's structural-prompt path expects all eight blocks present;
+  # fail loud if the blueprint parser dropped any.
+  printf '%s' "${stdin_json}" \
+    | jq -e '.prompt.style and .prompt.subject and .prompt.environment and
+             .prompt.action and .prompt.camera and .prompt.lens and
+             .prompt.lighting and .prompt.mood' >/dev/null \
+    || aiv_die 3 "${ADAPTER_ID}: stdin JSON missing one or more required prompt blocks"
+
+  aiv_die 9 "${ADAPTER_ID}: live submit not yet wired"
+}
+
+aiv_cmd_poll() {
+  local job_id="${1:-}"
+  [ -n "${job_id}" ] || aiv_die 2 "${ADAPTER_ID}: poll <job_id> required"
+  aiv_assert_dryrun
+  aiv_die 9 "${ADAPTER_ID}: live poll not yet wired (job=${job_id})"
+}
+
+aiv_cmd_fetch() {
+  local job_id="${1:-}"
+  [ -n "${job_id}" ] || aiv_die 2 "${ADAPTER_ID}: fetch <job_id> required"
+  aiv_assert_dryrun
+  aiv_die 9 "${ADAPTER_ID}: live fetch not yet wired (job=${job_id})"
+}
+
+aiv_dispatch "${ADAPTER_ID}" "native" "$@"

package/scripts/ai-video/lib/adapter-common.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# adapter-common.sh — shared boilerplate sourced by every adapter under
+# scripts/ai-video/adapters/. Keeps individual adapters thin and makes
+# the contract surface (subcommand dispatch, dry-run plumbing, stdout
+# shape) uniform across providers.
+#
+# Sourced; never executed directly. Strict-mode flags are the caller's
+# responsibility (every adapter starts with `set -euo pipefail`).
+
+if [ -n "${AIV_ADAPTER_COMMON_LOADED:-}" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+AIV_ADAPTER_COMMON_LOADED=1
+
+# Resolve the lib dir from this file's location so adapters can source
+# us via the canonical `$(dirname "$0")/../lib/...` path.
+_aiv_lib_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "${_aiv_lib_dir}/redact.sh"
+# shellcheck source=/dev/null
+. "${_aiv_lib_dir}/load-config.sh"
+
+AIV_LIB_DIR="${_aiv_lib_dir}"
+AIV_FIXTURE_ROOT="${_aiv_lib_dir}/fixtures"
+export AIV_LIB_DIR AIV_FIXTURE_ROOT
+
+# aiv_die <exit-code> <message> — write redacted message to stderr.
+aiv_die() {
+  local code="${1:-1}"; shift || true
+  printf 'adapter: %s\n' "$*" | aiv_redact_stream >&2
+  exit "${code}"
+}
+
+# aiv_require_cmd <cmd> [<cmd> ...] — fail fast on missing dependency.
+aiv_require_cmd() {
+  local cmd
+  for cmd in "$@"; do
+    command -v "${cmd}" >/dev/null 2>&1 \
+      || aiv_die 3 "required tool not found: ${cmd}"
+  done
+}
+
+# aiv_emit_dry_run <adapter-id> — print contract-shaped stdout JSON
+# pointing at the adapter's fixture directory. Used by every adapter's
+# `dry-run` subcommand.
+aiv_emit_dry_run() {
+  local adapter="${1:-}"
+  [ -n "${adapter}" ] || aiv_die 3 "aiv_emit_dry_run: adapter id required"
+  local fixture_dir="${AIV_FIXTURE_ROOT}/${adapter}"
+  local result="${fixture_dir}/result.json"
+  if [ ! -f "${result}" ]; then
+    aiv_die 3 "fixture missing: ${result}"
+  fi
+  cat "${result}"
+}
+
+# aiv_capability <flag> — print the capability JSON for `--help`-style
+# discovery: `{"audio": "native|none|per-model"}`.
+aiv_capability() {
+  local flag="${1:-none}"
+  printf '{"audio":"%s"}\n' "${flag}"
+}
+
+# aiv_assert_dryrun — refuse to run a network path unless the caller
+# explicitly opted in (AIV_DRYRUN=false set in this turn).
+aiv_assert_dryrun() {
+  case "${AIV_DRYRUN:-true}" in
+    false|FALSE|0|no|NO) return 0 ;;
+    *) aiv_die 4 "live call refused: AIV_DRYRUN=${AIV_DRYRUN:-true}; use dry-run subcommand or set AIV_DRYRUN=false" ;;
+  esac
+}
+
+# aiv_dispatch <adapter-id> <capability> "$@" — generic subcommand router.
+# Adapters override individual subcommands by defining bash functions
+# named `aiv_cmd_submit` / `aiv_cmd_poll` / `aiv_cmd_fetch` / `aiv_cmd_run`
+# BEFORE calling aiv_dispatch. Anything not overridden falls through to
+# a stub that exits non-zero with a clear message.
+aiv_dispatch() {
+  local adapter="${1:-}"; shift || true
+  local cap="${1:-none}"; shift || true
+  local sub="${1:-}"; shift || true
+  case "${sub}" in
+    capability)
+      aiv_capability "${cap}"
+      ;;
+    dry-run)
+      aiv_emit_dry_run "${adapter}"
+      ;;
+    submit)
+      declare -F aiv_cmd_submit >/dev/null \
+        && aiv_cmd_submit "$@" \
+        || aiv_die 5 "${adapter}: submit not implemented"
+      ;;
+    poll)
+      declare -F aiv_cmd_poll >/dev/null \
+        && aiv_cmd_poll "$@" \
+        || aiv_die 5 "${adapter}: poll not implemented"
+      ;;
+    fetch)
+      declare -F aiv_cmd_fetch >/dev/null \
+        && aiv_cmd_fetch "$@" \
+        || aiv_die 5 "${adapter}: fetch not implemented"
+      ;;
+    run)
+      declare -F aiv_cmd_run >/dev/null \
+        && aiv_cmd_run "$@" \
+        || aiv_die 5 "${adapter}: run not implemented"
+      ;;
+    "")
+      aiv_die 2 "${adapter}: subcommand required (capability|dry-run|submit|poll|fetch|run)"
+      ;;
+    *)
+      aiv_die 2 "${adapter}: unknown subcommand '${sub}'"
+      ;;
+  esac
+}