repo-nexus 0.1.2 → 0.2.5

package/README.md

@@ -7,20 +7,47 @@
 [![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux-lightgrey)](#)
 [![FAQ](https://img.shields.io/badge/docs-FAQ-blue.svg)](docs/FAQ.md)
 
-A tooling-independent, zero-dependency workspace orchestrator for multiple repositories with shared, auto-synced AI context across projects using Unix symlinks.
+A **simple, lightweight companion tool** for multi-repo workflows. It links multiple independent repositories and shares universal AI instructions (like `AGENTS.md`) using standard Unix symlinks — **without Git submodules, monorepo migrations, or complex setup**.
 
-- **No git submodules, subtrees, or nested git friction**
-- **No IDE lock-in** (works across VS Code, Cursor, Antigravity, Claude Code, Zed, terminal agents)
-- **AI provider-agnostic** (shares `AGENTS.md`, Copilot instructions, Cursor rules, and custom prompts)
-- **Automatic AI context injection** on repository registration
-- **Auto-detects existing AI configs** (`CLAUDE.md`, `.cursorrules`, `.windsurfrules`, Copilot instructions, etc.)
-- **Context-aware**: Finds and uses `rnex.yaml` automatically from your current directory or parent tree
-- **Zero dependencies** (pure POSIX shell CLI)
+- **No Git Submodules or Nested Git Friction**: Keep your repositories completely independent. No detached HEADs, no `.gitmodules`, and no merge conflicts between repos.
+- **A Lean Companion, Not a Workspace Replacer**: It does not replace your editor, terminal, build tools, or package manager. It is a tiny (~20 KB) helper that seamlessly complements your existing workflow.
+- **Unified Workspace for AI Coding Assistants**: Open one folder to give Cursor, Claude Code, GitHub Copilot, or Antigravity complete cross-repo visibility.
+- **Single Source of Truth for AI Guidelines**: Share and sync `AGENTS.md`, Copilot instructions (`.github/copilot-instructions.md`), Cursor rules (`.cursorrules`), Claude instructions (`CLAUDE.md`), and custom prompts across all projects.
+- **Zero Dependencies**: Pure POSIX shell CLI (`rnex`). Works out of the box with zero external runtimes required.
+A **simple, lightweight companion tool** for multi-repo workflows. It links multiple independent repositories and shares universal AI instructions (like `AGENTS.md`) using standard Unix symlinks — **without Git submodules, monorepo migrations, or complex setup**.
+
+- **No Git Submodules or Nested Git Friction**: Keep your repositories completely independent. No detached HEADs, no `.gitmodules`, and no merge conflicts between repos.
+- **A Lean Companion, Not a Workspace Replacer**: It does not replace your editor, terminal, build tools, or package manager. It is a tiny (~20 KB) helper that seamlessly complements your existing workflow.
+- **Unified Workspace for AI Coding Assistants**: Open one folder to give Cursor, Claude Code, GitHub Copilot, or Antigravity complete cross-repo visibility.
+- **Single Source of Truth for AI Guidelines**: Share and sync `AGENTS.md`, Copilot instructions (`.github/copilot-instructions.md`), Cursor rules (`.cursorrules`), Claude instructions (`CLAUDE.md`), and custom prompts across all projects.
+- **Zero Dependencies**: Pure POSIX shell CLI (`rnex`). Works out of the box with zero external runtimes required.
 
 > 💡 **Have questions?** Check out the **[Frequently Asked Questions (FAQ)](docs/FAQ.md)** for architecture deep dives, Git workflows, and AI context strategies.
 
 ---
 
+## What Repo Nexus Is (and What It Isn't)
+
+| What It Is | What It Isn't |
+| :--- | :--- |
+| **A lightweight companion utility** (~20 KB POSIX script). | **NOT a replacement for your workspace or tools.** It doesn't replace VS Code, Cursor, JetBrains, or your terminal. |
+| **A simple symlink manager** that groups existing repos into one folder for convenience. | **NOT a build tool or monorepo orchestrator.** It doesn't manage builds or replace tools like Nx, Turborepo, Cargo, or Gradle. |
+| **Zero Git friction.** Repositories remain normal, autonomous Git repos. | **NOT Git submodules or subtrees.** No `.gitmodules` files, no detached HEADs, no commit coordination lock-in. |
+| **Non-invasive.** If you delete the workspace, your repos remain completely untouched. | **NOT a proprietary platform.** No background daemons, no database, no vendor lock-in. |
+
+---
+
+## What Repo Nexus Is (and What It Isn't)
+
+| What It Is | What It Isn't |
+| :--- | :--- |
+| **A lightweight companion utility** (~20 KB POSIX script). | **NOT a replacement for your workspace or tools.** It doesn't replace VS Code, Cursor, JetBrains, or your terminal. |
+| **A simple symlink manager** that groups existing repos into one folder for convenience. | **NOT a build tool or monorepo orchestrator.** It doesn't manage builds or replace tools like Nx, Turborepo, Cargo, or Gradle. |
+| **Zero Git friction.** Repositories remain normal, autonomous Git repos. | **NOT Git submodules or subtrees.** No `.gitmodules` files, no detached HEADs, no commit coordination lock-in. |
+| **Non-invasive.** If you delete the workspace, your repos remain completely untouched. | **NOT a proprietary platform.** No background daemons, no database, no vendor lock-in. |
+
+---
+
 ## How It Works: The Two Symlink Flows
 
 ```
@@ -54,14 +81,19 @@ A tooling-independent, zero-dependency workspace orchestrator for multiple repos
 
 ## Key Principles
 
-1. **Symlink Write-Through**:
-   Symlinks are transparent pointers. When an AI agent or developer edits `repos/backend/src/index.ts`, the OS resolves the link and writes directly to the source repository on disk.
+1. **No Git Submodules (Complete Repository Autonomy)**:
+   Member repositories are never converted into Git submodules or subtrees. Each repository keeps its own standalone Git history, remotes, branches, and commits. `rnex` simply links them on your local filesystem.
+1. **No Git Submodules (Complete Repository Autonomy)**:
+   Member repositories are never converted into Git submodules or subtrees. Each repository keeps its own standalone Git history, remotes, branches, and commits. `rnex` simply links them on your local filesystem.
 
-2. **Autonomous Git Repositories**:
-   Each member repository retains its own Git history, branches, and remotes. Git operations (commit, push, pull) are executed directly inside each member repo.
+2. **Symlink Write-Through**:
+   Symlinks are transparent pointers resolved by your OS. When you or an AI agent edit `repos/backend/src/index.ts`, the OS resolves the link and writes directly to the source repository on disk.
+2. **Symlink Write-Through**:
+   Symlinks are transparent pointers resolved by your OS. When you or an AI agent edit `repos/backend/src/index.ts`, the OS resolves the link and writes directly to the source repository on disk.
 
 3. **Single Source of Truth for AI Context**:
-   Edit `AGENTS.md` in Repo Nexus, and changes immediately reflect across all member repositories.
+   Edit `AGENTS.md` once in Repo Nexus, and changes immediately reflect across all member repositories.
+   Edit `AGENTS.md` once in Repo Nexus, and changes immediately reflect across all member repositories.
 
 4. **Dynamic Workspace Scope**:
    Easily show or hide member repos from the active workspace without modifying disk contents.
@@ -70,27 +102,49 @@ A tooling-independent, zero-dependency workspace orchestrator for multiple repos
 
 ## Installation
 
-You can install `rnex` using either the native zero-dependency installer or via npm:
+Install `rnex` via npm, GitHub Packages, or the zero-dependency native installer:
 
-### Option 1: Native Installer (Zero Dependencies)
+### Option 1: Via npm (Recommended)
 
-Clone the repository and run the built-in installer:
+```bash
+npm install -g repo-nexus
+```
+*(Installs both `repo-nexus` and `rnex` commands globally, or run via `npx repo-nexus init`)*
+
+### Option 2: Via GitHub Packages
 
 ```bash
-git clone https://github.com/nu-nenoi/repo-nexus.git
-cd repo-nexus
-./rnex install
+npm install -g @nu-nenoi/repo-nexus --registry=https://npm.pkg.github.com
 ```
-*(Installs `rnex` and `repo-nexus` symlinks into `~/.local/bin`, or pass a custom directory like `./rnex install /usr/local/bin`)*
+Install `rnex` via npm, GitHub Packages, or the zero-dependency native installer:
 
-### Option 2: Via npm
+### Option 1: Via npm (Recommended)
 
 ```bash
 npm install -g repo-nexus
 ```
-*(Installs both `repo-nexus` and `rnex` executable commands globally)*
+*(Installs both `repo-nexus` and `rnex` commands globally, or run via `npx repo-nexus init`)*
 
-### Option 3: Shell Alias
+### Option 2: Via GitHub Packages
+
+```bash
+npm install -g @nu-nenoi/repo-nexus --registry=https://npm.pkg.github.com
+```
+
+### Option 3: Native Installer (Zero Dependencies)
+### Option 3: Native Installer (Zero Dependencies)
+
+Clone the repository and run the built-in installer:
+
+```bash
+git clone https://github.com/nu-nenoi/repo-nexus.git
+cd repo-nexus
+./rnex install
+```
+*(Installs `rnex` and `repo-nexus` symlinks into `~/.local/bin`, or pass a custom directory like `./rnex install /usr/local/bin`)*
+
+### Option 4: Shell Alias
+### Option 4: Shell Alias
 
 Add to your `~/.zshrc` or `~/.bashrc`:
 ```bash
@@ -146,9 +200,39 @@ rnex remove my-app
 
 ---
 
+## Plugins & AI Context Packs
+
+Repo Nexus features a zero-dependency plugin architecture. Plugins package curated AI instructions, agent behavioral rules, and architecture templates that are automatically synchronized into member repositories via symlinks.
+
+```bash
+# List available and active plugins
+rnex plugin list
+
+# Inspect plugin details and provided files
+rnex plugin info karpathy-llm
+
+# Enable a plugin across your workspace
+rnex plugin enable karpathy-llm
+
+# Disable a plugin and clean up injected files
+rnex plugin disable karpathy-llm
+```
+
+### Built-in Plugin: `karpathy-llm`
+The `karpathy-llm` plugin packages Andrej Karpathy's verified LLM agent design patterns and context engineering principles:
+* **The 4 Cardinal Agent Rules** (`.agents/rules/KARPATHY_RULES.md`):
+  1. *Think Before Coding:* Formulate explicit assumptions, boundary checks, and trade-offs before writing code.
+  2. *Simplicity First:* Minimal abstractions, readable implementations, zero speculative boilerplate.
+  3. *Surgical Changes:* Minimal blast radius, preserved comments/docstrings, and tight diffs.
+  4. *Goal-Driven Execution:* Upfront verification criteria, automated tests, and diff inspection.
+* **Multi-Repo Context Engineering:** Guidelines for AI agents respecting member repo autonomy and symlink write-through semantics.
+* **LLM Wiki Knowledge Pattern** (`docs/LLM_WIKI.sample.md`): Persistent, indexed multi-repo architecture documentation that compounds across agent sessions.
+
+---
+
 ## Workspace Configuration (`rnex.yaml`)
 
-The configuration file defines repo symlink directory, AI context files to sync, and registered repositories:
+The configuration file defines repo symlink directory, AI context files to sync, enabled plugins, and registered repositories:
 
 ```yaml
 # Directory for repository symlinks (relative or absolute)
@@ -161,6 +245,10 @@ ai_files:
   # - .cursorrules
   # - CLAUDE.md
 
+# Workspace plugins
+plugins:
+  - karpathy-llm
+
 # Member repositories
 repos:
   backend:
@@ -193,7 +281,7 @@ repos:
 |:---|:---|
 | `rnex init [dir]` | Initialize a new workspace in current (or target) directory |
 | `rnex install [dir]` | Install `rnex` & `repo-nexus` globally into `~/.local/bin` (or custom dir) |
-| `rnex add <name> <path>` | Register repo, create scope symlink, and auto-inject AI context |
+| `rnex add [-y] <name> <path>` | Register repo, create scope symlink, and sync AI context (prompts to extend existing files) |
 | `rnex remove <name>` | Unregister repo, unlink from scope, and clean up injected AI files |
 | `rnex list` | List all registered repos and visibility scopes |
 | `rnex status` | Display status of AI context files, active member repos, and paths |
@@ -201,6 +289,8 @@ repos:
 | `rnex hide <name>` | Hide a repo from active workspace indexing |
 | `rnex sync` | Reconcile all scope symlinks and AI context files from config |
 
+> **Note on Existing AI Files**: Pre-existing files in member repositories are never overwritten. When adding a new repo, `rnex` prompts whether to update existing files and safely extends them with workspace context between managed markers. Pass `-y` / `--yes` to auto-confirm.
+
 ---
 
 ## Operating on External Workspaces via `--config`

package/docs/FAQ.md

@@ -6,7 +6,10 @@ This document answers common questions about **Repo Nexus (`rnex`)**, why it exi
 
 ## Table of Contents
 
-- [Overview & Value Proposition](#overview--value-proposition)
+- [General Setup & Philosophy](#general-setup--philosophy)
+  - [What is repo-nexus?](#what-is-repo-nexus)
+  - [How does it differ from "monster" monorepo orchestrators?](#how-does-it-differ-from-monster-monorepo-orchestrators)
+  - [Does it require Git Submodules?](#does-it-require-git-submodules)
   - [Why do I need rnex?](#why-do-i-need-rnex)
   - [Who is this useful and interesting for?](#who-is-this-useful-and-interesting-for)
   - [Why not just use a monorepo or Git submodules?](#why-not-just-use-a-monorepo-or-git-submodules)
@@ -16,9 +19,13 @@ This document answers common questions about **Repo Nexus (`rnex`)**, why it exi
   - [Can I use Git commands (pull, push, commit) on symlinked repos?](#can-i-use-git-commands-pull-push-commit-on-symlinked-repos)
   - [Can AI agents create and modify files inside member repos via symlinks?](#can-ai-agents-create-and-modify-files-inside-member-repos-via-symlinks)
   - [Will rnex interfere with Git branches, remotes, or commit histories?](#will-rnex-interfere-with-git-branches-remotes-or-commit-histories)
-- [AI Context Strategy: Workspace vs. Member Repos](#ai-context-strategy-workspace-vs-member-repos)
+- [AI Context & IDE Workspace Integration](#ai-context--ide-workspace-integration)
+  - [How does it optimize workspaces for IDEs?](#how-does-it-optimize-workspaces-for-ides)
+  - [How does it support accurate AI context?](#how-does-it-support-accurate-ai-context)
+  - [What is the risk of tool lock-in?](#what-is-the-risk-of-tool-lock-in)
   - [Do I need rnex to inject symlinks into my member repos?](#do-i-need-rnex-to-inject-symlinks-into-my-member-repos)
   - [How should AI instructions be structured across repos? (Committed files vs. symlinks)](#how-should-ai-instructions-be-structured-across-repos-committed-files-vs-symlinks)
+  - [What happens if a member repository already has an existing AI configuration file?](#what-happens-if-a-member-repository-already-has-an-existing-ai-configuration-file)
   - [Which AI assistants and configuration files are supported?](#which-ai-assistants-and-configuration-files-are-supported)
   - [How do I prevent AI agents from running out of context or token bloat?](#how-do-i-prevent-ai-agents-from-running-out-of-context-or-token-bloat)
 - [Platforms & Setup](#platforms--setup)
@@ -29,7 +36,25 @@ This document answers common questions about **Repo Nexus (`rnex`)**, why it exi
 
 ---
 
-## Overview & Value Proposition
+## General Setup & Philosophy
+
+### What is repo-nexus?
+
+It is a zero-dependency workspace utility designed to treat multiple independent Git repositories as subprojects under a single, unified development workspace.
+
+---
+
+### How does it differ from "monster" monorepo orchestrators?
+
+Unlike heavy, invasive tools that take over your entire terminal workflow, execute automated pipelines, or bundle massive dependency trees, repo-nexus acts strictly as a lightweight, metadata-only layout manager. It does not inject wrapper scripts or run automated build pipelines.
+
+---
+
+### Does it require Git Submodules?
+
+No. It manages the directory mappings internally via configuration files. Your independent Git repositories remain clean, isolated, and completely untouched at the Git history level.
+
+---
 
 ### Why do I need rnex?
 
@@ -107,7 +132,25 @@ The Repo Nexus workspace ignores `repos/` in `.gitignore`, ensuring your workspa
 
 ---
 
-## AI Context Strategy: Workspace vs. Member Repos
+## AI Context & IDE Workspace Integration
+
+### How does it optimize workspaces for IDEs?
+
+By defining your multi-repo structure through repo-nexus, it bridges the gap across decoupled project folders to generate seamless multi-root workspaces for modern code editors.
+
+---
+
+### How does it support accurate AI context?
+
+It serves as an informational metadata layer across repositories. It allows you to synchronize and propagate AI rule parameters, prompt setups, and documentation frameworks (like `.cursorrules`, `AGENTS.md`, or `CLAUDE.md`) globally so that coding assistants see the entire multi-repo architecture as one coherent context.
+
+---
+
+### What is the risk of tool lock-in?
+
+Zero. Because repo-nexus only overlays structural configuration metadata rather than refactoring your code, removing it from your stack is as simple as deleting its single config file. Your codebases remain independent and functional.
+
+---
 
 ### Do I need rnex to inject symlinks into my member repos?
 
@@ -138,6 +181,16 @@ The cleanest architecture separates concerns into two distinct layers:
 
 ---
 
+### What happens if a member repository already has an existing AI configuration file?
+
+`rnex` will **never replace or overwrite** existing AI files in a member repository.
+
+When you run `rnex add <name> <path>`, `rnex` detects any pre-existing AI context files (such as `AGENTS.md` or `.cursorrules`) and prompts you whether to update them. If confirmed, `rnex` **extends** the existing file by appending the workspace context enclosed within clearly demarcated markers (`# --- REPO-NEXUS AI CONTEXT ---`).
+
+This preserves all repository-specific rules while layering universal workspace guidelines on top. Subsequent `rnex sync` calls keep the extended block synchronized without duplicating content or modifying the repository's custom instructions. Pass `-y` / `--yes` to `rnex add` to auto-confirm updating existing files.
+
+---
+
 ### Which AI assistants and configuration files are supported?
 
 `rnex` is tool-agnostic and auto-detects or syncs standard configuration files for:

package/docs/rnex.example.yaml

@@ -22,9 +22,11 @@ repos_dir: ./repos
 # ------------------------------------------------------------------------------
 # ai_files — AI context files to auto-sync into member repositories
 # ------------------------------------------------------------------------------
-# Each file listed here is symlinked from the workspace root into every
-# registered member repository. This keeps AI instructions consistent
-# across all your projects.
+# Each file listed here is synced from the workspace root into every
+# registered member repository. If a member repository already contains an
+# existing file, it is extended (never replaced) with workspace context.
+# When adding a new repository, rnex prompts whether to update existing files.
+# This keeps AI instructions consistent across all your projects.
 #
 # Paths are relative to the workspace root (where this config file lives).
 # Both files and directories are supported.
@@ -53,6 +55,27 @@ ai_files:
   # - CONVENTIONS.md
   # - toolkit/prompts/review-checklist.md
 
+# ------------------------------------------------------------------------------
+# plugins — Workspace plugins and AI instruction packs
+# ------------------------------------------------------------------------------
+# Plugins extend your workspace with curated AI guidelines, context rules,
+# and scaffolding templates. When enabled, plugin context files are automatically
+# synchronized into all registered member repositories during `rnex sync`.
+#
+# Manage plugins with:
+#   rnex plugin list              # View available and active plugins
+#   rnex plugin enable <name>     # Enable and sync into member repos
+#   rnex plugin disable <name>    # Disable and clean up
+#
+# Built-in plugins:
+#   karpathy-llm   — Andrej Karpathy's agent behavioral principles,
+#                    multi-repo context engineering, and LLM Wiki pattern
+#
+# Local / custom plugins can also be placed in .nexus/plugins/<name>/
+
+plugins:
+  # - karpathy-llm
+
 # ------------------------------------------------------------------------------
 # repos — Member repositories managed by Repo Nexus
 # ------------------------------------------------------------------------------

package/package.json

@@ -1,16 +1,21 @@
 {
   "name": "repo-nexus",
-  "version": "0.1.2",
-  "description": "Tooling-independent multi-repo workspace manager with auto-synced AI context via symlinks",
+  "version": "0.2.5",
+  "description": "Lightweight, zero-dependency companion tool for multi-repo workspaces and shared AI context via symlinks (no git submodules)",
   "bin": {
-    "repo-nexus": "./rnex",
-    "rnex": "./rnex"
+    "repo-nexus": "rnex",
+    "rnex": "rnex"
+  },
+  "scripts": {
+    "prepare": "git config core.hooksPath .githooks 2>/dev/null || true",
+    "test": "./tests/test_cli.sh"
   },
   "files": [
     "rnex",
     "README.md",
     "LICENSE",
-    "docs/"
+    "docs/",
+    "toolkit/"
   ],
   "repository": {
     "type": "git",
@@ -21,18 +26,29 @@
   },
   "homepage": "https://github.com/nu-nenoi/repo-nexus#readme",
   "keywords": [
-    "repo",
-    "repository",
-    "workspace",
+    "rnex",
+    "repo-nexus",
+    "rnex",
+    "repo-nexus",
     "multi-repo",
     "monorepo",
-    "symlink",
-    "ai-context",
-    "cli",
-    "agents",
+    "ai-agents",
+    "agents.md",
+    "cursor-rules",
+    "claude-code",
+    "ai-agents",
+    "agents.md",
+    "cursor-rules",
+    "claude-code",
     "copilot",
     "cursor",
-    "developer-tools"
+    "plugins",
+    "karpathy",
+    "context-engineering",
+    "symlink",
+    "workspace",
+    "developer-tools",
+    "cli"
   ],
   "license": "MIT",
   "author": "Anton Shramkov",
@@ -43,4 +59,4 @@
     "darwin",
     "linux"
   ]
-}
+}