repo-nexus 0.7.23 → 0.7.26

package/docs/CLI.md

@@ -37,7 +37,7 @@ rnex sync [-y|--yes] [-q|--quiet]
 2. **Git Ignore & Search Indexing**: Reconciles `.gitignore` (ignoring `repos/*` and `.local.rnex.yaml`) and `.ignore` (un-ignoring `repos/*` for search tools).
 3. **Plugin Sync**: Prunes disabled plugins and deterministically copies enabled plugin assets, rules, skills, templates, and executable lifecycle hooks into `.rnex/plugins/<plugin-name>/`.
 4. **Compiled AI Instructions**: Compiles `.rnex/ai-instructions.md` by combining the base template with active configuration and all enabled plugin `instructions.md` fragments. Top-level provider files (`AGENTS.md`, `CLAUDE.md`, etc.) receive only a single strict directive pointing to `.rnex/ai-instructions.md`.
-5. **Skill Reconciliation & User Skill Generation**: Copies core agentic skills from `toolkit/skills/` to `.rnex/skills/`, and generates lightweight, zero-logic User Skills (prefixed with `rnex-`) in configured AI assistant directories (`.cursor/rules/`, `.claude/skills/`, `.gemini/skills/`, `.windsurf/rules/`) pointing directly to `.rnex/skills/` or plugin skill directories.
+5. **Skill Reconciliation & User Skill Generation**: Copies core agentic skills from `toolkit/skills/` to `.rnex/skills/`, and generates lightweight, zero-logic User Skills (prefixed with `rnex-`) in configured AI assistant directories (`.cursor/rules/`, `.claude/skills/`, `.agents/skills/`, `.windsurf/rules/`) pointing directly to `.rnex/skills/` or plugin skill directories.
 6. **Harness Sync**: Reconciles root `.rnex/` and member repository harnesses (`repos/<name>/.rnex/`) for all enabled member repositories where `rnex_dir: true`.
 7. **Git Hooks**: Installs or reconciles workspace Git hooks in `.rnex/hooks` when `git_hooks: true`.
 8. **Multi-Root Workspace**: Synchronizes `.code-workspace` folder mappings when `code_workspace: true`.

package/docs/cli/workspace.md

@@ -28,7 +28,7 @@ rnex init [options] [directory]
 | `--no-hooks` | | boolean | `false` | Skip Git hooks configuration during initialization. |
 | `--claude` | | boolean | `false` | Enable Claude Code plugin (maintains `CLAUDE.md`, generates skills in `.claude/skills/`). |
 | `--cursor` | | boolean | `false` | Enable Cursor plugin (maintains `.cursorrules`, generates skills in `.cursor/rules/`). |
-| `--gemini` | | boolean | `false` | Enable Google Gemini plugin (maintains `GEMINI.md`, generates skills in `.gemini/skills/`). |
+| `--gemini` | | boolean | `false` | Enable Google Gemini plugin (maintains `GEMINI.md`, generates skills in `.agents/skills/`). |
 | `--windsurf` | | boolean | `false` | Enable Windsurf plugin (maintains `.windsurfrules`, generates skills in `.windsurf/rules/`). |
 
 ### Examples

package/docs/examples/ai-workflows.md

