repo-nexus 0.4.2 → 0.4.3

package/README.md

@@ -213,7 +213,7 @@ rnex plugin disable karpathy-llm
 
 ### Built-in Plugin: `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/KARPATHY_RULES.md`):
+* **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.
   2. *Simplicity First:* Minimal abstractions, readable implementations, zero speculative boilerplate.
   3. *Surgical Changes:* Minimal blast radius, preserved comments/docstrings, and tight diffs.

package/package.json

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

package/toolkit/plugins/karpathy-llm/README.md

@@ -10,16 +10,16 @@ Reference specification: [setup-karpathy-wiki.md](https://github.com/nu-nenoi/ai
 
 ## What It Provides
 
-### 1. The 4 Cardinal Principles for Coding Agents (`rules/KARPATHY_RULES.md`)
+### 1. The 4 Cardinal Principles for Coding Agents (`rules/behavioral.md`)
 * **Think Before Coding:** Explicit assumptions, problem formulation, and trade-off evaluation before writing code.
 * **Simplicity First:** Minimal abstractions, readable implementations, and zero boilerplate bloat.
 * **Surgical Changes:** Minimal blast radius, preserved comments/docstrings, and tightly focused diffs.
 * **Goal-Driven Execution:** Upfront verification criteria, automated tests, and rigorous diff review.
 
-### 2. Multi-Repo Context Engineering & Autonomy
+### 2. Multi-Repo Context Engineering & Autonomy (`rules/behavioral.md`)
 * Guidelines tailored for Repo Nexus workspaces respecting member repository autonomy and physical repository boundaries.
 
-### 3. Complete Karpathy LLM Wiki Architecture
+### 3. Complete Karpathy LLM Wiki Architecture (`instructions/wiki-architecture.md`)
 * **`/raw/` Intake Directory:** Append-only directory where unmodified source material (articles, transcripts, docs, meeting notes) is deposited. Includes `.gitkeep`.
 * **`/wiki/` Curated Knowledge Base:** Interlinked atomic markdown pages, each with typed frontmatter relations (`sources`, `related`, `extends`, `contradicts`, `mentioned_in`).
 * **`/wiki/index.md` Navigation Index:** Master categorized catalog organizing atomic concepts, architecture decisions, and cross-project knowledge.
@@ -37,7 +37,7 @@ Reference specification: [setup-karpathy-wiki.md](https://github.com/nu-nenoi/ai
 When an AI agent or developer sets up the Karpathy LLM Wiki in a repository or workspace, consult the Step 0 configuration questions:
 
 1. **[Q1] Which AI agent instruction file should the wiki rules be written to?**
-   - In a **Repo Nexus workspace**: Instructions are maintained in separate instructions files (`.rnex/instructions/karpathy-llm.md` and `.rnex/rules/KARPATHY_RULES.md`). Agents read `rnex.yaml` to detect enabled plugins and read their dedicated instructions files automatically.
+   - In a **Repo Nexus workspace**: Instructions are scoped under `.rnex/plugins/karpathy-llm/` (`rules/behavioral.md` and `instructions/wiki-architecture.md`). Agents read `rnex.yaml` to detect enabled plugins and route context automatically.
    - In a **standalone setup** (outside Repo Nexus):
      - `AGENTS.md` (universal, works across most harnesses)
      - `CLAUDE.md` (Claude Code / Anthropic)
@@ -82,9 +82,9 @@ my-workspace/
 │   └── plugins/
 │       └── karpathy-llm/
 │           ├── instructions/
-│           │   └── karpathy-llm.md  # Dedicated plugin instructions
+│           │   └── wiki-architecture.md# LLM Wiki architecture & relation schema
 │           ├── rules/
-│           │   └── KARPATHY_RULES.md# Cardinal principles & wiki rules
+│           │   └── behavioral.md    # Cardinal principles & context engineering
 │           ├── workflows/
 │           │   ├── wiki-ingest.md   # 8-step decomposition & ingestion workflow
 │           │   └── wiki-lint.md     # 10-step graph validation & maintenance workflow
@@ -107,7 +107,7 @@ rnex plugin enable karpathy-llm
 This command:
 1. Adds `karpathy-llm` to `plugins:` in `rnex.yaml`.
 2. Copies initial templates (`wiki/index.md`, `wiki/_log.md`, `wiki/hot.md`, `raw/.gitkeep`, `.rnex/templates/wiki-page.template.md`, `.rnex/templates/LLM_WIKI.sample.md`).
-3. Links `KARPATHY_RULES.md` and workflows into `.rnex/rules/` and `.rnex/workflows/`.
+3. Scopes `rules/`, `instructions/`, and `workflows/` into `.rnex/plugins/karpathy-llm/`.
 4. Syncs scope links and AI context files across all registered member repositories via `rnex fix`.
 
 ### Option 2: Declarative in `rnex.yaml`

package/toolkit/plugins/karpathy-llm/instructions/wiki-architecture.md

@@ -0,0 +1,43 @@
+# Karpathy LLM Wiki Knowledge Architecture
+
+> "A persistent, compounding knowledge base optimized for AI agents." — Andrej Karpathy
+
+This instruction document defines the operational rules, intake lifecycle, and typed relation schema for the Karpathy LLM Wiki (`/wiki/` and `/raw/` directories).
+
+---
+
+## 1. Operating Rules
+
+When working in a workspace with an active Karpathy LLM Wiki:
+
+- **Intake**: All source material (articles, transcripts, docs, notes) goes to `/raw/` unmodified. Never write directly to `/wiki/` without ingesting.
+- **Orientation**: Before answering domain questions, read `/wiki/index.md` to find relevant pages, then read only those pages. If `hot.md` exists, read it first as a quick-orient step.
+- **Ingestion**: When files appear in `/raw/`, run the `wiki-ingest` workflow (`.rnex/plugins/karpathy-llm/workflows/wiki-ingest.md`). One source document typically produces many atomic pages (commonly 5–25 pages) — do not collapse a source into a single file.
+- **Maintenance**: Run the `wiki-lint` workflow (`.rnex/plugins/karpathy-llm/workflows/wiki-lint.md`) to validate paths, update `mentioned_in`, and preserve graph integrity.
+
+---
+
+## 2. Typed Frontmatter Relation Schema
+
+Every page in `/wiki/` must maintain typed frontmatter relations:
+
+```yaml
+---
+title: ""
+tags: []
+last_updated: YYYY-MM-DD
+# Typed relation fields — paths relative to /wiki/
+sources: []          # /raw/ files this page was derived from
+related: []          # thematically related wiki pages
+extends: []          # pages this one builds upon or specialises
+contradicts: []      # pages with conflicting information
+mentioned_in: []     # pages that link to this one (maintained by lint)
+---
+```
+
+**Body Structure:**
+- Concise summary of the concept.
+- Key facts, definitions, or insights.
+- Inline standard Markdown links (`[Label](./path.md)`) where contextually useful in prose.
+
+The relation graph lives in frontmatter, not in prose links. Agents traverse the graph by reading frontmatter fields, not by scanning body text.

package/toolkit/plugins/karpathy-llm/plugin.yaml

@@ -1,14 +1,14 @@
 name: karpathy-llm
-version: 0.4.0
+version: 0.4.1
 description: Andrej Karpathy's agent behavioral principles, context engineering guidelines, and autonomous LLM Wiki knowledge architecture
 author: nu-nenoi
 homepage: https://github.com/nu-nenoi/repo-nexus
 rules:
-  - rules/KARPATHY_RULES.md: .rnex/plugins/karpathy-llm/rules/KARPATHY_RULES.md
+  - rules/behavioral.md: .rnex/plugins/karpathy-llm/rules/behavioral.md
   - workflows/wiki-ingest.md: .rnex/plugins/karpathy-llm/workflows/wiki-ingest.md
   - workflows/wiki-lint.md: .rnex/plugins/karpathy-llm/workflows/wiki-lint.md
 instructions:
-  - instructions/karpathy-llm.md: .rnex/plugins/karpathy-llm/instructions/karpathy-llm.md
+  - instructions/wiki-architecture.md: .rnex/plugins/karpathy-llm/instructions/wiki-architecture.md
 templates:
   - templates/index.md: wiki/index.md
   - templates/_log.md: wiki/_log.md

package/toolkit/plugins/karpathy-llm/rules/{KARPATHY_RULES.md → behavioral.md}

@@ -1,8 +1,8 @@
-# Karpathy LLM Agent Guidelines & Behavioral Principles
+# Karpathy Coding Agent Behavioral Principles
 
 > "The delicate art and science of context engineering: filling the context window with just the right information for the next step." — Andrej Karpathy
 
-These guidelines provide standing operational instructions for AI coding assistants (Cursor, Claude Code, GitHub Copilot, Antigravity, Windsurf) working within multi-repository environments and managing Karpathy LLM Wiki knowledge bases.
+These rules define standing behavioral principles for AI coding assistants (Cursor, Claude Code, GitHub Copilot, Antigravity, Windsurf) working in this workspace.
 
 ---
 
@@ -45,38 +45,3 @@ In a Repo Nexus workspace, independent repositories are organized into `./repos/
 3. **Context Economy:**
    - Do not redundantly read entire files or directory trees when targeted symbol lookups or line ranges suffice.
    - Rely on active workspace context, indexing, and compiled documentation rather than re-scanning raw files repeatedly.
-
----
-
-## 3. Karpathy Wiki Rules
-
-When working in a repository with an active Karpathy LLM Wiki (`/wiki/` and `/raw/` directories):
-
-- **Intake**: All source material (articles, transcripts, docs, notes) goes to `/raw/` unmodified. Never write directly to `/wiki/` without ingesting.
-- **Orientation**: Before answering domain questions, read `/wiki/index.md` to find relevant pages, then read only those pages. If `hot.md` exists, read it first as a quick-orient step.
-- **Ingestion**: When files appear in `/raw/`, run the `wiki-ingest` workflow (`.rnex/workflows/wiki-ingest.md`). One source document typically produces many atomic pages (commonly 5–25 pages) — do not collapse a source into a single file.
-- **Maintenance**: Run the `wiki-lint` workflow (`.rnex/workflows/wiki-lint.md`) to validate paths, update `mentioned_in`, and preserve graph integrity.
-
----
-
-## 4. Typed Frontmatter Relation Schema
-
-Every page in `/wiki/` must maintain typed frontmatter relations:
-
-```yaml
----
-title: ""
-tags: []
-last_updated: YYYY-MM-DD
-# Typed relation fields — paths relative to /wiki/
-sources: []          # /raw/ files this page was derived from
-related: []          # thematically related wiki pages
-extends: []          # pages this one builds upon or specialises
-contradicts: []      # pages with conflicting information
-mentioned_in: []     # pages that link to this one (maintained by lint)
----
-```
-
-**Body:** concise summary, key facts or insights, and inline standard Markdown links (`[Label](./path.md)`) where contextually useful in prose.
-
-The relation graph lives in frontmatter, not in prose links. Agents traverse the graph by reading frontmatter fields, not by scanning body text.

package/toolkit/plugins/karpathy-llm/templates/LLM_WIKI.sample.md

@@ -37,7 +37,7 @@
 ### ADR-001: Independent Git Repositories over Monorepo
 * **Date:** YYYY-MM-DD
 * **Decision:** Keep repositories completely independent without Git submodules. Orchestrate via Repo Nexus Virtual Meta-Repo.
-* **Consequences:** Autonomous CI/CD per repo; AI assistants maintain shared context via `AGENTS.md` and `KARPATHY_RULES.md`.
+* **Consequences:** Autonomous CI/CD per repo; AI assistants maintain shared context via `AGENTS.md` and `behavioral.md`.
 
 ---
 

package/toolkit/prompts/setup-karpathy-wiki.md

@@ -17,7 +17,7 @@ Do not hard-code any specific AI tool or harness into the wiki structure itself.
 Ask ALL of the following questions and wait for answers:
 
 [Q1] Which AI agent instruction file should the wiki rules be written to?
-  - In a Repo Nexus workspace: plugin instructions are maintained in separate instructions files (`.rnex/instructions/karpathy-llm.md` and `.rnex/rules/KARPATHY_RULES.md`). Agents read `rnex.yaml` to detect enabled plugins and read their separate instructions files.
+  - In a Repo Nexus workspace: plugin instructions are maintained under `.rnex/plugins/karpathy-llm/` (`rules/behavioral.md` and `instructions/wiki-architecture.md`). Agents read `rnex.yaml` to detect enabled plugins and read their scoped files.
   - In a standalone setup (outside Repo Nexus):
     - `AGENTS.md` (universal, works across most harnesses)
     - `CLAUDE.md` (Claude Code / Anthropic)

package/toolkit/plugins/karpathy-llm/instructions/karpathy-llm.md

@@ -1,82 +0,0 @@
-# Karpathy LLM Agent Guidelines & Behavioral Principles
-
-> "The delicate art and science of context engineering: filling the context window with just the right information for the next step." — Andrej Karpathy
-
-These guidelines provide standing operational instructions for AI coding assistants (Cursor, Claude Code, GitHub Copilot, Antigravity, Windsurf) working within multi-repository environments and managing Karpathy LLM Wiki knowledge bases.
-
----
-
-## 1. The Four Cardinal Principles
-
-### Principle 1: Think Before Coding
-* **State Assumptions Explicitly:** Before implementing any non-trivial change, state your understanding of the problem, assumptions made, and proposed solution.
-* **Surface Trade-Offs:** If multiple approaches exist, outline the alternatives with their trade-offs before generating code.
-* **Verify Repository Boundaries:** In multi-repo workspaces, determine which member repositories are affected. Never make silent architectural assumptions that span across repo boundaries.
-
-### Principle 2: Simplicity First
-* **Favor Readable Over Clever:** Write the simplest code that solves the immediate problem. Avoid unnecessary abstractions, speculative generics, and premature optimizations.
-* **Zero Boilerplate Bloat:** Do not introduce extra wrapper layers, helper classes, or framework-heavy patterns unless explicitly requested or required by existing codebase conventions.
-* **Less Code is Better Code:** If an existing utility, POSIX primitive, or library function does the job, reuse it.
-
-### Principle 3: Surgical Changes
-* **Minimal Blast Radius:** Touch *only* the lines and files required to achieve the goal.
-* **Preserve Documentation & Comments:** Never delete or overwrite existing comments, documentation, or code structure unrelated to your changes.
-* **Zero Unintended Reformatting:** Avoid running blanket code formatters across entire files that create massive, unreadable git diffs. Keep diffs tight, focused, and reviewable.
-
-### Principle 4: Goal-Driven Execution & Verification
-* **Define Success Criteria Upfront:** Know how you will prove that your change works before you write the first line of code.
-* **Verify with Automated Checks:** Run linters, unit tests, and build commands before declaring a task complete.
-* **Inspect the Diff:** Review your own git diff before committing or presenting the solution to ensure no extraneous changes were introduced.
-
----
-
-## 2. Multi-Repo Context Engineering
-
-In a Repo Nexus workspace, independent repositories are organized into `./repos/<name>/` as autonomous Git repositories. Coding agents must follow these rules:
-
-1. **Repository Boundaries:**
-   - Edits made to `repos/<name>/` modify the underlying member repository directly.
-   - Member repositories are independent projects. Do not introduce cross-repository source imports or shared runtime dependencies unless an explicit monorepo architecture is configured.
-
-2. **Member .rnex Directory Routing:**
-   - Member repositories may contain an `.rnex/` directory (e.g. `repos/<name>/.rnex/`) containing repository-specific documents, instructions, rules, workflows, and scripts. Coding assistants must inspect this directory for member-specific instructions.
-   - Run git operations (commits, branches, pushes) directly within the respective member repository root (`repos/<name>/`).
-
-3. **Context Economy:**
-   - Do not redundantly read entire files or directory trees when targeted symbol lookups or line ranges suffice.
-   - Rely on active workspace context, indexing, and compiled documentation rather than re-scanning raw files repeatedly.
-
----
-
-## 3. Karpathy Wiki Rules
-
-When working in a repository with an active Karpathy LLM Wiki (`/wiki/` and `/raw/` directories):
-
-- **Intake**: All source material (articles, transcripts, docs, notes) goes to `/raw/` unmodified. Never write directly to `/wiki/` without ingesting.
-- **Orientation**: Before answering domain questions, read `/wiki/index.md` to find relevant pages, then read only those pages. If `hot.md` exists, read it first as a quick-orient step.
-- **Ingestion**: When files appear in `/raw/`, run the `wiki-ingest` workflow (`.rnex/workflows/wiki-ingest.md`). One source document typically produces many atomic pages (commonly 5–25 pages) — do not collapse a source into a single file.
-- **Maintenance**: Run the `wiki-lint` workflow (`.rnex/workflows/wiki-lint.md`) to validate paths, update `mentioned_in`, and preserve graph integrity.
-
----
-
-## 4. Typed Frontmatter Relation Schema
-
-Every page in `/wiki/` must maintain typed frontmatter relations:
-
-```yaml
----
-title: ""
-tags: []
-last_updated: YYYY-MM-DD
-# Typed relation fields — paths relative to /wiki/
-sources: []          # /raw/ files this page was derived from
-related: []          # thematically related wiki pages
-extends: []          # pages this one builds upon or specialises
-contradicts: []      # pages with conflicting information
-mentioned_in: []     # pages that link to this one (maintained by lint)
----
-```
-
-**Body:** concise summary, key facts or insights, and inline standard Markdown links (`[Label](./path.md)`) where contextually useful in prose.
-
-The relation graph lives in frontmatter, not in prose links. Agents traverse the graph by reading frontmatter fields, not by scanning body text.