@rune-kit/rune 2.1.1 → 2.2.0

package/compiler/adapters/antigravity.js

@@ -41,7 +41,7 @@ export default {
     return [
       '',
       '---',
-      '> **Rune Skill Mesh** — 49 skills, 170+ connections',
+      '> **Rune Skill Mesh** — 58 skills, 200+ connections',
       '> Source: https://github.com/rune-kit/rune',
       '> Full experience with subagents, hooks, adaptive routing → use Rune on Claude Code.',
     ].join('\n');

package/compiler/adapters/codex.js

@@ -0,0 +1,77 @@
+/**
+ * OpenAI Codex Adapter
+ *
+ * Emits SKILL.md files into .codex/skills/{name}/ directories.
+ * Codex uses the same SKILL.md frontmatter format (name, description)
+ * with markdown body — very close to Rune's native format.
+ *
+ * Codex project context: AGENTS.md (equivalent to CLAUDE.md)
+ * Codex skills dir: .codex/skills/
+ * Codex skill format: .codex/skills/{name}/SKILL.md
+ */
+
+const TOOL_MAP = {
+  Read: 'read the file',
+  Write: 'write/create the file',
+  Edit: 'edit the file',
+  Glob: 'find files by pattern',
+  Grep: 'search file contents',
+  Bash: 'run a shell command',
+  TodoWrite: 'track task progress',
+  Skill: 'follow the referenced skill',
+  Agent: 'execute the workflow',
+};
+
+export default {
+  name: 'codex',
+  outputDir: '.codex/skills',
+  fileExtension: '.md',
+  skillPrefix: 'rune-',
+  skillSuffix: '',
+
+  // Codex uses directory-per-skill: .codex/skills/{name}/SKILL.md
+  useSkillDirectories: true,
+  skillFileName: 'SKILL.md',
+
+  transformReference(skillName, raw) {
+    const isBackticked = raw.startsWith('`') && raw.endsWith('`');
+    const ref = `the rune-${skillName} skill`;
+    return isBackticked ? `\`${ref}\`` : ref;
+  },
+
+  transformToolName(toolName) {
+    return TOOL_MAP[toolName] || toolName;
+  },
+
+  generateHeader(skill) {
+    const desc = (skill.description || '').replace(/"/g, '\\"');
+    return [
+      '---',
+      `name: rune-${skill.name}`,
+      `description: "${desc}"`,
+      '---',
+      '',
+      '',
+    ].join('\n');
+  },
+
+  generateFooter() {
+    return [
+      '',
+      '---',
+      '> **Rune Skill Mesh** — 58 skills, 200+ connections',
+      '> Source: https://github.com/rune-kit/rune',
+      '> Full experience with subagents, hooks, adaptive routing → use Rune on Claude Code.',
+    ].join('\n');
+  },
+
+  transformSubagentInstruction(text) {
+    return text;
+  },
+
+  postProcess(content) {
+    return content
+      .replace(/^context: fork\n/gm, '')
+      .replace(/^agent: general-purpose\n/gm, '');
+  },
+};

package/compiler/adapters/cursor.js

@@ -49,7 +49,7 @@ export default {
     return [
       '',
       '---',
-      '> **Rune Skill Mesh** — 49 skills, 170+ connections',
+      '> **Rune Skill Mesh** — 58 skills, 200+ connections',
       '> Source: https://github.com/rune-kit/rune',
       '> Full experience with subagents, hooks, adaptive routing → use Rune on Claude Code.',
     ].join('\n');

package/compiler/adapters/generic.js

@@ -42,7 +42,7 @@ export default {
     return [
       '',
       '---',
-      '> **Rune Skill Mesh** — 49 skills, 170+ connections',
+      '> **Rune Skill Mesh** — 58 skills, 200+ connections',
       '> Source: https://github.com/rune-kit/rune',
       '> Full experience with subagents, hooks, adaptive routing → use Rune on Claude Code.',
     ].join('\n');

package/compiler/adapters/index.js

@@ -10,6 +10,8 @@ import windsurf from './windsurf.js';
 import antigravity from './antigravity.js';
 import generic from './generic.js';
 import openclaw from './openclaw.js';
+import codex from './codex.js';
+import opencode from './opencode.js';
 
 const adapters = {
   claude,
@@ -18,6 +20,8 @@ const adapters = {
   antigravity,
   generic,
   openclaw,
+  codex,
+  opencode,
 };
 
 /**

package/compiler/adapters/opencode.js

@@ -0,0 +1,86 @@
+/**
+ * OpenCode Adapter
+ *
+ * Emits SKILL.md files into .opencode/skills/{name}/ directories.
+ * OpenCode uses the same SKILL.md frontmatter format (name, description)
+ * with markdown body — identical to Codex pattern.
+ *
+ * OpenCode project context: AGENTS.md (+ CLAUDE.md fallback)
+ * OpenCode skills dir: .opencode/skills/
+ * OpenCode skill format: .opencode/skills/{name}/SKILL.md
+ * OpenCode agents dir: .opencode/agents/
+ *
+ * OpenCode also searches:
+ *   .claude/skills/{name}/SKILL.md (Claude-compatible)
+ *   .agents/skills/{name}/SKILL.md (agent-compatible)
+ *
+ * @see https://opencode.ai/docs/skills/
+ * @see https://opencode.ai/docs/agents/
+ */
+
+const TOOL_MAP = {
+  Read: 'read the file',
+  Write: 'write/create the file',
+  Edit: 'edit the file',
+  Glob: 'find files by pattern',
+  Grep: 'search file contents',
+  Bash: 'run a shell command',
+  TodoWrite: 'track task progress',
+  Skill: 'invoke the named skill',
+  Agent: 'delegate to a subagent',
+};
+
+export default {
+  name: 'opencode',
+  outputDir: '.opencode/skills',
+  fileExtension: '.md',
+  skillPrefix: 'rune-',
+  skillSuffix: '',
+
+  // OpenCode uses directory-per-skill: .opencode/skills/{name}/SKILL.md
+  useSkillDirectories: true,
+  skillFileName: 'SKILL.md',
+
+  transformReference(skillName, raw) {
+    const isBackticked = raw.startsWith('`') && raw.endsWith('`');
+    const ref = `the rune-${skillName} skill`;
+    return isBackticked ? `\`${ref}\`` : ref;
+  },
+
+  transformToolName(toolName) {
+    return TOOL_MAP[toolName] || toolName;
+  },
+
+  generateHeader(skill) {
+    const desc = (skill.description || '').replace(/"/g, '\\"');
+    return [
+      '---',
+      `name: rune-${skill.name}`,
+      `description: "${desc}"`,
+      '---',
+      '',
+      '',
+    ].join('\n');
+  },
+
+  generateFooter() {
+    return [
+      '',
+      '---',
+      '> **Rune Skill Mesh** — 58 skills, 200+ connections',
+      '> Source: https://github.com/rune-kit/rune',
+      '> Full experience with subagents, hooks, adaptive routing → use Rune on Claude Code.',
+    ].join('\n');
+  },
+
+  transformSubagentInstruction(text) {
+    // OpenCode has native subagent support — preserve parallel agent instructions
+    return text;
+  },
+
+  postProcess(content) {
+    return content
+      .replace(/^context: fork\n/gm, '')
+      .replace(/^agent: general-purpose\n/gm, '');
+  },
+};

package/compiler/adapters/windsurf.js

@@ -42,7 +42,7 @@ export default {
     return [
       '',
       '---',
-      '> **Rune Skill Mesh** — 49 skills, 170+ connections',
+      '> **Rune Skill Mesh** — 58 skills, 200+ connections',
       '> Source: https://github.com/rune-kit/rune',
       '> Full experience with subagents, hooks, adaptive routing → use Rune on Claude Code.',
     ].join('\n');

package/compiler/bin/rune.js

@@ -46,6 +46,8 @@ function detectPlatform(projectRoot) {
   if (existsSync(path.join(projectRoot, '.windsurf'))) return 'windsurf';
   if (existsSync(path.join(projectRoot, '.agent'))) return 'antigravity';
   if (existsSync(path.join(projectRoot, '.openclaw'))) return 'openclaw';
+  if (existsSync(path.join(projectRoot, '.codex'))) return 'codex';
+  if (existsSync(path.join(projectRoot, '.opencode'))) return 'opencode';
   return null;
 }
 
@@ -159,7 +161,7 @@ async function cmdBuild(projectRoot, args) {
 
   const adapter = getAdapter(platform);
   const runeRoot = config?.source || RUNE_ROOT;
-  const outputRoot = args.output || projectRoot;
+  const outputRoot = typeof args.output === 'string' ? args.output : projectRoot;
   const disabledSkills = config?.skills?.disabled || [];
   const enabledPacks = config?.extensions?.enabled || null;
 
@@ -220,6 +222,9 @@ async function cmdDoctor(projectRoot, args) {
 
 // ─── Arg Parsing ───
 
+// Flags that require a string value (not boolean)
+const VALUE_REQUIRED_FLAGS = new Set(['platform', 'output', 'disable', 'extensions']);
+
 function parseArgs(argv) {
   const args = {};
   const positional = [];
@@ -232,6 +237,9 @@ function parseArgs(argv) {
       if (next && !next.startsWith('--')) {
         args[key] = next;
         i++;
+      } else if (VALUE_REQUIRED_FLAGS.has(key)) {
+        log(`  ✗ Flag --${key} requires a value. Example: --${key} <value>`);
+        process.exit(1);
       } else {
         args[key] = true;
       }
@@ -271,7 +279,7 @@ async function main() {
       log('    doctor   Validate compiled output');
       log('');
       log('  Options:');
-      log('    --platform <name>   Override platform (cursor, windsurf, antigravity, openclaw, generic)');
+      log('    --platform <name>   Override platform (cursor, windsurf, antigravity, codex, openclaw, opencode, generic)');
       log('    --output <dir>      Override output directory');
       log('    --disable <skills>  Comma-separated skills to disable');
       log('');

package/compiler/emitter.js

@@ -124,15 +124,29 @@ export async function buildAll({ runeRoot, outputRoot, adapter, disabledSkills =
 
       const { header, body, footer } = transformSkill(parsed, adapter);
       const output = [header, body, footer].filter(Boolean).join('\n');
-      const fileName = outputFileName(parsed.name, adapter);
-      const outputPath = path.join(outputDir, fileName);
+
+      let outputPath;
+      let displayName;
+
+      if (adapter.useSkillDirectories) {
+        // Directory-per-skill: .codex/skills/rune-{name}/SKILL.md
+        const dirName = `${adapter.skillPrefix}${parsed.name}`;
+        const skillDir = path.join(outputDir, dirName);
+        await mkdir(skillDir, { recursive: true });
+        outputPath = path.join(skillDir, adapter.skillFileName || 'SKILL.md');
+        displayName = `${dirName}/${adapter.skillFileName || 'SKILL.md'}`;
+      } else {
+        const fileName = outputFileName(parsed.name, adapter);
+        outputPath = path.join(outputDir, fileName);
+        displayName = fileName;
+      }
 
       await writeFile(outputPath, output, 'utf-8');
 
       stats.skillCount++;
       stats.crossRefsResolved += parsed.crossRefs.length;
       stats.toolRefsResolved += parsed.toolRefs.length;
-      stats.files.push(fileName);
+      stats.files.push(displayName);
     } catch (err) {
       stats.errors.push({ file: skillPath, error: err.message });
     }
@@ -143,16 +157,33 @@ export async function buildAll({ runeRoot, outputRoot, adapter, disabledSkills =
     try {
       const content = await readFile(packPath, 'utf-8');
       const parsed = parsePack(content, packPath);
+      const packName = path.basename(path.dirname(packPath));
+
+      // Normalize pack name for headers (ext-trading instead of @rune/trading)
+      parsed.name = `ext-${packName}`;
+
       const { header, body, footer } = transformSkill(parsed, adapter);
       const output = [header, body, footer].filter(Boolean).join('\n');
-      const packName = path.basename(path.dirname(packPath));
-      const fileName = outputFileName(`ext-${packName}`, adapter);
-      const outputPath = path.join(outputDir, fileName);
+
+      let outputPath;
+      let displayName;
+
+      if (adapter.useSkillDirectories) {
+        const dirName = `${adapter.skillPrefix}ext-${packName}`;
+        const packDir = path.join(outputDir, dirName);
+        await mkdir(packDir, { recursive: true });
+        outputPath = path.join(packDir, adapter.skillFileName || 'SKILL.md');
+        displayName = `${dirName}/${adapter.skillFileName || 'SKILL.md'}`;
+      } else {
+        const fileName = outputFileName(`ext-${packName}`, adapter);
+        outputPath = path.join(outputDir, fileName);
+        displayName = fileName;
+      }
 
       await writeFile(outputPath, output, 'utf-8');
 
       stats.packCount++;
-      stats.files.push(fileName);
+      stats.files.push(displayName);
     } catch (err) {
       stats.errors.push({ file: packPath, error: err.message });
     }
@@ -221,12 +252,12 @@ function generateIndex(stats, adapter) {
     '## Core Skills',
     '',
     ...stats.files
-      .filter(f => !f.includes('ext-') && !f.includes('index'))
+      .filter(f => !f.match(/[-/]ext-/) && !f.includes('index'))
       .map(f => `- ${f}`),
     '',
   ];
 
-  const extFiles = stats.files.filter(f => f.includes('ext-'));
+  const extFiles = stats.files.filter(f => f.match(/[-/]ext-/));
   if (extFiles.length > 0) {
     lines.push('## Extension Packs', '', ...extFiles.map(f => `- ${f}`), '');
   }

package/compiler/parser.js

@@ -197,6 +197,7 @@ export function parsePack(content, filePath = '') {
     description: frontmatter.description || '',
     version: frontmatter.version || '1.0.0',
     layer: 'L4',
+    group: 'extension',
     body,
     crossRefs: extractCrossRefs(body),
     toolRefs: extractToolRefs(body),

package/compiler/transforms/branding.js

@@ -7,7 +7,7 @@
 const DEFAULT_FOOTER = [
   '',
   '---',
-  '> **Rune Skill Mesh** — 49 skills, 170+ connections',
+  '> **Rune Skill Mesh** — 58 skills, 200+ connections',
   '> Source: https://github.com/rune-kit/rune',
   '> For the full experience with subagents, hooks, adaptive routing, and mesh analytics — use Rune as a Claude Code plugin.',
 ].join('\n');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rune-kit/rune",
-  "version": "2.1.1",
-  "description": "57-skill mesh for AI coding assistants — 5-layer architecture, 200+ connections, all platforms (Claude Code, Cursor, Windsurf, Antigravity)",
+  "version": "2.2.0",
+  "description": "58-skill mesh for AI coding assistants — 5-layer architecture, 200+ connections, 8 platforms (Claude Code, Cursor, Windsurf, Antigravity, Codex, OpenCode, OpenClaw, Generic)",
   "type": "module",
   "bin": {
     "rune": "./compiler/bin/rune.js"
@@ -16,6 +16,9 @@
     "cursor",
     "windsurf",
     "antigravity",
+    "codex",
+    "opencode",
+    "openclaw",
     "ai-assistant",
     "ai-coding",
     "skills",

package/skills/cook/SKILL.md

@@ -170,6 +170,8 @@ This phase is lightweight — a Read + pattern match, not a full scan. It does N
 
 **Goal**: Detect if a master plan already exists for this task. If so, skip Phase 1-2 and resume from the current phase.
 
+**Step 0.5 — Cross-Project Recall**: Call `neural-memory` (Recall Mode) with 3-5 topics relevant to the current task. Load applicable patterns, past decisions, and error history from neural memory. Always prefix queries with the project name to avoid cross-project noise (e.g., `"ProjectName auth pattern"` not just `"auth pattern"`). This activates neurons from past sessions and surfaces context that may not be in the local `.rune/` files.
+
 1. Use `Glob` to check for `.rune/plan-*.md` files
 2. If a master plan exists that matches the current task:
    - Read the master plan file
@@ -470,7 +472,8 @@ This is OPT-IN — only activate if:
    - If Phase 4 had 3 debug-fix loops (max) for a specific error pattern, write a routing override to `.rune/metrics/routing-overrides.json`:
      - Format: `{ "id": "r-<timestamp>", "condition": "<error pattern>", "action": "route to problem-solver before debug", "source": "auto", "active": true }`
    - Max 10 active rules — if exceeded, remove oldest inactive rule
-7. Mark Phase 8 as `completed`
+7. **Step 8.5 — Capture Learnings**: Call `neural-memory` (Capture Mode). Save 2-5 memories covering: architecture decisions made this session, patterns introduced or validated, errors encountered and their root-cause fixes, and any trade-offs chosen. Use rich cognitive language (causal, decisional, comparative — not flat facts). Tag each memory with `[project-name, technology, topic]`. Priority: 5 for routine patterns, 7-8 for key decisions, 9-10 for critical errors. Do NOT batch — save each memory immediately. Do NOT wait for the user to ask.
+8. Mark Phase 8 as `completed`
 
 ## Autonomous Loop Patterns
 
@@ -530,6 +533,7 @@ If any exit condition triggers without resolution → cook emits `BLOCKED` statu
 
 ## Calls (outbound)
 
+- `neural-memory` (external): Phase 0 (resume) + Phase 8 (complete) — Recall project context at start, capture learnings at end
 - `sentinel-env` (L3): Phase 0.5 — environment pre-flight (first run only)
 - `scout` (L2): Phase 1 — scan codebase before planning
 - `onboard` (L2): Phase 1 — if no CLAUDE.md exists, initialize project context first

package/skills/debug/SKILL.md

@@ -42,6 +42,7 @@ If root cause cannot be identified after 3 hypothesis cycles:
 - `problem-solver` (L3): structured reasoning (5 Whys, Fishbone) for complex bugs
 - `browser-pilot` (L3): capture browser console errors, network failures, visual bugs
 - `sequential-thinking` (L3): multi-variable root cause analysis
+- `neural-memory` (L3): after root cause found — capture error pattern for future recognition
 
 ## Called By (inbound)
 
@@ -130,6 +131,10 @@ Narrow to the single actual cause.
 - Identify the specific file, line number, and code construct responsible
 - Note any contributing factors (environment, data, timing, config)
 
+### Step 5b: Capture Error Pattern
+
+Call `neural-memory` (Capture Mode) to save the error pattern: root cause, symptoms, and fix approach. Tag with [project-name, error, technology].
+
 ### Step 6: 3-Fix Escalation Rule
 
 <HARD-GATE>

package/skills/fix/SKILL.md

@@ -38,6 +38,7 @@ If unsure whether the test is wrong or the implementation is wrong → call `run
 - `docs-seeker` (L3): check correct API usage before applying changes
 - `hallucination-guard` (L3): verify imports after code changes
 - `scout` (L2): find related code before applying changes
+- `neural-memory` (L3): after fix verified — capture fix pattern (cause → solution)
 
 ## Called By (inbound)
 
@@ -119,6 +120,10 @@ Verify correctness of the changes just made.
 - Call `rune:docs-seeker` if any external API, library method, or SDK call was added or changed
 - For complex or risky fixes (auth, data mutation, async logic): call `rune:review` for a full quality check
 
+### Step 6b: Capture Fix Pattern
+
+Call `neural-memory` (Capture Mode) to save the fix pattern: what broke, why, and how it was fixed. Priority 7 for recurring bugs.
+
 ### Step 7: Report
 
 Produce a structured summary of all changes made.

package/skills/neural-memory/SKILL.md

@@ -0,0 +1,362 @@
+---
+name: neural-memory
+description: "Cross-session cognitive persistence via Neural Memory MCP. Captures decisions, patterns, errors, and insights with rich semantic links. Provides recall, hypothesis tracking, and evidence-based reasoning across projects."
+metadata:
+  author: rune-kit
+  version: 0.1.0
+  layer: L3
+  model: haiku
+  group: state
+  tools:
+    - mcp__neural-memory__nmem_remember
+    - mcp__neural-memory__nmem_recall
+    - mcp__neural-memory__nmem_auto
+    - mcp__neural-memory__nmem_hypothesize
+    - mcp__neural-memory__nmem_evidence
+    - mcp__neural-memory__nmem_predict
+    - mcp__neural-memory__nmem_verify
+    - mcp__neural-memory__nmem_edit
+    - mcp__neural-memory__nmem_forget
+    - mcp__neural-memory__nmem_health
+    - mcp__neural-memory__nmem_consolidate
+    - mcp__neural-memory__nmem_explain
+    - mcp__neural-memory__nmem_gaps
+    - mcp__neural-memory__nmem_stats
+    - mcp__neural-memory__nmem_review
+    - mcp__neural-memory__nmem_cognitive
+    - Read
+    - Grep
+---
+
+# neural-memory
+
+## Purpose
+
+Bridges Rune's file-based persistence (session-bridge, journal) with Neural Memory MCP's semantic graph. While session-bridge saves decisions to `.rune/` files and journal tracks ADRs locally, neural-memory captures **cross-project learnable patterns** — decisions, error root causes, architectural insights, and workflow preferences — into a persistent cognitive layer that compounds across every project and session.
+
+Without this skill, each project is an island. With it, a caching pattern discovered in Project A auto-surfaces when Project B faces a similar problem.
+
+## Triggers
+
+**Auto-trigger:**
+- Session start → Run **Recall Mode** (load relevant context before any work)
+- After `cook` completes a feature → Run **Capture Mode** (save learnings)
+- After `debug` finds root cause → Run **Capture Mode** (save error pattern)
+- After `review` finds issues → Run **Capture Mode** (save code quality insight)
+- After `rescue` completes a phase → Run **Capture Mode** (save refactoring pattern)
+- After `journal` writes an ADR → Run **Capture Mode** (extract to nmem)
+- Session end / before compaction → Run **Flush Mode** (capture remaining context)
+
+**Manual trigger:**
+- `/rune recall <topic>` — search neural memory for a topic
+- `/rune remember <text>` — save a specific memory
+- `/rune brain-health` — check neural memory health + maintenance
+- `/rune hypothesize <question>` — start hypothesis tracking
+
+## Calls (outbound)
+
+| Skill | When | Why |
+|-------|------|-----|
+| `session-bridge` | After Capture Mode | Sync key decisions back to `.rune/` files |
+
+## Called By (inbound)
+
+| Skill | When | Why |
+|-------|------|-----|
+| `cook` | Phase 0 (resume) + Phase 8 (complete) | Recall project context at start, capture learnings at end |
+| `debug` | After root cause found | Capture error pattern for future recognition |
+| `fix` | After fix verified | Capture fix pattern (cause → solution) |
+| `review` | After review complete | Capture code quality insight |
+| `rescue` | Phase start + phase end | Recall past refactoring patterns, capture new ones |
+| `plan` | Before architecture decisions | Recall past decisions on similar problems |
+| `session-bridge` | Step 6 (cross-project extraction) | Extract generalizable patterns to nmem |
+| `journal` | After ADR written | Extract decision + rejected alternatives to nmem |
+| `context-engine` | Before compaction | Trigger Flush Mode to preserve context |
+| `sentinel` | After security finding | Capture vulnerability pattern |
+| `incident` | After resolution | Capture incident root cause + fix |
+
+## Modes
+
+### Mode 1: Recall (Session Start / Before Decisions)
+
+Load relevant context from neural memory before starting work.
+
+**Step 1 — Identify Recall Topics**
+Read `.rune/progress.md` and current task context to determine 3-5 diverse recall topics.
+Always prefix queries with the project name to avoid cross-project noise.
+
+```
+GOOD: "Rune compiler cross-reference resolution"
+GOOD: "MyTrend PocketBase auth session handling"
+BAD:  "cross-reference" (too generic, returns all projects)
+BAD:  "auth" (returns noise from every project)
+```
+
+**Step 2 — Execute Recall**
+Call `nmem_recall` for each topic. Use diverse angles:
+- Technology-specific: `"<project> React state management"`
+- Problem-specific: `"<project> caching strategy decision"`
+- Pattern-specific: `"<project> error handling approach"`
+
+**Step 3 — Synthesize Context**
+Summarize recalled memories into actionable context:
+- Decisions that apply to current task
+- Patterns that worked (or failed) before
+- Constraints or preferences from past sessions
+- Open hypotheses still being tracked
+
+**Step 4 — Surface Gaps**
+If recall returns thin results for the current domain, note the gap.
+Call `nmem_gaps(action="detect")` if working in a domain with sparse memories.
+
+---
+
+### Mode 2: Capture (After Task Completion)
+
+Extract learnable patterns from completed work and save to neural memory.
+
+**Step 1 — Classify What Happened**
+Determine which memory types to create from the completed task:
+
+| What happened | Memory type | Priority | Example |
+|---------------|-------------|----------|---------|
+| Chose approach A over B | `decision` | 7 | "Chose Zustand over Redux because single-store simpler for this scale" |
+| Found and fixed a bug | `error` | 7 | "Root cause was stale closure in useEffect — fixed by adding dep array" |
+| Discovered a reusable pattern | `insight` | 6 | "This codebase uses barrel exports for every feature module" |
+| Learned user preference | `preference` | 8 | "User prefers Phosphor Icons over Lucide for all UI work" |
+| Established a workflow | `workflow` | 6 | "Deploy: build → test → push → verify CI → tag" |
+| Found a fact worth keeping | `fact` | 5 | "API rate limit is 100 req/min on free tier" |
+| Received instruction to follow | `instruction` | 8 | "Always run prettier before commit in this project" |
+
+**Step 2 — Craft Rich Memories**
+Each memory MUST use cognitive language patterns for strong neural connections:
+
+```
+BAD:  "PostgreSQL" (flat, no context — orphan neuron)
+GOOD: "Chose PostgreSQL over MongoDB because ACID needed for payment processing"
+
+BAD:  "Fixed auth bug" (no root cause — useless for future recall)
+GOOD: "Auth cookie expired silently because SameSite=Lax blocked cross-origin. Fixed by setting SameSite=None + Secure flag"
+
+BAD:  "React project structure" (vague — won't match specific queries)
+GOOD: "Rune compiler uses 3-stage pipeline: Parse SKILL.md → Transform cross-refs → Emit per-platform files"
+```
+
+**Cognitive patterns to use:**
+- **Causal**: "X caused Y because Z", "Root cause was X which led to Y"
+- **Temporal**: "After upgrading to v3, the middleware broke because of new cookie format"
+- **Decisional**: "Chose X over Y because Z", "Rejected X due to Y"
+- **Comparative**: "X is 3x faster than Y for read-heavy workloads"
+- **Relational**: "X depends on Y", "X replaced Y", "X connects to Y through Z"
+
+**Step 3 — Tag and Prioritize**
+Every memory MUST include:
+- **Tags**: `[project-name, technology, topic]` — lowercase, specific
+- **Priority**: 5 (normal), 7-8 (important decisions/errors), 9-10 (critical security/breaking)
+- **Max length**: 1-3 sentences. If longer, split into focused pieces.
+
+**Step 4 — Save Memories**
+Call `nmem_remember` for each memory. Save 2-5 memories per completed task:
+- A bug fix has: root cause, fix approach, prevention insight
+- A feature has: architecture decision, pattern used, trade-off made
+- A review has: quality issue found, fix suggestion, pattern to avoid
+
+**Step 5 — Reinforce Connections**
+After saving, call `nmem_recall` on the topic to reinforce new neural connections.
+This activates related neurons and strengthens the memory graph.
+
+---
+
+### Mode 3: Hypothesis Tracking
+
+Track uncertain decisions with evidence over time.
+
+**Step 1 — Form Hypothesis**
+When making an uncertain architectural or design decision:
+```
+nmem_hypothesize("Redis will handle our session load better than Memcached
+                   because our access pattern is 80% reads with complex data types")
+```
+
+**Step 2 — Collect Evidence**
+As you work, update the hypothesis with evidence:
+```
+nmem_evidence(hypothesis_id, "Redis handled 10K concurrent sessions with
+              p99 < 5ms in load test — SUPPORTS hypothesis")
+
+nmem_evidence(hypothesis_id, "Memory usage 2x higher than Memcached estimate
+              — WEAKENS hypothesis for memory-constrained deployments")
+```
+
+**Step 3 — Make Predictions**
+Create falsifiable predictions:
+```
+nmem_predict("If we switch to Redis Cluster, session failover time will drop
+              from 30s to < 2s")
+```
+
+**Step 4 — Verify Outcomes**
+After deployment/testing, verify:
+```
+nmem_verify(prediction_id, outcome="Failover time dropped to 1.2s — CONFIRMED")
+```
+
+---
+
+### Mode 4: Flush (Session End / Pre-Compaction)
+
+Capture remaining context before session ends.
+
+**Step 1 — Scan Unsaved Context**
+Review the current session for:
+- Decisions made but not yet captured
+- Errors encountered and their resolutions
+- Patterns discovered during exploration
+- User preferences expressed
+
+**Step 2 — Batch Save**
+Call `nmem_auto(action="process", text="<session summary>")` with a concise summary
+of the session's key outcomes, decisions, and learnings.
+
+**Step 3 — Update Session Bridge**
+If significant decisions were captured, also call `session-bridge` to sync
+the most important ones to `.rune/decisions.md` for local persistence.
+
+---
+
+### Mode 5: Maintenance (Weekly / On-Demand)
+
+Keep the neural memory healthy and useful.
+
+**Step 1 — Health Check**
+Call `nmem_health()` to assess brain status. Key metrics:
+- Consolidation % (low = run consolidation)
+- Orphan % (>20% = prune disconnected memories)
+- Activation levels (low = recall more diverse topics)
+- Connectivity (low = use richer cognitive language)
+- Diversity (low = vary memory types)
+
+**Step 2 — Consolidation**
+If brain has >100 memories or consolidation is low:
+```
+nmem_consolidate  — merge episodic → semantic memories
+```
+
+**Step 3 — Review Queue**
+Call `nmem_review(action="queue")` to surface memories needing attention:
+- Outdated decisions that may no longer apply
+- Low-confidence memories that need evidence
+- Wall-of-text memories (>500 chars) that should be split
+
+**Step 4 — Corrections**
+Fix bad memories:
+- Wrong type → `nmem_edit(memory_id, type="correct_type")`
+- Wrong content → `nmem_edit(memory_id, content="corrected text")`
+- Outdated → `nmem_forget(memory_id, reason="outdated")`
+- Sensitive/garbage → `nmem_forget(memory_id, hard=true)`
+
+**Step 5 — Connection Tracing**
+Use `nmem_explain(entity_a, entity_b)` to trace paths between concepts.
+Useful for understanding why certain memories surface together.
+
+## Output Format
+
+### Recall Report
+```
+## Neural Memory Recall — <project>
+
+### Loaded Context
+- <memory 1 summary — decision/pattern/insight>
+- <memory 2 summary>
+- <memory 3 summary>
+
+### Applicable to Current Task
+- <how memory X applies>
+- <how memory Y applies>
+
+### Gaps Detected
+- <domain with sparse coverage>
+```
+
+### Capture Report
+```
+## Neural Memory Capture — <task summary>
+
+### Saved Memories
+| # | Type | Priority | Tags | Content (preview) |
+|---|------|----------|------|--------------------|
+| 1 | decision | 7 | [project, tech, topic] | Chose X over Y because... |
+| 2 | error | 7 | [project, bug, tech] | Root cause was X... |
+| 3 | insight | 6 | [project, pattern] | This codebase uses... |
+
+### Reinforced Topics
+- <topic recalled to strengthen connections>
+```
+
+### Health Report
+```
+## Neural Memory Health
+
+| Metric | Value | Status |
+|--------|-------|--------|
+| Total memories | N | — |
+| Consolidation | N% | ✅ / ⚠️ |
+| Orphans | N% | ✅ / ⚠️ |
+| Activation | level | ✅ / ⚠️ |
+| Top penalty | <metric> | Fix: <action> |
+
+### Recommended Actions
+1. <action with command>
+```
+
+## Constraints
+
+1. **MUST prefix all recall queries with project name** — generic queries return cross-project noise that confuses the AI. The ONLY exception is intentional cross-project searches.
+2. **MUST use rich cognitive language** — flat facts ("X exists") create orphan neurons with zero connections. Every memory MUST include WHY, BECAUSE, or relationship context.
+3. **MUST NOT save wall-of-text memories** — max 1-3 sentences per memory. Split longer content into focused pieces. Memories >500 chars degrade recall quality.
+4. **MUST NOT duplicate file-based state** — don't save task progress, file paths, or git history to nmem. Those belong in `.rune/` files (session-bridge) or git. nmem is for *learnable patterns* only.
+5. **MUST save 2-5 memories per completed task** — a single memory per task is insufficient. Capture the decision, the reasoning, the pattern, and the prevention insight separately.
+6. **MUST NOT save sensitive data** — no API keys, passwords, tokens, or PII. Mask or omit sensitive values.
+7. **MUST tag every memory** — always include `[project-name, technology, topic]`. Tags enable future recall precision.
+
+## Sharp Edges
+
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| Cross-project noise from generic queries | HIGH | Always prefix queries with project name. Use `nmem_explain` to trace unexpected connections |
+| Orphan neurons from flat facts | HIGH | Enforce cognitive language patterns (causal, decisional, comparative). Run `nmem_health` to detect orphan % |
+| Memory bloat from over-saving | MEDIUM | Cap at 5 memories per task. Run `nmem_consolidate` weekly. Use `nmem_review` to prune |
+| Stale decisions applied to changed codebase | MEDIUM | Include temporal context ("As of v2.1, ..."). Verify recalled decisions against current code before applying |
+| Duplicate memories from repeated sessions | MEDIUM | Before saving, `nmem_recall` the topic first to check for existing memories. Update rather than create duplicates |
+| Loss of nuance from oversimplification | LOW | Save rejected alternatives alongside chosen approach. Use `nmem_hypothesize` for uncertain decisions |
+
+## Done When
+
+**Recall Mode:**
+- 3-5 diverse topics recalled with project-name prefix
+- Applicable context summarized for current task
+- Gaps noted if coverage is thin
+
+**Capture Mode:**
+- 2-5 memories saved with rich cognitive language
+- All memories tagged with `[project, technology, topic]`
+- Priority assigned (5-10 scale)
+- Connections reinforced via post-save recall
+
+**Flush Mode:**
+- All significant unsaved decisions captured
+- `nmem_auto` called with session summary
+- Session-bridge synced if major decisions made
+
+**Maintenance Mode:**
+- `nmem_health` run and metrics assessed
+- Top penalty addressed with specific action
+- Review queue processed (outdated/bloated memories fixed)
+
+## Cost Profile
+
+- **Recall**: ~200-500 tokens (3-5 queries + synthesis)
+- **Capture**: ~300-600 tokens (2-5 memories + reinforcement)
+- **Flush**: ~100-300 tokens (auto-process + sync)
+- **Maintenance**: ~500-1000 tokens (health + consolidate + review)
+- **Hypothesis**: ~200-400 tokens per hypothesis lifecycle

package/skills/plan/SKILL.md

@@ -88,6 +88,7 @@ High-level multi-feature planning — organize features into milestones.
 - `research` (L3): external knowledge lookup
 - `sequential-thinking` (L3): complex architecture with many trade-offs
 - L4 extension packs: domain-specific architecture patterns
+- `neural-memory` | Before architecture decisions | Recall past decisions on similar problems
 
 ## Called By (inbound)
 
@@ -113,6 +114,8 @@ High-level multi-feature planning — organize features into milestones.
 
 Use findings from `rune:scout` if already available. If not, invoke `rune:scout` with the project root to scan directory structure, detect framework, identify key files, and extract existing patterns. Do NOT skip this step — plans without context produce wrong file paths.
 
+Call `neural-memory` (Recall Mode) to check for past architecture decisions on similar problems before making new ones.
+
 ### Step 2 — Classify Complexity
 
 Determine if the task needs master plan + phase files or inline plan:

package/skills/rescue/SKILL.md

@@ -40,6 +40,7 @@ Legacy refactoring orchestrator for safely modernizing messy codebases. Rescue r
 - `session-bridge` (L3): save rescue state between sessions
 - `onboard` (L2): generate context for unfamiliar legacy project
 - `dependency-doctor` (L3): audit dependencies in legacy project
+- `neural-memory` | Phase start + phase end | Recall past refactoring patterns, capture new ones
 
 ## Called By (inbound)
 
@@ -72,6 +73,8 @@ Note: SURGERY todos are added dynamically — one per module identified in Phase
 
 Mark todo[0] `in_progress`.
 
+Call `neural-memory` (Recall Mode) for past refactoring patterns in similar codebases.
+
 **0a. Full health assessment.**
 
 ```
@@ -344,6 +347,8 @@ REQUIRED SUB-SKILL: rune:journal
 Bash: git tag rune-rescue-complete
 ```
 
+Call `neural-memory` (Capture Mode) to save refactoring patterns and decisions from this rescue.
+
 Mark VERIFY todo `completed`.
 
 ---

package/skills/review/SKILL.md

@@ -41,6 +41,7 @@ Every review MUST cite at least one specific concern, suggestion, or explicit ap
 - `review-intake` (L2): structured intake for complex multi-file reviews
 - `sast` (L3): static analysis security scan on reviewed code
 - L4 extension packs: domain-specific review patterns when context matches (e.g., @rune/ui for frontend, @rune/security for auth code)
+- `neural-memory` | After review complete | Capture code quality insight
 
 ## Called By (inbound)
 
@@ -181,6 +182,7 @@ After reporting:
 - If any CRITICAL findings: call `rune:fix` immediately with the finding details
 - If any HIGH findings: call `rune:fix` with the finding details
 - If untested code: call `rune:test` with specific coverage gaps identified
+- Call `neural-memory` (Capture Mode) to save any novel code quality patterns or recurring issues found.
 
 ## Framework-Specific Checks
 

package/skills/skill-router/SKILL.md

@@ -133,10 +133,13 @@ These are rarely invoked directly — they're called by Tier 1/2 skills:
 | `rune:completion-gate` | cook | Validate claims |
 | `rune:sentinel-env` | cook, scaffold, onboard | Environment pre-flight |
 | `rune:research` / `rune:docs-seeker` | any | Look up docs |
-| `rune:session-bridge` | cook, team | Save context |
+| `rune:session-bridge` | cook, team | Save context (in-session state handoff) |
+| `rune:journal` | cook, team | Persistent work log within a session |
+| `rune:neural-memory` | cook, team, any L1/L2 | Cross-session cognitive persistence via Neural Memory MCP — semantic complement to session-bridge and journal |
 | `rune:git` | cook, scaffold, team, launch | Semantic commits, PRs, branches |
 | `rune:doc-processor` | docs, marketing | PDF/DOCX/XLSX/PPTX generation |
 | "Done" / "ship it" / "xong" | — | `rune:verification` → commit |
+| "recall", "remember", "brain", "nmem", "cross-project memory" | `rune:neural-memory` | Retrieve or persist cross-session context |
 
 #### Tier 4 — Domain Extension Packs (L4)
 
@@ -209,6 +212,19 @@ Once routed:
 3. Follow the skill's workflow exactly
 4. If the skill has a checklist/phases, track via TodoWrite
 
+### Step 5 — Post-Completion Neural Memory Capture
+
+After ANY L1 or L2 workflow completes (cook, team, launch, rescue, scaffold, plan, design, debug, fix, review, deploy, sentinel, perf, db, ba, docs, mcp-builder, etc.):
+
+1. Trigger `rune:neural-memory` in **Capture Mode** automatically
+2. Save 2–5 memories covering: key decisions made, bugs fixed, patterns applied, architectural choices
+3. Use rich cognitive language (causal, temporal, decisional) — NOT flat facts
+4. Tag memories with [project-name, skill-used, topic]
+5. This step is MANDATORY even if the user did not ask for it
+6. Exception: skip if the workflow produced zero technical output (e.g., only a clarifying question was asked)
+
+**Capture Mode trigger phrase**: "Session artifact — capturing to Neural Memory."
+
 ## Routing Exceptions
 
 These DO NOT need skill routing: