repo-nexus 0.5.6 → 0.5.8

package/CHANGELOG.md

@@ -8,6 +8,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **AI Provider Plugins for Claude, Gemini, Cursor, and Windsurf**:
+  - Built-in provider plugins (`toolkit/plugins/claude/`, `toolkit/plugins/gemini/`, `toolkit/plugins/cursor/`, `toolkit/plugins/windsurf/`) alongside `copilot`.
+  - Native instructions synthesis and sync for each provider: `CLAUDE.md`, `GEMINI.md`, `.cursorrules` (and `.cursor/rules/repo-nexus.mdc`), and `.windsurfrules`.
+  - Standardized prompt mirroring to `.claude/commands/`, `.gemini/prompts/`, `.cursor/prompts/`, and `.windsurf/prompts/`.
+  - Skill mirroring to `.claude/skills/`, `.gemini/skills/`, `.cursor/skills/`, and `.windsurf/skills/`.
+  - Granular configuration options per plugin (`instructions: true|false`, `prompts: true|false`, `skills: true|false`).
+  - Added `--claude`, `--gemini`, `--cursor`, and `--windsurf` initialization flags to `rnex init`.
+  - Diagnostics and configurable provider options displayed in `rnex status`.
+- **Unified Single-Process Workspace Reconcile & Upgrade (`rnex fix`)**:
+  - Merged configuration version updates directly into `rnex fix` as a single, idempotent process.
+  - Automatically migrates older workspace manifests to the current CLI version on `rnex fix` without requiring separate update commands.
+  - `rnex update` and `rnex upgrade` are maintained as clean aliases pointing directly to `rnex fix`.
 - **Explicit `git_hooks` Workspace Configuration (`rnex.yaml` & `.local.rnex.yaml`)**:
   - Top-level `git_hooks: true|false` setting establishes the workspace configuration as the single source of truth for automated Git hooks.
   - Two-level configuration support allowing per-workstation overrides in `.local.rnex.yaml` (e.g. keeping hooks globally enabled in `rnex.yaml` while disabling locally via `rnex hooks uninstall --local`).
@@ -30,6 +42,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Clean reconciliation in `rnex fix`: safely removes `.github/prompts/`, `.github/skills/`, `.github/agents/`, and `.github/copilot-instructions.md` when disabled or when specific target options are toggled off.
   - Diagnostics and configurable options reporting integrated into `rnex status`.
 
+### Changed
+- **Removed `ai_instructions` Configuration in Favor of AI Provider Plugins**:
+  - Removed the legacy `ai_instructions` configuration key. `AGENTS.md` is now the workspace standard.
+  - Users choosing provider-specific files (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.windsurfrules`) enable the respective AI provider plugin (`claude`, `gemini`, `cursor`, `windsurf`).
+  - When an AI provider plugin is enabled, `rnex fix` does not enforce or force-recreate `AGENTS.md`. If all provider plugins are disabled, `AGENTS.md` is cleanly restored as the fallback default.
+  - Older configurations specifying `ai_instructions: CLAUDE.md | GEMINI.md | .cursorrules` are automatically migrated to enable the respective plugin and stripped of the legacy key during `rnex fix`.
+
+### Fixed
+- **Surgical Non-Destructive Cleanup of Skills, Agents, and Prompts**:
+  - Replaced destructive `rm -rf` on `.github/skills`, `.github/agents`, and provider directories with targeted cleanup (`clean_provider_skills`, `clean_provider_prompts`, `clean_copilot_agents`).
+  - Only Repo Nexus base prompts (`rnex-*`) and active plugin-generated skills/agents/prompts are removed during disable or reconciliation.
+  - User-authored custom skills in `.github/skills/`, custom agents in `.github/agents/`, and custom prompts are now safely preserved regardless of whether a provider plugin is enabled or disabled.
+- **Variable Shadowing and Directory Creation in Hook / Init Synchronization**:
+  - Fixed variable name shadowing (`_target_dir`) across `cmd_init` and provider sync routines in POSIX shell.
+  - Ensured target directories are created before moving temporary hook files in `_create_hook_script`.
+
 ### Fixed
 - **Git Hooks Self-Rewrite & Wrapper Preservation**:
   - Resolved self-rewrite bug where `rnex hooks run post-merge` invoked `cmd_fix`, which truncated and replaced `.rnex/hooks/post-merge` while the shell interpreter was actively executing it.

package/README.md

@@ -188,7 +188,7 @@ rnex list
 # Inspect workspace health, active repos, and plugin status
 rnex status
 
-# Reconcile workspace, plugins, and member .rnex/ directories (alias: sync)
+# Reconcile workspace, sync plugins, and upgrade config in a single pass (aliases: sync, update, upgrade)
 rnex fix
 
 # Unregister and delete a repository
@@ -233,7 +233,63 @@ The `copilot` plugin provides GitHub Copilot integration, automatically mirrorin
       agents: true         # mirror custom agents to .github/agents/*.agent.md (default: true)
   ```
 
-#### 2. `karpathy-llm`
+#### 2. `claude`
+The `claude` plugin integrates Anthropic's Claude Code and Claude CLI:
+* **Instructions (`CLAUDE.md`)**: Manages the root `CLAUDE.md` routing context, replacing `AGENTS.md`.
+* **Slash Commands (`.claude/commands/*.md`)**: Standardized commands (`/rnex-cross-repo-feature`, etc.) for Claude Code.
+* **Agent Skills (`.claude/skills/<name>/SKILL.md`)**: Mirrored tool skills and workflows.
+* **Configurable Options**:
+  ```yaml
+  plugins:
+    claude:
+      instructions: true   # maintain CLAUDE.md (default: true)
+      prompts: true        # mirror slash commands to .claude/commands/ (default: true)
+      skills: true         # mirror skills to .claude/skills/ (default: true)
+  ```
+
+#### 3. `gemini`
+The `gemini` plugin integrates Google Gemini CLI and Gemini Code Assist:
+* **Instructions (`GEMINI.md`)**: Manages root `GEMINI.md` context, replacing `AGENTS.md`.
+* **Prompts (`.gemini/prompts/*.prompt.md`)**: Standardized prompts formatted with YAML frontmatter.
+* **Skills (`.gemini/skills/<name>/SKILL.md`)**: Mirrored tool skills for Gemini agents.
+* **Configurable Options**:
+  ```yaml
+  plugins:
+    gemini:
+      instructions: true   # maintain GEMINI.md (default: true)
+      prompts: true        # mirror prompts to .gemini/prompts/ (default: true)
+      skills: true         # mirror skills to .gemini/skills/ (default: true)
+  ```
+
+#### 4. `cursor`
+The `cursor` plugin integrates the Cursor IDE:
+* **Instructions (`.cursorrules` & `.cursor/rules/repo-nexus.mdc`)**: Synchronizes project routing rules.
+* **Prompts (`.cursor/prompts/*.md`)**: Mirrored prompt files.
+* **Skills (`.cursor/skills/<name>/SKILL.md`)**: Mirrored agent skills.
+* **Configurable Options**:
+  ```yaml
+  plugins:
+    cursor:
+      instructions: true   # maintain .cursorrules and MDC rule (default: true)
+      prompts: true        # mirror prompts to .cursor/prompts/ (default: true)
+      skills: true         # mirror skills to .cursor/skills/ (default: true)
+  ```
+
+#### 5. `windsurf`
+The `windsurf` plugin integrates the Codeium Windsurf IDE:
+* **Instructions (`.windsurfrules`)**: Synchronizes project routing rules.
+* **Prompts (`.windsurf/prompts/*.md`)**: Mirrored prompt files.
+* **Skills (`.windsurf/skills/<name>/SKILL.md`)**: Mirrored agent skills.
+* **Configurable Options**:
+  ```yaml
+  plugins:
+    windsurf:
+      instructions: true   # maintain .windsurfrules (default: true)
+      prompts: true        # mirror prompts to .windsurf/prompts/ (default: true)
+      skills: true         # mirror skills to .windsurf/skills/ (default: true)
+  ```
+
+#### 6. `karpathy-llm`
 The `karpathy-llm` plugin packages Andrej Karpathy's verified LLM agent design patterns, context engineering principles, and the autonomous **Karpathy LLM Wiki** architecture:
 * **The 4 Cardinal Agent Rules** (`.rnex/plugins/karpathy-llm/rules/behavioral.md`):
   1. *Think Before Coding:* Formulate explicit assumptions, boundary checks, and trade-offs before writing code.

package/docs/CLI.md

@@ -68,33 +68,35 @@ rnex init [options] [directory]
 #### Arguments & Options
 - `directory` *(optional)*: Target directory to initialize. Defaults to current working directory (`$PWD`).
 - `-y`, `--yes`: Non-interactive mode. Accepts all defaults automatically without prompting.
-- `--ai <filename>`, `--instructions <filename>`: Name of the primary AI instructions file (e.g. `CLAUDE.md`, `GEMINI.md`, `.cursorrules`). Default: `AGENTS.md`.
 - `--code-workspace [filename]`: Enable VS Code / Cursor multi-root workspace file generation. Defaults to `<directory-name>.code-workspace` if omitted.
 - `--hooks`: Force-enable automated Git hooks setup during initialization.
 - `--no-hooks`: Skip Git hooks configuration during initialization.
 - `--copilot`: Enable GitHub Copilot integration plugin (mirrors prompts, skills, agents, and instructions to `.github/`).
-- `--no-copilot`: Skip GitHub Copilot plugin (default).
+- `--claude`: Enable Anthropic Claude Code plugin (maintains `CLAUDE.md`, mirrors prompts/skills/agents to `.claude/`).
+- `--gemini`: Enable Google Gemini & Antigravity plugin (maintains `GEMINI.md`, mirrors prompts/skills/agents to `.gemini/`).
+- `--cursor`: Enable Cursor IDE plugin (maintains `.cursorrules` / `.cursor/rules/`, mirrors prompts/skills/agents to `.cursor/`).
+- `--windsurf`: Enable Windsurf IDE plugin (maintains `.windsurfrules`, mirrors prompts/skills/agents to `.windsurf/`).
 
 #### What it does:
 1. Creates `rnex.yaml` with schema versioning (`version: <version>`), `repos_dir: ./repos`, and configured defaults.
-2. Merges Repo Nexus routing instructions (`<!-- REPO-NEXUS:START -->` ... `<!-- REPO-NEXUS:END -->`) into the target AI instructions file.
+2. Merges Repo Nexus routing instructions (`<!-- REPO-NEXUS:START -->` ... `<!-- REPO-NEXUS:END -->`) into `AGENTS.md` (or the respective provider file if a provider plugin flag was specified).
 3. Creates `./repos/` directory with a tracked `.gitkeep`.
 4. Creates `.rnex/`, `.rnex/plugins/`, and copies standardized prompts to `.rnex/prompts/`.
 5. Reconciles `.gitignore` to ensure `repos/` and `.local.rnex.yaml` are never tracked by the meta-repo (while keeping `.rnex/` tracked).
 6. Generates a multi-root `.code-workspace` file if configured.
 7. Prompts to configure automated workspace Git hooks (`core.hooksPath = .rnex/hooks`) if inside a Git repository.
-8. Configures enabled plugins (including `copilot` if requested).
+8. Configures and syncs enabled plugins.
 
 #### Examples:
 ```sh
-# Initialize in current directory with interactive prompts
+# Initialize in current directory with interactive prompts (creates AGENTS.md)
 rnex init
 
 # Non-interactive initialization for CI or automated setup
 rnex init -y
 
-# Initialize for Anthropic Claude Code with automated Git hooks
-rnex init -y --ai CLAUDE.md --hooks
+# Initialize for Anthropic Claude Code with automated Git hooks (creates CLAUDE.md)
+rnex init -y --claude --hooks
 
 # Initialize with VS Code multi-root workspace support
 rnex init --code-workspace my-team.code-workspace
@@ -147,15 +149,16 @@ rnex fix [options]
 
 ### `rnex update` (alias: `upgrade`)
 
-Safely updates an existing workspace's configuration schema and routing instructions to match the currently installed CLI version.
+Safely updates an existing workspace's configuration schema and routing instructions to match the currently installed CLI version as part of the unified `rnex fix` reconciliation process.
 
 ```sh
 rnex update [-y]
 ```
 
 - Compares `version:` in `rnex.yaml` with the running `rnex` CLI version.
-- Non-destructively updates the `version:` key and inserts newly introduced schema keys (`ai_instructions`, `code_workspace`) while strictly preserving existing comments, indentation, and repository declarations.
-- Reconciles AI instructions in `AGENTS.md` / `CLAUDE.md` to the newest standard.
+- Non-destructively upgrades the configuration schema and inserts newly introduced keys while strictly preserving existing comments, indentation, and repository declarations.
+- Reconciles AI instructions, active provider plugins, and workspace routing in a single execution.
+- `rnex update` and `rnex upgrade` are aliases that invoke the unified `rnex fix` workflow.
 
 ---
 

package/docs/rnex.example.yaml

@@ -31,19 +31,6 @@ version: 0.5.0
 
 repos_dir: ./repos
 
-# ------------------------------------------------------------------------------
-# ai_instructions — Main AI instructions routing file
-# ------------------------------------------------------------------------------
-# Main instructions file created and managed by Repo Nexus.
-# Default: AGENTS.md (recognized by modern AI coding assistants)
-#
-# Examples:
-#   ai_instructions: AGENTS.md     # default standard
-#   ai_instructions: CLAUDE.md     # for Anthropic Claude Code CLI
-#   ai_instructions: GEMINI.md     # for Google Gemini / Antigravity CLI
-#
-ai_instructions: AGENTS.md
-
 # ------------------------------------------------------------------------------
 # code_workspace — VS Code / Cursor multi-root workspace file
 # ------------------------------------------------------------------------------
@@ -88,6 +75,14 @@ git_hooks: true
 # Built-in plugins:
 #   copilot        — GitHub Copilot integration: mirrors operational prompts, skills,
 #                    agents, and synthesized instructions into .github/
+#   claude         — Anthropic Claude Code integration: maintains CLAUDE.md instructions
+#                    and mirrors commands, prompts, skills, and agents into .claude/
+#   gemini         — Google Gemini / Antigravity integration: maintains GEMINI.md instructions
+#                    and mirrors prompts, skills, and agents into .gemini/
+#   cursor         — Cursor IDE integration: maintains .cursorrules / .cursor/rules/
+#                    and mirrors prompts, skills, and agents into .cursor/
+#   windsurf       — Windsurf IDE integration: maintains .windsurfrules
+#                    and mirrors prompts, skills, and agents into .windsurf/
 #   karpathy-llm   — Andrej Karpathy's agent behavioral principles,
 #                    context engineering guidelines, and LLM Wiki architecture
 
@@ -97,6 +92,26 @@ plugins:
   #   skills: true         # mirror skills to .github/skills/<name>/SKILL.md (default: true)
   #   instructions: true   # mirror instructions to .github/copilot-instructions.md (default: true)
   #   agents: true         # mirror custom agents to .github/agents/*.agent.md (default: true)
+  # claude:
+  #   instructions: true   # maintain routing in CLAUDE.md (default: true)
+  #   prompts: true        # mirror commands & prompts to .claude/commands/ (default: true)
+  #   skills: true         # mirror skills to .claude/skills/ (default: true)
+  #   agents: true         # mirror custom agents to .claude/agents/ (default: true)
+  # gemini:
+  #   instructions: true   # maintain routing in GEMINI.md (default: true)
+  #   prompts: true        # mirror prompts to .gemini/prompts/ (default: true)
+  #   skills: true         # mirror skills to .gemini/skills/ (default: true)
+  #   agents: true         # mirror custom agents to .gemini/agents/ (default: true)
+  # cursor:
+  #   instructions: true   # maintain routing in .cursorrules & .cursor/rules/ (default: true)
+  #   prompts: true        # mirror prompts to .cursor/prompts/ (default: true)
+  #   skills: true         # mirror skills to .cursor/skills/ (default: true)
+  #   agents: true         # mirror custom agents to .cursor/agents/ (default: true)
+  # windsurf:
+  #   instructions: true   # maintain routing in .windsurfrules (default: true)
+  #   prompts: true        # mirror prompts to .windsurf/prompts/ (default: true)
+  #   skills: true         # mirror skills to .windsurf/skills/ (default: true)
+  #   agents: true         # mirror custom agents to .windsurf/agents/ (default: true)
   # karpathy-llm: {}
 
 # ------------------------------------------------------------------------------

package/package.json

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