@rune-kit/rune 2.1.1

package/compiler/parser.js

@@ -0,0 +1,208 @@
+/**
+ * SKILL.md Parser
+ *
+ * Parses SKILL.md files into a structured intermediate representation (IR).
+ * Extracts frontmatter, cross-references, tool references, HARD-GATE blocks, and sections.
+ */
+
+const CROSS_REF_PATTERN = /`?rune:([a-z][\w-]*)`?/g;
+const TOOL_REF_PATTERN = /`(Read|Write|Edit|Glob|Grep|Bash|TodoWrite|Skill|Agent)`/g;
+const HARD_GATE_PATTERN = /<HARD-GATE>([\s\S]*?)<\/HARD-GATE>/g;
+const SECTION_PATTERN = /^## (.+)$/gm;
+
+/**
+ * Parse YAML-like frontmatter from SKILL.md
+ * Handles nested metadata block
+ */
+function parseFrontmatter(content) {
+  // Normalize line endings to \n for cross-platform compatibility
+  const normalized = content.replace(/\r\n/g, '\n');
+  const match = normalized.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return { frontmatter: {}, body: normalized };
+
+  const raw = match[1];
+  const body = normalized.slice(match[0].length).trim();
+  const frontmatter = {};
+
+  let currentIndent = null;
+  let nestedKey = null;
+  const nestedObj = {};
+
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    // Detect nested block (e.g., metadata:)
+    if (/^\w+:\s*$/.test(trimmed)) {
+      nestedKey = trimmed.replace(':', '').trim();
+      frontmatter[nestedKey] = {};
+      currentIndent = 'nested';
+      continue;
+    }
+
+    if (currentIndent === 'nested' && line.startsWith('  ')) {
+      const kvMatch = trimmed.match(/^(\w+):\s*(.+)$/);
+      if (kvMatch) {
+        let value = kvMatch[2].replace(/^["']|["']$/g, '');
+        frontmatter[nestedKey][kvMatch[1]] = value;
+      }
+      continue;
+    }
+
+    // Top-level key-value
+    currentIndent = null;
+    nestedKey = null;
+    const kvMatch = trimmed.match(/^(\w[\w-]*):\s*(.+)$/);
+    if (kvMatch) {
+      let value = kvMatch[2].replace(/^["']|["']$/g, '');
+      frontmatter[kvMatch[1]] = value;
+    }
+  }
+
+  return { frontmatter, body };
+}
+
+/**
+ * Extract all rune:<name> cross-references from body
+ */
+function extractCrossRefs(body) {
+  const refs = [];
+  const lines = body.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    let match;
+    const regex = new RegExp(CROSS_REF_PATTERN.source, 'g');
+
+    while ((match = regex.exec(line)) !== null) {
+      refs.push({
+        raw: match[0],
+        skillName: match[1],
+        line: i + 1,
+        context: line.trim(),
+      });
+    }
+  }
+
+  return refs;
+}
+
+/**
+ * Extract all Claude Code tool references from body
+ */
+function extractToolRefs(body) {
+  const refs = [];
+  const lines = body.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    let match;
+    const regex = new RegExp(TOOL_REF_PATTERN.source, 'g');
+
+    while ((match = regex.exec(line)) !== null) {
+      refs.push({
+        raw: match[0],
+        toolName: match[1],
+        line: i + 1,
+        context: line.trim(),
+      });
+    }
+  }
+
+  return refs;
+}
+
+/**
+ * Extract HARD-GATE blocks
+ */
+function extractHardGates(body) {
+  const gates = [];
+  let match;
+  const regex = new RegExp(HARD_GATE_PATTERN.source, 'gs');
+
+  while ((match = regex.exec(body)) !== null) {
+    gates.push(match[1].trim());
+  }
+
+  return gates;
+}
+
+/**
+ * Extract ## sections as a Map<sectionName, content>
+ */
+function extractSections(body) {
+  const sections = new Map();
+  const lines = body.split('\n');
+  let currentSection = null;
+  let currentContent = [];
+
+  for (const line of lines) {
+    const sectionMatch = line.match(/^## (.+)$/);
+    if (sectionMatch) {
+      if (currentSection) {
+        sections.set(currentSection, currentContent.join('\n').trim());
+      }
+      currentSection = sectionMatch[1];
+      currentContent = [];
+    } else if (currentSection) {
+      currentContent.push(line);
+    }
+  }
+
+  if (currentSection) {
+    sections.set(currentSection, currentContent.join('\n').trim());
+  }
+
+  return sections;
+}
+
+/**
+ * Parse a SKILL.md file content into structured IR
+ *
+ * @param {string} content - raw SKILL.md content
+ * @param {string} [filePath] - optional file path for error reporting
+ * @returns {ParsedSkill}
+ */
+export function parseSkill(content, filePath = '') {
+  const { frontmatter, body } = parseFrontmatter(content);
+
+  const metadata = frontmatter.metadata || {};
+
+  return {
+    name: frontmatter.name || '',
+    description: frontmatter.description || '',
+    layer: metadata.layer || 'L2',
+    model: metadata.model || 'sonnet',
+    group: metadata.group || 'general',
+    contextFork: frontmatter.context === 'fork',
+    agentType: frontmatter.agent || null,
+    body,
+    crossRefs: extractCrossRefs(body),
+    toolRefs: extractToolRefs(body),
+    hardGates: extractHardGates(body),
+    sections: extractSections(body),
+    filePath,
+    frontmatter,
+  };
+}
+
+/**
+ * Parse a PACK.md extension file (same format, slightly different metadata)
+ */
+export function parsePack(content, filePath = '') {
+  const { frontmatter, body } = parseFrontmatter(content);
+
+  return {
+    name: frontmatter.name || '',
+    description: frontmatter.description || '',
+    version: frontmatter.version || '1.0.0',
+    layer: 'L4',
+    body,
+    crossRefs: extractCrossRefs(body),
+    toolRefs: extractToolRefs(body),
+    hardGates: extractHardGates(body),
+    sections: extractSections(body),
+    filePath,
+    frontmatter,
+  };
+}

package/compiler/transformer.js

@@ -0,0 +1,69 @@
+/**
+ * Transform Pipeline
+ *
+ * Applies all transforms in order to convert a parsed skill into platform-specific output.
+ * Pipeline: frontmatter → cross-refs → tool-names → subagents → hooks → branding
+ */
+
+import { transformCrossReferences } from './transforms/cross-references.js';
+import { transformToolNames } from './transforms/tool-names.js';
+import { transformFrontmatter } from './transforms/frontmatter.js';
+import { transformSubagents } from './transforms/subagents.js';
+import { generateHookConstraints } from './transforms/hooks.js';
+import { addBranding } from './transforms/branding.js';
+
+/**
+ * Run the full transform pipeline on a parsed skill
+ *
+ * @param {object} parsedSkill - output from parser.parseSkill()
+ * @param {object} adapter - platform adapter
+ * @returns {{ header: string, body: string, footer: string }}
+ */
+export function transformSkill(parsedSkill, adapter) {
+  // For Claude Code, return body unchanged
+  if (adapter.name === 'claude') {
+    return {
+      header: '',
+      body: parsedSkill.body,
+      footer: '',
+    };
+  }
+
+  let body = parsedSkill.body;
+
+  // 1. Rewrite cross-references (rune:cook → platform-native)
+  body = transformCrossReferences(body, adapter);
+
+  // 2. Rewrite tool names (Read, Edit, Bash → generic)
+  body = transformToolNames(body, adapter);
+
+  // 3. Convert subagent/parallel instructions to sequential
+  body = transformSubagents(body, adapter);
+
+  // 4. Platform-specific post-processing
+  body = adapter.postProcess(body);
+
+  // 5. Generate header (platform-specific frontmatter/preamble)
+  const header = adapter.generateHeader(parsedSkill);
+
+  // 6. Generate hook constraints section
+  const hookConstraints = generateHookConstraints(parsedSkill, adapter);
+
+  // 7. Inject hook constraints after the first heading
+  if (hookConstraints) {
+    const firstHeadingEnd = body.indexOf('\n## ');
+    if (firstHeadingEnd !== -1) {
+      // Insert before the first ## section
+      const titleSection = body.substring(0, firstHeadingEnd);
+      const rest = body.substring(firstHeadingEnd);
+      body = titleSection + hookConstraints + rest;
+    } else {
+      body = body + hookConstraints;
+    }
+  }
+
+  // 8. Generate footer (branding + CTA)
+  const footer = adapter.generateFooter();
+
+  return { header, body, footer };
+}

package/compiler/transforms/branding.js

@@ -0,0 +1,27 @@
+/**
+ * Branding Transform
+ *
+ * Adds Rune attribution footer to compiled skill files.
+ */
+
+const DEFAULT_FOOTER = [
+  '',
+  '---',
+  '> **Rune Skill Mesh** — 49 skills, 170+ 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');
+
+/**
+ * Add branding footer to skill output
+ *
+ * @param {string} body - transformed skill body
+ * @param {object} adapter - platform adapter
+ * @returns {string} body with footer
+ */
+export function addBranding(body, adapter) {
+  if (adapter.name === 'claude') return body;
+
+  const footer = adapter.generateFooter ? adapter.generateFooter() : DEFAULT_FOOTER;
+  return body + '\n' + footer;
+}

package/compiler/transforms/cross-references.js

@@ -0,0 +1,29 @@
+/**
+ * Cross-Reference Transform
+ *
+ * Rewrites `rune:<name>` references to platform-native format.
+ */
+
+const CROSS_REF_PATTERN = /`rune:([a-z][\w-]*)`/g;
+const BARE_REF_PATTERN = /(?<!`)rune:([a-z][\w-]*)(?!`)/g;
+
+/**
+ * Transform cross-references in skill body using the platform adapter
+ *
+ * @param {string} body - skill markdown body
+ * @param {object} adapter - platform adapter with transformReference method
+ * @returns {string} transformed body
+ */
+export function transformCrossReferences(body, adapter) {
+  // First pass: backtick-wrapped references (`rune:cook`)
+  let result = body.replace(CROSS_REF_PATTERN, (match, skillName) => {
+    return adapter.transformReference(skillName, match);
+  });
+
+  // Second pass: bare references (rune:cook without backticks)
+  result = result.replace(BARE_REF_PATTERN, (match, skillName) => {
+    return adapter.transformReference(skillName, match);
+  });
+
+  return result;
+}

package/compiler/transforms/frontmatter.js

@@ -0,0 +1,38 @@
+/**
+ * Frontmatter Transform
+ *
+ * Strips or rewrites Claude Code-specific frontmatter directives.
+ * - context: fork → removed on non-Claude platforms
+ * - agent: general-purpose → removed on non-Claude platforms
+ * - model: → removed or converted to comment
+ */
+
+/**
+ * Strip Claude Code-specific frontmatter lines from raw content
+ *
+ * @param {string} content - full SKILL.md content (with frontmatter)
+ * @param {object} adapter - platform adapter
+ * @returns {string} content with cleaned frontmatter
+ */
+export function transformFrontmatter(content, adapter) {
+  if (adapter.name === 'claude') return content;
+
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return content;
+
+  const frontmatterBlock = match[1];
+  const afterFrontmatter = content.slice(match[0].length);
+
+  // Remove Claude Code-specific directives
+  const cleaned = frontmatterBlock
+    .split('\n')
+    .filter(line => {
+      const trimmed = line.trim();
+      if (trimmed.startsWith('context:')) return false;
+      if (trimmed.startsWith('agent:')) return false;
+      return true;
+    })
+    .join('\n');
+
+  return `---\n${cleaned}\n---${afterFrontmatter}`;
+}

package/compiler/transforms/hooks.js

@@ -0,0 +1,68 @@
+/**
+ * Hook Constraint Inlining
+ *
+ * Converts Claude Code hook behaviors into inline MUST/NEVER instructions.
+ * These get injected as a "Platform Constraints" section.
+ */
+
+const HOOK_CONSTRAINTS = [
+  {
+    id: 'secrets-scan',
+    instruction: 'MUST NOT: Never run commands containing hardcoded secrets, API keys, or tokens. Scan all shell commands for secret patterns before execution.',
+    relevantTools: ['Bash'],
+  },
+  {
+    id: 'auto-format',
+    instruction: 'MUST: After editing JS/TS files, ensure code follows project formatting conventions (Prettier/ESLint).',
+    relevantTools: ['Edit', 'Write'],
+  },
+  {
+    id: 'typecheck',
+    instruction: 'MUST: After editing .ts/.tsx files, verify TypeScript compilation succeeds (no type errors).',
+    relevantTools: ['Edit', 'Write'],
+  },
+  {
+    id: 'context-watch',
+    instruction: 'SHOULD: Monitor your context usage. If working on a long task, summarize progress before context fills up.',
+    relevantTools: [],
+  },
+  {
+    id: 'pre-compact',
+    instruction: 'MUST: Before summarizing/compacting context, save important decisions and progress to project files.',
+    relevantTools: [],
+  },
+  {
+    id: 'post-session',
+    instruction: 'SHOULD: Before ending, save architectural decisions and progress to .rune/ directory for future sessions.',
+    relevantTools: [],
+  },
+];
+
+/**
+ * Generate inline hook constraints section for non-Claude platforms
+ *
+ * @param {object} parsedSkill - parsed skill IR
+ * @param {object} adapter - platform adapter
+ * @returns {string} constraints section to inject, or empty string
+ */
+export function generateHookConstraints(parsedSkill, adapter) {
+  if (adapter.name === 'claude') return '';
+
+  // Filter to relevant constraints based on tool usage in this skill
+  const skillToolNames = parsedSkill.toolRefs.map(r => r.toolName);
+  const relevant = HOOK_CONSTRAINTS.filter(h =>
+    h.relevantTools.length === 0 || h.relevantTools.some(t => skillToolNames.includes(t))
+  );
+
+  if (relevant.length === 0) return '';
+
+  const lines = [
+    '',
+    '## Platform Constraints',
+    '',
+    ...relevant.map(h => `- ${h.instruction}`),
+    '',
+  ];
+
+  return lines.join('\n');
+}

package/compiler/transforms/subagents.js

@@ -0,0 +1,36 @@
+/**
+ * Subagent Transform
+ *
+ * Converts parallel agent/subagent execution instructions to sequential workflow.
+ * On non-Claude platforms, there is no multi-agent support.
+ */
+
+const PARALLEL_PATTERNS = [
+  { pattern: /Launch (\d+) parallel agents?/gi, replace: 'Execute the following $1 steps sequentially' },
+  { pattern: /as independent Task agents?/gi, replace: 'one at a time' },
+  { pattern: /PARALLEL EXECUTION:/gi, replace: 'SEQUENTIAL EXECUTION:' },
+  { pattern: /Run these? (?:as )?parallel (?:sub)?agents?/gi, replace: 'Run these steps in order' },
+  { pattern: /spawn (?:a )?(?:sub)?agent/gi, replace: 'execute the workflow' },
+  { pattern: /in a separate (?:sub)?agent/gi, replace: 'as the next step' },
+  { pattern: /Launch (?:a )?background agent/gi, replace: 'Execute in the background' },
+];
+
+/**
+ * Transform subagent/parallel execution instructions to sequential
+ *
+ * @param {string} body - skill markdown body
+ * @param {object} adapter - platform adapter
+ * @returns {string} transformed body
+ */
+export function transformSubagents(body, adapter) {
+  if (adapter.name === 'claude') return body;
+
+  let result = body;
+  for (const { pattern, replace } of PARALLEL_PATTERNS) {
+    result = result.replace(pattern, replace);
+  }
+
+  return adapter.transformSubagentInstruction
+    ? adapter.transformSubagentInstruction(result)
+    : result;
+}

package/compiler/transforms/tool-names.js

@@ -0,0 +1,60 @@
+/**
+ * Tool Name Transform
+ *
+ * Rewrites Claude Code-specific tool names to platform-generic language.
+ */
+
+// "Use `Tool` to ..." or "Use `Tool` for ..." → contextual rewrite
+const TOOL_INSTRUCTION_TO_PATTERN = /Use `(Read|Write|Edit|Glob|Grep|Bash|TodoWrite|Skill|Agent)` (?:to |for )/gi;
+
+// "Use `Tool`:" or "Use `Tool`." → direct tool usage
+const TOOL_INSTRUCTION_DIRECT_PATTERN = /Use `(Read|Write|Edit|Glob|Grep|Bash|TodoWrite|Skill|Agent)`(?=\s*[:.])/gi;
+
+// Standalone `Tool` reference in any context
+const TOOL_REF_PATTERN = /`(Read|Write|Edit|Glob|Grep|Bash|TodoWrite|Skill|Agent)`/g;
+
+// Action verbs for direct patterns (no "to" suffix)
+const DIRECT_ACTION = {
+  Read: 'Read the relevant files',
+  Write: 'Create the files',
+  Edit: 'Edit the files',
+  Glob: 'Find files by pattern',
+  Grep: 'Search file contents',
+  Bash: 'Run in the terminal',
+  TodoWrite: 'Track progress',
+  Skill: 'Follow the skill rules',
+  Agent: 'Execute the workflow',
+};
+
+/**
+ * Transform tool name references in skill body
+ *
+ * @param {string} body - skill markdown body
+ * @param {object} adapter - platform adapter with transformToolName method
+ * @returns {string} transformed body
+ */
+export function transformToolNames(body, adapter) {
+  // Skip passthrough adapter
+  if (adapter.name === 'claude') return body;
+
+  // First: "Use `Tool` to/for ..." patterns
+  let result = body.replace(TOOL_INSTRUCTION_TO_PATTERN, (match, toolName) => {
+    const mapped = adapter.transformToolName(toolName);
+    if (mapped === toolName) return match;
+    return mapped.charAt(0).toUpperCase() + mapped.slice(1) + ' to ';
+  });
+
+  // Second: "Use `Tool`:" or "Use `Tool`." patterns
+  result = result.replace(TOOL_INSTRUCTION_DIRECT_PATTERN, (match, toolName) => {
+    return DIRECT_ACTION[toolName] || match;
+  });
+
+  // Third: standalone `Tool` references
+  result = result.replace(TOOL_REF_PATTERN, (match, toolName) => {
+    const mapped = adapter.transformToolName(toolName);
+    if (mapped === toolName) return match;
+    return mapped;
+  });
+
+  return result;
+}

package/contexts/dev.md

@@ -0,0 +1,34 @@
+# Development Mode
+
+Behavioral context for active coding sessions. Prioritize action over analysis.
+
+## Principles
+
+- **Code first, explain after** — show working code, not paragraphs about what you'll do
+- **Working → Right → Clean** — get it running, make it correct, then refine
+- **Bias toward action** — if the path is 80% clear, start coding rather than analyzing further
+
+## Tool Priority
+
+```
+HIGH:    Edit, Write, Bash (run tests/build)
+MEDIUM:  Read (targeted files), Grep (specific patterns)
+LOW:     Glob (broad search), WebSearch (external docs)
+```
+
+## Behavioral Rules
+
+1. Read the file BEFORE editing — never guess at existing code
+2. Run tests after every meaningful change
+3. If stuck for >2 iterations on the same error, switch strategy:
+   - Try a different approach rather than debugging deeper
+   - Use `rune:debug` for structured root cause analysis
+4. Keep explanations to 1-2 sentences between code blocks
+5. Commit working increments — don't batch everything into one giant change
+
+## Anti-Patterns
+
+- Lengthy analysis before writing a single line of code
+- Reading 10+ files "for context" when 2-3 would suffice
+- Explaining what you're about to do instead of doing it
+- Over-engineering the first pass (violates Working → Right → Clean)

package/contexts/research.md

@@ -0,0 +1,43 @@
+# Research Mode
+
+Behavioral context for investigation, exploration, and understanding. Prioritize breadth and accuracy over speed.
+
+## Principles
+
+- **Read widely before concluding** — check 3+ sources before forming an opinion
+- **Map before moving** — understand the full landscape before recommending a path
+- **Evidence over intuition** — every claim should reference a file, doc, or search result
+
+## Tool Priority
+
+```
+HIGH:    Grep, Glob, Read, WebSearch, WebFetch
+MEDIUM:  Bash (non-destructive: git log, dependency checks)
+LOW:     Edit, Write (only for saving findings)
+```
+
+## Investigation Framework
+
+1. **Define the question** — what exactly are we trying to learn?
+2. **Internal scan** — search the codebase first (Grep, Glob, Read)
+3. **External lookup** — check docs, changelogs, GitHub issues (WebSearch, WebFetch)
+4. **Cross-reference** — validate findings against 2+ sources
+5. **Synthesize** — present findings with confidence levels:
+   - **Confirmed**: found in code/docs, verified
+   - **Likely**: strong evidence but not 100% confirmed
+   - **Uncertain**: limited evidence, needs more investigation
+
+## Behavioral Rules
+
+1. Never modify code in research mode — read-only exploration
+2. Present findings in structured format (tables, bullet points)
+3. Include file paths and line numbers for all code references
+4. Flag contradictions between sources rather than picking one silently
+5. Estimate scope/effort when the research is for planning purposes
+
+## Anti-Patterns
+
+- Jumping to a solution after reading one file
+- Modifying code "while we're here" during research
+- Presenting opinions as facts without evidence trail
+- Stopping research early because the first answer looks plausible

package/contexts/review.md

@@ -0,0 +1,55 @@
+# Review Mode
+
+Behavioral context for evaluating code quality, correctness, and security. Prioritize thoroughness and constructive feedback.
+
+## Principles
+
+- **Read everything in scope** — review the full diff, not just highlighted sections
+- **Severity matters** — distinguish blockers from suggestions, label clearly
+- **Constructive over critical** — pair every issue with a concrete fix or alternative
+
+## Tool Priority
+
+```
+HIGH:    Read (full files), Grep (pattern search), Bash (git diff)
+MEDIUM:  Glob (find related files), WebSearch (verify best practices)
+LOW:     Edit, Write (only for review notes/reports)
+```
+
+## Review Dimensions
+
+Check each dimension systematically:
+
+| Dimension | What to Check |
+|-----------|--------------|
+| **Correctness** | Logic errors, off-by-one, null handling, async/await misuse |
+| **Security** | OWASP patterns, secret exposure, input validation |
+| **Performance** | N+1 queries, unnecessary re-renders, missing indexes |
+| **Maintainability** | Naming clarity, function length, coupling, duplication |
+| **Completeness** | Error handling, edge cases, loading/error states, tests |
+| **Conventions** | Project patterns, naming style, file organization |
+
+## Severity Scale
+
+```
+BLOCK     — Must fix before merge (bugs, security, data loss risk)
+HIGH      — Should fix before merge (logic issues, missing validation)
+MEDIUM    — Fix soon (code quality, minor performance)
+LOW       — Nice to have (style preference, minor improvements)
+PRAISE    — Highlight good patterns worth replicating
+```
+
+## Behavioral Rules
+
+1. Always include at least one PRAISE item — acknowledge what's done well
+2. Group findings by file, then by severity (BLOCK first)
+3. Show the problematic code AND the suggested fix side-by-side
+4. Check git blame for context — is this new code or existing?
+5. Verify the fix actually works before suggesting it
+
+## Anti-Patterns
+
+- Drive-by "LGTM" without reading the code
+- Nitpicking style while missing logic bugs
+- Suggesting rewrites when the code is correct and readable
+- Reviewing only the files explicitly mentioned, ignoring related changes