@@ -23,7 +23,7 @@ When a workspace is initialized, Repo Nexus maintains core agentic skills in `.r
 | `wiki-ingest` | Plugin (`karpathy-llm`) | Ingest raw intake documents into atomic Karpathy LLM Wiki pages. | `.rnex/plugins/karpathy-llm/skills/wiki-ingest.md` |
 | `wiki-lint` | Plugin (`karpathy-llm`) | Validate markdown links, compute backlinks, and update the master index. | `.rnex/plugins/karpathy-llm/skills/wiki-lint.md` |
 
-When provider plugins (such as `claude`, `gemini`, `cursor`, or `windsurf`) are enabled with `skills: true`, zero-logic User Skill pointers (`rnex-<skill-name>.md`) are generated directly into the respective native provider directories (`.cursor/rules/`, `.claude/skills/`, `.gemini/skills/`, `.windsurf/rules/`).
+When provider plugins (such as `claude`, `gemini`, `cursor`, or `windsurf`) are enabled with `skills: true`, zero-logic User Skill pointers (`rnex-<skill-name>.md`) are generated directly into the respective native provider directories (`.cursor/rules/`, `.claude/skills/`, `.agents/skills/`, `.windsurf/rules/`).
 
 ---
 

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

@@ -1,13 +1,13 @@
 ---
 title: Google Gemini & Antigravity Plugin
-description: Integrate Google Gemini and Antigravity IDE with Repo Nexus, generating zero-logic user skill pointers in .gemini/skills/.
+description: Integrate Google Gemini and Antigravity IDE with Repo Nexus, generating zero-logic user skill pointers in .agents/skills/.
 ---
 
 # Google Gemini & Antigravity Plugin
 
 The **`gemini`** plugin integrates Google Gemini CLI and Google Antigravity IDE into a Repo Nexus Virtual Meta-Repo.
 
-All AI assistants in Repo Nexus share [`AGENTS.md`](file:///Users/admin/Projects/ai/repo-nexus/AGENTS.md) at the workspace root as the single universal source of truth for routing. When enabled, the `gemini` plugin generates zero-logic User Skill pointers into `.gemini/skills/` (e.g. `rnex-clone-sync.md`, `rnex-batch-exec.md`, `rnex-karpathy-llm-wiki-ingest`).
+All AI assistants in Repo Nexus share [`AGENTS.md`](file:///Users/admin/Projects/ai/repo-nexus/AGENTS.md) at the workspace root as the single universal source of truth for routing. When enabled, the `gemini` plugin generates zero-logic User Skill pointers into `.agents/skills/` (e.g. `rnex-clone-sync/SKILL.md`, `rnex-batch-exec/SKILL.md`, `rnex-karpathy-llm-wiki-ingest/SKILL.md`).
 
 Operational skills, rules, and subagents remain cleanly encapsulated within `.rnex/skills/` and active plugin directories (`.rnex/plugins/<plugin-name>/`).
 
@@ -15,12 +15,12 @@ Operational skills, rules, and subagents remain cleanly encapsulated within `.rn
 
 ## Capabilities
 
-1. **Zero-Logic User Skills (`.gemini/skills/rnex-*/SKILL.md`)**:
-   - Generates native `SKILL.md` bundles prefixed with `rnex-` in `.gemini/skills/` with YAML frontmatter for Gemini and Antigravity skill discovery.
+1. **Zero-Logic User Skills (`.agents/skills/rnex-*/SKILL.md`)**:
+   - Generates native `SKILL.md` bundles prefixed with `rnex-` in `.agents/skills/` with YAML frontmatter for Gemini and Antigravity skill discovery.
    - 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 .gemini/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)
     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 `.gemini/skills/rnex-*.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,15 +76,19 @@ When `gemini` is enabled with functional plugins like `karpathy-llm`, it generat
 
 ```text
 my-workspace/
-├── AGENTS.md                          # Universal workspace instructions & routing
-├── GEMINI.md                          # Gemini-specific instructions (if instructions: true)
-├── .gemini/
+├── GEMINI.md                          # Gemini-specific instructions
+├── .agents/
 │   └── skills/                        # Zero-logic User Skill pointers
-│       ├── rnex-clone-sync.md
-│       ├── rnex-batch-exec.md
-│       ├── rnex-workspace-status.md
+│       ├── rnex-clone-sync/
+│       │   └── SKILL.md
+│       ├── rnex-batch-exec/
+│       │   └── SKILL.md
+│       ├── rnex-workspace-status/
+│       │   └── SKILL.md
 │       ├── rnex-karpathy-llm-wiki-ingest/
+│       │   └── SKILL.md
 │       └── rnex-karpathy-llm-wiki-lint/
+│           └── SKILL.md
 ├── .rnex/
 │   ├── skills/                        # Core workspace agentic skills
 │   └── plugins/
@@ -103,6 +107,6 @@ rnex plugin disable gemini
 ```
 
 Repo Nexus automatically performs surgical cleanup:
-- Removes auto-generated user skills under `.gemini/skills/rnex-*.md`.
+- Removes auto-generated user skills under `.agents/skills/rnex-*`.
 - Cleans up managed routing instructions in `GEMINI.md`.
-- Developer-created files under `.gemini/` that do not originate from Repo Nexus are preserved.
+- Developer-created files under `.agents/` or `.gemini/` that do not originate from Repo Nexus are preserved.

package/docs/plugins/index.md

@@ -23,7 +23,7 @@ Active plugins are mirrored into each active member repository under `repos/<nam
 Repo Nexus decouples functional plugins from AI provider plugins:
 - **Core Skills (`toolkit/skills/` $\rightarrow$ `.rnex/skills/`)**: Workspace-level capabilities owned by Repo Nexus core.
 - **Plugin Skills (`toolkit/plugins/<plugin>/skills/` $\rightarrow$ `.rnex/plugins/<plugin>/skills/`)**: Scoped domain skills owned exclusively by individual plugins.
-- **User Skills**: Provider plugins (`copilot`, `claude`, `gemini`, `cursor`, and `windsurf`) project zero-logic user skill pointers into active provider directories using native `SKILL.md` bundles with YAML frontmatter in skill directories (`.github/skills/`, `.claude/skills/`, `.gemini/skills/`) and flat files in rule directories (`.cursor/rules/`, `.windsurf/rules/`), redirecting AI assistants directly to the underlying agentic skills in `.rnex/`.
+- **User Skills**: Provider plugins (`copilot`, `claude`, `gemini`, `cursor`, and `windsurf`) project zero-logic user skill pointers into active provider directories using native `SKILL.md` bundles with YAML frontmatter in skill directories (`.github/skills/`, `.claude/skills/`, `.agents/skills/`) and flat files in rule directories (`.cursor/rules/`, `.windsurf/rules/`), redirecting AI assistants directly to the underlying agentic skills in `.rnex/`.
 
 ### 4. Non-Destructive Delimited Merging
 When plugins update root instruction files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.windsurfrules`), Repo Nexus isolates auto-managed routing between explicit delimiters:
@@ -48,7 +48,7 @@ Developer-authored instructions outside of these delimiters are strictly preserv
 |:---|:---|:---|:---|
 | [`claude`](claude.md) | AI Provider | Anthropic Claude Code & Desktop integration: maintains `CLAUDE.md` and generates user skills in `.claude/skills/`. | [Read Guide](claude.md) |
 | [`cursor`](cursor.md) | AI Provider | Cursor IDE integration: maintains `.cursorrules`, `.cursorignore`, and generates user skills in `.cursor/rules/`. | [Read Guide](cursor.md) |
-| [`gemini`](gemini.md) | AI Provider | Google Gemini CLI & Antigravity IDE integration: maintains `GEMINI.md`, `.geminiignore`, and generates user skills in `.gemini/skills/`. | [Read Guide](gemini.md) |
+| [`gemini`](gemini.md) | AI Provider | Google Gemini CLI & Antigravity IDE integration: maintains `GEMINI.md`, `.geminiignore`, and generates user skills in `.agents/skills/`. | [Read Guide](gemini.md) |
 | [`windsurf`](windsurf.md) | AI Provider | Windsurf IDE integration: maintains `.windsurfrules` and generates user skills in `.windsurf/rules/`. | [Read Guide](windsurf.md) |
 | [`karpathy-llm`](karpathy-llm.md) | Knowledge & Rules | Andrej Karpathy's 4 cardinal principles for coding agents, multi-repo context engineering standards, and autonomous zero-dependency LLM Wiki architecture (`./docs`, `.rnex/wiki`). | [Read Guide](karpathy-llm.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/karpathy-llm.md

@@ -169,7 +169,7 @@ The `karpathy-llm` plugin encapsulates its agentic skills in `.rnex/plugins/karp
 - `wiki-ingest.md`
 - `wiki-lint.md`
 
-During `rnex sync`, its `after_sync.sh` lifecycle hook automatically registers zero-logic User Skill pointers (`rnex-karpathy-llm-wiki-ingest` and `rnex-karpathy-llm-wiki-lint`) across all enabled AI provider directories (`.cursor/rules/`, `.claude/skills/`, `.gemini/skills/`, `.windsurf/rules/`).
+During `rnex sync`, its `after_sync.sh` lifecycle hook automatically registers zero-logic User Skill pointers (`rnex-karpathy-llm-wiki-ingest` and `rnex-karpathy-llm-wiki-lint`) across all enabled AI provider directories (`.cursor/rules/`, `.claude/skills/`, `.agents/skills/`, `.windsurf/rules/`).
 
 When running `rnex plugin disable karpathy-llm`, its `before_plugin_disable.sh` lifecycle hook automatically unregisters the User Skills from all provider directories, while keeping core workspace skills intact.
 

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

@@ -74,7 +74,7 @@ git_hooks: true
 #
 # Built-in plugins:
 #   claude         — Anthropic Claude Code integration: manages CLAUDE.md; generates user skills in .claude/skills/
-#   gemini         — Google Gemini / Antigravity integration: manages GEMINI.md; generates user skills in .gemini/skills/
+#   gemini         — Google Gemini / Antigravity integration: manages GEMINI.md; generates user skills in .agents/skills/
 #   cursor         — Cursor IDE integration: manages .cursorrules & .cursor/rules/; generates user skills in .cursor/rules/
 #   windsurf       — Windsurf IDE integration: manages .windsurfrules; generates user skills in .windsurf/rules/
 #   karpathy-llm   — Andrej Karpathy's agent behavioral principles,
@@ -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 .gemini/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

@@ -405,7 +405,7 @@ get_active_provider_skill_dirs() {
           cursor)   _sdir=".cursor/rules" ;;
           claude)   _sdir=".claude/skills" ;;
           windsurf) _sdir=".windsurf/rules" ;;
-          gemini)   _sdir=".gemini/skills" ;;
+          gemini)   _sdir=".agents/skills" ;;
         esac
       fi
       if [ -n "$_sdir" ]; then
@@ -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/init.sh

@@ -162,8 +162,18 @@ YAML_EOF
     log_ok "Created $RNEX_CONFIG_FILE"
   fi
 
+  # Set active workspace context for initialization
+  _orig_nexus="$NEXUS_DIR"
+  _orig_yaml="$WORKSPACE_YAML"
+  _orig_local_yaml="$WORKSPACE_LOCAL_YAML"
+  NEXUS_DIR="$_init_dir"
+  WORKSPACE_YAML="$_target_yaml"
+  WORKSPACE_LOCAL_YAML="$_init_dir/$RNEX_LOCAL_CONFIG_FILE"
+
   # ---- 2. Merge routing instructions into AI instructions files ------------
-  merge_rnex_instructions "$_init_dir/AGENTS.md"
+  if ! has_active_provider_instructions "$_init_dir"; then
+    merge_rnex_instructions "$_init_dir/AGENTS.md"
+  fi
   [ -f "$_init_dir/CLAUDE.md" ] && merge_rnex_instructions "$_init_dir/CLAUDE.md"
   [ -f "$_init_dir/GEMINI.md" ] && merge_rnex_instructions "$_init_dir/GEMINI.md"
   [ -f "$_init_dir/.cursorrules" ] && merge_rnex_instructions "$_init_dir/.cursorrules"
@@ -178,12 +188,6 @@ YAML_EOF
   # ---- 4. Create internal .rnex directory and sync base assets -------------
   mkdir -p "$_init_dir/.rnex"
   mkdir -p "$_init_dir/.rnex/plugins"
-  _orig_nexus="$NEXUS_DIR"
-  _orig_yaml="$WORKSPACE_YAML"
-  _orig_local_yaml="$WORKSPACE_LOCAL_YAML"
-  NEXUS_DIR="$_init_dir"
-  WORKSPACE_YAML="$_target_yaml"
-  WORKSPACE_LOCAL_YAML="$_init_dir/$RNEX_LOCAL_CONFIG_FILE"
   sync_plugins
   build_ai_instructions "$_init_dir"
   sync_skills

