agentfold 0.1.0

package/lib/pipeline-steps.mjs

@@ -0,0 +1,853 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { listFiles, parseFrontMatter, pathExists, toPosixPath, stripScopeFrontMatter } from './util.mjs';
+import { emptyScopeSelector, matchesScope, normalizeScopeMetadata } from './scope.mjs';
+
+function shouldInclude({ selector, metadata, fallbackCandidates }) {
+  const normalizedSelector = selector || emptyScopeSelector();
+  return matchesScope({ selector: normalizedSelector, metadata, fallbackCandidates });
+}
+
+async function readScopeMetadata(filePath) {
+  const content = await fs.readFile(filePath, 'utf8');
+  const frontMatter = parseFrontMatter(content) || {};
+  const metadata = normalizeScopeMetadata(frontMatter);
+  const strippedContent = stripScopeFrontMatter(content);
+  return { content, metadata, strippedContent };
+}
+
+function removeSuffix(name, suffix) {
+  return name.endsWith(suffix) ? name.slice(0, -suffix.length) : name;
+}
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function mergeObjects(base, override) {
+  const result = { ...base };
+
+  for (const [key, overrideValue] of Object.entries(override)) {
+    const baseValue = result[key];
+    if (isPlainObject(baseValue) && isPlainObject(overrideValue)) {
+      result[key] = mergeObjects(baseValue, overrideValue);
+      continue;
+    }
+
+    result[key] = overrideValue;
+  }
+
+  return result;
+}
+
+function formatTomlPrimitive(value) {
+  if (typeof value === 'string') {
+    return `"${value
+      .replace(/\\/g, '\\\\')
+      .replace(/"/g, '\\"')
+      .replace(/\n/g, '\\n')}"`;
+  }
+
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new Error('Cannot serialize non-finite number to TOML.');
+    }
+    return String(value);
+  }
+
+  if (typeof value === 'boolean') {
+    return value ? 'true' : 'false';
+  }
+
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+
+  throw new Error(`Unsupported TOML primitive value type: ${typeof value}`);
+}
+
+function isTomlInlineValue(value) {
+  if (value === null || value === undefined) {
+    return false;
+  }
+
+  if (Array.isArray(value)) {
+    return value.every((item) => isTomlInlineValue(item));
+  }
+
+  if (isPlainObject(value)) {
+    return false;
+  }
+
+  return ['string', 'number', 'boolean'].includes(typeof value) || value instanceof Date;
+}
+
+function toTomlDocument(value) {
+  if (!isPlainObject(value)) {
+    throw new Error('TOML output requires a JSON object root.');
+  }
+
+  const lines = [];
+
+  function formatTomlKeySegment(segment) {
+    if (/^[A-Za-z0-9_-]+$/.test(segment)) {
+      return segment;
+    }
+
+    return `"${segment
+      .replace(/\\/g, '\\\\')
+      .replace(/"/g, '\\"')}"`;
+  }
+
+  function emitTable(tablePath, tableValue) {
+    const keys = Object.keys(tableValue).sort((a, b) => a.localeCompare(b));
+    const scalarLines = [];
+    const nestedTables = [];
+
+    for (const key of keys) {
+      const currentValue = tableValue[key];
+      if (currentValue === null || currentValue === undefined) {
+        continue;
+      }
+
+      if (isPlainObject(currentValue)) {
+        nestedTables.push({ key, value: currentValue });
+        continue;
+      }
+
+      if (Array.isArray(currentValue)) {
+        if (!currentValue.every((item) => isTomlInlineValue(item))) {
+          throw new Error(
+            `Unsupported array value for TOML key "${tablePath ? `${tablePath}.` : ''}${key}".`
+          );
+        }
+        const serializedItems = currentValue.map((item) => formatTomlPrimitive(item));
+        scalarLines.push(`${key} = [${serializedItems.join(', ')}]`);
+        continue;
+      }
+
+      scalarLines.push(`${key} = ${formatTomlPrimitive(currentValue)}`);
+    }
+
+    if (tablePath && scalarLines.length > 0) {
+      lines.push(`[${tablePath}]`);
+    }
+
+    for (const scalarLine of scalarLines) {
+      lines.push(scalarLine);
+    }
+
+    if (nestedTables.length > 0) {
+      if (tablePath || scalarLines.length > 0) {
+        lines.push('');
+      }
+
+      nestedTables.forEach((entry, index) => {
+        const childSegment = formatTomlKeySegment(entry.key);
+        const childPath = tablePath ? `${tablePath}.${childSegment}` : childSegment;
+        emitTable(childPath, entry.value);
+        if (index < nestedTables.length - 1) {
+          lines.push('');
+        }
+      });
+    }
+  }
+
+  emitTable('', value);
+  return `${lines.join('\n').trimEnd()}\n`;
+}
+
+function normalizeCodexMcpConfig(mergedConfig) {
+  if (!isPlainObject(mergedConfig)) {
+    throw new Error('Codex MCP config must be an object.');
+  }
+
+  if (isPlainObject(mergedConfig.mcp_servers)) {
+    return mergedConfig;
+  }
+
+  if (!isPlainObject(mergedConfig.servers)) {
+    return mergedConfig;
+  }
+
+  const { servers, ...rest } = mergedConfig;
+  return {
+    ...rest,
+    mcp_servers: servers,
+  };
+}
+
+function codexProjectTrustComment() {
+  return [
+    '# NOTE: Project-scoped MCP servers require trusting the project in Codex.',
+    '# Codex -> Settings -> Configuration -> Open config.toml',
+    '# Add:',
+    '# [projects."/path/to/your/project"]',
+    '# trust_level = "trusted"',
+    '',
+  ].join('\n');
+}
+
+async function listFilesMaybeRecursive(rootDir, recursive) {
+  if (!(await pathExists(rootDir))) {
+    return [];
+  }
+
+  if (recursive) {
+    return listFiles(rootDir);
+  }
+
+  const entries = await fs.readdir(rootDir, { withFileTypes: true });
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  return entries
+    .filter((entry) => entry.isFile())
+    .map((entry) => path.join(rootDir, entry.name));
+}
+
+async function collectSkillDirs(skillsRoot) {
+  const dirs = [];
+
+  async function walk(currentDir) {
+    const entries = await fs.readdir(currentDir, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+
+    let hasSkillFile = false;
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name === 'SKILL.md') {
+        hasSkillFile = true;
+        break;
+      }
+    }
+
+    if (hasSkillFile) {
+      dirs.push(currentDir);
+    }
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        await walk(path.join(currentDir, entry.name));
+      }
+    }
+  }
+
+  if (await pathExists(skillsRoot)) {
+    await walk(skillsRoot);
+  }
+
+  dirs.sort((a, b) => a.localeCompare(b));
+  return dirs;
+}
+
+export async function buildRenderPlan({ preset, layers, logger, projectRoot, configRoot }) {
+  const renderMap = new Map();
+  const warnings = [];
+  const skillDefinitions = [];
+  const promptDefinitions = [];
+  const subagentDefinitions = [];
+
+  function addRenderedText(relativePath, content, sourceLabel) {
+    const key = toPosixPath(relativePath);
+    if (renderMap.has(key)) {
+      const existing = renderMap.get(key);
+      throw new Error(
+        `Destination collision for ${key} between ${existing.source} and ${sourceLabel}`
+      );
+    }
+    renderMap.set(key, { content, source: sourceLabel });
+  }
+
+  function addRenderedFile(relativePath, content, sourcePath) {
+    addRenderedText(relativePath, content, toPosixPath(sourcePath));
+  }
+
+  function normalizeSubagentId(baseName) {
+    if (baseName.endsWith('.agent.md')) {
+      return removeSuffix(baseName, '.agent.md');
+    }
+    if (baseName.endsWith('.md')) {
+      return removeSuffix(baseName, '.md');
+    }
+    return baseName;
+  }
+
+  function normalizeRuleId(baseName) {
+    if (baseName.endsWith('.instructions.md')) {
+      return removeSuffix(baseName, '.instructions.md');
+    }
+    if (baseName.endsWith('.rule.md')) {
+      return removeSuffix(baseName, '.rule.md');
+    }
+    if (baseName.endsWith('.mdc')) {
+      return removeSuffix(baseName, '.mdc');
+    }
+    if (baseName.endsWith('.md')) {
+      return removeSuffix(baseName, '.md');
+    }
+    return baseName;
+  }
+
+  async function collectCanonicalRules() {
+    const rules = new Map();
+
+    for (const layer of layers) {
+      const rulesRoot = path.join(layer.path, 'rules');
+      const files = await listFilesMaybeRecursive(rulesRoot, preset.organization.includeRuleSubdirs);
+
+      for (const filePath of files) {
+        const baseName = path.basename(filePath);
+        if (!baseName.endsWith('.md') && !baseName.endsWith('.mdc')) {
+          continue;
+        }
+
+        const id = normalizeRuleId(baseName);
+        const relativePath = toPosixPath(path.relative(rulesRoot, filePath));
+        const { strippedContent, metadata } = await readScopeMetadata(filePath);
+        if (!shouldInclude({
+          selector: layer.select.rules,
+          metadata,
+          fallbackCandidates: [id, baseName, relativePath],
+        })) {
+          continue;
+        }
+
+        if (rules.has(id)) {
+          const existing = rules.get(id);
+          throw new Error(`Rule collision for id "${id}" between ${existing.sourcePath} and ${filePath}`);
+        }
+
+        rules.set(id, { id, layer: layer.name, sourcePath: filePath, content: strippedContent });
+      }
+    }
+
+    return rules;
+  }
+
+  async function collectLegacyRules(target) {
+    const rules = new Map();
+
+    for (const layer of layers) {
+      const root =
+        target === 'copilot'
+          ? path.join(layer.path, 'copilot', 'instructions')
+          : path.join(layer.path, 'cursor', 'rules');
+
+      const files = await listFilesMaybeRecursive(root, preset.organization.includeRuleSubdirs);
+      for (const filePath of files) {
+        const baseName = path.basename(filePath);
+        if (!baseName.endsWith('.instructions.md') && !baseName.endsWith('.md') && !baseName.endsWith('.mdc')) {
+          continue;
+        }
+
+        const id = normalizeRuleId(baseName);
+        const relativePath = toPosixPath(path.relative(root, filePath));
+        const { strippedContent, metadata } = await readScopeMetadata(filePath);
+        if (!shouldInclude({
+          selector: layer.select.rules,
+          metadata,
+          fallbackCandidates: [id, baseName, relativePath],
+        })) {
+          continue;
+        }
+
+        if (rules.has(id)) {
+          const existing = rules.get(id);
+          throw new Error(
+            `Rule collision for target "${target}" and id "${id}" between ${existing.sourcePath} and ${filePath}`
+          );
+        }
+
+        rules.set(id, { id, layer: layer.name, sourcePath: filePath, content: strippedContent });
+      }
+    }
+
+    return rules;
+  }
+
+  async function collectPortableSubagents() {
+    const portable = new Map();
+
+    for (const layer of layers) {
+      const portableRoot = path.join(layer.path, 'subagents');
+      const files = await listFilesMaybeRecursive(
+        portableRoot,
+        preset.organization.includeAgentSubdirs
+      );
+
+      for (const filePath of files) {
+        const baseName = path.basename(filePath);
+        if (!baseName.endsWith('.md')) {
+          continue;
+        }
+
+        const agentId = normalizeSubagentId(baseName);
+        const relativePath = toPosixPath(path.relative(portableRoot, filePath));
+        const { strippedContent, metadata } = await readScopeMetadata(filePath);
+        if (!shouldInclude({
+          selector: layer.select.subagents,
+          metadata,
+          fallbackCandidates: [agentId, baseName, relativePath],
+        })) {
+          continue;
+        }
+
+        if (portable.has(agentId)) {
+          const existing = portable.get(agentId);
+          throw new Error(
+            `Subagent collision for id "${agentId}" between ${existing.sourcePath} and ${filePath}`
+          );
+        }
+
+        portable.set(agentId, {
+          id: agentId,
+          layer: layer.name,
+          sourcePath: filePath,
+          content: strippedContent,
+          sourceKind: 'portable',
+        });
+      }
+    }
+
+    return portable;
+  }
+
+  async function collectToolSpecificSubagents(target) {
+    const perTarget = new Map();
+
+    for (const layer of layers) {
+      const root =
+        target === 'copilot'
+          ? path.join(layer.path, 'copilot', 'agents')
+          : target === 'claude'
+            ? path.join(layer.path, 'claude', 'agents')
+            : path.join(layer.path, 'cursor', 'agents');
+      const files = await listFilesMaybeRecursive(root, preset.organization.includeAgentSubdirs);
+
+      for (const filePath of files) {
+        const baseName = path.basename(filePath);
+        if (target === 'copilot' && !baseName.endsWith('.agent.md')) {
+          continue;
+        }
+        if (target === 'cursor' && !baseName.endsWith('.md')) {
+          continue;
+        }
+        if (target === 'claude' && !baseName.endsWith('.md')) {
+          continue;
+        }
+
+        const agentId = normalizeSubagentId(baseName);
+        const relativePath = toPosixPath(path.relative(root, filePath));
+        const { strippedContent, metadata } = await readScopeMetadata(filePath);
+        if (!shouldInclude({
+          selector: layer.select.subagents,
+          metadata,
+          fallbackCandidates: [agentId, baseName, relativePath],
+        })) {
+          continue;
+        }
+
+        if (perTarget.has(agentId)) {
+          const existing = perTarget.get(agentId);
+          throw new Error(
+            `Subagent collision for target "${target}" and id "${agentId}" between ${existing.sourcePath} and ${filePath}`
+          );
+        }
+
+        perTarget.set(agentId, {
+          id: agentId,
+          layer: layer.name,
+          sourcePath: filePath,
+          content: strippedContent,
+          sourceKind: target,
+        });
+      }
+    }
+
+    return perTarget;
+  }
+
+  const agentSections = [];
+  for (const layer of layers) {
+    const filePath = path.join(layer.path, 'agents', 'AGENTS.md');
+    if (!(await pathExists(filePath))) {
+      continue;
+    }
+
+    const content = await fs.readFile(filePath, 'utf8');
+    agentSections.push(`<!-- Layer: ${layer.name} -->\n${content.trim()}\n`);
+  }
+  const isConfigRootProject =
+    typeof projectRoot === 'string' &&
+    typeof configRoot === 'string' &&
+    path.resolve(projectRoot) === path.resolve(configRoot);
+
+  if (agentSections.length > 0 && !isConfigRootProject) {
+    addRenderedText('AGENTS.md', `${agentSections.join('\n').trim()}\n`, 'generated:AGENTS');
+    if (preset.targets.claude) {
+      addRenderedText('CLAUDE.md', `${agentSections.join('\n').trim()}\n`, 'generated:CLAUDE');
+    }
+  }
+
+  if (preset.targets.copilot) {
+    const instructionSections = [];
+    for (const layer of layers) {
+      const filePath = path.join(layer.path, 'copilot', 'copilot-instructions.md');
+      if (!(await pathExists(filePath))) {
+        continue;
+      }
+
+      const content = await fs.readFile(filePath, 'utf8');
+      instructionSections.push(`<!-- Layer: ${layer.name} -->\n${content.trim()}\n`);
+    }
+
+    if (instructionSections.length > 0) {
+      addRenderedText(
+        '.github/copilot-instructions.md',
+        `${instructionSections.join('\n').trim()}\n`,
+        'generated:copilot-instructions'
+      );
+    }
+  }
+
+  for (const layer of layers) {
+    const skillsRoot = path.join(layer.path, 'skills');
+    if (!(await pathExists(skillsRoot))) {
+      continue;
+    }
+
+    const skillDirs = await collectSkillDirs(skillsRoot);
+    for (const skillDir of skillDirs) {
+      const skillName = path.basename(skillDir);
+      const relativePath = toPosixPath(path.relative(skillsRoot, skillDir));
+      const skillFilePath = path.join(skillDir, 'SKILL.md');
+      const skillMeta = await readScopeMetadata(skillFilePath).catch(() => ({
+        metadata: { namespace: '', tags: [] },
+      }));
+
+      if (!shouldInclude({
+        selector: layer.select.skills,
+        metadata: skillMeta.metadata,
+        fallbackCandidates: [skillName, relativePath],
+      })) {
+        continue;
+      }
+
+      const files = await listFiles(skillDir);
+      for (const filePath of files) {
+        const relativeInSkill = toPosixPath(path.relative(skillDir, filePath));
+        const content = await fs.readFile(filePath, 'utf8');
+        const strippedContent = stripScopeFrontMatter(content);
+        addRenderedFile(path.posix.join('.agents/skills', skillName, relativeInSkill), strippedContent, filePath);
+      }
+
+      skillDefinitions.push({
+        name: skillName,
+        layer: layer.name,
+        relativePath,
+        skillDir,
+        skillFilePath,
+      });
+    }
+  }
+
+  async function renderPortableTree({ sourceFolder, destinationFolder, selectorKey }) {
+    for (const layer of layers) {
+      const sourceRoot = path.join(layer.path, sourceFolder);
+      const files = await listFilesMaybeRecursive(sourceRoot, true);
+
+      for (const filePath of files) {
+        const relativePath = toPosixPath(path.relative(sourceRoot, filePath));
+        const baseName = path.basename(filePath);
+        if (baseName.startsWith('.')) {
+          continue;
+        }
+        const id = removeSuffix(baseName, path.extname(baseName));
+        const { strippedContent, metadata } = await readScopeMetadata(filePath);
+        if (!shouldInclude({
+          selector: layer.select[selectorKey],
+          metadata,
+          fallbackCandidates: [id, baseName, relativePath],
+        })) {
+          continue;
+        }
+        addRenderedFile(path.posix.join(destinationFolder, relativePath), strippedContent, filePath);
+      }
+    }
+  }
+
+  await renderPortableTree({
+    sourceFolder: 'commands',
+    destinationFolder: '.agents/commands',
+    selectorKey: 'commands',
+  });
+
+  async function collectSelectedMcpJsonFiles() {
+    const files = [];
+
+    for (const layer of layers) {
+      const sourceRoot = path.join(layer.path, 'mcp');
+      const layerFiles = await listFilesMaybeRecursive(sourceRoot, true);
+
+      for (const filePath of layerFiles) {
+        const relativePath = toPosixPath(path.relative(sourceRoot, filePath));
+        const baseName = path.basename(filePath);
+        if (baseName.startsWith('.')) {
+          continue;
+        }
+
+        const id = removeSuffix(baseName, path.extname(baseName));
+        const { strippedContent, metadata } = await readScopeMetadata(filePath);
+        if (!shouldInclude({
+          selector: layer.select.mcp,
+          metadata,
+          fallbackCandidates: [id, baseName, relativePath],
+        })) {
+          continue;
+        }
+
+        const extension = path.extname(baseName).toLowerCase();
+        if (extension !== '.json') {
+          throw new Error(
+            `Unsupported MCP config format at ${filePath}. Only .json files can be merged into .vscode/mcp.json.`
+          );
+        }
+
+        files.push({
+          layer: layer.name,
+          filePath,
+          relativePath,
+          content: strippedContent,
+        });
+      }
+    }
+
+    return files;
+  }
+
+  async function renderMergedMcpConfig({ destinationPath, format }) {
+    const selectedFiles = await collectSelectedMcpJsonFiles();
+    if (selectedFiles.length === 0) {
+      return;
+    }
+
+    let merged = {};
+    for (const file of selectedFiles) {
+      let parsed;
+      try {
+        parsed = JSON.parse(file.content);
+      } catch (error) {
+        throw new Error(`Invalid JSON in MCP config ${file.filePath}: ${error.message}`);
+      }
+
+      if (!isPlainObject(parsed)) {
+        throw new Error(`MCP config must contain a JSON object at ${file.filePath}`);
+      }
+
+      merged = mergeObjects(merged, parsed);
+    }
+
+    const renderedContent =
+      format === 'toml'
+        ? `${codexProjectTrustComment()}${toTomlDocument(normalizeCodexMcpConfig(merged))}`
+        : `${JSON.stringify(merged, null, 2)}\n`;
+
+    addRenderedText(destinationPath, renderedContent, 'generated:mcp-merged');
+  }
+
+  if (preset.targets.copilot) {
+    await renderMergedMcpConfig({ destinationPath: '.vscode/mcp.json', format: 'json' });
+  }
+
+  if (preset.targets.cursor) {
+    await renderMergedMcpConfig({ destinationPath: '.cursor/mcp.json', format: 'json' });
+  }
+
+  if (preset.targets.codex) {
+    await renderMergedMcpConfig({ destinationPath: '.codex/config.toml', format: 'toml' });
+  }
+
+  if (preset.targets.copilot) {
+    for (const layer of layers) {
+      const promptsRoot = path.join(layer.path, 'prompts');
+      const promptFiles = await listFilesMaybeRecursive(promptsRoot, true);
+
+      for (const filePath of promptFiles) {
+        const baseName = path.basename(filePath);
+        if (!baseName.endsWith('.prompt.md')) {
+          continue;
+        }
+
+        const promptName = removeSuffix(baseName, '.prompt.md');
+        const relativePath = toPosixPath(path.relative(promptsRoot, filePath));
+        const { strippedContent, metadata } = await readScopeMetadata(filePath);
+        if (!shouldInclude({
+          selector: layer.select.prompts,
+          metadata,
+          fallbackCandidates: [promptName, baseName, relativePath],
+        })) {
+          continue;
+        }
+
+        addRenderedFile(path.posix.join('.github/prompts', baseName), strippedContent, filePath);
+        promptDefinitions.push({
+          name: baseName,
+          layer: layer.name,
+          sourcePath: filePath,
+          relativePath,
+        });
+      }
+
+    }
+  }
+
+  const canonicalRules = await collectCanonicalRules();
+
+  async function renderRules(target) {
+    const destinationRoot = target === 'copilot' ? '.github/instructions' : '.cursor/rules';
+    const extension = target === 'copilot' ? '.instructions.md' : '.mdc';
+
+    const source =
+      canonicalRules.size > 0 ? canonicalRules : await collectLegacyRules(target);
+
+    for (const rule of source.values()) {
+      const outputName = `${rule.id}${extension}`;
+      addRenderedFile(path.posix.join(destinationRoot, outputName), rule.content, rule.sourcePath);
+    }
+  }
+
+  if (preset.targets.copilot) {
+    await renderRules('copilot');
+  }
+
+  const sourceMode = preset.subagents.sourceMode;
+  const portableSubagents = await collectPortableSubagents();
+
+  if (preset.targets.cursor) {
+    await renderRules('cursor');
+  }
+
+  if (preset.subagents.portable) {
+    for (const agent of portableSubagents.values()) {
+      const portableName = `${agent.id}.md`;
+      addRenderedFile(path.posix.join('.agents/subagents', portableName), agent.content, agent.sourcePath);
+      subagentDefinitions.push({
+        target: 'portable',
+        id: agent.id,
+        name: portableName,
+        layer: agent.layer,
+        sourcePath: agent.sourcePath,
+        sourceKind: agent.sourceKind,
+      });
+    }
+  }
+
+  async function renderToolSubagents(target) {
+    const destinationRoot =
+      target === 'copilot'
+        ? '.github/agents'
+        : target === 'claude'
+          ? '.claude/agents'
+          : '.cursor/agents';
+    const extension = target === 'copilot' ? '.agent.md' : '.md';
+
+    if (sourceMode === 'centralized' && portableSubagents.size > 0) {
+      for (const agent of portableSubagents.values()) {
+        const outputName = `${agent.id}${extension}`;
+        addRenderedFile(path.posix.join(destinationRoot, outputName), agent.content, agent.sourcePath);
+        subagentDefinitions.push({
+          target,
+          id: agent.id,
+          name: outputName,
+          layer: agent.layer,
+          sourcePath: agent.sourcePath,
+          sourceKind: agent.sourceKind,
+        });
+      }
+      return;
+    }
+
+    const specific = await collectToolSpecificSubagents(target);
+    for (const agent of specific.values()) {
+      const outputName = `${agent.id}${extension}`;
+      addRenderedFile(path.posix.join(destinationRoot, outputName), agent.content, agent.sourcePath);
+      subagentDefinitions.push({
+        target,
+        id: agent.id,
+        name: outputName,
+        layer: agent.layer,
+        sourcePath: agent.sourcePath,
+        sourceKind: agent.sourceKind,
+      });
+    }
+  }
+
+  if (preset.targets.copilot) {
+    await renderToolSubagents('copilot');
+  }
+
+  if (preset.targets.cursor) {
+    await renderToolSubagents('cursor');
+  }
+
+  if (preset.targets.claude) {
+    await renderToolSubagents('claude');
+  }
+
+  function collectReferencedPortableReferences() {
+    const references = new Set();
+    const referencePattern = /\.agents\/references\/([A-Za-z0-9._\/-]+)/g;
+
+    for (const [relativePath, record] of renderMap.entries()) {
+      if (relativePath.startsWith('.agents/references/')) {
+        continue;
+      }
+
+      const content = record.content;
+      let match = referencePattern.exec(content);
+      while (match) {
+        const normalized = match[1].replace(/^\/+/, '');
+        references.add(normalized);
+        match = referencePattern.exec(content);
+      }
+    }
+
+    return [...references].sort((a, b) => a.localeCompare(b));
+  }
+
+  async function renderReferencedPortableReferences() {
+    const referencedPaths = collectReferencedPortableReferences();
+    const unresolved = new Set(referencedPaths);
+
+    for (const layer of layers) {
+      const sourceRoot = path.join(layer.path, 'references');
+      if (!(await pathExists(sourceRoot))) {
+        continue;
+      }
+
+      for (const referencePath of referencedPaths) {
+        const fullPath = path.join(sourceRoot, referencePath);
+        if (!(await pathExists(fullPath))) {
+          continue;
+        }
+
+        const content = await fs.readFile(fullPath, 'utf8');
+        const strippedContent = stripScopeFrontMatter(content);
+        addRenderedFile(path.posix.join('.agents/references', referencePath), strippedContent, fullPath);
+        unresolved.delete(referencePath);
+      }
+    }
+
+    for (const missing of unresolved) {
+      warnings.push(
+        `Referenced file .agents/references/${missing} was not found in selected layers references folders.`
+      );
+    }
+  }
+
+  await renderReferencedPortableReferences();
+
+  for (const warning of warnings) {
+    logger.warn(`Warning: ${warning}`);
+  }
+
+  return { renderMap, warnings, skillDefinitions, promptDefinitions, subagentDefinitions };
+}