contextos-agents 2.1.0 → 2.2.0

package/bin/lib/git-snapshot.js

@@ -61,7 +61,7 @@ function getStagedFiles(cwd = process.cwd()) {
   try {
     const output = execFileSync(
       'git',
-      ['diff', '--cached', '-z', '--name-status'],
+      ['-c', 'core.quotepath=false', 'diff', '--cached', '-z', '--name-status', '--no-ext-diff'],
       { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
     );
 
@@ -104,78 +104,105 @@ function getStagedFiles(cwd = process.cwd()) {
 
 /**
  * Reads the content of a file directly from the Git staged index.
+ * Fails closed with an error if the staged blob cannot be read.
  *
  * @param {string} relativePath - Path relative to repo root
  * @param {string} [cwd=process.cwd()] - Working directory
- * @returns {Buffer|null} Staged file buffer or null if deleted/missing
+ * @returns {Buffer} Staged file buffer
  */
 function getStagedBlob(relativePath, cwd = process.cwd()) {
+  const posixPath = relativePath.replace(/\\/g, '/');
   try {
-    const posixPath = relativePath.replace(/\\/g, '/');
-    const buf = execFileSync('git', ['show', `:${posixPath}`], {
-      cwd,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      maxBuffer: 10 * 1024 * 1024,
-    });
+    const buf = execFileSync(
+      'git',
+      ['--literal-pathspecs', 'show', `:${posixPath}`],
+      {
+        cwd,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        maxBuffer: 10 * 1024 * 1024,
+      }
+    );
     return buf;
   } catch (err) {
-    // If file was deleted or unreadable in index, return null
-    return null;
+    const errMsg = err.stderr ? err.stderr.toString('utf8').trim() : err.message;
+    throw new Error(`Failed to read staged blob for "${posixPath}": ${errMsg}`);
   }
 }
 
 /**
  * Extracts added lines from git diff --cached -U0 for each staged file.
  * Returns only lines that were added (+), excluding diff headers and deleted lines (-).
+ * Uses --literal-pathspecs, --no-ext-diff, and --no-textconv for strict path isolation.
  *
  * @param {string} [cwd=process.cwd()] - Working directory
+ * @param {string[]} [files=null] - Optional list of staged file paths. If omitted, discovered via getStagedFiles.
  * @returns {Map<string, Array<{ line: number, content: string }>>} Added lines by file
  */
-function getStagedAddedLines(cwd = process.cwd()) {
+function getStagedAddedLines(cwd = process.cwd(), files = null) {
   const addedLinesByFile = new Map();
 
-  try {
-    const diffOutput = execFileSync('git', ['diff', '--cached', '-U0'], {
-      cwd,
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-      maxBuffer: 10 * 1024 * 1024,
-    });
-
-    if (!diffOutput) return addedLinesByFile;
-
-    const lines = diffOutput.split(/\r?\n/);
-    let currentFile = null;
-    let currentLineNum = 0;
+  let targetFiles = files;
+  if (!targetFiles) {
+    const staged = getStagedFiles(cwd);
+    targetFiles = staged.filter(e => e.status !== 'D').map(e => e.path);
+  }
 
-    for (const line of lines) {
-      if (line.startsWith('+++ b/')) {
-        currentFile = line.slice(6).trim();
-        if (!addedLinesByFile.has(currentFile)) {
-          addedLinesByFile.set(currentFile, []);
-        }
-      } else if (line.startsWith('@@ ')) {
-        // Parse @@ -a,b +c,d @@ to get current target line number
-        const match = line.match(/\+([0-9]+)(?:,([0-9]+))?/);
-        if (match) {
-          currentLineNum = parseInt(match[1], 10);
+  for (const filePath of targetFiles) {
+    try {
+      const posixPath = filePath.replace(/\\/g, '/');
+      const diffOutput = execFileSync(
+        'git',
+        [
+          '--literal-pathspecs',
+          '-c', 'core.quotepath=false',
+          'diff',
+          '--cached',
+          '-U0',
+          '--no-ext-diff',
+          '--no-textconv',
+          '--',
+          posixPath,
+        ],
+        {
+          cwd,
+          encoding: 'utf8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+          maxBuffer: 10 * 1024 * 1024,
         }
-      } else if (line.startsWith('+') && !line.startsWith('+++')) {
-        if (currentFile) {
+      );
+
+      if (!diffOutput) continue;
+
+      const lines = diffOutput.split(/\r?\n/);
+      let currentLineNum = 0;
+      const fileAddedLines = [];
+
+      for (const line of lines) {
+        if (line.startsWith('@@ ')) {
+          // Parse @@ -a,b +c,d @@ to get current target line number
+          const match = line.match(/\+([0-9]+)(?:,([0-9]+))?/);
+          if (match) {
+            currentLineNum = parseInt(match[1], 10);
+          }
+        } else if (line.startsWith('+') && !line.startsWith('+++')) {
           const content = line.slice(1);
-          addedLinesByFile.get(currentFile).push({
+          fileAddedLines.push({
             line: currentLineNum,
             content,
           });
+          currentLineNum++;
         }
-        currentLineNum++;
       }
-    }
 
-    return addedLinesByFile;
-  } catch {
-    return addedLinesByFile;
+      if (fileAddedLines.length > 0) {
+        addedLinesByFile.set(filePath, fileAddedLines);
+      }
+    } catch (err) {
+      throw new Error(`Failed to extract staged diff for "${filePath}": ${err.message}`);
+    }
   }
+
+  return addedLinesByFile;
 }
 
 module.exports = {

package/bin/lib/scan.js

@@ -127,18 +127,25 @@ const PLACEHOLDER_PATTERNS = [
   },
 ];
 
-// Exempt path substrings (e.g. test fixtures, test files, lockfiles)
-const EXEMPT_PATH_SUBSTRINGS = [
-  path.join('tests', ''),
-  path.join('.git', ''),
+// Exempt path segments and exact files (e.g. test fixtures, test files)
+const EXEMPT_SEGMENTS = new Set([
+  'tests',
+  '.git',
   'node_modules',
-  'check-secrets.js',
-  'scan.js',
-];
+]);
+
+const EXEMPT_EXACT_PATHS = new Set([
+  'scripts/check-secrets.js',
+  'bin/lib/scan.js',
+]);
 
 function isExempt(filePath) {
-  const norm = path.normalize(filePath);
-  return EXEMPT_PATH_SUBSTRINGS.some(exempt => norm.includes(exempt));
+  const norm = filePath.replace(/\\/g, '/');
+  if (EXEMPT_EXACT_PATHS.has(norm)) {
+    return true;
+  }
+  const segments = norm.split('/');
+  return segments.some(seg => EXEMPT_SEGMENTS.has(seg));
 }
 
 function redact(str) {
@@ -147,7 +154,7 @@ function redact(str) {
 }
 
 /**
- * Checks if a relative path matches a glob pattern or prefix.
+ * Checks if a relative path matches a glob pattern or prefix with strict segment boundaries.
  */
 function matchesScope(filePath, pattern) {
   const normFile = filePath.replace(/\\/g, '/').toLowerCase();
@@ -155,15 +162,16 @@ function matchesScope(filePath, pattern) {
 
   if (normPattern.endsWith('/**')) {
     const prefix = normPattern.slice(0, -3);
-    return normFile.startsWith(prefix);
+    return normFile === prefix || normFile.startsWith(prefix + '/');
   }
   if (normPattern.endsWith('/*')) {
     const prefix = normPattern.slice(0, -2);
+    if (!normFile.startsWith(prefix + '/')) return false;
     const rest = normFile.slice(prefix.length + 1);
-    return normFile.startsWith(prefix) && !rest.includes('/');
+    return !rest.includes('/');
   }
   if (normPattern.includes('*')) {
-    const reg = new RegExp('^' + normPattern.replace(/\./g, '\\.').replace(/\*/g, '.*') + '$');
+    const reg = new RegExp('^' + normPattern.replace(/\./g, '\\.').replace(/\*/g, '[^/]*') + '$');
     return reg.test(normFile);
   }
   return normFile === normPattern || normFile.startsWith(normPattern + '/');
@@ -191,17 +199,26 @@ function runScan(options = {}) {
 
   const checkSecrets = options.secrets !== false;
   const checkPlaceholders = Boolean(options.placeholders);
-  const scopeFile = options.scope || null;
   const enforce = Boolean(options.enforce);
 
+  let targetScopeFile = options.scope || null;
+  let scopeStatus = 'not_configured';
+
+  if (!targetScopeFile) {
+    const defaultScope = path.join(gitRoot, '.agents', 'task-scope.json');
+    if (fs.existsSync(defaultScope)) {
+      targetScopeFile = '.agents/task-scope.json';
+    }
+  }
+
   let allowedScopePatterns = null;
-  if (scopeFile) {
-    const resolvedScopePath = path.resolve(gitRoot, scopeFile);
+  if (targetScopeFile) {
+    const resolvedScopePath = path.resolve(gitRoot, targetScopeFile);
     if (!fs.existsSync(resolvedScopePath)) {
       return {
         ok: false,
         code: 2,
-        error: `Scope file not found: ${scopeFile}`,
+        error: `Scope file not found: ${targetScopeFile}`,
         findings: [],
         stats: { filesScanned: 0, violations: 0 },
       };
@@ -218,6 +235,7 @@ function runScan(options = {}) {
         }
       }
       allowedScopePatterns = list;
+      scopeStatus = `active (${targetScopeFile})`;
     } catch (err) {
       return {
         ok: false,
@@ -243,17 +261,28 @@ function runScan(options = {}) {
   }
 
   const findings = [];
-  const addedLinesMap = checkPlaceholders ? getStagedAddedLines(gitRoot) : new Map();
+  let addedLinesMap = new Map();
+  if (checkPlaceholders) {
+    try {
+      const activePaths = stagedEntries.filter(e => e.status !== 'D').map(e => e.path);
+      addedLinesMap = getStagedAddedLines(gitRoot, activePaths);
+    } catch (err) {
+      return {
+        ok: false,
+        code: 2,
+        error: `Failed to inspect staged added lines: ${err.message}`,
+        findings: [],
+        stats: { filesScanned: stagedEntries.length, violations: 0 },
+      };
+    }
+  }
 
   for (const entry of stagedEntries) {
-    // Skip deleted files from content and blocked filename checks
-    if (entry.status === 'D') continue;
-
     const relPath = entry.path;
     const baseName = path.basename(relPath).toLowerCase();
     const extName = path.extname(relPath).toLowerCase();
 
-    // 1. Scope Containment Check
+    // 1. Scope Containment Check (checked for ALL staged actions: added, modified, deleted, renamed)
     if (allowedScopePatterns) {
       const inScope = allowedScopePatterns.some(p => matchesScope(relPath, p));
       if (!inScope) {
@@ -265,8 +294,23 @@ function runScan(options = {}) {
           details: `Staged file "${relPath}" is outside allowed task scope`,
         });
       }
+      if (entry.oldPath) {
+        const oldInScope = allowedScopePatterns.some(p => matchesScope(entry.oldPath, p));
+        if (!oldInScope) {
+          findings.push({
+            ruleId: 'SCOPE-001',
+            file: entry.oldPath,
+            type: 'Scope Violation',
+            severity: 'error',
+            details: `Source file of rename "${entry.oldPath}" is outside allowed task scope`,
+          });
+        }
+      }
     }
 
+    // Skip deleted files from content and blocked filename checks
+    if (entry.status === 'D') continue;
+
     // 2. Blocked Exact Names Check
     if (checkSecrets && BLOCKED_EXACT_NAMES.has(baseName)) {
       findings.push({
@@ -294,12 +338,43 @@ function runScan(options = {}) {
     // Skip content scan for exempt paths
     if (isExempt(relPath)) continue;
 
-    // Read blob from index
-    const blob = getStagedBlob(relPath, gitRoot);
-    if (!blob) continue;
+    // Read blob from index (fails closed with code 2 on read errors in any mode)
+    let blob;
+    try {
+      blob = getStagedBlob(relPath, gitRoot);
+    } catch (err) {
+      return {
+        ok: false,
+        code: 2,
+        error: `Failed to read staged blob for "${relPath}": ${err.message}`,
+        findings,
+        stats: { filesScanned: stagedEntries.length, violations: findings.length },
+      };
+    }
 
-    // Skip large files (> 2MB)
-    if (blob.length > 2 * 1024 * 1024) continue;
+    if (!blob) {
+      return {
+        ok: false,
+        code: 2,
+        error: `Failed to read staged blob for "${relPath}": file unreadable in git index`,
+        findings,
+        stats: { filesScanned: stagedEntries.length, violations: findings.length },
+      };
+    }
+
+    // Large files (> 2MB): fail-closed in enforce mode
+    if (blob.length > 2 * 1024 * 1024) {
+      if (enforce) {
+        findings.push({
+          ruleId: 'SCAN-SKIP-001',
+          file: relPath,
+          type: 'Skipped Large File',
+          severity: 'error',
+          details: `Staged file "${relPath}" exceeds 2MB limit (${(blob.length / (1024 * 1024)).toFixed(2)}MB) and cannot be verified for secrets in enforce mode.`,
+        });
+      }
+      continue;
+    }
 
     const content = blob.toString('utf8');
     const lines = content.split(/\r?\n/);
@@ -352,13 +427,19 @@ function runScan(options = {}) {
 
   const hasViolations = findings.length > 0;
   // If enforce is true, violations return code 1. If enforce is false, warnings return code 0.
+  // Incomplete/failed inspection returns code 2 in all modes.
   const exitCode = hasViolations && enforce ? 1 : 0;
 
   return {
     ok: exitCode === 0,
     code: exitCode,
+    message: exitCode === 0 ? 'Verification completed cleanly, no blocking violations' : 'Blocking violations detected in staged index',
     gitRoot,
     enforce,
+    scope: {
+      file: targetScopeFile,
+      status: scopeStatus,
+    },
     findings,
     stats: {
       stagedFilesCount: stagedEntries.length,

package/bin/lib/ui.js

@@ -0,0 +1,140 @@
+/**
+ * bin/lib/ui.js
+ * Terminal visual formatting & progress helpers for ContextOS.
+ * Zero external dependencies - uses standard Node.js ANSI and process streams.
+ */
+
+'use strict';
+
+const isTTY = Boolean(process.stdout && process.stdout.isTTY && !process.env.CI && process.env.NODE_ENV !== 'test');
+const noColor = Boolean(process.env.NO_COLOR || (!isTTY && !process.env.FORCE_COLOR));
+
+const c = {
+  cyan:    (s) => noColor ? s : `\x1b[36m${s}\x1b[0m`,
+  green:   (s) => noColor ? s : `\x1b[32m${s}\x1b[0m`,
+  yellow:  (s) => noColor ? s : `\x1b[33m${s}\x1b[0m`,
+  red:     (s) => noColor ? s : `\x1b[31m${s}\x1b[0m`,
+  blue:    (s) => noColor ? s : `\x1b[34m${s}\x1b[0m`,
+  magenta: (s) => noColor ? s : `\x1b[35m${s}\x1b[0m`,
+  dim:     (s) => noColor ? s : `\x1b[2m${s}\x1b[0m`,
+  bold:    (s) => noColor ? s : `\x1b[1m${s}\x1b[0m`,
+  gray:    (s) => noColor ? s : `\x1b[90m${s}\x1b[0m`,
+};
+
+/**
+ * Render a sleek ASCII brand banner with version.
+ */
+function renderBanner(version) {
+  const title = `ContextOS  v${version}`;
+  const subtitle = 'Deterministic Context & Policy Engine for Coding Agents';
+  const width = Math.max(title.length, subtitle.length) + 6;
+  const topBorder    = ` ╭${'─'.repeat(width)}╮`;
+  const bottomBorder = ` ╰${'─'.repeat(width)}╯`;
+
+  console.log('\n' + c.cyan(topBorder));
+  console.log(` ${c.cyan('│')}   ${c.bold(c.cyan('ContextOS'))}  ${c.dim('v' + version)}${' '.repeat(width - title.length - 3)}${c.cyan('│')}`);
+  console.log(` ${c.cyan('│')}   ${c.gray(subtitle)}${' '.repeat(width - subtitle.length - 3)}${c.cyan('│')}`);
+  console.log(c.cyan(bottomBorder) + '\n');
+}
+
+/**
+ * Format a step badge: e.g. [1/4]
+ */
+function formatStepBadge(step, total) {
+  return c.cyan(`[${step}/${total}]`);
+}
+
+/**
+ * Render an installation step with title and detailed item.
+ */
+function renderStep(step, total, title, detail = null, isSuccess = true) {
+  const badge = formatStepBadge(step, total);
+  console.log(`  ${badge}  ${c.bold(title)}`);
+  if (detail) {
+    const symbol = isSuccess ? c.green('✓') : c.yellow('•');
+    if (Array.isArray(detail)) {
+      if (detail.length > 0) {
+        console.log(`         ${symbol} ${detail[0]}`);
+        for (let i = 1; i < detail.length; i++) {
+          console.log(`           ${c.dim(detail[i])}`);
+        }
+      }
+    } else {
+      console.log(`         ${symbol} ${detail}`);
+    }
+  }
+}
+
+/**
+ * Render an interactive or batch progress bar for skills/files.
+ */
+function renderProgressBar(current, total, label = '', width = 26) {
+  const percent = total > 0 ? Math.min(100, Math.round((current / total) * 100)) : 100;
+  const filledCount = total > 0 ? Math.min(width, Math.round((current / total) * width)) : width;
+  const emptyCount = Math.max(0, width - filledCount);
+
+  const filledBar = '█'.repeat(filledCount);
+  const emptyBar  = '░'.repeat(emptyCount);
+  const barStr = `${c.cyan(filledBar)}${c.dim(emptyBar)}`;
+  const progressText = `[${barStr}] ${String(percent).padStart(3)}% (${current}/${total})${label ? ' ' + c.gray(label) : ''}`;
+
+  if (isTTY) {
+    process.stdout.write(`\r  ${progressText}   `);
+    if (current >= total) {
+      process.stdout.write('\n');
+    }
+  } else {
+    // In CI or non-TTY test runners, log only at completion to avoid log bloat
+    if (current === total) {
+      console.log(`  ${progressText}`);
+    }
+  }
+}
+
+/**
+ * Render the final readiness card with next steps and commands.
+ */
+function stripAnsi(str) {
+  return String(str).replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+function renderCardLine(content, innerWidth = 62) {
+  const visible = stripAnsi(content);
+  const padding = Math.max(0, innerWidth - visible.length);
+  return ` ${c.green('│')}  ${content}${' '.repeat(padding)}${c.green('│')}`;
+}
+
+/**
+ * Render the final readiness card with next steps and commands.
+ */
+function renderSuccessCard(options = {}) {
+  const innerWidth = 62;
+  const topBorder    = ` ╭${'─'.repeat(innerWidth + 2)}╮`;
+  const bottomBorder = ` ╰${'─'.repeat(innerWidth + 2)}╯`;
+
+  console.log('\n' + c.green(topBorder));
+  console.log(renderCardLine(c.bold(c.green('✓ Project ready for AI coding agents!')), innerWidth));
+  console.log(renderCardLine('', innerWidth));
+  console.log(renderCardLine(c.bold('Next steps:'), innerWidth));
+  console.log(renderCardLine(`1. Open project in your AI assistant (${c.cyan('Gemini')}, ${c.cyan('Cursor')}, ${c.cyan('Copilot')})`, innerWidth));
+  console.log(renderCardLine(`   Rules are auto-loaded from ${c.cyan('.agents/AGENTS.md')}`, innerWidth));
+  console.log(renderCardLine('', innerWidth));
+  console.log(renderCardLine('2. Explore and install domain skills:', innerWidth));
+  console.log(renderCardLine(`   ${c.cyan('contextos skill list --available')}`, innerWidth));
+  console.log(renderCardLine(`   ${c.cyan('contextos skill add <name>')}    (or ${c.cyan('--all')})`, innerWidth));
+  console.log(renderCardLine('', innerWidth));
+  console.log(renderCardLine('3. Inspect project health anytime:', innerWidth));
+  console.log(renderCardLine(`   ${c.cyan('contextos doctor')}`, innerWidth));
+  console.log(c.green(bottomBorder) + '\n');
+}
+
+module.exports = {
+  isTTY,
+  noColor,
+  c,
+  renderBanner,
+  formatStepBadge,
+  renderStep,
+  renderProgressBar,
+  renderSuccessCard,
+};

package/catalog/skills/adapters/EXAMPLES.md

@@ -0,0 +1,19 @@
+# adapters Examples - Anti-patterns vs ContextOS Standard
+
+## Example 1: Multi-Agent Configuration
+
+### Anti-pattern: Manually Syncing 6 Different Rule Files
+
+```text
+Editing .cursorrules, then forgetting to update CLAUDE.md, then editing copilot-instructions.md.
+Rules diverge across teammates using different IDEs.
+```
+
+### Best practice: ContextOS Standard (Single Source of Truth)
+
+```bash
+# Edit skills once in .agents/core/skills/
+# Compile to all agents with one command:
+node .agents/ctx.js export all
+# Automatically updates .cursorrules, CLAUDE.md, copilot-instructions.md, .aider, .zed
+```

package/catalog/skills/adapters/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: adapters
+description: >
+  Generates agent-specific configuration files from the unified ContextOS format.
+  One internal system, multiple output formats for Claude, Gemini, Copilot, 
+  Cursor, Aider, Continue, OpenHands, and others.
+---
+
+# agent-adapters
+
+## Overview
+
+Unified cross-agent configuration engine. Translates single ContextOS source rules into optimized native formats for Claude Code (CLAUDE.md), Gemini (.agents/skills), Cursor (.cursorrules, .cursor/rules/*.mdc), GitHub Copilot, Zed, Aider, and Continue.
+
+## When to Use
+
+Activate when configuring, synchronizing, or exporting agent rules and skills across multiple IDEs and AI programming assistants.
+
+## Rules & Patterns
+
+ContextOS is agent-agnostic. This skill generates the right config format for any AI agent.
+
+## Supported Agents
+
+| Agent | Config Target | Format |
+| --- | --- | --- |
+| **Gemini / Antigravity** | `.agents/generated/gemini/skills/` | Native modular skills |
+| **Claude Code** | `.agents/generated/claude/skills/` | Aggregated markdown skills |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | Single instructions file with on-demand skill references |
+| **Cursor** | `.cursor/rules/*.mdc` + `.cursorrules` | MDC modular glob rules + fallback |
+| **Aider** | `.aider.conf.yml` + `CONVENTIONS.md` | YAML config + conventions markdown |
+| **Zed IDE** | `.zed/rules.md` + `.zed/prompts/*.md` | Native rules and prompt templates |
+
+## Generation Commands
+
+- `contextos export <agent>` (or `node .agents/ctx.js export <agent>`) - Generate config for a specific agent (`gemini`, `claude`, `cursor`, `copilot`, `aider`, `zed`).
+- `contextos export all` - Generate configs for all supported agents in a single transaction.
+
+## Adapter Logic
+
+### For Claude Code (`CLAUDE.md`)
+
+Compile into a single markdown file:
+
+1. Project overview from `docs/PRD.md` (summary only)
+2. Architecture summary from `docs/ARCHITECTURE.md`
+3. Coding rules from loaded skills
+4. Active Decision Records
+5. Current tasks from `docs/TASKS.md`
+
+### For Gemini (`.agents/AGENTS.md`)
+
+Already native format. Just ensure:
+
+1. `AGENTS.md` references the skill directory
+2. Skills have proper SKILL.md with frontmatter
+3. Context Manager rules are in AGENTS.md
+
+### For Cursor (`.cursorrules`)
+
+Compile into a flat text file:
+
+1. Project context (condensed)
+2. Coding style rules
+3. Framework-specific instructions
+4. Anti-patterns to avoid
+
+### For Aider (`.aider.conf.yml`)
+
+```yaml
+read:
+  - docs/ARCHITECTURE.md
+  - docs/API.md
+  - docs/PROJECT_GRAPH.md
+conventions:
+  - {{coding rules from skills}}
+```
+
+## Sync Rules
+
+- Adapters read from the canonical ContextOS documents
+- Never edit adapter output files directly
+- Re-run `contextos export all` after any skill or rule change
+- Each adapter file includes a header: `# Generated by ContextOS - do not edit directly`
+
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed code examples.
+
+## Validation Checklist
+
+What to verify during the review phase before completing the task.
+
+## Common Mistakes
+
+Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+
+## Integration Notes
+
+How this skill interacts with other skills.

package/catalog/skills/adapters/TROUBLESHOOTING.md

@@ -0,0 +1,7 @@
+# adapters Troubleshooting & Common Mistakes
+
+## 1. Overwriting Custom Configs
+
+- **Symptom**: Custom non-ContextOS rules wiped out during export.
+- **Root Cause**: Running export with force flags over unmanaged files.
+- **Fix**: Keep custom project overrides in dedicated config files or use plugin skills.

package/catalog/skills/adapters/VALIDATION.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "rules_followed": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "rules_followed"
+  ]
+}

package/catalog/skills/adapters/skill.yaml

@@ -0,0 +1,13 @@
+schemaVersion: 2
+name: adapters
+category: engineering
+type: compiler
+description: >
+  Generates agent-specific configuration files from unified ContextOS format.
+  Produces configs for Claude, Gemini, Copilot, Cursor, Aider, Continue, and Zed.
+version: 1.0.0
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json