@ainova-systems/intelligence 0.11.0-rc.1

package/engine/scripts/sync.sh

@@ -0,0 +1,311 @@
+#!/bin/bash
+# intelligence-sync: Unified sync entry point
+# Reads config.yaml from the umbrella folder and syncs to all enabled targets.
+#
+# Usage:
+#   bash <umbrella>/sync/scripts/sync.sh           # Sync all enabled targets
+#   bash <umbrella>/sync/scripts/sync.sh claude    # Sync only Claude
+#   bash <umbrella>/sync/scripts/sync.sh cursor    # Sync only Cursor
+#
+# Layout-agnostic: detect_layout finds the umbrella (the dir holding
+# config.yaml; name not hardcoded) and migrates a pre-0.3.1 flat layout into
+# the <umbrella>/sync/ module. REPO_ROOT: auto-detected from git, or via env.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+source "$SCRIPT_DIR/lib/common.sh"
+source "$SCRIPT_DIR/lib/layout.sh"
+source "$SCRIPT_DIR/lib/migrations.sh"
+
+# Umbrella = whatever folder holds config.yaml (name not hardcoded). The
+# module is wherever this script lives — sync.sh self-locates and does NOT
+# assume a folder name.
+detect_layout "$SCRIPT_DIR"
+INTELLIGENCE_DIR="$LS_UMBRELLA_DIR"
+
+# sync.sh is a PURE synchronizer — it is not a migrator. Migration across a
+# breaking-change gap is owned solely by the intelligence-update flow
+# (update.sh + skill). sync refuses to run across an un-applied gap so a
+# stale/mismatched engine can never generate against a newer layout.
+if [ "${IS_CLI:-0}" != "1" ] && [ "$LS_LAYOUT" != "modular" ]; then
+    is_status needs-update "layout=$LS_LAYOUT"
+    echo "ERROR: engine is not in the modular layout (layout=$LS_LAYOUT)." >&2
+    echo "       Run the update flow: tell your agent \"Update intelligence-sync\"." >&2
+    exit "$IS_RC_NEEDS_UPDATE"
+fi
+
+# CLI mode (IS_CLI=1): the engine runs from outside the repo (the npm install
+# dir), so detect_layout cannot see the project — the project arrives through
+# the environment instead: CONFIG_FILE names the root manifest, REPO_ROOT the
+# project. The layout gate above is bypassed and the manifest is required up
+# front, before the version gates read it.
+if [ "${IS_CLI:-0}" = "1" ] && { [ -z "${CONFIG_FILE:-}" ] || [ ! -f "$CONFIG_FILE" ]; }; then
+    is_status config-missing "cli-mode"
+    echo "ERROR: CLI mode requires CONFIG_FILE to point at an existing manifest." >&2
+    exit "$IS_RC_CONFIG_MISSING"
+fi
+
+# Schema version lives in config.yaml (the frozen contract key).
+_cf="${CONFIG_FILE:-$INTELLIGENCE_DIR/config.yaml}"
+
+# Stale engine vs project schema stamped NEWER (ahead-of-engine) → refuse.
+_vc_rc=0
+check_version_compat "$_cf" || _vc_rc=$?
+if [ "$_vc_rc" -ne 0 ]; then exit "$_vc_rc"; fi
+
+# Schema gap → refuse; the update flow must apply the migration chain first.
+# Per the contract, an ABSENT stamp means pre-0.3.1 / un-applied schema — a
+# modular tree with no `sync_version` must NOT silently sync
+# (that would bypass migrations). A correctly bootstrapped project always has
+# the key (INIT emits it; update.sh stamps it).
+_stamp="$(read_engine_stamp "$_cf")"
+_eng="$(engine_version)"
+if [ -z "$_stamp" ]; then
+    is_status needs-update "stamped= engine=$_eng (no sync_version)"
+    echo "ERROR: config.yaml has no sync_version — schema un-applied." >&2
+    echo "       Run the update flow first: tell your agent \"Update intelligence-sync\"." >&2
+    exit "$IS_RC_NEEDS_UPDATE"
+elif [ -n "$_eng" ] && _ver_gt "$_eng" "$_stamp"; then
+    is_status needs-update "stamped=$_stamp engine=$_eng"
+    echo "ERROR: project at $_stamp but engine is $_eng — pending breaking changes." >&2
+    echo "       Run the update flow first: tell your agent \"Update intelligence-sync\"." >&2
+    exit "$IS_RC_NEEDS_UPDATE"
+fi
+
+# Normalize REPO_ROOT to the same `cd && pwd` style as INTELLIGENCE_DIR so
+# prefix-stripping in path comparisons works (Git Bash on Windows: git
+# rev-parse returns `D:/...` while cd && pwd returns `/d/...`; the styles
+# do not match without normalization).
+REPO_ROOT_RAW="${REPO_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || (cd "$INTELLIGENCE_DIR/.." && pwd))}"
+REPO_ROOT="$(cd "$REPO_ROOT_RAW" && pwd)"
+unset REPO_ROOT_RAW
+
+# Layout tokens for generated output (see finalize_output_file in common.sh).
+# Engine-shipped rules/agents cannot hardcode the umbrella's name — the project
+# chooses it — so they write `<umbrella>` / `<module>` and every adapter expands
+# them to these repo-relative paths on the way out. In CLI mode both values are
+# part of the env contract: the umbrella is the project's content dir and the
+# module is the staged engine content inside the package store.
+if [ "${IS_CLI:-0}" = "1" ]; then
+    # Re-normalize CONFIG_FILE the same way REPO_ROOT is above — the CLI (or
+    # the Node shim behind it) may hand us `D:/...` while `cd && pwd` yields
+    # `/d/...`, and prefix comparisons downstream need one spelling.
+    CONFIG_FILE="$(cd "$(dirname "$CONFIG_FILE")" && pwd)/$(basename "$CONFIG_FILE")"
+    IS_UMBRELLA_REL="${IS_UMBRELLA_REL:-intelligence}"
+    IS_MODULE_REL="${IS_MODULE_REL:-.intelligence/engine}"
+    # Project-owned adapters keep their v1 home: <umbrella>/adapters/.
+    INTELLIGENCE_DIR="$REPO_ROOT/$IS_UMBRELLA_REL"
+else
+    IS_UMBRELLA_REL="$(repo_rel_dir "$REPO_ROOT" "$LS_UMBRELLA_DIR")"
+    IS_MODULE_REL="$(repo_rel_dir "$REPO_ROOT" "$LS_MODULE_DIR")"
+    IS_UMBRELLA_REL="${IS_UMBRELLA_REL:-intelligence}"
+    IS_MODULE_REL="${IS_MODULE_REL:-intelligence/sync}"
+fi
+export IS_UMBRELLA_REL IS_MODULE_REL
+
+# Config: explicit env > config.yaml in the umbrella folder
+if [ -n "${CONFIG_FILE:-}" ]; then
+    CONFIG_FILE="$CONFIG_FILE"
+elif [ -f "$INTELLIGENCE_DIR/config.yaml" ]; then
+    CONFIG_FILE="$INTELLIGENCE_DIR/config.yaml"
+else
+    CONFIG_FILE=""
+fi
+
+if [ -z "$CONFIG_FILE" ] || [ ! -f "$CONFIG_FILE" ]; then
+    is_status config-missing "umbrella=$INTELLIGENCE_DIR"
+    echo "ERROR: Config file not found."
+    echo "Looked for: config.yaml (in $INTELLIGENCE_DIR)"
+    echo "Run INIT.md bootstrap or create config.yaml manually."
+    exit "$IS_RC_CONFIG_MISSING"
+fi
+
+TARGET_FILTER="${1:-}"
+
+echo "=== intelligence-sync ==="
+echo "  Config: $CONFIG_FILE"
+echo "  Root:   $REPO_ROOT"
+echo ""
+
+# Invariant: AGENTS.md is the canonical carrier of always-on rules for
+# Cursor / Copilot / Codex / Pi / opencode (their adapters skip always-on
+# rules to avoid duplication, since each tool reads AGENTS.md natively for
+# baseline project context). If those targets are enabled, `agents` must
+# also be enabled — otherwise always-on rules go nowhere for those tools.
+# Skip the check when the user requested a single target via $TARGET_FILTER:
+# they may be syncing only one IDE intentionally.
+if [ -z "$TARGET_FILTER" ]; then
+    agents_enabled=$(is_target_enabled "$CONFIG_FILE" "agents")
+    if [ "$agents_enabled" != "1" ]; then
+        # AGENTS.md-dependent adapters: any tool whose adapter skips always-on
+        # rule emission (because the tool reads AGENTS.md natively) must be
+        # listed here. Add new adapters to this list when they ship.
+        for tool in cursor copilot codex pi opencode; do
+            if [ "$(is_target_enabled "$CONFIG_FILE" "$tool")" = "1" ]; then
+                echo "ERROR: targets.$tool is enabled but targets.agents is not." >&2
+                echo "  $tool relies on AGENTS.md to deliver always-on rules — without it," >&2
+                echo "  always-on rules would be invisible to $tool." >&2
+                echo "  Either enable targets.agents in $CONFIG_FILE, or disable targets.$tool." >&2
+                exit 1
+            fi
+        done
+    fi
+fi
+
+# Remote sources (declared `packs:` reached via `@<pack>`, and inline `git+`
+# specs in sources.*) are shallow-cloned on demand by resolve_source_dir. Give
+# it a run-scoped cache dir so each spec is fetched at most once per sync and is
+# removed on exit. Honors $TMPDIR (never hardcodes /tmp), mirroring update.sh.
+IS_REMOTE_CACHE="$(mktemp -d -t intelligence-sync-remotes-XXXXXX 2>/dev/null || mktemp -d)"
+export IS_REMOTE_CACHE
+trap 'rm -rf "$IS_REMOTE_CACHE"' EXIT INT TERM
+
+# A `@<pack>` token carries only the reference; its url / ref / mirror live in
+# config.yaml. resolve_source_dir keeps its published two-argument contract so
+# project-owned adapters written against it keep working, so the config path
+# reaches it the same way the clone cache does — through the environment.
+IS_CONFIG_FILE="$CONFIG_FILE"
+export IS_CONFIG_FILE
+
+# Fail closed on an undeclared pack reference or an unsafe mirror, before any
+# adapter runs — see validate_pack_refs for why this cannot live in the resolver.
+validate_pack_refs "$REPO_ROOT" "$CONFIG_FILE"
+
+# A pack that declares `mirror:` is additionally materialized into a tracked
+# directory in the repo, so an upstream bump is visible in `git diff` rather
+# than only in the generated output. Without it, the pack stays transient.
+while IFS= read -r mirror_rel; do
+    [ -n "$mirror_rel" ] && echo "  Pack mirror: $mirror_rel"
+done < <(list_pack_mirrors "$REPO_ROOT" "$CONFIG_FILE")
+
+# Lint frontmatter across all source files (rules, agents, skills).
+# Catches issues like unquoted colons that strict YAML consumers reject.
+for section in rules agents skills; do
+    while IFS= read -r src; do
+        [ -z "$src" ] && continue
+        src_dir="$(resolve_source_dir "$REPO_ROOT" "$src")"
+        [ -d "$src_dir" ] || continue
+        if [ "$section" = "skills" ]; then
+            while IFS= read -r f; do
+                [ -n "$f" ] && lint_frontmatter "$f"
+            done < <(find "$src_dir" -mindepth 2 -maxdepth 2 -name 'SKILL.md' 2>/dev/null)
+        else
+            for f in "$src_dir"/*.md; do
+                [ -f "$f" ] && lint_frontmatter "$f"
+            done
+        fi
+    done < <(read_yaml_list "$CONFIG_FILE" "$section")
+done
+
+# Adapters come from two places, discovered by filename (minus `.sh`,
+# `_template` excluded):
+#
+#   1. Built-in   — <module>/scripts/adapters/   (upstream-owned; update.sh
+#                   replaces this directory wholesale on every engine update)
+#   2. Project    — <umbrella>/adapters/         (project-owned; update.sh
+#                   never touches it)
+#
+# A custom adapter therefore belongs in the umbrella's `adapters/` — put one in
+# the engine's own adapters/ and the next update deletes it. A project adapter
+# whose name matches a built-in overrides it (an escape hatch for patching a
+# built-in without forking the engine — announced, never silent).
+ADAPTERS=()
+ADAPTER_FILES=()
+
+register_adapter() {
+    local name="$1" file="$2"
+    local n=${#ADAPTERS[@]} i=0
+    while [ "$i" -lt "$n" ]; do
+        if [ "${ADAPTERS[$i]}" = "$name" ]; then
+            ADAPTER_FILES[$i]="$file"
+            echo "  NOTE: project adapter '$name' overrides the built-in one ($(basename "$INTELLIGENCE_DIR")/adapters/$(basename "$file"))"
+            return 0
+        fi
+        i=$((i + 1))
+    done
+    ADAPTERS+=("$name")
+    ADAPTER_FILES+=("$file")
+}
+
+for adapters_dir in "$SCRIPT_DIR/adapters" "$INTELLIGENCE_DIR/adapters"; do
+    [ -d "$adapters_dir" ] || continue
+    for adapter_file in "$adapters_dir"/*.sh; do
+        [ -f "$adapter_file" ] || continue
+        adapter_name="$(basename "$adapter_file" .sh)"
+        [ "$adapter_name" = "_template" ] && continue
+        register_adapter "$adapter_name" "$adapter_file"
+    done
+done
+
+synced=0
+adapter_count=${#ADAPTERS[@]}
+adapter_idx=0
+
+while [ "$adapter_idx" -lt "$adapter_count" ]; do
+    adapter="${ADAPTERS[$adapter_idx]}"
+    adapter_file="${ADAPTER_FILES[$adapter_idx]}"
+    adapter_idx=$((adapter_idx + 1))
+
+    # Skip if user requested specific target and this isn't it
+    if [ -n "$TARGET_FILTER" ] && [ "$adapter" != "$TARGET_FILTER" ]; then
+        continue
+    fi
+
+    # Check if target is enabled in config
+    enabled=$(is_target_enabled "$CONFIG_FILE" "$adapter")
+    if [ "$enabled" != "1" ] && [ -z "$TARGET_FILTER" ]; then
+        continue
+    fi
+
+    # Get output directory
+    output=$(get_target_output "$CONFIG_FILE" "$adapter")
+    if [ -z "$output" ]; then
+        output=".$adapter"
+    fi
+    output_dir="$REPO_ROOT/$output"
+
+    # Refuse to run if the output would clobber content — `output: "."`,
+    # `output: "intelligence"`, or a `../` path that escapes the repo. Applies
+    # to EVERY adapter, `agents` included: dir-writing adapters `rm -rf` their
+    # output, and `agents` overwrites whatever single file it is handed. Both
+    # turn a bad config line into a destructive write.
+    validate_output_path "$REPO_ROOT" "$CONFIG_FILE" "$adapter" "$output_dir"
+
+    # Source adapter and run.
+    # shellcheck source=/dev/null
+    source "$adapter_file"
+    "sync_to_$adapter" "$REPO_ROOT" "$CONFIG_FILE" "$output_dir"
+    echo ""
+    synced=$((synced + 1))
+done
+
+if [ $synced -eq 0 ]; then
+    if [ -n "$TARGET_FILTER" ]; then
+        echo "ERROR: Adapter '$TARGET_FILTER' not found."
+        echo "Available: ${ADAPTERS[*]}"
+    else
+        echo "WARNING: No targets enabled in $CONFIG_FILE"
+    fi
+    exit 1
+fi
+
+# Warn about unsynced directories
+warn_unsynced "$REPO_ROOT" "$CONFIG_FILE"
+
+# Report model overrides that drift from intelligence-sync defaults
+# (helpful when defaults move forward — e.g., gpt-5.5 -> gpt-5.6).
+report_model_drift "$CONFIG_FILE"
+
+# The intelligence CLI is the recommended setup for new projects. Recommend it
+# to vendored setups — stderr only, so IS_STATUS stdout parsing (skills, CI)
+# is untouched, and suppressible for pipelines.
+if [ "${IS_CLI:-0}" != "1" ] && [ -z "${IS_SUPPRESS_CLI_NOTE:-}" ]; then
+    echo "NOTE: the intelligence CLI is now the recommended setup — 'npm i -g @ainova-systems/intelligence', then 'intelligence migrate'. This vendored flow keeps working." >&2
+fi
+
+echo ""
+# sync.sh never migrates (the update flow owns that), so success is always ok.
+is_status ok "synced=$synced"
+echo "=== Done: $synced target(s) synced ==="

package/engine/scripts/update.sh

@@ -0,0 +1,237 @@
+#!/bin/bash
+# intelligence-sync: self-update
+# Pulls the latest upstream-owned content into the local vendored module:
+#   <umbrella>/sync/scripts/            sync engine + adapters
+#   <umbrella>/sync/INIT.md             bootstrap prompt
+#   <umbrella>/sync/skills/intelligence-*  meta-skills (by reserved prefix)
+#   <umbrella>/sync/docs/               vendored docs
+# Project content (config.yaml, rules/, agents/, non-meta skills/) is never
+# touched — except an idempotent additive line in config.yaml sources.skills
+# when migrating a pre-0.3.1 flat project.
+#
+# The umbrella folder name is not hardcoded (intelligence/, Intelligence/, …).
+# Pre-0.3.1 projects laid the engine out flat under the umbrella; this script
+# transparently migrates them into the <umbrella>/sync/ module.
+#
+# Usage:
+#   bash <umbrella>/sync/scripts/update.sh            # interactive
+#   bash <umbrella>/sync/scripts/update.sh --yes      # apply without prompt
+#   REPO_URL=<url> bash .../update.sh                 # custom upstream
+#
+# Cross-platform: uses `mktemp -d` (Linux/macOS/Windows Git Bash).
+# Honors $TMPDIR / $TMP / $TEMP — never hardcodes /tmp.
+
+set -euo pipefail
+
+REPO_URL="${REPO_URL:-https://github.com/ainova-systems/intelligence-sync.git}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+AUTO_YES=0
+[ "${1:-}" = "--yes" ] && AUTO_YES=1
+
+source "$SCRIPT_DIR/lib/layout.sh"
+source "$SCRIPT_DIR/lib/migrations.sh"
+
+detect_layout "$SCRIPT_DIR"
+UMBRELLA="$LS_UMBRELLA_DIR"
+CONFIG_FILE_PATH="$UMBRELLA/config.yaml"
+
+# Local module dir = wherever this engine lives (self-located, any name) when
+# already modular; for a pre-0.3.1 flat project the module does not exist yet,
+# so it is created under the conventional name `sync`. MODULE_NAME is only the
+# creation convention — not a rename feature, not used to find the upstream.
+if [ "$LS_LAYOUT" = "modular" ]; then
+    MODULE_DIR="$LS_MODULE_DIR"
+    MODULE_NAME="$LS_MODULE_NAME"
+else
+    MODULE_NAME="sync"
+    MODULE_DIR="$UMBRELLA/$MODULE_NAME"
+fi
+# The upstream repo's module is always `sync/` by convention, independent of
+# whatever the local module is named.
+UPSTREAM_MODULE="sync"
+
+WORK_DIR=$(mktemp -d -t intelligence-sync-update-XXXXXX 2>/dev/null || mktemp -d)
+trap 'rm -rf "$WORK_DIR"' EXIT INT TERM
+
+echo "=== intelligence-sync: self-update ==="
+echo "  Upstream:    $REPO_URL"
+echo "  Umbrella:    $UMBRELLA  (layout: $LS_LAYOUT)"
+echo "  Module:      $MODULE_DIR"
+echo "  Work dir:    $WORK_DIR"
+echo ""
+
+if ! command -v git >/dev/null 2>&1; then
+    echo "ERROR: git is required."
+    exit 1
+fi
+
+echo "  Cloning latest..."
+# LF regardless of the host's core.autocrlf: this checkout is copied verbatim
+# into the project, so a CRLF one on Windows would install CRLF shell scripts.
+git -c core.autocrlf=false -c core.eol=lf clone --depth=1 --quiet "$REPO_URL" "$WORK_DIR"
+
+# Normalize the upstream into a single module-shaped staging dir so the rest
+# of this script is layout-agnostic. Accept either upstream shape:
+#   modular: $WORK_DIR/intelligence/sync/{scripts,INIT.md,docs,skills}
+#   legacy : $WORK_DIR/intelligence/{scripts,INIT.md,skills} + $WORK_DIR/docs
+UPMOD="$WORK_DIR/_module"
+mkdir -p "$UPMOD/skills"
+if [ -d "$WORK_DIR/intelligence/$UPSTREAM_MODULE/scripts" ]; then
+    _SRC="$WORK_DIR/intelligence/$UPSTREAM_MODULE"
+    cp -r "$_SRC/scripts" "$UPMOD/scripts"
+    [ -f "$_SRC/INIT.md" ] && cp "$_SRC/INIT.md" "$UPMOD/INIT.md"
+    [ -d "$_SRC/docs" ] && cp -r "$_SRC/docs" "$UPMOD/docs"
+    # Engine-owned rule + agent (0.7.0+). Absent in older upstreams — optional.
+    [ -d "$_SRC/rules" ] && cp -r "$_SRC/rules" "$UPMOD/rules"
+    [ -d "$_SRC/agents" ] && cp -r "$_SRC/agents" "$UPMOD/agents"
+    for s in "$_SRC"/skills/intelligence-*; do
+        [ -d "$s" ] && cp -r "$s" "$UPMOD/skills/"
+    done
+elif [ -d "$WORK_DIR/intelligence/scripts" ]; then
+    cp -r "$WORK_DIR/intelligence/scripts" "$UPMOD/scripts"
+    [ -f "$WORK_DIR/intelligence/INIT.md" ] && cp "$WORK_DIR/intelligence/INIT.md" "$UPMOD/INIT.md"
+    [ -d "$WORK_DIR/docs" ] && cp -r "$WORK_DIR/docs" "$UPMOD/docs"
+    for s in "$WORK_DIR/intelligence"/skills/intelligence-*; do
+        [ -d "$s" ] && cp -r "$s" "$UPMOD/skills/"
+    done
+else
+    is_status error "upstream-layout-unrecognized"
+    echo "ERROR: upstream layout unrecognized — no intelligence/$UPSTREAM_MODULE/scripts/ or intelligence/scripts/."
+    exit "$IS_RC_ERROR"
+fi
+
+# Local module dir to diff against: the existing module, or (pre-migration)
+# the flat legacy locations.
+if [ -d "$MODULE_DIR/scripts" ]; then
+    _LOCAL="$MODULE_DIR"
+else
+    _LOCAL="$UMBRELLA"   # legacy flat
+fi
+
+echo ""
+echo "  Diff (scripts/):"
+diff -ruN "$_LOCAL/scripts" "$UPMOD/scripts" || true
+echo ""
+echo "  Diff (INIT.md):"
+diff -uN "$_LOCAL/INIT.md" "$UPMOD/INIT.md" 2>/dev/null || true
+echo ""
+echo "  Diff (meta-skills intelligence-*):"
+for up in "$UPMOD"/skills/intelligence-*; do
+    [ -d "$up" ] || continue
+    name=$(basename "$up")
+    diff -ruN "$_LOCAL/skills/$name" "$up" 2>/dev/null || true
+done
+if [ -d "$UPMOD/docs" ]; then
+    echo ""
+    echo "  Diff (docs/):"
+    diff -ruN "$_LOCAL/docs" "$UPMOD/docs" 2>/dev/null || true
+fi
+# Engine-owned rule + agent (0.7.0+): upstream-owned like the meta-skills, and
+# distinct from the project's own <umbrella>/rules and <umbrella>/agents.
+for _d in rules agents; do
+    [ -d "$UPMOD/$_d" ] || continue
+    echo ""
+    echo "  Diff (engine $_d/):"
+    diff -ruN "$_LOCAL/$_d" "$UPMOD/$_d" 2>/dev/null || true
+done
+
+if [ $AUTO_YES -ne 1 ]; then
+    echo ""
+    if [ "$LS_LAYOUT" = "legacy" ]; then
+        echo "  NOTE: pre-0.3.1 flat layout — the engine will be MIGRATED into '$MODULE_NAME/'."
+        echo "        Legacy scripts/, INIT.md, docs/, and intelligence-* skills move there;"
+        echo "        a single additive line is added to config.yaml sources.skills."
+    fi
+    read -r -p "Apply update? Engine/INIT/meta-skills/docs + engine rule/agent overwritten; YOUR rules/agents/skills NOT touched. [y/N] " confirm
+    case "$confirm" in
+        y|Y|yes|YES) ;;
+        *) echo "  Cancelled."; exit 0 ;;
+    esac
+fi
+
+# CRITICAL: run the DESTINATION engine's migration chain, not the stale local
+# one. A breaking migration shipped in the new version is defined only in the
+# upstream migrations.sh; re-source it so MIGRATIONS / migrate_to_* /
+# run_migrations / engine_version all reflect the version we are applying.
+# Otherwise a new breaking change would be silently skipped while the version
+# still advances — the exact corruption this architecture exists to prevent.
+if [ -f "$UPMOD/scripts/lib/migrations.sh" ]; then
+    # shellcheck source=/dev/null
+    source "$UPMOD/scripts/lib/migrations.sh"
+fi
+
+# Migrate via the upstream chain (authoritative content from UPMOD).
+# Idempotent: a no-op on already-current projects. Fail-closed: on a state
+# bash will not resolve it emits IS_STATUS + a stable code and we stop so the
+# intelligence-update skill can take over (never partially destroys).
+_mig_rc=0
+run_migrations "$UMBRELLA" "$MODULE_NAME" "$UPMOD" || _mig_rc=$?
+if [ "$_mig_rc" -ne 0 ]; then exit "$_mig_rc"; fi
+
+# In-place refresh of the module (covers already-modular projects, and
+# re-asserts content post-migration). Idempotent.
+mkdir -p "$MODULE_DIR/skills"
+if command -v rsync >/dev/null 2>&1; then
+    rsync -a --delete "$UPMOD/scripts/" "$MODULE_DIR/scripts/"
+else
+    rm -rf "$MODULE_DIR/scripts"; cp -r "$UPMOD/scripts" "$MODULE_DIR/scripts"
+fi
+[ -f "$UPMOD/INIT.md" ] && cp "$UPMOD/INIT.md" "$MODULE_DIR/INIT.md"
+for _d in rules agents; do
+    [ -d "$UPMOD/$_d" ] || continue
+    if command -v rsync >/dev/null 2>&1; then
+        mkdir -p "$MODULE_DIR/$_d"
+        rsync -a --delete "$UPMOD/$_d/" "$MODULE_DIR/$_d/"
+    else
+        # `:?` so an empty MODULE_DIR/_d can never expand this into `rm -rf /`.
+        rm -rf "${MODULE_DIR:?}/${_d:?}"; cp -r "$UPMOD/$_d" "$MODULE_DIR/$_d"
+    fi
+done
+if [ -d "$UPMOD/docs" ]; then
+    if command -v rsync >/dev/null 2>&1; then
+        rsync -a --delete "$UPMOD/docs/" "$MODULE_DIR/docs/"
+    else
+        rm -rf "$MODULE_DIR/docs"; cp -r "$UPMOD/docs" "$MODULE_DIR/docs"
+    fi
+fi
+for up in "$UPMOD"/skills/intelligence-*; do
+    [ -d "$up" ] || continue
+    name=$(basename "$up")
+    if command -v rsync >/dev/null 2>&1; then
+        rsync -a --delete "$up/" "$MODULE_DIR/skills/$name/"
+    else
+        rm -rf "$MODULE_DIR/skills/$name"; cp -r "$up" "$MODULE_DIR/skills/$name"
+    fi
+done
+# Prune local meta-skills no longer upstream (deprecated ones disappear; no
+# duplicates, project skills untouched).
+for local_skill in "$MODULE_DIR"/skills/intelligence-*; do
+    [ -d "$local_skill" ] || continue
+    name=$(basename "$local_skill")
+    [ -d "$UPMOD/skills/$name" ] || { echo "  Removing meta-skill no longer upstream: $name"; rm -rf "$local_skill"; }
+done
+
+# Stamp the applied schema version into config.yaml (the frozen contract
+# key). Covers the already-modular in-place path where no migration ran.
+_ver="0.3.1"
+[ -f "$UPMOD/scripts/VERSION" ] && _ver="$(tr -d ' \r\n' < "$UPMOD/scripts/VERSION")"
+stamp_version "$CONFIG_FILE_PATH" "$_ver"
+
+find "$MODULE_DIR/scripts" -name '*.sh' -exec chmod +x {} \; 2>/dev/null || true
+
+echo ""
+if [ "${IS_MIGRATED:-0}" -eq 1 ]; then
+    is_status migrated "version=$_ver"
+else
+    is_status ok "version=$_ver"
+fi
+echo "  Updated:   $MODULE_NAME/{scripts,INIT.md,docs}, $MODULE_NAME/skills/intelligence-*, $MODULE_NAME/{rules,agents}  (version $_ver)"
+echo "  Untouched: your <umbrella>/rules, <umbrella>/agents, project skills, <umbrella>/adapters."
+echo "             config.yaml only gains the engine's managed keys (sync_version, module sources)."
+echo "  Next: bash $MODULE_NAME/scripts/sync.sh"
+
+# The intelligence CLI is the recommended setup for new projects. stderr only,
+# so IS_STATUS stdout parsing (skills, CI) is untouched; suppressible for CI.
+if [ -z "${IS_SUPPRESS_CLI_NOTE:-}" ]; then
+    echo "NOTE: the intelligence CLI is now the recommended setup — 'npm i -g @ainova-systems/intelligence', then 'intelligence migrate'. This vendored flow keeps working." >&2
+fi

package/engine/skills/intelligence-add-agent/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: intelligence-add-agent
+description: "Create new specialized agent"
+argument-hint: <domain> [description]
+---
+
+# Add Agent
+
+## Steps
+
+1. **Determine domain prefix** (the scope is required):
+   - **Reuse the existing domain when one fits**: list `intelligence/agents/` and `intelligence/skills/`. If a domain prefix is already established for the target area (`backend-`, `frontend-`, `devops-`), use it. Introduce a new domain only when the scope is materially different from all existing ones.
+   - **When no existing domain fits**, derive from repo structure:
+     - Single / root project → use the project codename from `intelligence/config.yaml` → `project.name`
+     - Backend service / API component → `backend-`
+     - Frontend / web / UI component → `frontend-`
+     - Infrastructure, IaC, CI/CD, deployment → `devops-`
+     - Shared library / common / cross-cutting code → `core-`
+     - Test suites (e2e, integration) → `tests-`
+     - Tool-internal (intelligence-sync itself) → `intelligence-`
+   - If the repo is a monorepo with named components (e.g., `apps/billing`, `services/auth`), prefer the component name as the domain (`billing-`, `auth-`).
+   - **Every agent needs a domain prefix.** If the scope is unclear, ask the user before proceeding.
+
+2. **Check existing agents**: Read `intelligence/agents/` to avoid duplicates. If an agent for this domain exists, ask user whether to update it instead.
+
+3. **Determine tier and access**:
+   - Developer agents: `tier: heavy`, `access: full`
+   - Reviewer/validator agents: `tier: standard`, `access: readonly`
+   - Simple lookup agents: `tier: light`, `access: readonly`
+   - Caveat: `readonly`'s closed tools list also removes MCP and tool-search access. A reviewer
+     that needs MCP reads takes `access: full` with a read-only boundary stated in its body.
+
+4. **Analyze codebase**: Read source files in the domain's directory to determine:
+   - Technology stack and frameworks
+   - Architecture patterns
+   - Build and test commands
+   - Key conventions and forbidden patterns
+
+5. **Create agent**: Write `intelligence/agents/<domain>-<role>.md` with frontmatter:
+   ```yaml
+   ---
+   name: <domain>-<role>
+   description: "<when to use this agent - IDEs use this to suggest the agent>"
+   tier: heavy|standard|light
+   access: full|readonly
+   skills:
+     - <existing-skills-for-this-domain>
+   ---
+   ```
+
+   **YAML safety (required):** **always wrap `description` (and any other free-text string field) in double quotes**, regardless of content. Codex CLI uses strict YAML — an unquoted colon, leading hyphen, or word that parses as boolean (`yes`, `no`, `true`) silently breaks the agent. Quoting unconditionally prevents the entire class of bug. If the value itself contains a double quote, escape it as `\"` or wrap it in single quotes so an inner quote does not terminate the scalar early.
+
+6. **Write body** with sections: **Expertise** -> **Boundaries** -> **Build & Verify**
+   - An agent is **thin**: who it is, where it stops, how it verifies. Everything else already reaches it.
+   - **Do not tell the agent to read the rules.** Rules load on their own: Claude Code loads `.claude/rules/` into every custom subagent's startup context alongside `CLAUDE.md` (*Subagents → What loads at startup*), and Cursor / Copilot / Codex / Pi / opencode receive always-on rules inlined in `AGENTS.md`. A `Read intelligence/rules/<domain>.md before starting` line duplicates content the agent already has — double the tokens, and a second copy that drifts from the rule it copied.
+   - **Point at a rule, never restate it.** If you want to copy a rule into the agent, the rule is in the wrong place — move it, do not clone it.
+   - **Do carry** what is genuinely the agent's own: its boundaries ("if the app is not running, stop — do not hand-write the output"), its verification commands, its definition of done.
+   - All content must come from actual codebase analysis.
+
+7. **Link existing skills**: Find skills in `intelligence/skills/` matching this domain prefix and add them to the agent's `skills:` frontmatter.
+
+8. **Run `/intelligence-sync`** to distribute to all enabled IDE targets.

package/engine/skills/intelligence-add-rule/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: intelligence-add-rule
+description: "Create new intelligence rule"
+argument-hint: <name> [paths-glob]
+---
+
+# Add Rule
+
+## Steps
+
+1. **Determine rule name from domain** (the scope is required):
+   - **Reuse the existing domain when one fits**: list `intelligence/rules/`. If a rule file covers the target area (e.g., `backend.md`, `frontend.md`), extend it. Introduce a new domain only when the scope is materially different from all existing rules.
+   - **When no existing rule fits**, derive the filename from repo structure:
+     - Single / root project → use the project codename from `intelligence/config.yaml` → `project.name` (e.g., `<codename>.md`)
+     - Backend service / API component → `backend.md`
+     - Frontend / web / UI component → `frontend.md`
+     - Infrastructure, IaC, CI/CD, deployment → `devops.md`
+     - Shared library / common / cross-cutting code → `core.md`
+     - Test suites (e2e, integration) → `tests.md`
+     - Always-loaded global context → `context.md`
+   - If the repo is a monorepo with named components (e.g., `apps/billing`, `services/auth`), prefer the component name as the rule name (`billing.md`, `auth.md`).
+   - **Rule filenames match the domain used by skills/agents.** If the scope is unclear, ask the user before proceeding.
+
+2. **Check existing rules**: Read `intelligence/rules/` to detect overlapping scope — favor extending an existing rule over creating a new one.
+
+3. **Determine scope**:
+   - If paths glob provided — scoped rule with `paths:` frontmatter
+   - If no paths — always-loaded rule (no `paths:` in frontmatter)
+
+4. **Analyze codebase**: Read source files matching the scope to extract:
+   - REQUIRED patterns (conventions consistently followed across the codebase — judgment calls expressed as positive defaults)
+   - Invariants (true must-nots — safety, output format, security; not judgment calls)
+   - Architecture patterns (layer dependencies, module structure)
+   - Build and test commands specific to this scope
+   - Anti-patterns observed in code, each paired with the positive replacement that should adopt instead
+
+5. **Create rule**: Write `intelligence/rules/<name>.md`:
+   ```yaml
+   ---
+   paths:
+     - "<glob-pattern>"
+   ---
+   ```
+
+6. **Write body** with sections: **REQUIRED** → **Invariants** → **Architecture** → **Build & Test** → **Examples** → **Patterns to recognize and replace** (optional)
+   - Lead with REQUIRED (positive defaults) — the LLM follows the positive instruction first
+   - Reserve **Invariants** for true must-nots — security, safety, output format. Use absolute language (MUST / NEVER) only here, never for judgment calls
+   - **Patterns to recognize and replace** is reference documentation of anti-patterns paired with positive replacements — readers recognize the pattern, apply the replacement
+   - Examples come from the actual codebase — reference real files
+   - Every REQUIRED / Invariant / Pattern is backed by observed code
+
+7. **Update config.yaml** if needed: Add source path to `sources.rules` if rule is in a new directory not yet listed.
+
+8. **Run `/intelligence-sync`** to distribute to all enabled IDE targets.