package/lib/commands/plugin.sh

@@ -70,7 +70,7 @@ cmd_plugin_info() {
   [ -z "$_skill_target" ] && case "$_name" in
     copilot)  _skill_target=".github/skills/" ;;
     claude)   _skill_target=".claude/skills/" ;;
-    gemini)   _skill_target=".gemini/skills/" ;;
+    gemini)   _skill_target=".agents/skills/" ;;
     cursor)   _skill_target=".cursor/rules/" ;;
     windsurf) _skill_target=".windsurf/rules/" ;;
   esac

package/lib/commands/status.sh

@@ -142,7 +142,7 @@ cmd_status() {
   fi
   if [ -f "$NEXUS_DIR/AGENTS.md" ]; then
     printf '  %b✓%b %s %b(standard instructions directive)%b\n' "$_G" "$_NC" "AGENTS.md" "$_DIM" "$_NC"
-  else
+  elif ! has_active_provider_instructions "$NEXUS_DIR"; then
     printf '  %b✗%b %s %b(standard instructions directive — MISSING; run "rnex sync" to create)%b\n' "$_R" "$_NC" "AGENTS.md" "$_R" "$_NC"
   fi
   if [ -f "$NEXUS_DIR/CLAUDE.md" ]; then
@@ -187,7 +187,9 @@ cmd_status() {
   if [ -d "$NEXUS_DIR/.windsurf/rules" ] && ls "$NEXUS_DIR/.windsurf/rules"/rnex-*.md >/dev/null 2>&1; then
     printf '  %b✓%b %s %b(Windsurf user skills)%b\n' "$_G" "$_NC" ".windsurf/rules/" "$_DIM" "$_NC"
   fi
-  if [ -d "$NEXUS_DIR/.gemini/skills" ] && { ls "$NEXUS_DIR/.gemini/skills"/rnex-*.md >/dev/null 2>&1 || ls -d "$NEXUS_DIR/.gemini/skills"/rnex-* >/dev/null 2>&1; }; then
+  if [ -d "$NEXUS_DIR/.agents/skills" ] && { ls "$NEXUS_DIR/.agents/skills"/rnex-*.md >/dev/null 2>&1 || ls -d "$NEXUS_DIR/.agents/skills"/rnex-* >/dev/null 2>&1; }; then
+    printf '  %b✓%b %s %b(Gemini user skills)%b\n' "$_G" "$_NC" ".agents/skills/" "$_DIM" "$_NC"
+  elif [ -d "$NEXUS_DIR/.gemini/skills" ] && { ls "$NEXUS_DIR/.gemini/skills"/rnex-*.md >/dev/null 2>&1 || ls -d "$NEXUS_DIR/.gemini/skills"/rnex-* >/dev/null 2>&1; }; then
     printf '  %b✓%b %s %b(Gemini user skills)%b\n' "$_G" "$_NC" ".gemini/skills/" "$_DIM" "$_NC"
   fi
   if [ -d "$NEXUS_DIR/.github/skills" ] && { ls "$NEXUS_DIR/.github/skills"/rnex-*.md >/dev/null 2>&1 || ls -d "$NEXUS_DIR/.github/skills"/rnex-* >/dev/null 2>&1; }; then
@@ -211,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/commands/sync.sh

@@ -78,7 +78,11 @@ cmd_sync() {
   reconcile_gitignore "$NEXUS_DIR"
 
   # 1.2. Reconcile universal workspace instructions in AGENTS.md
-  merge_rnex_instructions "$NEXUS_DIR/AGENTS.md"
+  if has_active_provider_instructions; then
+    clean_rnex_instructions "$NEXUS_DIR/AGENTS.md"
+  else
+    merge_rnex_instructions "$NEXUS_DIR/AGENTS.md"
+  fi
 
   # 1.3. Generate auto-sync script and AI session-start hooks (hardcoded harness)
   _write_auto_sync_script "$NEXUS_DIR"