claudecode-omc 5.3.0 → 5.5.0

package/src/guidelines/apply.js

@@ -0,0 +1,152 @@
+const fs = require('fs');
+const fsp = require('fs/promises');
+const path = require('path');
+const { getProjectRoot } = require('../config/paths');
+const { sha256 } = require('./optimizer');
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+async function ensureDir(dirPath) {
+  await fsp.mkdir(dirPath, { recursive: true });
+}
+
+async function writeJson(filePath, value) {
+  await ensureDir(path.dirname(filePath));
+  await fsp.writeFile(filePath, JSON.stringify(value, null, 2) + '\n', 'utf8');
+}
+
+async function writeText(filePath, value) {
+  await ensureDir(path.dirname(filePath));
+  await fsp.writeFile(filePath, value, 'utf8');
+}
+
+function validateResult(result) {
+  assert(result && typeof result === 'object', 'Result file must contain a JSON object.');
+  assert(result.version === 1, 'Result file must set "version": 1.');
+  assert(typeof result.generatedBy === 'string' && result.generatedBy.trim(), 'Result file must include generatedBy.');
+  assert(typeof result.summary === 'string' && result.summary.trim(), 'Result file must include summary.');
+  assert(
+    typeof result.runtimeGuidelinesMarkdown === 'string' &&
+    result.runtimeGuidelinesMarkdown.trim().startsWith('# '),
+    'runtimeGuidelinesMarkdown must be markdown starting with a top-level heading.'
+  );
+  assert(Array.isArray(result.decisions), 'Result file must include a decisions array.');
+  assert(Array.isArray(result.conflicts), 'Result file must include a conflicts array.');
+
+  for (const [index, decision] of result.decisions.entries()) {
+    assert(typeof decision === 'object' && decision, `decisions[${index}] must be an object.`);
+    assert(typeof decision.action === 'string' && decision.action.trim(), `decisions[${index}].action is required.`);
+    assert(Array.isArray(decision.sourceSectionIds), `decisions[${index}].sourceSectionIds must be an array.`);
+    assert(typeof decision.title === 'string' && decision.title.trim(), `decisions[${index}].title is required.`);
+    assert(typeof decision.rationale === 'string' && decision.rationale.trim(), `decisions[${index}].rationale is required.`);
+  }
+
+  for (const [index, conflict] of result.conflicts.entries()) {
+    assert(typeof conflict === 'object' && conflict, `conflicts[${index}] must be an object.`);
+    assert(Array.isArray(conflict.sourceSectionIds), `conflicts[${index}].sourceSectionIds must be an array.`);
+    assert(typeof conflict.resolution === 'string' && conflict.resolution.trim(), `conflicts[${index}].resolution is required.`);
+  }
+}
+
+function buildDecisionLog(result) {
+  const lines = [
+    '# Guideline Optimization Decision Log',
+    '',
+    `Generated by: ${result.generatedBy}`,
+    '',
+    `Summary: ${result.summary}`,
+    '',
+    '## Decisions',
+    '',
+  ];
+
+  for (const decision of result.decisions) {
+    lines.push(`### ${decision.title}`);
+    lines.push(`- Action: ${decision.action}`);
+    lines.push(`- Source sections: ${decision.sourceSectionIds.join(', ') || 'none'}`);
+    lines.push(`- Rationale: ${decision.rationale}`);
+    lines.push('');
+  }
+
+  lines.push('## Conflicts');
+  lines.push('');
+
+  if (result.conflicts.length === 0) {
+    lines.push('- None');
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  for (const conflict of result.conflicts) {
+    lines.push(`- Sections: ${conflict.sourceSectionIds.join(', ') || 'none'}`);
+    lines.push(`  Resolution: ${conflict.resolution}`);
+  }
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+async function applyGuidelineResult(options = {}) {
+  const root = getProjectRoot();
+  assert(options.resultFile, 'apply requires --result-file <path>.');
+
+  const resultFile = path.resolve(root, options.resultFile);
+  assert(fs.existsSync(resultFile), `Result file not found: ${resultFile}`);
+
+  const result = readJson(resultFile);
+  validateResult(result);
+
+  const runtimePath = path.join(root, '.local', 'guidelines', 'CLAUDE.md');
+  const outputDir = options.outputDir
+    ? path.resolve(root, options.outputDir)
+    : path.join(root, '.omc', 'guidelines');
+  const latestDir = path.join(outputDir, 'latest');
+  const appliedDir = path.join(outputDir, 'applied');
+  const appliedRunDir = path.join(appliedDir, new Date().toISOString().replace(/[:.]/g, '-'));
+  const runtimeMarkdown = result.runtimeGuidelinesMarkdown.trimEnd() + '\n';
+  const appliedSummary = {
+    appliedAt: new Date().toISOString(),
+    generatedBy: result.generatedBy,
+    summary: result.summary,
+    resultFile,
+    runtimePath,
+    runtimeGuidelinesHash: sha256(runtimeMarkdown),
+    decisions: result.decisions.length,
+    conflicts: result.conflicts.length,
+  };
+
+  if (!options.dryRun) {
+    await writeText(runtimePath, runtimeMarkdown);
+    await writeText(path.join(latestDir, 'current-local-guidelines.md'), runtimeMarkdown);
+    await writeJson(path.join(latestDir, 'result.json'), result);
+    await writeText(path.join(latestDir, 'decision-log.md'), buildDecisionLog(result));
+    await writeJson(path.join(latestDir, 'applied-summary.json'), appliedSummary);
+
+    await writeText(path.join(appliedRunDir, 'current-local-guidelines.md'), runtimeMarkdown);
+    await writeJson(path.join(appliedRunDir, 'result.json'), result);
+    await writeText(path.join(appliedRunDir, 'decision-log.md'), buildDecisionLog(result));
+    await writeJson(path.join(appliedRunDir, 'applied-summary.json'), appliedSummary);
+  }
+
+  return {
+    resultFile,
+    runtimePath,
+    latestDir,
+    appliedRunDir,
+    appliedSummary,
+  };
+}
+
+module.exports = {
+  applyGuidelineResult,
+  buildDecisionLog,
+  validateResult,
+};

package/src/guidelines/optimizer.js

@@ -0,0 +1,325 @@
+/* eslint-disable no-console */
+const fs = require('fs');
+const fsp = require('fs/promises');
+const path = require('path');
+const crypto = require('crypto');
+const { getProjectRoot, getSourceArtifactDir } = require('../config/paths');
+const { readConfig } = require('../config/sources');
+const { loadClaudeMd } = require('../merge/claude-md-merger');
+
+function sanitizeSlug(value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 64) || 'untitled';
+}
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function getGuidelineSources(root, requestedSources = []) {
+  const config = readConfig();
+  const requested = new Set(requestedSources);
+
+  return Object.entries(config.sources)
+    .sort(([, a], [, b]) => a.priority - b.priority)
+    .filter(([name, source]) => {
+      if (source.role === 'reference') return false;
+      if (requested.size > 0 && !requested.has(name)) return false;
+      const artifacts = source.artifacts || [];
+      return artifacts.includes('guidelines') || artifacts.includes('claude-md');
+    })
+    .map(([name, source]) => {
+      const dir = getSourceArtifactDir(name, 'guidelines', root);
+      return { name, source, dir };
+    })
+    .filter(({ dir }) => fs.existsSync(dir))
+    .map(({ name, source, dir }) => {
+      const content = loadClaudeMd(dir);
+      if (!content) return null;
+      return {
+        sourceName: name,
+        priority: source.priority,
+        role: source.role || null,
+        dir,
+        content,
+      };
+    })
+    .filter(Boolean);
+}
+
+function extractDocumentTitle(content) {
+  const firstHeader = content.match(/^#\s+(.+)$/m);
+  return firstHeader ? firstHeader[1].trim() : 'Guidelines';
+}
+
+function splitGuidelineSections(content, sourceName) {
+  const normalized = content.replace(/\r\n/g, '\n').trim();
+  const docTitle = extractDocumentTitle(normalized);
+  const lines = normalized.split('\n');
+  const sections = [];
+  let current = null;
+  let sectionIndex = 0;
+
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      if (current && current.body.trim()) {
+        sections.push(current);
+      }
+      sectionIndex += 1;
+      current = {
+        id: `${sourceName}:${sectionIndex}`,
+        sourceName,
+        title: line.replace(/^##\s+/, '').trim(),
+        body: '',
+      };
+      continue;
+    }
+
+    if (!current) {
+      current = {
+        id: `${sourceName}:0`,
+        sourceName,
+        title: docTitle,
+        body: '',
+      };
+    }
+
+    current.body += (current.body ? '\n' : '') + line;
+  }
+
+  if (current && current.body.trim()) {
+    sections.push(current);
+  }
+
+  return sections
+    .map((section, index) => ({
+      ...section,
+      id: `${sourceName}:${index + 1}`,
+      body: section.body.trim(),
+      slug: sanitizeSlug(section.title),
+    }))
+    .filter(section => section.body.length > 0);
+}
+
+function buildOptimizerPrompt({ sources, sections, currentLocalGuidelines, outputPath }) {
+  const sourceSummary = sources
+    .map(source => `- ${source.sourceName} (priority ${source.priority}${source.role ? `, role ${source.role}` : ''})`)
+    .join('\n');
+
+  const sectionText = sections.map((section) => (
+    `### ${section.id} — ${section.title}\n` +
+    `Source: ${section.sourceName}\n\n` +
+    `${section.body}\n`
+  )).join('\n');
+
+  const currentLocalText = currentLocalGuidelines
+    ? currentLocalGuidelines.trim()
+    : '_No current local guidelines file found._';
+
+  return `# Guideline Optimizer Input
+
+You are maintaining OMC's canonical runtime guidelines.
+
+## Goal
+
+Produce an improved \`CLAUDE.md\` section for OMC by semantically deduplicating,
+merging, rewriting, and prioritizing the guideline material collected below.
+
+## Constraints
+
+- This is a maintainer workflow. The optimizer logic itself does not ship to end users.
+- The runtime output must stay concise, high-signal, and suitable for always-on use.
+- Prefer rewriting combined rules over stacking near-duplicates.
+- Preserve behaviorally important constraints even if wording changes.
+- Surface genuine conflicts explicitly instead of silently averaging them away.
+- The final markdown should be written to \`${outputPath}\`.
+- Output markdown body only. Do not include surrounding commentary.
+
+## Source Summary
+
+${sourceSummary}
+
+## Current Local Guidelines
+
+${currentLocalText}
+
+## Extracted Source Sections
+
+${sectionText}
+
+## Required Output Shape
+
+1. A canonical markdown document body suitable for \`${outputPath}\`
+2. Short internal rationale notes for:
+   - merged rules
+   - dropped rules
+   - unresolved conflicts
+
+When two sections are semantically overlapping, prefer a single clearer rule.
+When one section is a stronger, more specific operationalization of another,
+keep the stronger wording and note the collapse in rationale.`;
+}
+
+async function ensureDir(dirPath) {
+  await fsp.mkdir(dirPath, { recursive: true });
+}
+
+async function writeJson(filePath, value) {
+  await ensureDir(path.dirname(filePath));
+  await fsp.writeFile(filePath, JSON.stringify(value, null, 2) + '\n', 'utf8');
+}
+
+async function writeText(filePath, value) {
+  await ensureDir(path.dirname(filePath));
+  await fsp.writeFile(filePath, value, 'utf8');
+}
+
+function buildNextSteps({ summary, latestDir }) {
+  const lines = [
+    '# Guideline Optimizer Next Steps',
+    '',
+    'This workflow is for Claude Code CLI or Codex operating inside the OMC repository.',
+    '',
+    '## Read First',
+    '',
+    `- ${path.join(latestDir, 'optimizer-input.md')}`,
+    `- ${path.join(latestDir, 'sections.json')}`,
+    `- ${path.join(latestDir, 'sources.json')}`,
+    `- ${path.join(summary.root, '.maintainer', 'skills', 'guideline-optimizer', 'SKILL.md')}`,
+    '',
+    '## Edit Target',
+    '',
+    `- ${summary.outputPath}`,
+    '',
+    '## Required Verification',
+    '',
+    '```bash',
+    'node bin/omc-manage.js setup --dry-run --type guidelines',
+    'node bin/omc-manage.js artifact list --type guidelines',
+    '```',
+    '',
+    '## Rules',
+    '',
+    '- Apply semantic merging, not text-level dedupe.',
+    '- Keep maintainer reasoning out of the runtime guideline file.',
+    '- Do not move maintainer-only workflow prompts into `.local/skills/`.',
+    '',
+    '## Structured Result Contract',
+    '',
+    'Create a JSON file with this shape, then apply it with the CLI:',
+    '',
+    '```json',
+    '{',
+    '  "version": 1,',
+    '  "generatedBy": "claude-code | codex | other",',
+    '  "summary": "short description of what changed",',
+    '  "runtimeGuidelinesMarkdown": "# Coding Discipline\\n...",',
+    '  "decisions": [',
+    '    {',
+    '      "action": "keep | merge | rewrite | drop",',
+    '      "sourceSectionIds": ["local:2"],',
+    '      "title": "Think Before Coding",',
+    '      "rationale": "why this rule stayed or changed"',
+    '    }',
+    '  ],',
+    '  "conflicts": [',
+    '    {',
+    '      "sourceSectionIds": ["a:2", "b:4"],',
+    '      "resolution": "how the conflict was resolved"',
+    '    }',
+    '  ]',
+    '}',
+    '```',
+    '',
+    'Apply it with:',
+    '',
+    '```bash',
+    'node bin/omc-manage.js guidelines apply --result-file /absolute/path/to/result.json',
+    'node bin/omc-manage.js setup --dry-run --type guidelines',
+    '```',
+  ];
+
+  return lines.join('\n') + '\n';
+}
+
+async function optimizeGuidelines(options = {}) {
+  const root = getProjectRoot();
+  const selectedSources = options.sources || [];
+  const sources = getGuidelineSources(root, selectedSources);
+
+  if (sources.length === 0) {
+    throw new Error('No guideline sources found. Add a guidelines source or create .local/guidelines/CLAUDE.md.');
+  }
+
+  const sections = sources.flatMap(source => splitGuidelineSections(source.content, source.sourceName));
+  const localGuidelinesPath = path.join(root, '.local', 'guidelines', 'CLAUDE.md');
+  const currentLocalGuidelines = fs.existsSync(localGuidelinesPath)
+    ? fs.readFileSync(localGuidelinesPath, 'utf8')
+    : '';
+
+  const runId = new Date().toISOString().replace(/[:.]/g, '-');
+  const baseOutputDir = options.outputDir
+    ? path.resolve(root, options.outputDir)
+    : path.join(root, '.omc', 'guidelines');
+  const latestDir = path.join(baseOutputDir, 'latest');
+  const runDir = path.join(baseOutputDir, 'runs', runId);
+
+  const summary = {
+    runId,
+    root,
+    sourceCount: sources.length,
+    sectionCount: sections.length,
+    outputPath: localGuidelinesPath,
+    currentLocalGuidelinesHash: sha256(currentLocalGuidelines || ''),
+    latestDir,
+    runDir,
+    sources: sources.map(source => ({
+      sourceName: source.sourceName,
+      priority: source.priority,
+      role: source.role,
+      dir: source.dir,
+      title: extractDocumentTitle(source.content),
+      contentHash: sha256(source.content),
+    })),
+  };
+
+  const prompt = buildOptimizerPrompt({
+    sources: summary.sources,
+    sections,
+    currentLocalGuidelines,
+    outputPath: localGuidelinesPath,
+  });
+
+  if (!options.dryRun) {
+    await ensureDir(latestDir);
+    await ensureDir(runDir);
+    const nextSteps = buildNextSteps({ summary, latestDir });
+
+    await writeJson(path.join(latestDir, 'summary.json'), summary);
+    await writeJson(path.join(latestDir, 'sections.json'), sections);
+    await writeJson(path.join(latestDir, 'sources.json'), summary.sources);
+    await writeText(path.join(latestDir, 'optimizer-input.md'), prompt);
+    await writeText(path.join(latestDir, 'current-local-guidelines.md'), currentLocalGuidelines || '');
+    await writeText(path.join(latestDir, 'next-steps.md'), nextSteps);
+
+    await writeJson(path.join(runDir, 'summary.json'), summary);
+    await writeJson(path.join(runDir, 'sections.json'), sections);
+    await writeJson(path.join(runDir, 'sources.json'), summary.sources);
+    await writeText(path.join(runDir, 'optimizer-input.md'), prompt);
+    await writeText(path.join(runDir, 'current-local-guidelines.md'), currentLocalGuidelines || '');
+    await writeText(path.join(runDir, 'next-steps.md'), nextSteps);
+  }
+
+  return { summary, prompt };
+}
+
+module.exports = {
+  optimizeGuidelines,
+  getGuidelineSources,
+  splitGuidelineSections,
+  buildOptimizerPrompt,
+  sha256,
+};

package/src/merge/claude-md-merger.js

@@ -25,28 +25,51 @@ function assembleSections(sections) {
   return sections.map(s => s.content).join('\n\n').trimEnd() + '\n';
 }
 
+function getMarkers(markerKey) {
+  return {
+    start: `<!-- OMC:${markerKey}:START -->`,
+    end: `<!-- OMC:${markerKey}:END -->`,
+  };
+}
+
+function replaceFirstMatchingBlock(result, markerKeys, block) {
+  for (const markerKey of markerKeys) {
+    const { start, end } = getMarkers(markerKey);
+    const startIdx = result.indexOf(start);
+    const endIdx = result.indexOf(end);
+
+    if (startIdx !== -1 && endIdx !== -1) {
+      return result.slice(0, startIdx) + block + result.slice(endIdx + end.length);
+    }
+  }
+
+  return null;
+}
+
 /**
  * Merge new sections into an existing CLAUDE.md
  * Wraps each source block in OMC markers to allow idempotent updates
  */
-function mergeIntoExisting(existing, sections) {
+function mergeIntoExisting(existing, sections, options = {}) {
+  const markerNamespace = options.markerNamespace || 'claude-md';
   let result = existing;
 
   for (const { sourceName, content } of sections) {
-    const startMarker = `<!-- OMC:${sourceName}:START -->`;
-    const endMarker = `<!-- OMC:${sourceName}:END -->`;
+    const markerKey = `${markerNamespace}:${sourceName}`;
+    const { start: startMarker, end: endMarker } = getMarkers(markerKey);
     const block = `${startMarker}\n${content.trimEnd()}\n${endMarker}`;
+    const legacyMarkerKeys = options.legacyMarkerKeys
+      ? options.legacyMarkerKeys(sourceName)
+      : [sourceName];
+    const replaced = replaceFirstMatchingBlock(result, [markerKey, ...legacyMarkerKeys], block);
 
-    const startIdx = result.indexOf(startMarker);
-    const endIdx = result.indexOf(endMarker);
-
-    if (startIdx !== -1 && endIdx !== -1) {
-      // Replace existing block
-      result = result.slice(0, startIdx) + block + result.slice(endIdx + endMarker.length);
-    } else {
-      // Append new block
-      result = result.trimEnd() + '\n\n' + block + '\n';
+    if (replaced !== null) {
+      result = replaced;
+      continue;
     }
+
+    // Append new block
+    result = result.trimEnd() + '\n\n' + block + '\n';
   }
 
   return result;

package/templates/merge-config.json

@@ -7,5 +7,16 @@
     { "name": "oh-my-claudecode", "priority": 2 },
     { "name": "superpowers", "priority": 3 }
   ],
-  "preferences": {}
+  "preferences": {},
+  "exclude": {
+    "skills": [
+      "ask",
+      "ccg",
+      "multi-model-research",
+      "test-gen",
+      "release",
+      "omc-teams",
+      "using-superpowers"
+    ]
+  }
 }

package/bundled/upstream/oh-my-claudecode/skills/omc-doctor/skill-debugger.md

@@ -1,101 +0,0 @@
----
-description: Debug why a Claude Code skill isn't triggering when expected
----
-
-# Skill Debugger
-
-[SKILL DEBUG MODE ACTIVATED]
-
-## Objective
-
-Systematically diagnose why a skill isn't triggering as expected. Identify root causes and provide actionable fixes.
-
-## Debugging Workflow
-
-### Step 1: Identify Target Skill
-
-Ask the user which skill isn't working, or infer from context. Then verify it exists:
-
-```bash
-# Check plugin skills
-ls ~/.claude/plugins/cache/omc/oh-my-claudecode/*/skills/<skill-name>/ 2>/dev/null
-
-# Check global skills
-ls ~/.claude/skills/<skill-name>/ 2>/dev/null
-```
-
-### Step 2: Validate SKILL.md
-
-Use the `Read` tool to read the target skill's `SKILL.md` and check:
-
-- [ ] File exists and is readable
-- [ ] YAML frontmatter has `---` delimiters
-- [ ] `name:` field matches folder name
-- [ ] `description:` is 50-150 characters, specific, not vague
-- [ ] No vague words ("helps", "assists", "various")
-
-### Step 3: Analyze Description Quality
-
-Compare the skill description against what the user asked. Check:
-
-- Does the description contain keywords the user would naturally say?
-- Is there a `<Use_When>` or "When to Use" section?
-- Are there at least 3 usage examples?
-
-### Step 4: Check for Conflicts
-
-Scan all installed skills for overlapping descriptions:
-
-```bash
-# List all skill descriptions
-for dir in ~/.claude/plugins/cache/omc/oh-my-claudecode/*/skills/*/; do
-  if [ -f "$dir/SKILL.md" ]; then
-    echo "=== $(basename $dir) ==="
-    head -5 "$dir/SKILL.md"
-    echo
-  fi
-done
-```
-
-Look for skills with similar keywords or overlapping use cases.
-
-### Step 5: Check Command Registration
-
-Verify if the skill has a corresponding slash command:
-
-```bash
-ls ~/.claude/plugins/cache/omc/oh-my-claudecode/*/commands/<skill-name>.md 2>/dev/null
-```
-
-If no command exists, the skill relies purely on semantic matching.
-
-## Diagnosis Report Format
-
-```
-## Skill Debug Report
-
-Skill: <name>
-Path: <location>
-Status: OK / NOT TRIGGERING / CONFLICT
-
-### Issues Found
-| Priority | Issue | Fix |
-|----------|-------|-----|
-| CRITICAL | ... | ... |
-| HIGH | ... | ... |
-| MEDIUM | ... | ... |
-
-### Recommendations
-1. [Specific fix with before/after examples]
-2. [...]
-```
-
-## Common Fixes
-
-| Problem | Fix |
-|---------|-----|
-| Description too vague | Add specific keywords and use cases |
-| No trigger keywords | Add words users would naturally say |
-| Wrong skill triggers | Differentiate descriptions between conflicting skills |
-| Skill not found | Check installation path and folder name |
-| No slash command | Create `commands/<name>.md` for explicit triggering |