repo-nexus 0.7.24 → 0.7.26

package/docs/examples/monorepo-coexistence.md

@@ -52,7 +52,6 @@ repos:
 
 plugins:
   claude:
-    instructions: true
     skills: true
 ```
 

package/docs/examples/multi-repo-workspace.md

@@ -50,10 +50,8 @@ repos:
 
 plugins:
   claude:
-    instructions: true
     skills: true
   cursor:
-    instructions: true
     skills: true
 ```
 

package/docs/guide/configuration.md

@@ -64,11 +64,10 @@ repos:
 plugins:
   # AI Provider Plugins
   claude:
-    instructions: true
     skills: true
+    auto_sync_on: SessionStart
 
   cursor:
-    instructions: true
     skills: true
 
   # Knowledge & Agent Protocol Plugins
@@ -116,7 +115,7 @@ repos:
 
 plugins:
   gemini:
-    instructions: true
+    skills: true
 ```
 
 After modifying configuration files directly, reconcile the workspace state:

package/docs/plugins/claude.md

@@ -21,8 +21,8 @@ Operational skills, rules, and subagents remain cleanly encapsulated within `.rn
 
 2. **Native Instruction Support via `CLAUDE.md` & `AGENTS.md`**:
    - Claude Code natively reads `CLAUDE.md` as its primary instructions file; it only falls back to `AGENTS.md` when no `CLAUDE.md` exists in the project.
-   - When enabled (`instructions: true`), the Claude plugin synchronizes Repo Nexus routing instructions to `CLAUDE.md` (or merges them cleanly if you already have custom instructions).
-   - If `CLAUDE.md` is absent and `instructions: false`, Claude Code falls back to reading `AGENTS.md` directly.
+   - When enabled, the Claude plugin automatically synchronizes Repo Nexus routing instructions to `CLAUDE.md` (or merges them cleanly if you already have custom instructions).
+   - If the plugin is disabled, the routing block is removed, allowing Claude Code to read `AGENTS.md` directly.
 
 3. **Subagent & Skill Execution**:
    - Core skills reside under `.rnex/skills/`.
@@ -58,15 +58,15 @@ Configure options under `plugins.claude` in `rnex.yaml` or `.local.rnex.yaml`:
 ```yaml
 plugins:
   claude:
-    instructions: true   # Sync routing instructions to CLAUDE.md (default: true)
     skills: true         # Generate user skills in .claude/skills/ (default: true)
+    auto_sync_on: SessionStart # Trigger auto-sync on lifecycle event (default: SessionStart, or false)
     enabled: true        # Set to false to disable
 ```
 
 | Option | Type | Default | Description |
 |:---|:---|:---|:---|
-| `instructions` | boolean | `true` | Merge routing instructions into `CLAUDE.md`. |
 | `skills` | boolean | `true` | Generate user skill pointers in `.claude/skills/rnex-*.md`. |
+| `auto_sync_on` | string/boolean | `SessionStart` | Lifecycle event triggering auto-sync in `.claude/settings.json` (or `false` to disable). |
 | `enabled` | boolean | `true` | Enable or disable the plugin. Overridable in `.local.rnex.yaml`. |
 
 ---
@@ -78,7 +78,7 @@ When `claude` is enabled with functional plugins like `karpathy-llm`, it generat
 ```text
 my-workspace/
 ├── AGENTS.md                          # Universal workspace instructions & routing
-├── CLAUDE.md                          # Claude-specific instructions (if instructions: true)
+├── CLAUDE.md                          # Claude-specific instructions
 ├── .claude/
 │   └── skills/                        # Zero-logic User Skill pointers
 │       ├── rnex-clone-sync.md

package/docs/plugins/copilot.md

@@ -11,7 +11,7 @@ The `copilot` plugin integrates GitHub Copilot with Repo Nexus by projecting wor
 
 GitHub Copilot operates natively within VS Code, Visual Studio, JetBrains, and GitHub.com:
 - **Universal Routing (`AGENTS.md`)**: GitHub Copilot natively reads `AGENTS.md` at the workspace root.
-- **Custom Instructions (`.github/copilot-instructions.md`)**: When `instructions: true`, Repo Nexus injects its non-destructive routing block inside `<!-- REPO-NEXUS:START -->` and `<!-- REPO-NEXUS:END -->`. Custom developer rules outside these markers are strictly preserved.
+- **Custom Instructions (`.github/copilot-instructions.md`)**: When enabled, Repo Nexus injects its non-destructive routing block inside `<!-- REPO-NEXUS:START -->` and `<!-- REPO-NEXUS:END -->`. Custom developer rules outside these markers are strictly preserved.
 - **User Skills (`.github/skills/`)**: When `skills: true`, Repo Nexus generates native `SKILL.md` directory bundles (`.github/skills/rnex-<name>/SKILL.md`) with YAML frontmatter, making them automatically discoverable in VS Code and Copilot Chat skill-pickers while redirecting to the underlying agentic skills under `.rnex/skills/` and active plugins.
 
 ## Configuration
@@ -21,7 +21,6 @@ Enable in `rnex.yaml`:
 ```yaml
 plugins:
   copilot:
-    instructions: true   # Maintain routing in .github/copilot-instructions.md
     skills: true         # Generate user skills in .github/skills/
 ```
 

package/docs/plugins/cursor.md

@@ -20,7 +20,7 @@ Operational skills, rules, and subagents remain cleanly encapsulated within `.rn
    - Contains zero inline heuristics—redirects Cursor directly to the underlying agentic skill protocols inside `.rnex/`.
 
 2. **Native Instructions & Rules Support**:
-   - Synchronizes Repo Nexus routing instructions to `.cursorrules` when `instructions: true` (default).
+   - Automatically synchronizes Repo Nexus routing instructions to `.cursorrules` and `.cursor/rules/rnex-context.mdc`.
    - Preserves user custom rules and custom sections in `.cursorrules`.
 
 3. **Subagent & Skill Execution**:
@@ -57,14 +57,12 @@ Configure options under `plugins.cursor` in `rnex.yaml` or `.local.rnex.yaml`:
 ```yaml
 plugins:
   cursor:
-    instructions: true   # Sync routing instructions to .cursorrules (default: true)
     skills: true         # Generate user skills in .cursor/rules/ (default: true)
     enabled: true        # Set to false to disable
 ```
 
 | Option | Type | Default | Description |
 |:---|:---|:---|:---|
-| `instructions` | boolean | `true` | Merge routing instructions into `.cursorrules`. |
 | `skills` | boolean | `true` | Generate user skill pointers in `.cursor/rules/rnex-*.md`. |
 | `enabled` | boolean | `true` | Enable or disable the plugin. Overridable in `.local.rnex.yaml`. |
 
@@ -77,7 +75,7 @@ When `cursor` is enabled with functional plugins like `karpathy-llm`, it generat
 ```text
 my-workspace/
 ├── AGENTS.md                          # Universal workspace instructions & routing
-├── .cursorrules                       # Cursor root instructions (if instructions: true)
+├── .cursorrules                       # Cursor root instructions
 ├── .cursor/
 │   └── rules/                         # Zero-logic User Skill pointers
 │       ├── rnex-clone-sync.md

package/docs/plugins/gemini.md

@@ -20,7 +20,7 @@ Operational skills, rules, and subagents remain cleanly encapsulated within `.rn
    - Contains zero inline heuristics—redirects Gemini/Antigravity directly to the underlying agentic skill protocols inside `.rnex/`.
 
 2. **Native Instructions Support via `GEMINI.md`**:
-   - Synchronizes Repo Nexus routing instructions to `GEMINI.md` (when `instructions: true`, default) for native support by the Google Gemini CLI.
+   - Automatically synchronizes Repo Nexus routing instructions to `GEMINI.md` for native support by the Google Gemini CLI and Antigravity.
    - Preserves user-defined custom sections in `GEMINI.md` across updates.
 
 3. **Subagent & Skill Execution**:
@@ -57,15 +57,15 @@ Configure options under `plugins.gemini` in `rnex.yaml` or `.local.rnex.yaml`:
 ```yaml
 plugins:
   gemini:
-    instructions: true   # Sync routing instructions to GEMINI.md (default: true)
     skills: true         # Generate user skills in .agents/skills/ (default: true)
+    auto_sync_on: SessionStart # Trigger auto-sync on lifecycle event (default: SessionStart, or false)
     enabled: true        # Set to false to disable
 ```
 
 | Option | Type | Default | Description |
 |:---|:---|:---|:---|
-| `instructions` | boolean | `true` | Merge routing instructions into `GEMINI.md`. |
 | `skills` | boolean | `true` | Generate user skill pointers in `.agents/skills/rnex-*/SKILL.md`. |
+| `auto_sync_on` | string/boolean | `SessionStart` | Lifecycle event triggering auto-sync in `.agents/hooks.json` (or `false` to disable). |
 | `enabled` | boolean | `true` | Enable or disable the plugin. Overridable in `.local.rnex.yaml`. |
 
 ---
@@ -76,7 +76,7 @@ When `gemini` is enabled with functional plugins like `karpathy-llm`, it generat
 
 ```text
 my-workspace/
-├── GEMINI.md                          # Gemini-specific instructions (if instructions: true)
+├── GEMINI.md                          # Gemini-specific instructions
 ├── .agents/
 │   └── skills/                        # Zero-logic User Skill pointers
 │       ├── rnex-clone-sync/

package/docs/plugins/index.md

@@ -97,12 +97,12 @@ repos_dir: ./repos
 plugins:
   # AI Provider Plugins
   claude:
-    instructions: true
     skills: true
+    auto_sync_on: SessionStart
 
   gemini:
-    instructions: true
     skills: true
+    auto_sync_on: SessionStart
 
   # Functional / Knowledge Plugins
   karpathy-llm:

package/docs/plugins/windsurf.md

@@ -20,7 +20,7 @@ Operational skills, rules, and subagents remain cleanly encapsulated within `.rn
    - Contains zero inline heuristics—redirects Cascade directly to the underlying agentic skill protocols inside `.rnex/`.
 
 2. **Native Instructions Support via `.windsurfrules`**:
-   - Synchronizes Repo Nexus routing instructions to `.windsurfrules` when `instructions: true` (default).
+   - Automatically synchronizes Repo Nexus routing instructions to `.windsurfrules`.
    - Preserves user custom rules and custom sections in `.windsurfrules`.
 
 3. **Subagent & Skill Execution**:
@@ -57,14 +57,12 @@ Configure options under `plugins.windsurf` in `rnex.yaml` or `.local.rnex.yaml`:
 ```yaml
 plugins:
   windsurf:
-    instructions: true   # Sync routing instructions to .windsurfrules (default: true)
     skills: true         # Generate user skills in .windsurf/rules/ (default: true)
     enabled: true        # Set to false to disable
 ```
 
 | Option | Type | Default | Description |
 |:---|:---|:---|:---|
-| `instructions` | boolean | `true` | Merge routing instructions into `.windsurfrules`. |
 | `skills` | boolean | `true` | Generate user skill pointers in `.windsurf/rules/rnex-*.md`. |
 | `enabled` | boolean | `true` | Enable or disable the plugin. Overridable in `.local.rnex.yaml`. |
 
@@ -77,7 +75,7 @@ When `windsurf` is enabled with functional plugins like `karpathy-llm`, it gener
 ```text
 my-workspace/
 ├── AGENTS.md                          # Universal workspace instructions & routing
-├── .windsurfrules                     # Windsurf instructions (if instructions: true)
+├── .windsurfrules                     # Windsurf instructions
 ├── .windsurf/
 │   └── rules/                         # Zero-logic User Skill pointers
 │       ├── rnex-clone-sync.md

package/docs/rnex.example.yaml

@@ -84,24 +84,22 @@ git_hooks: true
 #   AGENTS.md at workspace root is the universal cross-tool standard. Assistants that read AGENTS.md
 #   all the time need no separate top-level instructions file. Assistants with native
 #   formats (Claude with CLAUDE.md, Gemini with GEMINI.md, Cursor with .cursorrules, Windsurf with .windsurfrules)
-#   have their instruction files maintained when their plugin is enabled (instructions: true).
+#   have their instruction files maintained automatically when their plugin is enabled.
 #   Agentic skills live self-contained inside .rnex/skills/ (core) and .rnex/plugins/<plugin>/skills/ (plugins).
 #   Provider plugins generate zero-logic User Skills (prefixed with rnex-) into IDE-specific skill directories
 #   linking directly to the agentic skill protocols inside .rnex/.
 
 plugins:
   # claude:
-  #   instructions: true   # sync routing instructions to CLAUDE.md (default: true)
-  #   skills: true         # generate user skills in .claude/skills/ (default: true)
+  #   skills: true              # generate user skills in .claude/skills/ (default: true)
+  #   auto_sync_on: SessionStart # trigger auto-sync on lifecycle event (default: SessionStart, or false)
   # gemini:
-  #   instructions: true   # sync routing instructions to GEMINI.md (default: true)
-  #   skills: true         # generate user skills in .agents/skills/ (default: true)
+  #   skills: true              # generate user skills in .agents/skills/ (default: true)
+  #   auto_sync_on: SessionStart # trigger auto-sync on lifecycle event (default: SessionStart, or false)
   # cursor:
-  #   instructions: true   # sync routing instructions to .cursorrules (default: true)
-  #   skills: true         # generate user skills in .cursor/rules/ (default: true)
+  #   skills: true              # generate user skills in .cursor/rules/ (default: true)
   # windsurf:
-  #   instructions: true   # sync routing instructions to .windsurfrules (default: true)
-  #   skills: true         # generate user skills in .windsurf/rules/ (default: true)
+  #   skills: true              # generate user skills in .windsurf/rules/ (default: true)
   # karpathy-llm:
   #   raw_dir: "./docs"           # Append-only directory for unmodified intake documents (default: ./docs)
   #   wiki_dir: ".rnex/wiki"      # Directory for curated atomic markdown pages (default: .rnex/wiki)

package/lib/ai.sh

@@ -495,6 +495,96 @@ clean_provider_agents() {
   rmdir "$_ag_dir" 2>/dev/null || true
 }
 
+clean_claude_auto_sync_hook() {
+  _settings="$1"
+  [ -f "$_settings" ] || return 0
+  if grep -q "auto-sync.sh" "$_settings" 2>/dev/null; then
+    _tmp="$(mktemp)"
+    awk '
+      /\{[ \t]*"command"[ \t]*:[ \t]*"\.rnex\/bin\/auto-sync\.sh"[ \t]*\}/ { next }
+      /"command"[ \t]*:[ \t]*"\.rnex\/bin\/auto-sync\.sh"/ { next }
+      { print }
+    ' "$_settings" > "$_tmp"
+    _clean="$(sed -e 's/"hooks"//g' -e 's/"SessionStart"//g' < "$_tmp" | tr -d ' \t\r\n[]{}:,"')"
+    if [ -z "$_clean" ]; then
+      rm -f "$_tmp" "$_settings"
+    else
+      awk '
+        { lines[NR] = $0 }
+        END {
+          for (i = 1; i <= NR; i++) {
+            if (i < NR && lines[i] ~ /,[ \t]*$/) {
+              next_is_bracket = 0
+              for (j = i + 1; j <= NR; j++) {
+                if (lines[j] ~ /^[ \t]*$/) continue
+                if (lines[j] ~ /^[ \t]*[\]\}]/) next_is_bracket = 1
+                break
+              }
+              if (next_is_bracket) {
+                sub(/,[ \t]*$/, "", lines[i])
+              }
+            }
+            print lines[i]
+          }
+        }
+      ' "$_tmp" > "$_settings"
+      rm -f "$_tmp"
+    fi
+  fi
+}
+
+clean_agents_auto_sync_hook() {
+  _hooks="$1"
+  [ -f "$_hooks" ] || return 0
+  if grep -q '"rnex-auto-sync"' "$_hooks" 2>/dev/null; then
+    _tmp="$(mktemp)"
+    awk '
+      BEGIN { skip=0; depth=0 }
+      /"rnex-auto-sync"[ \t]*:[ \t]*\{/ { skip=1; depth=1; next }
+      skip {
+        for (i=1; i<=length($0); i++) {
+          c = substr($0, i, 1)
+          if (c == "{") depth++
+          if (c == "}") {
+            depth--
+            if (depth == 0) {
+              skip = 0
+              next
+            }
+          }
+        }
+        next
+      }
+      { print }
+    ' "$_hooks" > "$_tmp"
+    _clean="$(tr -d " \t\r\n{}" < "$_tmp")"
+    if [ -z "$_clean" ]; then
+      rm -f "$_tmp" "$_hooks"
+    else
+      awk '
+        { lines[NR] = $0 }
+        END {
+          for (i = 1; i <= NR; i++) {
+            if (i < NR && lines[i] ~ /,[ \t]*$/) {
+              next_is_brace = 0
+              for (j = i + 1; j <= NR; j++) {
+                if (lines[j] ~ /^[ \t]*$/) continue
+                if (lines[j] ~ /^[ \t]*\}/) next_is_brace = 1
+                break
+              }
+              if (next_is_brace) {
+                sub(/,[ \t]*$/, "", lines[i])
+              }
+            }
+            print lines[i]
+          }
+        }
+      ' "$_tmp" > "$_hooks"
+      rm -f "$_tmp"
+    fi
+  fi
+}
+
 sync_rnex_base_assets() {
   _src_toolkit=""
   if [ -d "$SCRIPT_LOCATION/toolkit" ]; then

package/lib/commands/status.sh

@@ -213,10 +213,20 @@ cmd_status() {
         else
           printf '  %b●%b %-18s %b(v%s)%b %s\n' "$_G" "$_NC" "$_pname" "$_DIM" "${_ver:-0.1.0}" "$_NC" "${_desc:+- $_desc}"
           printf '    %bScoped directory: .rnex/plugins/%s%b\n' "$_DIM" "$_pname" "$_NC"
-          if [ -n "$_pdir" ] && { grep -q "instructions:" "$_pdir/plugin.yaml" 2>/dev/null || [ -n "$(yaml_plugin_get "$_pname" "instructions" 2>/dev/null)" ]; }; then
-            printf '    %b↳ Options: instructions=%s, skills=%s%b\n' "$_DIM" \
-              "$(provider_option_enabled "$_pname" "instructions" && echo "true" || echo "false")" \
-              "$(provider_option_enabled "$_pname" "skills" && echo "true" || echo "false")" "$_NC"
+          if [ -n "$_pdir" ] && [ -f "$_pdir/plugin.yaml" ]; then
+            _opts=""
+            if grep -q "skills:" "$_pdir/plugin.yaml" 2>/dev/null || [ -n "$(yaml_plugin_get "$_pname" "skills" 2>/dev/null)" ]; then
+              _opts="${_opts:+$_opts, }skills=$(provider_option_enabled "$_pname" "skills" && echo "true" || echo "false")"
+            fi
+            if grep -q "auto_sync_on:" "$_pdir/plugin.yaml" 2>/dev/null || grep -q "autoSyncOn:" "$_pdir/plugin.yaml" 2>/dev/null || [ -n "$(yaml_plugin_get "$_pname" "auto_sync_on" 2>/dev/null)" ] || [ -n "$(yaml_plugin_get "$_pname" "autoSyncOn" 2>/dev/null)" ]; then
+              _aso="$(yaml_plugin_get "$_pname" "auto_sync_on" 2>/dev/null || true)"
+              [ -z "$_aso" ] && _aso="$(yaml_plugin_get "$_pname" "autoSyncOn" 2>/dev/null || true)"
+              [ -z "$_aso" ] && _aso="SessionStart"
+              _opts="${_opts:+$_opts, }auto_sync_on=$_aso"
+            fi
+            if [ -n "$_opts" ]; then
+              printf '    %b↳ Options: %s%b\n' "$_DIM" "$_opts" "$_NC"
+            fi
           fi
         fi
       else

package/lib/yaml.sh

@@ -157,24 +157,39 @@ provider_option_enabled() {
   esac
 }
 
+provider_auto_sync_enabled() {
+  _p="$1"
+  provider_plugin_enabled "$_p" || return 1
+  _val="$(yaml_plugin_get "$_p" "auto_sync_on")"
+  [ -z "$_val" ] && _val="$(yaml_plugin_get "$_p" "autoSyncOn")"
+  [ -z "$_val" ] && _val="SessionStart"
+  _val="$(printf '%s' "$_val" | tr '[:upper:]' '[:lower:]')"
+  case "$_val" in
+    false|no|0|disabled|off|none) return 1 ;;
+    *) return 0 ;;
+  esac
+}
+
 copilot_plugin_enabled() { provider_plugin_enabled "copilot"; }
-copilot_instructions_enabled() { provider_option_enabled "copilot" "instructions"; }
+copilot_instructions_enabled() { provider_plugin_enabled "copilot"; }
 copilot_skills_enabled() { provider_option_enabled "copilot" "skills"; }
 
 claude_plugin_enabled() { provider_plugin_enabled "claude"; }
-claude_instructions_enabled() { provider_option_enabled "claude" "instructions"; }
+claude_instructions_enabled() { provider_plugin_enabled "claude"; }
 claude_skills_enabled() { provider_option_enabled "claude" "skills"; }
+claude_auto_sync_enabled() { provider_auto_sync_enabled "claude"; }
 
 gemini_plugin_enabled() { provider_plugin_enabled "gemini"; }
-gemini_instructions_enabled() { provider_option_enabled "gemini" "instructions"; }
+gemini_instructions_enabled() { provider_plugin_enabled "gemini"; }
 gemini_skills_enabled() { provider_option_enabled "gemini" "skills"; }
+gemini_auto_sync_enabled() { provider_auto_sync_enabled "gemini"; }
 
 cursor_plugin_enabled() { provider_plugin_enabled "cursor"; }
-cursor_instructions_enabled() { provider_option_enabled "cursor" "instructions"; }
+cursor_instructions_enabled() { provider_plugin_enabled "cursor"; }
 cursor_skills_enabled() { provider_option_enabled "cursor" "skills"; }
 
 windsurf_plugin_enabled() { provider_plugin_enabled "windsurf"; }
-windsurf_instructions_enabled() { provider_option_enabled "windsurf" "instructions"; }
+windsurf_instructions_enabled() { provider_plugin_enabled "windsurf"; }
 windsurf_skills_enabled() { provider_option_enabled "windsurf" "skills"; }
 
 has_active_provider_instructions() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repo-nexus",
-  "version": "0.7.24",
+  "version": "0.7.26",
   "description": "Lightweight, zero-dependency Virtual Meta-Repo companion for multi-repo workspaces and shared AI context (no git submodules)",
   "bin": {
     "repo-nexus": "rnex",

package/templates/rnex-env.sh

@@ -9,7 +9,6 @@ if [ -z "$RNEX_PROVIDER_SKILL_DIRS" ]; then
   [ -d "$RNEX_ROOT/.claude" ] && _dirs="${_dirs:+$_dirs }.claude/skills"
   [ -d "$RNEX_ROOT/.windsurf" ] && _dirs="${_dirs:+$_dirs }.windsurf/rules"
   [ -d "$RNEX_ROOT/.agents" ] && _dirs="${_dirs:+$_dirs }.agents/skills"
-  [ -d "$RNEX_ROOT/.gemini" ] && _dirs="${_dirs:+$_dirs }.agents/skills"
   export RNEX_PROVIDER_SKILL_DIRS="$_dirs"
 fi
 
@@ -106,8 +105,54 @@ rnex_unregister_user_skill() {
 }
 
 # Provider configuration check helper
-if ! command -v provider_option_enabled >/dev/null 2>&1; then
-  provider_option_enabled() {
+if ! command -v provider_plugin_enabled >/dev/null 2>&1; then
+  provider_plugin_enabled() {
+    _p="$1"
+    _r="${NEXUS_DIR:-${RNEX_ROOT:-.}}"
+    _val=""
+    if [ -f "$_r/.local.rnex.yaml" ]; then
+      _val="$(awk -v p="$_p" '
+        /^plugins:/ { in_p=1; next }
+        in_p && /^[^ #]/ { in_p=0; in_target=0 }
+        in_p && match($0, "^[ ]*" p ":[ ]*(#.*)?$") { in_target=1; next }
+        in_p && match($0, "^[ ]*-[ ]*" p "[ ]*(#.*)?$") { print "true"; exit }
+        in_target && (/^[ ]{1,2}[^ #]/ || /^[^ #]/) { in_target=0 }
+        in_target && $0 ~ "^[ ]*enabled:[ ]*" {
+          sub("^[ ]*enabled:[ ]*", "")
+          sub(/[ ]*#.*/, "")
+          gsub(/["\047]/, "")
+          print
+          exit
+        }
+      ' "$_r/.local.rnex.yaml")"
+    fi
+    if [ -z "$_val" ] && [ -f "$_r/rnex.yaml" ]; then
+      _val="$(awk -v p="$_p" '
+        /^plugins:/ { in_p=1; next }
+        in_p && /^[^ #]/ { in_p=0; in_target=0 }
+        in_p && match($0, "^[ ]*" p ":[ ]*(#.*)?$") { in_target=1; next }
+        in_p && match($0, "^[ ]*-[ ]*" p "[ ]*(#.*)?$") { print "true"; exit }
+        in_target && (/^[ ]{1,2}[^ #]/ || /^[^ #]/) { in_target=0 }
+        in_target && $0 ~ "^[ ]*enabled:[ ]*" {
+          sub("^[ ]*enabled:[ ]*", "")
+          sub(/[ ]*#.*/, "")
+          gsub(/["\047]/, "")
+          print
+          exit
+        }
+      ' "$_r/rnex.yaml")"
+    fi
+    [ -n "$_val" ] || return 1
+    _val="$(printf '%s' "$_val" | tr '[:upper:]' '[:lower:]')"
+    case "$_val" in
+      false|no|0|disabled|off) return 1 ;;
+      *) return 0 ;;
+    esac
+  }
+fi
+
+if ! command -v provider_option_get >/dev/null 2>&1; then
+  provider_option_get() {
     _p="$1"; _opt="$2"
     _r="${NEXUS_DIR:-${RNEX_ROOT:-.}}"
     _val=""
@@ -141,6 +186,14 @@ if ! command -v provider_option_enabled >/dev/null 2>&1; then
         }
       ' "$_r/rnex.yaml")"
     fi
+    printf '%s' "$_val"
+  }
+fi
+
+if ! command -v provider_option_enabled >/dev/null 2>&1; then
+  provider_option_enabled() {
+    _p="$1"; _opt="$2"
+    _val="$(provider_option_get "$_p" "$_opt")"
     _val="$(printf '%s' "$_val" | tr '[:upper:]' '[:lower:]')"
     case "$_val" in
       false|no|0|disabled|off) return 1 ;;
@@ -149,17 +202,125 @@ if ! command -v provider_option_enabled >/dev/null 2>&1; then
   }
 fi
 
+if ! command -v provider_auto_sync_enabled >/dev/null 2>&1; then
+  provider_auto_sync_enabled() {
+    _p="$1"
+    _val="$(provider_option_get "$_p" "auto_sync_on")"
+    [ -z "$_val" ] && _val="$(provider_option_get "$_p" "autoSyncOn")"
+    [ -z "$_val" ] && _val="SessionStart"
+    _val="$(printf '%s' "$_val" | tr '[:upper:]' '[:lower:]')"
+    case "$_val" in
+      false|no|0|disabled|off|none) return 1 ;;
+      *) return 0 ;;
+    esac
+  }
+fi
+
 if ! command -v has_active_provider_instructions >/dev/null 2>&1; then
   has_active_provider_instructions() {
-    provider_option_enabled "copilot" "instructions" 2>/dev/null && return 0
-    provider_option_enabled "claude" "instructions" 2>/dev/null && return 0
-    provider_option_enabled "gemini" "instructions" 2>/dev/null && return 0
-    provider_option_enabled "cursor" "instructions" 2>/dev/null && return 0
-    provider_option_enabled "windsurf" "instructions" 2>/dev/null && return 0
+    provider_plugin_enabled "copilot" 2>/dev/null && return 0
+    provider_plugin_enabled "claude" 2>/dev/null && return 0
+    provider_plugin_enabled "gemini" 2>/dev/null && return 0
+    provider_plugin_enabled "cursor" 2>/dev/null && return 0
+    provider_plugin_enabled "windsurf" 2>/dev/null && return 0
     return 1
   }
 fi
 
+if ! command -v clean_claude_auto_sync_hook >/dev/null 2>&1; then
+  clean_claude_auto_sync_hook() {
+    _settings="$1"
+    [ -f "$_settings" ] || return 0
+    if grep -q "auto-sync.sh" "$_settings" 2>/dev/null; then
+      _tmp="$(mktemp)"
+      awk '
+        /\{[ \t]*"command"[ \t]*:[ \t]*"\.rnex\/bin\/auto-sync\.sh"[ \t]*\}/ { next }
+        /"command"[ \t]*:[ \t]*"\.rnex\/bin\/auto-sync\.sh"/ { next }
+        { print }
+      ' "$_settings" > "$_tmp"
+      _clean="$(sed -e 's/"hooks"//g' -e 's/"SessionStart"//g' < "$_tmp" | tr -d ' \t\r\n[]{}:,"')"
+      if [ -z "$_clean" ]; then
+        rm -f "$_tmp" "$_settings"
+      else
+        awk '
+          { lines[NR] = $0 }
+          END {
+            for (i = 1; i <= NR; i++) {
+              if (i < NR && lines[i] ~ /,[ \t]*$/) {
+                next_is_bracket = 0
+                for (j = i + 1; j <= NR; j++) {
+                  if (lines[j] ~ /^[ \t]*$/) continue
+                  if (lines[j] ~ /^[ \t]*[\]\}]/) next_is_bracket = 1
+                  break
+                }
+                if (next_is_bracket) {
+                  sub(/,[ \t]*$/, "", lines[i])
+                }
+              }
+              print lines[i]
+            }
+          }
+        ' "$_tmp" > "$_settings"
+        rm -f "$_tmp"
+      fi
+    fi
+  }
+fi
+
+if ! command -v clean_agents_auto_sync_hook >/dev/null 2>&1; then
+  clean_agents_auto_sync_hook() {
+    _hooks="$1"
+    [ -f "$_hooks" ] || return 0
+    if grep -q '"rnex-auto-sync"' "$_hooks" 2>/dev/null; then
+      _tmp="$(mktemp)"
+      awk '
+        BEGIN { skip=0; depth=0 }
+        /"rnex-auto-sync"[ \t]*:[ \t]*\{/ { skip=1; depth=1; next }
+        skip {
+          for (i=1; i<=length($0); i++) {
+            c = substr($0, i, 1)
+            if (c == "{") depth++
+            if (c == "}") {
+              depth--
+              if (depth == 0) {
+                skip = 0
+                next
+              }
+            }
+          }
+          next
+        }
+        { print }
+      ' "$_hooks" > "$_tmp"
+      _clean="$(tr -d " \t\r\n{}" < "$_tmp")"
+      if [ -z "$_clean" ]; then
+        rm -f "$_tmp" "$_hooks"
+      else
+        awk '
+          { lines[NR] = $0 }
+          END {
+            for (i = 1; i <= NR; i++) {
+              if (i < NR && lines[i] ~ /,[ \t]*$/) {
+                next_is_brace = 0
+                for (j = i + 1; j <= NR; j++) {
+                  if (lines[j] ~ /^[ \t]*$/) continue
+                  if (lines[j] ~ /^[ \t]*\}/) next_is_brace = 1
+                  break
+                }
+                if (next_is_brace) {
+                  sub(/,[ \t]*$/, "", lines[i])
+                }
+              }
+              print lines[i]
+            }
+          }
+        ' "$_tmp" > "$_hooks"
+        rm -f "$_tmp"
+      fi
+    fi
+  }
+fi
+
 # Instructions routing helpers
 if ! command -v merge_rnex_instructions >/dev/null 2>&1; then
   merge_rnex_instructions() {

package/templates/rnex.example.yaml

@@ -84,24 +84,22 @@ git_hooks: true
 #   AGENTS.md at workspace root is the universal cross-tool standard. Assistants that read AGENTS.md
 #   all the time need no separate top-level instructions file. Assistants with native
 #   formats (Claude with CLAUDE.md, Gemini with GEMINI.md, Cursor with .cursorrules, Windsurf with .windsurfrules)
-#   have their instruction files maintained when their plugin is enabled (instructions: true).
+#   have their instruction files maintained automatically when their plugin is enabled.
 #   Agentic skills live self-contained inside .rnex/skills/ (core) and .rnex/plugins/<plugin>/skills/ (plugins).
 #   Provider plugins generate zero-logic User Skills (prefixed with rnex-) into IDE-specific skill directories
 #   linking directly to the agentic skill protocols inside .rnex/.
 
 plugins:
   # claude:
-  #   instructions: true   # sync routing instructions to CLAUDE.md (default: true)
-  #   skills: true         # generate user skills in .claude/skills/ (default: true)
+  #   skills: true              # generate user skills in .claude/skills/ (default: true)
+  #   auto_sync_on: SessionStart # trigger auto-sync on lifecycle event (default: SessionStart, or false)
   # gemini:
-  #   instructions: true   # sync routing instructions to GEMINI.md (default: true)
-  #   skills: true         # generate user skills in .agents/skills/ (default: true)
+  #   skills: true              # generate user skills in .agents/skills/ (default: true)
+  #   auto_sync_on: SessionStart # trigger auto-sync on lifecycle event (default: SessionStart, or false)
   # cursor:
-  #   instructions: true   # sync routing instructions to .cursorrules (default: true)
-  #   skills: true         # generate user skills in .cursor/rules/ (default: true)
+  #   skills: true              # generate user skills in .cursor/rules/ (default: true)
   # windsurf:
-  #   instructions: true   # sync routing instructions to .windsurfrules (default: true)
-  #   skills: true         # generate user skills in .windsurf/rules/ (default: true)
+  #   skills: true              # generate user skills in .windsurf/rules/ (default: true)
   # karpathy-llm:
   #   raw_dir: "./docs"           # Append-only directory for unmodified intake documents (default: ./docs)
   #   wiki_dir: ".rnex/wiki"      # Directory for curated atomic markdown pages (default: .rnex/wiki)

package/toolkit/plugins/claude/README.md

@@ -18,14 +18,14 @@ Or configure options in `rnex.yaml` or `.local.rnex.yaml`:
 ```yaml
 plugins:
   claude:
-    instructions: true
     skills: true
+    auto_sync_on: SessionStart
 ```
 
 ## Options
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `instructions` | boolean | `true` | Maintain routing in `CLAUDE.md` |
 | `skills` | boolean | `true` | Generate user skills in `.claude/skills/` |
+| `auto_sync_on` | string/boolean | `SessionStart` | Lifecycle event triggering auto-sync in `.claude/settings.json` (or `false` to disable) |
 | `enabled` | boolean | `true` | Set to `false` in `.local.rnex.yaml` to override team config |

package/toolkit/plugins/claude/hooks/after_sync.sh

@@ -8,13 +8,8 @@ if ! command -v merge_rnex_instructions >/dev/null 2>&1; then
   fi
 fi
 
-# Instructions management
-_inst="$(provider_option_enabled "claude" "instructions" 2>/dev/null && echo "true" || echo "false")"
-if [ "$_inst" = "true" ]; then
-  merge_rnex_instructions "$_root/CLAUDE.md"
-else
-  clean_rnex_instructions "$_root/CLAUDE.md"
-fi
+# Instructions management (always maintained when claude plugin is enabled)
+merge_rnex_instructions "$_root/CLAUDE.md"
 
 # Skills management
 _sk="$(provider_option_enabled "claude" "skills" 2>/dev/null && echo "true" || echo "false")"
@@ -22,11 +17,12 @@ if [ "$_sk" != "true" ]; then
   clean_provider_user_skills "$_root/.claude/skills"
 fi
 
-# SessionStart auto-sync hook configuration
-mkdir -p "$_root/.claude"
+# Auto-sync hook configuration (SessionStart)
 _settings="$_root/.claude/settings.json"
-if [ ! -f "$_settings" ]; then
-  cat > "$_settings" <<'EOF'
+if provider_auto_sync_enabled "claude"; then
+  mkdir -p "$_root/.claude"
+  if [ ! -f "$_settings" ]; then
+    cat > "$_settings" <<'EOF'
 {
   "hooks": {
     "SessionStart": [
@@ -37,26 +33,30 @@ if [ ! -f "$_settings" ]; then
   }
 }
 EOF
-elif ! grep -q "auto-sync.sh" "$_settings" 2>/dev/null; then
-  if grep -q '"SessionStart"' "$_settings" 2>/dev/null; then
-    _tmp="$(mktemp)"
-    awk '
-      /"SessionStart"[ ]*:[ ]*\[/ {
-        print
-        print "      { \"command\": \".rnex/bin/auto-sync.sh\" },"
-        next
-      }
-      { print }
-    ' "$_settings" > "$_tmp" && mv "$_tmp" "$_settings"
-  elif grep -q '"hooks"' "$_settings" 2>/dev/null; then
-    _tmp="$(mktemp)"
-    awk '
-      /"hooks"[ ]*:[ ]*\{/ {
-        print
-        print "    \"SessionStart\": [ { \"command\": \".rnex/bin/auto-sync.sh\" } ],"
-        next
-      }
-      { print }
-    ' "$_settings" > "$_tmp" && mv "$_tmp" "$_settings"
+  elif ! grep -q "auto-sync.sh" "$_settings" 2>/dev/null; then
+    if grep -q '"SessionStart"' "$_settings" 2>/dev/null; then
+      _tmp="$(mktemp)"
+      awk '
+        /"SessionStart"[ ]*:[ ]*\[/ {
+          print
+          print "      { \"command\": \".rnex/bin/auto-sync.sh\" },"
+          next
+        }
+        { print }
+      ' "$_settings" > "$_tmp" && mv "$_tmp" "$_settings"
+    elif grep -q '"hooks"' "$_settings" 2>/dev/null; then
+      _tmp="$(mktemp)"
+      awk '
+        /"hooks"[ ]*:[ ]*\{/ {
+          print
+          print "    \"SessionStart\": [ { \"command\": \".rnex/bin/auto-sync.sh\" } ],"
+          next
+        }
+        { print }
+      ' "$_settings" > "$_tmp" && mv "$_tmp" "$_settings"
+    fi
   fi
+else
+  clean_claude_auto_sync_hook "$_settings"
+  rmdir "$_root/.claude" 2>/dev/null || true
 fi

package/toolkit/plugins/claude/hooks/before_plugin_disable.sh

@@ -10,5 +10,6 @@ fi
 
 clean_rnex_instructions "$_root/CLAUDE.md"
 clean_provider_user_skills "$_root/.claude/skills"
+clean_claude_auto_sync_hook "$_root/.claude/settings.json"
 rm -rf "$_root/.claude/commands" "$_root/.claude/prompts" 2>/dev/null || true
 rmdir "$_root/.claude" 2>/dev/null || true

package/toolkit/plugins/claude/instructions/rnex-claude-integration.md

@@ -13,8 +13,8 @@ Configure plugin options in `rnex.yaml` or override them per developer in `.loca
 ```yaml
 plugins:
   claude:
-    instructions: true   # Maintain routing in CLAUDE.md (default: true)
     skills: true         # Generate user skills in .claude/skills/ (default: true)
+    auto_sync_on: SessionStart # Trigger auto-sync on lifecycle event (default: SessionStart, or false)
 ```
 
 To disable locally without altering team configuration, add to `.local.rnex.yaml`:

package/toolkit/plugins/claude/plugin.yaml

@@ -6,12 +6,12 @@ homepage: https://github.com/unoxen/repo-nexus
 skill_dir: .claude/skills
 
 config_defaults:
-  instructions: true
   skills: true
+  auto_sync_on: SessionStart
 
 config_descriptions:
-  instructions: "true|false  (maintain provider instructions)"
   skills: "true|false        (generate user skills in {skill_dir})"
+  auto_sync_on: "SessionStart|false  (trigger auto-sync on lifecycle event, e.g. SessionStart)"
 
 instructions:
   - instructions/rnex-claude-integration.md: .rnex/plugins/claude/instructions/rnex-claude-integration.md

package/toolkit/plugins/copilot/README.md

@@ -18,7 +18,6 @@ Or configure options in `rnex.yaml` or `.local.rnex.yaml`:
 ```yaml
 plugins:
   copilot:
-    instructions: true
     skills: true
 ```
 
@@ -26,6 +25,5 @@ plugins:
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `instructions` | boolean | `true` | Maintain routing in `.github/copilot-instructions.md` |
 | `skills` | boolean | `true` | Generate user skills in `.github/skills/` |
 | `enabled` | boolean | `true` | Set to `false` in `.local.rnex.yaml` to override team config |

package/toolkit/plugins/copilot/hooks/after_sync.sh

@@ -142,16 +142,9 @@ if ! command -v clean_provider_user_skills >/dev/null 2>&1; then
   }
 fi
 
-_inst="$(provider_option_enabled "copilot" "instructions" 2>/dev/null && echo "true" || echo "false")"
-if [ "$_inst" = "true" ]; then
-  mkdir -p "$_root/.github"
-  if command -v merge_rnex_instructions >/dev/null 2>&1; then
-    merge_rnex_instructions "$_root/.github/copilot-instructions.md"
-  fi
-else
-  if command -v clean_rnex_instructions >/dev/null 2>&1; then
-    clean_rnex_instructions "$_root/.github/copilot-instructions.md"
-  fi
+mkdir -p "$_root/.github"
+if command -v merge_rnex_instructions >/dev/null 2>&1; then
+  merge_rnex_instructions "$_root/.github/copilot-instructions.md"
 fi
 
 _sk="$(provider_option_enabled "copilot" "skills" 2>/dev/null && echo "true" || echo "false")"

package/toolkit/plugins/copilot/instructions/rnex-copilot-integration.md

@@ -12,7 +12,6 @@ Configure plugin options in `rnex.yaml` or override them per developer in `.loca
 ```yaml
 plugins:
   copilot:
-    instructions: true   # Maintain routing in .github/copilot-instructions.md (default: true)
     skills: true         # Generate user skills in .github/skills/ (default: true)
 ```
 

package/toolkit/plugins/copilot/plugin.yaml

@@ -6,11 +6,9 @@ homepage: https://github.com/unoxen/repo-nexus
 skill_dir: .github/skills
 
 config_defaults:
-  instructions: true
   skills: true
 
 config_descriptions:
-  instructions: "true|false  (maintain provider instructions)"
   skills: "true|false        (generate user skills in {skill_dir})"
 
 instructions:

package/toolkit/plugins/cursor/README.md

@@ -19,7 +19,6 @@ Or configure options in `rnex.yaml` or `.local.rnex.yaml`:
 ```yaml
 plugins:
   cursor:
-    instructions: true
     skills: true
 ```
 
@@ -27,6 +26,5 @@ plugins:
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `instructions` | boolean | `true` | Maintain routing in `.cursorrules` & `.cursor/rules/` |
 | `skills` | boolean | `true` | Generate user skills in `.cursor/rules/` |
 | `enabled` | boolean | `true` | Set to `false` in `.local.rnex.yaml` to override team config |

package/toolkit/plugins/cursor/hooks/after_sync.sh

@@ -20,23 +20,18 @@ elif ! grep -q '!repos/\*' "$_ci" 2>/dev/null; then
   [ "${RNEX_QUIET:-0}" -eq 0 ] && log_dim "Added !repos/* to .cursorignore"
 fi
 
-_inst="$(provider_option_enabled "cursor" "instructions" 2>/dev/null && echo "true" || echo "false")"
-if [ "$_inst" = "true" ]; then
-  merge_rnex_instructions "$_root/.cursorrules"
-  mkdir -p "$_root/.cursor/rules"
-  _c_body="$(mktemp)"
-  get_rnex_instructions > "$_c_body"
-  {
-    printf -- '---\ndescription: Repo Nexus Virtual Meta-Repo routing protocol\nglobs: *\nalwaysApply: true\n---\n\n%s\n' "${AI_MARKER_START:-<!-- REPO-NEXUS:START -->}"
-    cat "$_c_body"
-    printf '\n%s\n' "${AI_MARKER_END:-<!-- REPO-NEXUS:END -->}"
-  } > "$_root/.cursor/rules/rnex-context.mdc"
-  rm -f "$_c_body"
-  rm -f "$_root/.cursor/rules/repo-nexus.mdc" 2>/dev/null || true
-else
-  clean_rnex_instructions "$_root/.cursorrules"
-  rm -f "$_root/.cursor/rules/rnex-context.mdc" "$_root/.cursor/rules/repo-nexus.mdc" 2>/dev/null || true
-fi
+# Instructions management (always maintained when cursor plugin is enabled)
+merge_rnex_instructions "$_root/.cursorrules"
+mkdir -p "$_root/.cursor/rules"
+_c_body="$(mktemp)"
+get_rnex_instructions > "$_c_body"
+{
+  printf -- '---\ndescription: Repo Nexus Virtual Meta-Repo routing protocol\nglobs: *\nalwaysApply: true\n---\n\n%s\n' "${AI_MARKER_START:-<!-- REPO-NEXUS:START -->}"
+  cat "$_c_body"
+  printf '\n%s\n' "${AI_MARKER_END:-<!-- REPO-NEXUS:END -->}"
+} > "$_root/.cursor/rules/rnex-context.mdc"
+rm -f "$_c_body"
+rm -f "$_root/.cursor/rules/repo-nexus.mdc" 2>/dev/null || true
 
 _sk="$(provider_option_enabled "cursor" "skills" 2>/dev/null && echo "true" || echo "false")"
 if [ "$_sk" != "true" ]; then

package/toolkit/plugins/cursor/instructions/rnex-cursor-integration.md

@@ -14,7 +14,6 @@ Configure plugin options in `rnex.yaml` or override them per developer in `.loca
 ```yaml
 plugins:
   cursor:
-    instructions: true   # Maintain routing in .cursorrules & .cursor/rules/ (default: true)
     skills: true         # Generate user skills in .cursor/rules/ (default: true)
 ```
 

package/toolkit/plugins/cursor/plugin.yaml

@@ -6,11 +6,9 @@ homepage: https://github.com/unoxen/repo-nexus
 skill_dir: .cursor/rules
 
 config_defaults:
-  instructions: true
   skills: true
 
 config_descriptions:
-  instructions: "true|false  (maintain provider instructions)"
   skills: "true|false        (generate user skills in {skill_dir})"
 
 instructions:

package/toolkit/plugins/gemini/README.md

@@ -19,14 +19,14 @@ Or configure options in `rnex.yaml` or `.local.rnex.yaml`:
 ```yaml
 plugins:
   gemini:
-    instructions: true
     skills: true
+    auto_sync_on: SessionStart
 ```
 
 ## Options
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `instructions` | boolean | `true` | Maintain routing in `GEMINI.md` |
 | `skills` | boolean | `true` | Generate user skills in `.agents/skills/` |
+| `auto_sync_on` | string/boolean | `SessionStart` | Lifecycle event triggering auto-sync in `.agents/hooks.json` (or `false` to disable) |
 | `enabled` | boolean | `true` | Set to `false` in `.local.rnex.yaml` to override team config |

package/toolkit/plugins/gemini/hooks/after_sync.sh

@@ -20,18 +20,55 @@ elif ! grep -q '!repos/\*' "$_gi" 2>/dev/null; then
   [ "${RNEX_QUIET:-0}" -eq 0 ] && log_dim "Added !repos/* to .geminiignore"
 fi
 
-_inst="$(provider_option_enabled "gemini" "instructions" 2>/dev/null && echo "true" || echo "false")"
-if [ "$_inst" = "true" ]; then
-  merge_rnex_instructions "$_root/GEMINI.md"
-else
-  clean_rnex_instructions "$_root/GEMINI.md"
-fi
+# Instructions management (always maintained when gemini plugin is enabled)
+merge_rnex_instructions "$_root/GEMINI.md"
 
+# Skills management
 _sk="$(provider_option_enabled "gemini" "skills" 2>/dev/null && echo "true" || echo "false")"
 if [ "$_sk" != "true" ]; then
   clean_provider_user_skills "$_root/.agents/skills"
 fi
 
+# Auto-sync hook configuration (SessionStart)
+_hooks_file="$_root/.agents/hooks.json"
+if provider_auto_sync_enabled "gemini"; then
+  if [ ! -f "$_hooks_file" ]; then
+    mkdir -p "$_root/.agents"
+    cat > "$_hooks_file" <<'EOF'
+{
+  "rnex-auto-sync": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": ".rnex/bin/auto-sync.sh"
+      }
+    ]
+  }
+}
+EOF
+  elif ! grep -q '"rnex-auto-sync"' "$_hooks_file" 2>/dev/null; then
+    _tmp="$(mktemp)"
+    awk '
+      /^[ \t]*\{/ && !done {
+        print
+        print "  \"rnex-auto-sync\": {"
+        print "    \"SessionStart\": ["
+        print "      {"
+        print "        \"type\": \"command\","
+        print "        \"command\": \".rnex/bin/auto-sync.sh\""
+        print "      }"
+        print "    ]"
+        print "  },"
+        done = 1
+        next
+      }
+      { print }
+    ' "$_hooks_file" > "$_tmp" && mv "$_tmp" "$_hooks_file"
+  fi
+else
+  clean_agents_auto_sync_hook "$_hooks_file"
+fi
+
 # Clean legacy .gemini/skills if it exists
 if [ -d "$_root/.gemini/skills" ]; then
   clean_provider_user_skills "$_root/.gemini/skills"

package/toolkit/plugins/gemini/hooks/before_plugin_disable.sh

@@ -12,6 +12,7 @@ clean_provider_ignore "$_root/.geminiignore"
 clean_rnex_instructions "$_root/GEMINI.md"
 clean_provider_user_skills "$_root/.agents/skills"
 clean_provider_user_skills "$_root/.gemini/skills"
+clean_agents_auto_sync_hook "$_root/.agents/hooks.json"
 rm -rf "$_root/.gemini/prompts" 2>/dev/null || true
 rmdir "$_root/.gemini" 2>/dev/null || true
 rmdir "$_root/.agents" 2>/dev/null || true

package/toolkit/plugins/gemini/instructions/rnex-gemini-integration.md

@@ -14,8 +14,8 @@ Configure plugin options in `rnex.yaml` or override them per developer in `.loca
 ```yaml
 plugins:
   gemini:
-    instructions: true   # Maintain routing in GEMINI.md (default: true)
     skills: true         # Generate user skills in .agents/skills/ (default: true)
+    auto_sync_on: SessionStart # Trigger auto-sync on lifecycle event (default: SessionStart, or false)
 ```
 
 To disable locally without altering team configuration, add to `.local.rnex.yaml`:

package/toolkit/plugins/gemini/plugin.yaml

@@ -6,12 +6,12 @@ homepage: https://github.com/unoxen/repo-nexus
 skill_dir: .agents/skills
 
 config_defaults:
-  instructions: true
   skills: true
+  auto_sync_on: SessionStart
 
 config_descriptions:
-  instructions: "true|false  (maintain provider instructions)"
   skills: "true|false        (generate user skills in {skill_dir})"
+  auto_sync_on: "SessionStart|false  (trigger auto-sync on lifecycle event, e.g. SessionStart)"
 
 instructions:
   - instructions/rnex-gemini-integration.md: .rnex/plugins/gemini/instructions/rnex-gemini-integration.md

package/toolkit/plugins/windsurf/README.md

@@ -18,7 +18,6 @@ Or configure options in `rnex.yaml` or `.local.rnex.yaml`:
 ```yaml
 plugins:
   windsurf:
-    instructions: true
     skills: true
 ```
 
@@ -26,6 +25,5 @@ plugins:
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `instructions` | boolean | `true` | Maintain routing in `.windsurfrules` |
 | `skills` | boolean | `true` | Generate user skills in `.windsurf/rules/` |
 | `enabled` | boolean | `true` | Set to `false` in `.local.rnex.yaml` to override team config |

package/toolkit/plugins/windsurf/hooks/after_sync.sh

@@ -8,12 +8,8 @@ if ! command -v merge_rnex_instructions >/dev/null 2>&1; then
   fi
 fi
 
-_inst="$(provider_option_enabled "windsurf" "instructions" 2>/dev/null && echo "true" || echo "false")"
-if [ "$_inst" = "true" ]; then
-  merge_rnex_instructions "$_root/.windsurfrules"
-else
-  clean_rnex_instructions "$_root/.windsurfrules"
-fi
+# Instructions management (always maintained when windsurf plugin is enabled)
+merge_rnex_instructions "$_root/.windsurfrules"
 
 _sk="$(provider_option_enabled "windsurf" "skills" 2>/dev/null && echo "true" || echo "false")"
 if [ "$_sk" != "true" ]; then

package/toolkit/plugins/windsurf/instructions/rnex-windsurf-integration.md

@@ -13,7 +13,6 @@ Configure plugin options in `rnex.yaml` or override them per developer in `.loca
 ```yaml
 plugins:
   windsurf:
-    instructions: true   # Maintain routing in .windsurfrules (default: true)
     skills: true         # Generate user skills in .windsurf/rules/ (default: true)
 ```
 

package/toolkit/plugins/windsurf/plugin.yaml

@@ -6,11 +6,9 @@ homepage: https://github.com/unoxen/repo-nexus
 skill_dir: .windsurf/rules
 
 config_defaults:
-  instructions: true
   skills: true
 
 config_descriptions:
-  instructions: "true|false  (maintain provider instructions)"
   skills: "true|false        (generate user skills in {skill_dir})"
 
 instructions: