repo-nexus 0.4.2 → 0.4.4

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.4",
   "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.
@@ -32,37 +32,22 @@ Reference specification: [setup-karpathy-wiki.md](https://github.com/nu-nenoi/ai
 
 ---
 
-## Step 0 — Configuration Interview
-
-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 **standalone setup** (outside Repo Nexus):
-     - `AGENTS.md` (universal, works across most harnesses)
-     - `CLAUDE.md` (Claude Code / Anthropic)
-     - `.cursor/rules/wiki.mdc` (Cursor)
-     - `.github/copilot-instructions.md` (GitHub Copilot)
-     - `GEMINI.md` (Google Gemini / Antigravity)
-     - `.windsurfrules` (Windsurf)
-     - Other — specify path
-     *Append the `## Karpathy Wiki Rules` section to that file while preserving all existing content.*
-
-2. **[Q2] What is this wiki for?**
-   - Research / reading list — articles, papers, PDFs on a topic
-   - Personal second brain — meetings, notes, business context, personal projects
-   - Content archive — transcripts, podcast notes, newsletters
-   - Codebase knowledge — architecture decisions, runbooks, team conventions
-   - Other (describe briefly)
-
-3. **[Q3] How should the wiki be organized?**
-   - **Flat** — all pages at the top level of `/wiki/` (simpler, good default)
-   - **Structured** — subfolders by category, chosen based on Q2:
-     - Research → `concepts/`, `people/`, `organizations/`, `sources/`, `analysis/`
-     - Second brain → `projects/`, `people/`, `decisions/`, `logs/`
-     - Content archive → `sources/`, `people/`, `tools/`, `concepts/`
-     - Codebase → `architecture/`, `decisions/`, `runbooks/`, `people/`
-   - **Agent decides** — infer structure from the first batch of ingested content
+## Deterministic Lifecycle: Initialization vs. Evolutionary Growth
+
+To ensure workspaces remain 100% predictable, understandable, and consistent across all tools, the Karpathy LLM Wiki follows a strict two-phase lifecycle:
+
+### Phase 1: 100% Deterministic Initialization
+Enabling the plugin (`rnex plugin enable karpathy-llm`) performs an exact, zero-interview scaffolding step:
+* **Predictable Baseline**: Fixed standard files are created (`raw/.gitkeep`, `wiki/index.md`, `wiki/hot.md`, `wiki/_log.md`).
+* **Scoped Assets**: Behavioral rules, wiki architecture guides, workflows, and templates are cleanly isolated under `.rnex/plugins/karpathy-llm/`.
+* **Zero Guesswork**: No interactive interviews, no AI-generated folder variances, and no "agent decides" ambiguities at init time.
+* **Idempotent**: Safe to run repeatedly; existing user files are never overwritten.
+
+### Phase 2: Evolutionary Growth & Domain Specialization (Usage Phase)
+Once initialized, the workspace structure organically evolves according to actual domain needs and source materials:
+* **Source Ingestion (`wiki-ingest`)**: As raw source documents are deposited into `/raw/` and ingested, atomic pages are generated. Users or agents can organize pages into categorical subfolders (e.g. `architecture/`, `decisions/`, `concepts/`, `projects/`) or keep them flat.
+* **Customizable Guidelines**: Teams can tailor `rules/behavioral.md` and `instructions/wiki-architecture.md` for their specific team conventions.
+* **Graph Maintenance (`wiki-lint`)**: The periodic lint workflow validates relation paths, updates `mentioned_in`, and rebuilds `index.md` and `hot.md` to match the evolved knowledge graph.
 
 ---
 
@@ -82,9 +67,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 +92,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

@@ -12,54 +12,23 @@ Do not hard-code any specific AI tool or harness into the wiki structure itself.
 
 ---
 
-### Step 0 — Configuration (ask before creating any files)
-
-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 standalone setup (outside Repo Nexus):
-    - `AGENTS.md` (universal, works across most harnesses)
-    - `CLAUDE.md` (Claude Code / Anthropic)
-    - `.cursor/rules/wiki.mdc` (Cursor)
-    - `.github/copilot-instructions.md` (GitHub Copilot)
-    - `GEMINI.md` (Google Gemini / Antigravity)
-    - `.windsurfrules` (Windsurf)
-    - Other — specify path
-    Append a `## Karpathy Wiki Rules` section to that file. Preserve all existing content.
-
-[Q2] What is this wiki for?
-  - Research / reading list — articles, papers, PDFs on a topic
-  - Personal second brain — meetings, notes, business context, personal projects
-  - Content archive — transcripts, podcast notes, newsletters
-  - Codebase knowledge — architecture decisions, runbooks, team conventions
-  - Other (describe briefly)
-
-[Q3] How should the wiki be organized?
-  - Flat — all pages at the top level of `/wiki/` (simpler, good default)
-  - Structured — subfolders by category, chosen based on Q2 answer
-  - Agent decides — infer structure from the first batch of ingested content
+### 1. Deterministic Scaffolding (Create Immediately)
 
----
-
-### 1. Directories and Files
+Initialize the fixed baseline directories and control files:
 
-**`/raw/`** — Append-only intake directory. All original source material goes here unmodified. Add `.gitkeep`.
+- **`/raw/`** — Append-only intake directory. Add `.gitkeep`. All original source material goes here unmodified.
+- **`/wiki/index.md`** — Master navigation index organizing links to atomic pages.
+- **`/wiki/hot.md`** — Rolling ~500-word orientation cache for quick agent onboarding.
+- **`/wiki/_log.md`** — Append-only operation log recording all ingest and lint runs.
 
-**`/wiki/`** — Curated knowledge base of atomic markdown pages. Structure per Q3:
-  - Flat: all pages directly in `/wiki/`
-  - Structured: subfolders matching the project type from Q2:
-    - Research → `concepts/`, `people/`, `organizations/`, `sources/`, `analysis/`
-    - Second brain → `projects/`, `people/`, `decisions/`, `logs/`
-    - Content archive → `sources/`, `people/`, `tools/`, `concepts/`
-    - Codebase → `architecture/`, `decisions/`, `runbooks/`, `people/`
+Do not create arbitrary or speculative subdirectories during initialization. Scaffolding is 100% deterministic. Domain subfolders and categories emerge organically during the source ingestion phase (`wiki-ingest`).
 
-**`/wiki/index.md`** — Master navigation index. Contains:
-  - Categorized links to every wiki page. Auto-maintained after every ingest and lint run.
+---
 
-**`/wiki/_log.md`** — Append-only operation log. Every ingest and lint run appends a timestamped entry.
+### 2. Agent Rules & Routing
 
-**`/wiki/hot.md`** *(create only for second brain or codebase wiki)* — Rolling ~500-word cache of the most recently relevant context. Lets an agent orient without reading the full wiki.
+- **Repo Nexus Workspaces**: Scoped under `.rnex/plugins/karpathy-llm/` (`rules/behavioral.md` and `instructions/wiki-architecture.md`). Agents route through `rnex.yaml` automatically.
+- **Standalone Repositories**: Append the `## Karpathy Wiki Rules` section (see Section 4) to the primary AI instructions file (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, etc.), preserving all existing content.
 
 ---
 
@@ -104,9 +73,9 @@ The relation graph lives in frontmatter, not in prose links. Agents traverse the
 
 ---
 
-### 4. Agent Instructions
+### 4. Agent Instructions (Standalone Repositories)
 
-In the file chosen in Q1, append:
+In standalone repositories (outside Repo Nexus), append:
 
 ```markdown
 ## Karpathy Wiki Rules

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.