contextos-agents 2.2.0 → 2.3.1

package/.agents/adapters/copilot/export.js

@@ -5,7 +5,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { collectSkillDirectories, extractYamlField, stripFrontmatter } = require('../shared.js');
+const { getSkillEntrypointPath, collectSkillDirectories, extractYamlField, stripFrontmatter } = require('../shared.js');
 const { registerAdapter, applyArtifacts, createProvenanceHeader } = require('../pure-compiler.js');
 
 const GENERATOR_ID = 'copilot@2';
@@ -19,9 +19,9 @@ function describe() {
   };
 }
 
-function buildSkillSection(skillDir) {
+function buildSkillSection(skillDir, context) {
   const skillName = path.basename(skillDir);
-  const skillMdPath = path.join(skillDir, 'SKILL.md');
+  const skillMdPath = getSkillEntrypointPath(skillDir);
   const yamlPath = path.join(skillDir, 'skill.yaml');
 
   let title = skillName;
@@ -43,7 +43,8 @@ function buildSkillSection(skillDir) {
   }
 
   const descLine = description ? `> ${description.replace(/\r?\n+/g, ' ').trim()}\n` : '';
-  const skillRef = `*Source: \`.agents/skills/${skillName}/SKILL.md\` (Read on demand)*\n`;
+  const sourcePath = path.relative(context?.projectRoot || '.', skillMdPath).split(path.sep).join('/');
+  const skillRef = `*Source: \`${sourcePath}\` (Read on demand)*\n`;
   return `\n### ${title}\n${descLine}${skillRef}`;
 }
 
@@ -62,7 +63,7 @@ function render(context) {
     `# GitHub Copilot Instructions — ContextOS\n\n` +
     `## Project Rules\n\n` +
     `### Step 0 — Identify Before Acting\n\n` +
-    `Before writing a single line of code or plan, state:\n` +
+    `When useful for substantial work, identify:\n` +
     `\`\`\`\n1. WHAT DOMAIN?   → Frontend / Backend / Architecture / Full-Stack / DevOps\n2. WHAT PHASE?    → Define / Plan / Build / Verify / Review / Ship\n3. WHAT ROLE?     → Declare specialist role for this phase\n\`\`\`\n\n` +
     `> **Anti-Spam Invariant**: Declare this strictly once at the start of a task or phase. Never repeat before intermediate tool calls or step updates.\n\n` +
     `### Non-Negotiable Rules\n\n` +
@@ -89,22 +90,42 @@ function render(context) {
       const rawTags = extractYamlField(yaml, 'tags');
       if (rawTags) tags = rawTags.replace(/[\[\]]/g, '');
     }
-    const relPath = `.agents/core/skills/${skillName}/SKILL.md`;
+    const relPath = path.relative(context?.projectRoot || '.', getSkillEntrypointPath(skill)).replace(/\\/g, '/');
     lines.push(`| \`${tags}\` | **${skillName}** | \`${relPath}\` |\n`);
   }
   lines.push(`\n---\n`);
 
   for (const skill of skills) {
-    const section = buildSkillSection(skill);
+    const section = buildSkillSection(skill, context);
     if (section) {
       lines.push(section);
     }
   }
 
+  const target = path.join(context?.projectRoot || '.', '.github/copilot-instructions.md');
+  const existing = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : '';
+  const start = '<!-- CONTEXTOS:START -->';
+  const end = '<!-- CONTEXTOS:END -->';
+  const block = `${start}\n${lines.join('').replace(/\r\n/g, '\n')}${end}`;
+  let content;
+  if (existing.includes(start) || existing.includes(end)) {
+    if (existing.split(start).length !== 2 || existing.split(end).length !== 2 || existing.indexOf(end) < existing.indexOf(start)) {
+      throw new Error('Malformed ContextOS block in Copilot instructions; refusing to overwrite.');
+    }
+    content = existing.slice(0, existing.indexOf(start)) + block + existing.slice(existing.indexOf(end) + end.length);
+  } else {
+    const { LockfileV2Manager, computeExactHash } = require('../../filesystem/index.js');
+    const managed = new LockfileV2Manager(context?.projectRoot || '.').read()?.managedFiles?.['.github/copilot-instructions.md'];
+    const legacyManaged = managed?.generator === GENERATOR_ID && managed.exactSha256 === computeExactHash(Buffer.from(existing));
+    content = legacyManaged ? block + '\n' : existing + (existing && !existing.endsWith('\n') ? '\n' : '') + (existing ? '\n' : '') + block + '\n';
+  }
+
   return [
     {
       path: '.github/copilot-instructions.md',
-      content: lines.join('').replace(/\r\n/g, '\n'),
+      content,
+      preservesUserContent: true,
+      expectedBeforeHash: fs.existsSync(target) ? require('../../filesystem/index.js').computeExactHash(Buffer.from(existing)) : 'NONE',
       mediaType: 'text/markdown',
       kind: 'generated-adapter',
       generator: GENERATOR_ID,

package/.agents/adapters/cursor/export.js

@@ -5,7 +5,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { AGENTS_MD_PATH, collectSkillDirectories, extractYamlField, stripFrontmatter, readMeaningfulMarkdown } = require('../shared.js');
+const { getSkillEntrypointPath, AGENTS_MD_PATH, collectSkillDirectories, extractYamlField, stripFrontmatter } = require('../shared.js');
 const { registerAdapter, applyArtifacts, createProvenanceHeader } = require('../pure-compiler.js');
 
 const GENERATOR_ID = 'cursor@2';
@@ -20,11 +20,6 @@ function describe() {
 }
 
 function getSkillGlobsAndFlags(skillName, skillDir = null) {
-  const ALWAYS_APPLY_SKILLS = ['engineering-workflow', 'gstack-roles', 'ponytail-mindset', 'gemini-precision'];
-  if (ALWAYS_APPLY_SKILLS.includes(skillName)) {
-    return { globs: '', alwaysApply: true };
-  }
-
   // 1. Dynamic extraction from skill.yaml if available
   if (skillDir) {
     const yamlPath = path.join(skillDir, 'skill.yaml');
@@ -78,7 +73,7 @@ function getSkillGlobsAndFlags(skillName, skillDir = null) {
 
 function buildSkillSection(skillDir) {
   const skillName = path.basename(skillDir);
-  const skillMdPath = path.join(skillDir, 'SKILL.md');
+  const skillMdPath = getSkillEntrypointPath(skillDir);
   const yamlPath = path.join(skillDir, 'skill.yaml');
 
   let title = skillName;
@@ -92,7 +87,7 @@ function buildSkillSection(skillDir) {
   if (!fs.existsSync(skillMdPath)) return null;
 
   const raw = fs.readFileSync(skillMdPath, 'utf8');
-  const body = stripFrontmatter(raw);
+  const body = stripFrontmatter(raw).trimEnd();
 
   if (!description) {
     const firstLine = body.split(/\r?\n/).map(l => l.trim()).find(l => l && !l.startsWith('#'));
@@ -103,9 +98,9 @@ function buildSkillSection(skillDir) {
   return `\n## Skill: ${title}\n${descLine}*Rule file: \`.cursor/rules/${skillName}.mdc\` (load on demand)*\n`;
 }
 
-function generateCursorMdc(skillDir) {
+function generateCursorMdc(skillDir, context) {
   const skillName = path.basename(skillDir);
-  const skillMdPath = path.join(skillDir, 'SKILL.md');
+  const skillMdPath = getSkillEntrypointPath(skillDir);
   const yamlPath = path.join(skillDir, 'skill.yaml');
 
   if (!fs.existsSync(skillMdPath)) return null;
@@ -120,13 +115,7 @@ function generateCursorMdc(skillDir) {
   }
 
   let raw = fs.readFileSync(skillMdPath, 'utf8');
-  const examples = readMeaningfulMarkdown(path.join(skillDir, 'EXAMPLES.md'));
-  if (examples) raw += '\n\n' + examples;
-
-  const troubleshooting = readMeaningfulMarkdown(path.join(skillDir, 'TROUBLESHOOTING.md'));
-  if (troubleshooting) raw += '\n\n' + troubleshooting;
-
-  const body = stripFrontmatter(raw);
+  const body = stripFrontmatter(raw).trimEnd();
   const { globs, alwaysApply } = getSkillGlobsAndFlags(skillName, skillDir);
 
   let cleanDescription = description.replace(/\r?\n+/g, ' ').replace(/"/g, "'").trim();
@@ -141,6 +130,8 @@ alwaysApply: ${alwaysApply}
 
 # Skill: ${title}
 
+Resolve supporting resource paths relative to \`${path.relative(context?.projectRoot || process.cwd(), skillDir).replace(/\\/g, '/')}\`. Read examples and references only when needed.
+
 ${body}
 `;
 
@@ -189,7 +180,7 @@ ${agentsMd}
 
   const skills = collectSkillDirectories(context?.profile, context?.projectRoot);
   for (const skill of skills) {
-    const mdc = generateCursorMdc(skill);
+    const mdc = generateCursorMdc(skill, context);
     if (mdc) {
       const fullMdc = mdc.mdcContent.replace(/\r\n/g, '\n');
       artifacts.push({

package/.agents/adapters/gemini/export.js

@@ -5,7 +5,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { collectSkillDirectories, readMeaningfulMarkdown, extractYamlField } = require('../shared.js');
+const { getSkillEntrypointPath, readSkillManifest, collectSkillDirectories, renderSkillResources } = require('../shared.js');
 const { registerAdapter, applyArtifacts } = require('../pure-compiler.js');
 
 const GENERATOR_ID = 'gemini@2';
@@ -21,61 +21,23 @@ function describe() {
 
 function renderGeminiSkill(skillDir, context) {
   const skillName = path.basename(skillDir);
-  const yamlPath = path.join(skillDir, 'skill.yaml');
-  const existingSkillMdPath = path.join(skillDir, 'SKILL.md');
+  const manifest = readSkillManifest(skillDir);
+  const existingSkillMdPath = getSkillEntrypointPath(skillDir);
 
-  if (!fs.existsSync(existingSkillMdPath) && !fs.existsSync(yamlPath)) {
+  if (!fs.existsSync(existingSkillMdPath)) {
     return [];
   }
 
-  let name = skillName;
-  let description = null;
-
-  if (fs.existsSync(yamlPath)) {
-    const yamlText = fs.readFileSync(yamlPath, 'utf8');
-    name = extractYamlField(yamlText, 'name') || skillName;
-    description = extractYamlField(yamlText, 'description');
-    if (!description) {
-      const descRegex = new RegExp(`^description:\\s*>\\s*\\n\\s*([^\\n]+)`, 'm');
-      const descMatch = yamlText.match(descRegex);
-      if (descMatch) description = descMatch[1].trim();
-    }
-  }
-  description = description || `ContextOS skill for ${name}`;
-
-  const files = fs.readdirSync(skillDir).sort((a, b) => a.localeCompare(b, 'en', { sensitivity: 'base' }));
-  const mdFiles = files.filter(f => f.endsWith('.md'));
-
-  const primaryMd = mdFiles.includes('SKILL.md')
-    ? 'SKILL.md'
-    : (mdFiles.find(f => f === `${skillName}.md`) || mdFiles[0]);
-
-  let mergedContent = '';
-  if (primaryMd) {
-    let primaryText = fs.readFileSync(path.join(skillDir, primaryMd), 'utf8');
-    primaryText = primaryText.replace(/^---[\s\S]*?---\r?\n/, '');
-    mergedContent += primaryText;
-  }
-
-  const otherTopicFiles = mdFiles.filter(f => f !== primaryMd && f !== 'EXAMPLES.md' && f !== 'TROUBLESHOOTING.md');
-  const orderedExtras = [...otherTopicFiles];
-  if (mdFiles.includes('EXAMPLES.md') && primaryMd !== 'EXAMPLES.md') orderedExtras.push('EXAMPLES.md');
-  if (mdFiles.includes('TROUBLESHOOTING.md') && primaryMd !== 'TROUBLESHOOTING.md') orderedExtras.push('TROUBLESHOOTING.md');
-
-  for (const mdFile of orderedExtras) {
-    if (mergedContent.includes(`<!-- Source: ${mdFile} -->`)) continue;
-    const extraContent = readMeaningfulMarkdown(path.join(skillDir, mdFile));
-    if (extraContent) {
-      mergedContent += `\n\n<!-- Source: ${mdFile} -->\n\n` + extraContent;
-    }
-  }
+  const name = skillName;
+  const description = manifest?.description || `ContextOS skill for ${name}`;
+  const mergedContent = fs.readFileSync(existingSkillMdPath, 'utf8').replace(/^---[\s\S]*?---\r?\n/, '');
 
   const outputContent = `---
 name: ${name}
 description: >
   ${description}
 ---
-${mergedContent.trimStart()}
+${mergedContent.trim()}
 `.replace(/\r\n/g, '\n');
 
   const artifacts = [
@@ -99,6 +61,9 @@ ${mergedContent.trimStart()}
     },
   ];
 
+  artifacts.push(...renderSkillResources(skillDir, [
+    `.agents/generated/gemini/skills/${skillName}`, `.agents/skills/${skillName}`,
+  ], { kind: 'generated-adapter', generator: GENERATOR_ID, sourceSkillIds: [skillName], inputsHash: context?.sourceGraphHash || 'none' }));
   return artifacts;
 }
 

package/.agents/adapters/pure-compiler.js

@@ -107,8 +107,8 @@ function loadCompilerContext(projectRoot, options = {}) {
   // 3. Workspace Graph
   let workspace = null;
   try {
-    const { buildWorkspaceGraph } = require('../workspace/workspace-graph.js');
-    workspace = buildWorkspaceGraph(absRoot);
+    const { WorkspaceGraphBuilder } = require('../workspace/workspace-graph.js');
+    workspace = new WorkspaceGraphBuilder({ rootDir: absRoot }).build();
   } catch {
     workspace = null;
   }
@@ -256,6 +256,11 @@ function applyArtifacts(projectRoot, artifacts, options = {}) {
     });
 
     let hasModifications = false;
+    const legacyLockPath = path.join(absRoot, '.agents', 'contextos.lock.json');
+    let legacyLock = null;
+    if (fs.existsSync(legacyLockPath)) {
+      try { legacyLock = JSON.parse(fs.readFileSync(legacyLockPath, 'utf8')); } catch {}
+    }
 
     for (const art of artifacts) {
       const exactSha256 = computeExactHash(art.content);
@@ -272,15 +277,27 @@ function applyArtifacts(projectRoot, artifacts, options = {}) {
       }
       
       const absPath = path.resolve(absRoot, art.path);
+      let diskHash = 'NONE';
       if (fs.existsSync(absPath)) {
          const diskBuf = fs.readFileSync(absPath);
-         if (computeExactHash(diskBuf) === exactSha256) {
+         diskHash = computeExactHash(diskBuf);
+         if (diskHash === exactSha256) {
            needsWrite = false;
          }
+         if (needsWrite && !art.preservesUserContent) {
+           const legacyRecord = legacyLock?.managedFiles?.[art.path] || legacyLock?.files?.[art.path];
+           const legacyOwned = legacyRecord?.managed && legacyRecord.sha256 === computeSemanticHash(diskBuf).replace('sha256:', '');
+           const textEquivalent = /^text\/|yaml/.test(art.mediaType || '') && existingRecord?.semanticTextSha256 === computeSemanticHash(diskBuf);
+           if ((!existingRecord && !legacyOwned) || (existingRecord && diskHash !== existingRecord.exactSha256 && !textEquivalent)) {
+             const err = new Error(`Refusing to overwrite user-owned or modified file '${art.path}'. Move custom rules into a project override or restore the managed artifact before exporting.`);
+             err.code = 'CTX_ADAPTER_OWNERSHIP_CONFLICT';
+             throw err;
+           }
+         }
       }
 
       if (needsWrite) {
-        tx.stageWrite(art.path, art.content, { mode: art.mode || 420 });
+        tx.stageWrite(art.path, art.content, { mode: art.mode || 420, expectedBeforeHash: art.expectedBeforeHash || diskHash });
         hasModifications = true;
       }
 
@@ -310,13 +327,21 @@ function applyArtifacts(projectRoot, artifacts, options = {}) {
       } catch {}
     }
 
+    const prunedPaths = new Set();
     // 1. Prune stale files recorded in Lockfile v2
     if (lockfileData && lockfileData.managedFiles) {
       for (const [recordedPath, meta] of Object.entries(lockfileData.managedFiles)) {
         if (activeGenerators.has(meta.generator) && !activePaths.has(recordedPath)) {
           const absRecPath = path.resolve(absRoot, recordedPath);
           if (fs.existsSync(absRecPath)) {
-            tx.stageDelete(recordedPath);
+            const beforeHash = computeExactHash(fs.readFileSync(absRecPath));
+            if (beforeHash !== meta.exactSha256) {
+              const err = new Error(`Refusing to prune modified managed file '${recordedPath}'.`);
+              err.code = 'CTX_ADAPTER_OWNERSHIP_CONFLICT';
+              throw err;
+            }
+            tx.stageDelete(recordedPath, { expectedBeforeHash: beforeHash });
+            prunedPaths.add(recordedPath);
             hasModifications = true;
           }
           lockfileManager.removeManagedFile(lockfileData, recordedPath);
@@ -332,21 +357,14 @@ function applyArtifacts(projectRoot, artifacts, options = {}) {
         for (const file of fs.readdirSync(cursorRulesDir)) {
           if (file.endsWith('.mdc')) {
             const relPath = toPosix(path.relative(absRoot, path.join(cursorRulesDir, file)));
-            if (!activePaths.has(relPath)) {
+            if (!activePaths.has(relPath) && !prunedPaths.has(relPath)) {
               const isManagedInV1 = Boolean(v1Data?.files?.[relPath]?.managed || v1Data?.managedFiles?.[relPath]?.managed);
               const isManagedInV2 = Boolean(lockfileData?.managedFiles?.[relPath]);
-              let hasContextosMarker = false;
-              try {
-                const content = fs.readFileSync(path.join(cursorRulesDir, file), 'utf8');
-                hasContextosMarker =
-                  content.includes('ContextOS rules for') ||
-                  content.includes('<!-- Auto-generated by: node .agents/ctx.js export cursor -->') ||
-                  content.includes('ContextOS — Project Operating System Rules') ||
-                  content.includes('contextos:generator');
-              } catch {}
-
-              if (isManagedInV1 || isManagedInV2 || hasContextosMarker) {
-                tx.stageDelete(relPath);
+              if (isManagedInV1 || isManagedInV2) {
+                const beforeHash = computeExactHash(fs.readFileSync(path.join(absRoot, relPath)));
+                const expected = lockfileData?.managedFiles?.[relPath]?.exactSha256 || `sha256:${(v1Data?.files?.[relPath] || v1Data?.managedFiles?.[relPath])?.sha256}`;
+                if (beforeHash !== expected && computeSemanticHash(fs.readFileSync(path.join(absRoot, relPath))) !== expected) throw new Error(`Refusing to prune modified legacy artifact '${relPath}'.`);
+                tx.stageDelete(relPath, { expectedBeforeHash: beforeHash });
                 hasModifications = true;
                 if (v1Data?.files?.[relPath]) { delete v1Data.files[relPath]; hasModifications = true; }
                 if (v1Data?.managedFiles?.[relPath]) { delete v1Data.managedFiles[relPath]; hasModifications = true; }
@@ -365,21 +383,14 @@ function applyArtifacts(projectRoot, artifacts, options = {}) {
         for (const file of fs.readdirSync(zedPromptsDir)) {
           if (file.endsWith('.md')) {
             const relPath = toPosix(path.relative(absRoot, path.join(zedPromptsDir, file)));
-            if (!activePaths.has(relPath)) {
+            if (!activePaths.has(relPath) && !prunedPaths.has(relPath)) {
               const isManagedInV1 = Boolean(v1Data?.files?.[relPath]?.managed || v1Data?.managedFiles?.[relPath]?.managed);
               const isManagedInV2 = Boolean(lockfileData?.managedFiles?.[relPath]);
-              let hasContextosMarker = false;
-              try {
-                const content = fs.readFileSync(path.join(zedPromptsDir, file), 'utf8');
-                hasContextosMarker =
-                  content.includes('<!-- Auto-generated by: node .agents/ctx.js export zed -->') ||
-                  content.includes('# ContextOS —') ||
-                  content.includes('# ContextOS Master Prompt') ||
-                  content.includes('contextos:generator');
-              } catch {}
-
-              if (isManagedInV1 || isManagedInV2 || hasContextosMarker) {
-                tx.stageDelete(relPath);
+              if (isManagedInV1 || isManagedInV2) {
+                const beforeHash = computeExactHash(fs.readFileSync(path.join(absRoot, relPath)));
+                const expected = lockfileData?.managedFiles?.[relPath]?.exactSha256 || `sha256:${(v1Data?.files?.[relPath] || v1Data?.managedFiles?.[relPath])?.sha256}`;
+                if (beforeHash !== expected && computeSemanticHash(fs.readFileSync(path.join(absRoot, relPath))) !== expected) throw new Error(`Refusing to prune modified legacy artifact '${relPath}'.`);
+                tx.stageDelete(relPath, { expectedBeforeHash: beforeHash });
                 hasModifications = true;
                 if (v1Data?.files?.[relPath]) { delete v1Data.files[relPath]; hasModifications = true; }
                 if (v1Data?.managedFiles?.[relPath]) { delete v1Data.managedFiles[relPath]; hasModifications = true; }
@@ -392,10 +403,9 @@ function applyArtifacts(projectRoot, artifacts, options = {}) {
     }
 
     // Clean up empty/orphan skill directories in generated paths
-    const cleanupDirs = [
-      path.join(absRoot, '.agents', 'generated', 'gemini', 'skills'),
-      path.join(absRoot, '.agents', 'generated', 'claude', 'skills'),
-    ];
+    const cleanupDirs = ['gemini', 'claude']
+      .filter(name => activeGenerators.has(`${name}@2`))
+      .map(name => path.join(absRoot, '.agents', 'generated', name, 'skills'));
     for (const parentDir of cleanupDirs) {
       if (fs.existsSync(parentDir)) {
         for (const entry of fs.readdirSync(parentDir)) {
@@ -403,13 +413,26 @@ function applyArtifacts(projectRoot, artifacts, options = {}) {
           if (fs.statSync(entryPath).isDirectory()) {
             const relMd = toPosix(path.relative(absRoot, path.join(entryPath, 'SKILL.md')));
             if (!activePaths.has(relMd)) {
-              // Delete orphaned files inside the directory, if any. The generator writes SKILL.md and optional references.
-              for (const child of fs.readdirSync(entryPath)) {
-                tx.stageDelete(toPosix(path.relative(absRoot, path.join(entryPath, child))));
-                hasModifications = true;
-              }
-              const relDir = toPosix(path.relative(absRoot, entryPath));
-              tx.stageDeleteDir(relDir);
+              const pruneDirectory = (dir) => {
+                for (const child of fs.readdirSync(dir, { withFileTypes: true })) {
+                  const absChild = path.join(dir, child.name);
+                  const relChild = toPosix(path.relative(absRoot, absChild));
+                  if (child.isDirectory()) { pruneDirectory(absChild); continue; }
+                  if (prunedPaths.has(relChild)) continue;
+                  const v1Record = v1Data?.files?.[relChild] || v1Data?.managedFiles?.[relChild];
+                  if (!v1Record?.managed) {
+                    const err = new Error(`Refusing to prune untracked file '${relChild}' from an orphan skill.`);
+                    err.code = 'CTX_ADAPTER_OWNERSHIP_CONFLICT';
+                    throw err;
+                  }
+                  const before = fs.readFileSync(absChild);
+                  const beforeHash = computeExactHash(before);
+                  if (`sha256:${v1Record.sha256}` !== beforeHash && `sha256:${v1Record.sha256}` !== computeSemanticHash(before)) throw new Error(`Refusing to prune modified legacy resource '${relChild}'.`);
+                  tx.stageDelete(relChild, { expectedBeforeHash: beforeHash });
+                }
+                tx.stageDeleteDir(toPosix(path.relative(absRoot, dir)));
+              };
+              pruneDirectory(entryPath);
               hasModifications = true;
             }
           }

package/.agents/adapters/shared.js

@@ -115,6 +115,38 @@ function readMeaningfulMarkdown(filePath) {
   return content;
 }
 
+/** Read the same manifest precedence and entrypoint used by the compiler. */
+function readSkillManifest(skillDir) {
+  const manifestPath = ['skill.v2.yaml', 'skill.yaml'].map(name => path.join(skillDir, name)).find(file => fs.existsSync(file));
+  return manifestPath ? require('../compiler/vendor/yaml.js').parse(fs.readFileSync(manifestPath, 'utf8')) : {};
+}
+
+function getSkillEntrypointPath(skillDir) {
+  const manifest = readSkillManifest(skillDir);
+  return require('../filesystem/index.js').resolveManagedPath(skillDir, manifest?.entrypoint || 'SKILL.md').resolvedPath;
+}
+
+/** Copy declared resources beside exported entrypoints without inlining them. */
+function renderSkillResources(skillDir, destinations, metadata) {
+  const manifest = readSkillManifest(skillDir);
+  const resources = manifest?.resources || [];
+  const { resolveManagedPath } = require('../filesystem/index.js');
+  const artifacts = [];
+  const seen = new Set();
+  for (const resource of resources) {
+    const rel = typeof resource === 'string' ? resource : resource.path;
+    if (rel === 'SKILL.md' || rel === manifest?.entrypoint || seen.has(rel)) continue;
+    seen.add(rel);
+    const { resolvedPath, relativePosixPath } = resolveManagedPath(skillDir, rel);
+    if (!fs.statSync(resolvedPath).isFile()) throw new Error(`Skill resource must be a file: ${rel}`);
+    for (const destination of destinations) {
+      const mediaType = /\.(md|txt|js|ts|py)$/i.test(rel) ? 'text/plain' : /\.ya?ml$/i.test(rel) ? 'application/yaml' : /\.json$/i.test(rel) ? 'text/plain' : 'application/octet-stream';
+      artifacts.push({ ...metadata, path: `${destination}/${relativePosixPath}`, content: fs.readFileSync(resolvedPath), mediaType });
+    }
+  }
+  return artifacts;
+}
+
 module.exports = {
   AGENTS_DIR,
   AGENTS_MD_PATH,
@@ -124,5 +156,7 @@ module.exports = {
   readMeaningfulMarkdown,
   resetDirectory,
   stripFrontmatter,
+  renderSkillResources,
+  readSkillManifest,
+  getSkillEntrypointPath,
 };
-

package/.agents/adapters/zed/export.js

@@ -5,7 +5,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { AGENTS_MD_PATH, collectSkillDirectories, extractYamlField, stripFrontmatter } = require('../shared.js');
+const { getSkillEntrypointPath, AGENTS_MD_PATH, collectSkillDirectories, extractYamlField, stripFrontmatter } = require('../shared.js');
 const { registerAdapter, applyArtifacts, createProvenanceHeader } = require('../pure-compiler.js');
 
 const GENERATOR_ID = 'zed@2';
@@ -21,7 +21,7 @@ function describe() {
 
 function buildSkillSection(skillDir) {
   const skillName = path.basename(skillDir);
-  const skillMdPath = path.join(skillDir, 'SKILL.md');
+  const skillMdPath = getSkillEntrypointPath(skillDir);
   const yamlPath = path.join(skillDir, 'skill.yaml');
 
   let title = skillName;

package/.agents/compiled/registry.v2.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "compilerVersion": "2.0.0",
-  "sourceGraphHash": "sha256:938c5051454535087e03f26af35c434cf194f414d2ec8044b4ae754e8524cf37",
+  "sourceGraphHash": "sha256:efcac8692b9208232aa09a065009438cd7b151e7f4d19366d75b699645cddf94",
   "skills": {
     "context-manager": {
       "id": "context-manager",
@@ -67,7 +67,7 @@
       "type": "compiler",
       "entrypoint": "SKILL.md",
       "entrypointHash": "sha256:ab14bcd603573c975a69cb95b5ef8a305de8eb888c81c20c994121313f017239",
-      "resourceTreeHash": "sha256:48568f01d27fa53e2e01a6a63afd60eb2d43cabdc9eb2cfe6f02a2b67d0f53e1",
+      "resourceTreeHash": "sha256:1f9422adff6b9e69772dfeff2e1c9c9f8615b5fae56f8b60d2d7bef4a5c1c7fb",
       "estimatedTokens": 1365,
       "source": ".agents/core/skills/context-os/skill.yaml",
       "signals": {
@@ -133,13 +133,13 @@
       "id": "engineering-workflow",
       "displayName": "engineering-workflow",
       "version": "1.0.0",
-      "description": "Senior engineering workflow skill inspired by Addy Osmani's agent-skills. Enforces the full development lifecycle: spec → plan → build → test → review → ship. AI must never write code before a spec and plan are approved.\n",
+      "description": "Scope implementation work, verify behavior, and report evidence using a proportional lifecycle.",
       "category": "general",
       "type": "instruction-only",
       "entrypoint": "SKILL.md",
-      "entrypointHash": "sha256:88b606d086f63c5e293630ad84ff524d2542f2953fc1a5a451bd77352073b0ad",
-      "resourceTreeHash": "sha256:e78a054d8f54a72550cf10d551a82f56015aedb3f16a14021e654574bad5804f",
-      "estimatedTokens": 3083,
+      "entrypointHash": "sha256:e729b3bc21cecef2a39b64f0b301715974697600524629fa05609fd2d9175b48",
+      "resourceTreeHash": "sha256:6371d58615c6b5ba47c1523f6f99c106dcd9d99c5abc30338b4a3504271a23f1",
+      "estimatedTokens": 418,
       "source": ".agents/core/skills/engineering-workflow/skill.yaml",
       "signals": {
         "aliases": [
@@ -156,7 +156,7 @@
       },
       "context": {
         "priority": 50,
-        "estimatedTokens": 3083
+        "estimatedTokens": 418
       },
       "resources": [
         {
@@ -174,6 +174,10 @@
         {
           "path": "VALIDATION.json",
           "mode": "on-demand"
+        },
+        {
+          "path": "references/workflow.md",
+          "mode": "on-demand"
         }
       ],
       "deprecated": false,
@@ -235,13 +239,13 @@
       "id": "gstack-roles",
       "displayName": "gstack-roles",
       "version": "1.0.0",
-      "description": "Role-based AI specialist system inspired by Garry Tan's gstack. Defines 23 specialist roles (CEO, Eng Manager, Designer, QA, Security etc.) and teaches the AI to adopt the correct role before each task phase.\n",
+      "description": "Compatibility alias for engineering-workflow with optional specialist review perspectives.",
       "category": "general",
       "type": "instruction-only",
       "entrypoint": "SKILL.md",
-      "entrypointHash": "sha256:09334359de594f9c3e667ae0660db9a5c977c583b25ccf7de71fe25b7134454e",
-      "resourceTreeHash": "sha256:0bcfb511ef61a6782e3394c0779e5f5eed1833aff6e24c7749957df209c6185a",
-      "estimatedTokens": 1791,
+      "entrypointHash": "sha256:baeb5f187b8ea491f4854e6287c29d5c58b436c327e8df46c04651e6deb43513",
+      "resourceTreeHash": "sha256:d720b3727681e63f5212e97687b9ad32326685f22493214edc8750a3f504347a",
+      "estimatedTokens": 343,
       "source": ".agents/core/skills/gstack-roles/skill.yaml",
       "signals": {
         "aliases": [
@@ -258,7 +262,7 @@
       },
       "context": {
         "priority": 50,
-        "estimatedTokens": 1791
+        "estimatedTokens": 343
       },
       "resources": [
         {
@@ -276,6 +280,10 @@
         {
           "path": "VALIDATION.json",
           "mode": "on-demand"
+        },
+        {
+          "path": "references/roles.md",
+          "mode": "on-demand"
         }
       ],
       "deprecated": true,
@@ -286,13 +294,13 @@
       "id": "ponytail-mindset",
       "displayName": "ponytail-mindset",
       "version": "1.0.0",
-      "description": "Minimalist coding mindset based on DietrichGebert/ponytail. Teaches the AI to write only what is strictly necessary. Uses a 7-rung ladder: YAGNI → reuse → stdlib → platform → deps → one-liner → minimum. Minimizes unnecessary boilerplate and over-engineering while keeping all safety, validation and security guards.\n",
+      "description": "Choose a minimal maintainable implementation for substantive Build tasks while preserving safety and verification.",
       "category": "general",
       "type": "instruction-only",
       "entrypoint": "SKILL.md",
-      "entrypointHash": "sha256:122a01d74edfebcfe18e163242a038d61c943f3320b582723eb1a185b6ee53d6",
-      "resourceTreeHash": "sha256:a181af2582fd80a893c52db6a59ceb038c52dbb310fffd99f0f8f7a55a568990",
-      "estimatedTokens": 1812,
+      "entrypointHash": "sha256:837795e41d09af94040fb9ae318126c6ff3a24bf35b43bbf4cb2888a5067a950",
+      "resourceTreeHash": "sha256:3a4d757373ad00ae321c25d0774d35d0f8c9f25b1e95d58303ffb68d0128fd59",
+      "estimatedTokens": 413,
       "source": ".agents/core/skills/ponytail-mindset/skill.yaml",
       "signals": {
         "aliases": [
@@ -309,7 +317,7 @@
       },
       "context": {
         "priority": 50,
-        "estimatedTokens": 1812
+        "estimatedTokens": 413
       },
       "resources": [
         {
@@ -327,6 +335,10 @@
         {
           "path": "VALIDATION.json",
           "mode": "on-demand"
+        },
+        {
+          "path": "references/minimalism.md",
+          "mode": "on-demand"
         }
       ],
       "deprecated": false,
@@ -337,7 +349,7 @@
       "id": "security",
       "displayName": "Application Security",
       "version": "1.0.0",
-      "description": "ContextOS skill for Application Security",
+      "description": "Protect authentication, authorization, sensitive data, untrusted input, external integrations, and agent tool execution.",
       "category": "backend",
       "type": "instruction-only",
       "entrypoint": "SKILL.md",

package/.agents/compiled/registry.v2.sha256

@@ -1 +1 @@
-sha256:938c5051454535087e03f26af35c434cf194f414d2ec8044b4ae754e8524cf37  registry.v2.json
+sha256:efcac8692b9208232aa09a065009438cd7b151e7f4d19366d75b699645cddf94  registry.v2.json