repo-nexus 0.5.5 → 0.5.7

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`).
@@ -16,6 +28,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Interactive `rnex init` determines and records `git_hooks` preference upfront in new workspaces.
   - Workspace schema migration in `rnex update` and `rnex fix -y` non-destructively inserts `git_hooks` into older configurations.
   - `rnex status` and `rnex hooks status` display configuration state alongside runtime Git hooks status.
+- **Modular GitHub Copilot Plugin & Extensible Provider Sync (`plugins: copilot: ...`)**:
+  - Encapsulated GitHub Copilot integration as a built-in Repo Nexus plugin (`copilot`) located in `toolkit/plugins/copilot/`.
+  - Extensible configuration options per provider under `plugins:` in `rnex.yaml` and `.local.rnex.yaml`:
+    - `prompts: true|false`: Syncs operational prompts into `.github/prompts/*.prompt.md` with YAML frontmatter for VS Code Copilot Chat prompt picker & slash commands.
+    - `skills: true|false`: Syncs agent skills into `.github/skills/<name>/SKILL.md` for Copilot Agent mode & `gh skill`.
+    - `instructions: true|false`: Synthesizes workspace routing and active plugin guidelines into `.github/copilot-instructions.md`, preserving manual user instructions outside `<!-- REPO-NEXUS -->` markers.
+    - `agents: true|false`: Syncs active plugin custom agents into `.github/agents/*.agent.md` and Copilot skills.
+    - `enabled: false`: Allows local machine overrides in `.local.rnex.yaml` without altering team configuration.
+  - Decoupled cross-plugin asset discovery: `copilot` provider inspects all active plugins (e.g. `karpathy-llm`) and mirrors their prompts, workflows, skills, agents, and guidelines without introducing plugin dependencies.
+  - CLI management via `rnex plugin enable [--local] copilot`, `rnex plugin disable [--local] copilot`, and `rnex plugin info copilot`.
+  - Added `--copilot` initialization flag to `rnex init` enabling the plugin in newly generated workspaces.
+  - 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
+- **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**:

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
@@ -215,7 +215,81 @@ rnex plugin enable karpathy-llm
 rnex plugin disable karpathy-llm
 ```
 
-### Built-in Plugin: `karpathy-llm`
+### Built-in Plugins
+
+#### 1. `copilot`
+The `copilot` plugin provides GitHub Copilot integration, automatically mirroring workspace and active plugin assets:
+* **Prompts (`.github/prompts/*.prompt.md`)**: Formatted with YAML frontmatter (`name`, `description`) for the VS Code Copilot Chat prompt picker and slash commands.
+* **Agent Skills (`.github/skills/<name>/SKILL.md`)**: Configured for GitHub Copilot Agent mode and `gh skill`.
+* **Custom Agents (`.github/agents/*.agent.md`)**: Active plugins' agent definitions mirrored for Copilot workspace custom agents.
+* **Instructions (`.github/copilot-instructions.md`)**: Synthesized workspace routing and active plugin guidelines, preserving manual user instructions.
+* **Configurable Options**:
+  ```yaml
+  plugins:
+    copilot:
+      prompts: true        # mirror prompts to .github/prompts/*.prompt.md (default: true)
+      skills: true         # mirror skills to .github/skills/<name>/SKILL.md (default: true)
+      instructions: true   # mirror guidelines to .github/copilot-instructions.md (default: true)
+      agents: true         # mirror custom agents to .github/agents/*.agent.md (default: true)
+  ```
+
+#### 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.
@@ -248,8 +322,13 @@ repos_dir: ./repos
 # Automated workspace Git hooks (default: true)
 git_hooks: true
 
-# Workspace plugins
+# Workspace plugins and tool integrations
 plugins:
+  copilot:
+    prompts: true
+    skills: true
+    instructions: true
+    agents: true
   karpathy-llm: {}
 
 # Member repositories (enabled by default)

package/docs/CLI.md

@@ -68,30 +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/`).
+- `--claude`: Enable Anthropic Claude Code plugin (maintains `CLAUDE.md`, mirrors prompts/skills to `.claude/`).
+- `--gemini`: Enable Google Gemini & Antigravity plugin (maintains `GEMINI.md`, mirrors prompts/skills to `.gemini/`).
+- `--cursor`: Enable Cursor IDE plugin (maintains `.cursorrules` / `.cursor/rules/`, mirrors prompts/skills to `.cursor/`).
+- `--windsurf`: Enable Windsurf IDE plugin (maintains `.windsurfrules`, mirrors prompts/skills 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 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
@@ -144,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.
 
 ---
 
@@ -353,14 +359,14 @@ Unsets `core.hooksPath` in Git configuration, removes `.rnex/hooks/`, and record
 Repo Nexus features a modular plugin architecture where plugin rules, instructions, and templates are scoped strictly under `.rnex/plugins/<plugin-name>/`.
 
 ```sh
-rnex plugin <list|info|enable|disable> [name]
+rnex plugin <list|info|enable|disable> [options] [name]
 ```
 
 ### Subcommands
 - **`rnex plugin list`**: Displays all available plugins distributed with `rnex` and highlights enabled plugins.
-- **`rnex plugin info <name>`**: Shows description, version, scoped directory, and external template paths for a plugin.
-- **`rnex plugin enable <name>`**: Enables a plugin in `rnex.yaml`, copies assets to `.rnex/plugins/<name>/`, and reconciles workspace files.
-- **`rnex plugin disable <name>`**: Removes plugin assets from `.rnex/plugins/<name>/` and disables the plugin in `rnex.yaml`.
+- **`rnex plugin info <name>`**: Shows description, version, configurable options, scoped directory, and external template paths for a plugin.
+- **`rnex plugin enable [--local] <name>`**: Enables a plugin in `rnex.yaml` (or `.local.rnex.yaml` with `--local`), copies assets to `.rnex/plugins/<name>/`, and reconciles workspace files.
+- **`rnex plugin disable [--local] <name>`**: Removes plugin assets from `.rnex/plugins/<name>/` and disables the plugin in `rnex.yaml` (or overrides with `enabled: false` in `.local.rnex.yaml` with `--local`).
 
 ---
 

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
 # ------------------------------------------------------------------------------
@@ -74,21 +61,53 @@ code_workspace: false
 git_hooks: true
 
 # ------------------------------------------------------------------------------
-# plugins — Workspace plugins and AI instruction packs
+# plugins — Workspace plugins, tool integrations, and AI instruction packs
 # ------------------------------------------------------------------------------
 # Plugins extend your workspace with curated AI guidelines, context rules,
-# and scaffolding templates scoped within `.rnex/plugins/<plugin-name>/`.
+# tool provider integrations (e.g. GitHub Copilot), and templates.
 #
 # Manage plugins with:
-#   rnex plugin list              # View available and active plugins
-#   rnex plugin enable <name>     # Enable plugin in workspace
-#   rnex plugin disable <name>    # Disable plugin from workspace
+#   rnex plugin list                 # View available and active plugins
+#   rnex plugin enable [--local] <name>  # Enable plugin (global or local override)
+#   rnex plugin disable [--local] <name> # Disable plugin from workspace
+#   rnex plugin info <name>          # View plugin details & configurable options
 #
 # 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, and skills into .claude/
+#   gemini         — Google Gemini / Antigravity integration: maintains GEMINI.md instructions
+#                    and mirrors prompts and skills into .gemini/
+#   cursor         — Cursor IDE integration: maintains .cursorrules / .cursor/rules/
+#                    and mirrors prompts and skills into .cursor/
+#   windsurf       — Windsurf IDE integration: maintains .windsurfrules
+#                    and mirrors prompts and skills into .windsurf/
 #   karpathy-llm   — Andrej Karpathy's agent behavioral principles,
 #                    context engineering guidelines, and LLM Wiki architecture
 
 plugins:
+  # copilot:
+  #   prompts: true        # mirror prompts to .github/prompts/*.prompt.md (default: true)
+  #   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)
+  # 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)
+  # 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)
+  # 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)
   # karpathy-llm: {}
 
 # ------------------------------------------------------------------------------

package/package.json

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