aios-core 4.0.4 → 4.2.0

package/.aios-core/docs/standards/STORY-TEMPLATE-V2-SPECIFICATION.md

@@ -476,7 +476,7 @@ Use this checklist when creating or reviewing stories:
 #### Terminology
 - [ ] Uses "Squad" not "Expansion Pack"
 - [ ] Uses "@aios/" npm scope
-- [ ] References v2.1 architecture
+- [ ] References v4.0.4 architecture
 
 ---
 

package/.aios-core/framework-config.yaml

@@ -123,6 +123,10 @@ ide_sync_system:
       enabled: true
       path: ".claude/commands/AIOS/agents"
       format: "full-markdown-yaml"
+    codex:
+      enabled: true
+      path: ".codex/agents"
+      format: "full-markdown-yaml"
     cursor:
       enabled: true
       path: ".cursor/rules/agents"

package/.aios-core/infrastructure/scripts/codex-skills-sync/index.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const os = require('os');
+
+const {
+  parseAllAgents,
+  normalizeCommands,
+  getVisibleCommands,
+} = require('../ide-sync/agent-parser');
+
+function getCodexHome() {
+  return process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+}
+
+function getDefaultOptions() {
+  const projectRoot = process.cwd();
+  const envLocalDir = process.env.AIOS_CODEX_LOCAL_SKILLS_DIR;
+  const envGlobalDir = process.env.AIOS_CODEX_GLOBAL_SKILLS_DIR;
+  return {
+    projectRoot,
+    sourceDir: path.join(projectRoot, '.aios-core', 'development', 'agents'),
+    localSkillsDir: envLocalDir || path.join(projectRoot, '.codex', 'skills'),
+    globalSkillsDir: envGlobalDir || path.join(getCodexHome(), 'skills'),
+    global: false,
+    globalOnly: false,
+    dryRun: false,
+    quiet: false,
+  };
+}
+
+function trimText(text, max = 220) {
+  const normalized = String(text || '').replace(/\s+/g, ' ').trim();
+  if (normalized.length <= max) return normalized;
+  return `${normalized.slice(0, max - 3).trim()}...`;
+}
+
+function getSkillId(agentId) {
+  const id = String(agentId || '').trim();
+  if (id.startsWith('aios-')) return id;
+  return `aios-${id}`;
+}
+
+function buildSkillContent(agentData) {
+  const agent = agentData.agent || {};
+  const name = agent.name || agentData.id;
+  const title = agent.title || 'AIOS Agent';
+  const whenToUse = trimText(agent.whenToUse || `Use @${agentData.id} for specialized tasks.`);
+
+  const allCommands = normalizeCommands(agentData.commands || []);
+  const quick = getVisibleCommands(allCommands, 'quick');
+  const key = getVisibleCommands(allCommands, 'key');
+  const commands = [...quick, ...key.filter(k => !quick.some(q => q.name === k.name))]
+    .slice(0, 8)
+    .map(c => `- \`*${c.name}\` - ${c.description || 'No description'}`)
+    .join('\n');
+
+  const skillName = getSkillId(agentData.id);
+  const description = trimText(`${title} (${name}). ${whenToUse}`, 180);
+
+  return `---
+name: ${skillName}
+description: ${description}
+---
+
+# AIOS ${title} Activator
+
+## When To Use
+${whenToUse}
+
+## Activation Protocol
+1. Load \`.aios-core/development/agents/${agentData.filename}\` as source of truth (fallback: \`.codex/agents/${agentData.filename}\`).
+2. Adopt this agent persona and command system.
+3. Generate greeting via \`node .aios-core/development/scripts/generate-greeting.js ${agentData.id}\` and show it first.
+4. Stay in this persona until the user asks to switch or exit.
+
+## Starter Commands
+${commands || '- `*help` - List available commands'}
+
+## Non-Negotiables
+- Follow \`.aios-core/constitution.md\`.
+- Execute workflows/tasks only from declared dependencies.
+- Do not invent requirements outside the project artifacts.
+`;
+}
+
+function buildSkillPlan(agents, skillsDir) {
+  return agents
+    .filter(a => !a.error || a.error === 'YAML parse failed, using fallback extraction')
+    .map(agentData => {
+      const skillId = getSkillId(agentData.id);
+      const targetDir = path.join(skillsDir, skillId);
+      const targetFile = path.join(targetDir, 'SKILL.md');
+      return {
+        agentId: agentData.id,
+        skillId,
+        targetDir,
+        targetFile,
+        content: buildSkillContent(agentData),
+      };
+    });
+}
+
+function writeSkillPlan(plan, options) {
+  for (const item of plan) {
+    if (!options.dryRun) {
+      try {
+        fs.ensureDirSync(item.targetDir);
+        fs.writeFileSync(item.targetFile, item.content, 'utf8');
+      } catch (error) {
+        throw new Error(`Failed to write skill ${item.skillId} at ${item.targetFile}: ${error.message}`);
+      }
+    }
+  }
+}
+
+function syncSkills(options = {}) {
+  const resolved = { ...getDefaultOptions(), ...options };
+  if (resolved.globalOnly) {
+    resolved.global = true;
+  }
+  const agents = parseAllAgents(resolved.sourceDir);
+  const plan = buildSkillPlan(agents, resolved.localSkillsDir);
+
+  if (!resolved.globalOnly) {
+    writeSkillPlan(plan, resolved);
+  }
+
+  if (resolved.global) {
+    const globalPlan = buildSkillPlan(agents, resolved.globalSkillsDir);
+    writeSkillPlan(globalPlan, resolved);
+  }
+
+  return {
+    generated: plan.length,
+    localSkillsDir: resolved.localSkillsDir,
+    globalSkillsDir: resolved.global || resolved.globalOnly ? resolved.globalSkillsDir : null,
+    dryRun: resolved.dryRun,
+  };
+}
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const args = new Set(argv);
+  return {
+    global: args.has('--global'),
+    globalOnly: args.has('--global-only'),
+    dryRun: args.has('--dry-run'),
+    quiet: args.has('--quiet') || args.has('-q'),
+  };
+}
+
+function main() {
+  const options = parseArgs();
+  const result = syncSkills(options);
+
+  if (!options.quiet) {
+    if (!options.globalOnly) {
+      console.log(`✅ Generated ${result.generated} Codex skills in ${result.localSkillsDir}`);
+    }
+    if (result.globalSkillsDir) {
+      console.log(`✅ Installed ${result.generated} Codex skills in ${result.globalSkillsDir}`);
+    }
+    if (result.dryRun) {
+      console.log('ℹ️ Dry-run mode: no files written');
+    }
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  buildSkillContent,
+  buildSkillPlan,
+  syncSkills,
+  parseArgs,
+  getCodexHome,
+  getSkillId,
+};

package/.aios-core/infrastructure/scripts/codex-skills-sync/validate.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { parseAllAgents } = require('../ide-sync/agent-parser');
+const { getSkillId } = require('./index');
+
+function getDefaultOptions() {
+  const projectRoot = process.cwd();
+  return {
+    projectRoot,
+    sourceDir: path.join(projectRoot, '.aios-core', 'development', 'agents'),
+    skillsDir: path.join(projectRoot, '.codex', 'skills'),
+    strict: false,
+    quiet: false,
+    json: false,
+  };
+}
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const args = new Set(argv);
+  return {
+    strict: args.has('--strict'),
+    quiet: args.has('--quiet') || args.has('-q'),
+    json: args.has('--json'),
+  };
+}
+
+function isParsableAgent(agent) {
+  return !agent.error || agent.error === 'YAML parse failed, using fallback extraction';
+}
+
+function validateSkillContent(content, expected) {
+  const issues = [];
+  const requiredChecks = [
+    { ok: content.includes(`name: ${expected.skillId}`), reason: `missing frontmatter name "${expected.skillId}"` },
+    {
+      ok: content.includes(`.aios-core/development/agents/${expected.filename}`),
+      reason: `missing canonical agent path "${expected.filename}"`,
+    },
+    {
+      ok: content.includes(`generate-greeting.js ${expected.agentId}`),
+      reason: `missing canonical greeting command for "${expected.agentId}"`,
+    },
+    {
+      ok: content.includes('source of truth'),
+      reason: 'missing source-of-truth activation note',
+    },
+  ];
+
+  for (const check of requiredChecks) {
+    if (!check.ok) {
+      issues.push(check.reason);
+    }
+  }
+
+  return issues;
+}
+
+function validateCodexSkills(options = {}) {
+  const resolved = { ...getDefaultOptions(), ...options };
+  const errors = [];
+  const warnings = [];
+
+  if (!fs.existsSync(resolved.skillsDir)) {
+    errors.push(`Skills directory not found: ${resolved.skillsDir}`);
+    return { ok: false, checked: 0, expected: 0, errors, warnings, missing: [], orphaned: [] };
+  }
+
+  const agents = parseAllAgents(resolved.sourceDir).filter(isParsableAgent);
+  const expected = agents.map(agent => ({
+    agentId: agent.id,
+    filename: agent.filename,
+    skillId: getSkillId(agent.id),
+  }));
+
+  const missing = [];
+  for (const item of expected) {
+    const skillPath = path.join(resolved.skillsDir, item.skillId, 'SKILL.md');
+    if (!fs.existsSync(skillPath)) {
+      missing.push(item.skillId);
+      errors.push(`Missing skill file: ${path.relative(resolved.projectRoot, skillPath)}`);
+      continue;
+    }
+
+    let content;
+    try {
+      content = fs.readFileSync(skillPath, 'utf8');
+    } catch (error) {
+      errors.push(`${item.skillId}: unable to read skill file (${error.message})`);
+      continue;
+    }
+    const issues = validateSkillContent(content, item);
+    for (const issue of issues) {
+      errors.push(`${item.skillId}: ${issue}`);
+    }
+  }
+
+  const expectedIds = new Set(expected.map(item => item.skillId));
+  const orphaned = [];
+  if (resolved.strict) {
+    const dirs = fs.readdirSync(resolved.skillsDir, { withFileTypes: true })
+      .filter(entry => entry.isDirectory() && entry.name.startsWith('aios-'))
+      .map(entry => entry.name);
+    for (const dir of dirs) {
+      if (!expectedIds.has(dir)) {
+        orphaned.push(dir);
+        errors.push(`Orphaned skill directory: ${path.join(path.relative(resolved.projectRoot, resolved.skillsDir), dir)}`);
+      }
+    }
+  }
+
+  if (expected.length === 0) {
+    warnings.push('No parseable agents found in sourceDir');
+  }
+
+  return {
+    ok: errors.length === 0,
+    checked: expected.length,
+    expected: expected.length,
+    errors,
+    warnings,
+    missing,
+    orphaned,
+  };
+}
+
+function formatHumanReport(result) {
+  if (result.ok) {
+    return `✅ Codex skills validation passed (${result.checked} skills checked)`;
+  }
+
+  const lines = [
+    `❌ Codex skills validation failed (${result.errors.length} issue(s))`,
+    ...result.errors.map(error => `- ${error}`),
+  ];
+
+  if (result.warnings.length > 0) {
+    lines.push(...result.warnings.map(warning => `⚠️ ${warning}`));
+  }
+  return lines.join('\n');
+}
+
+function main() {
+  const args = parseArgs();
+  const result = validateCodexSkills(args);
+
+  if (!args.quiet) {
+    if (args.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatHumanReport(result));
+    }
+  }
+
+  if (!result.ok) {
+    process.exitCode = 1;
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  validateCodexSkills,
+  validateSkillContent,
+  parseArgs,
+  getDefaultOptions,
+};

package/.aios-core/infrastructure/scripts/ide-sync/README.md

@@ -10,10 +10,18 @@ Automatically synchronizes AIOS agent definitions to IDE command files.
 IDE Sync keeps agent definitions in `.aios-core/development/agents/` synchronized with IDE-specific command files in:
 
 - `.claude/commands/AIOS/agents/` (Claude Code)
+- `.codex/agents/` (Codex CLI support files)
 - `.cursor/rules/agents/` (Cursor)
 - `.windsurf/rules/agents/` (Windsurf)
 - `.antigravity/rules/agents/` (Antigravity)
 
+For Codex `/skills` activators, use the dedicated skills sync:
+
+```bash
+npm run sync:skills:codex
+npm run sync:skills:codex:global
+```
+
 ## Pre-commit Integration (Story TD-4)
 
 The pre-commit hook automatically:
@@ -48,6 +56,7 @@ Sync specific IDE only:
 
 ```bash
 npm run sync:ide:cursor
+npm run sync:ide:codex
 npm run sync:ide:windsurf
 ```
 
@@ -92,6 +101,10 @@ ideSync:
       enabled: true
       path: .claude/commands/AIOS/agents
       format: full-markdown-yaml
+    codex:
+      enabled: true
+      path: .codex/agents
+      format: full-markdown-yaml
     cursor:
       enabled: true
       path: .cursor/rules/agents
@@ -109,6 +122,7 @@ Each IDE has a specific format for agent files:
 | IDE         | Format                  | Extension |
 | ----------- | ----------------------- | --------- |
 | Claude Code | Full markdown with YAML | `.md`     |
+| Codex CLI   | Condensed rules         | `.md`     |
 | Cursor      | Condensed rules         | `.md`     |
 | Windsurf    | XML-tagged markdown     | `.md`     |
 | Antigravity | Cursor-style            | `.md`     |

package/.aios-core/infrastructure/scripts/ide-sync/index.js

@@ -61,6 +61,11 @@ function loadConfig(projectRoot) {
         path: '.claude/commands/AIOS/agents',
         format: 'full-markdown-yaml',
       },
+      codex: {
+        enabled: true,
+        path: '.codex/agents',
+        format: 'full-markdown-yaml',
+      },
       cursor: {
         enabled: true,
         path: '.cursor/rules/agents',
@@ -444,6 +449,7 @@ ${colors.bright}Options:${colors.reset}
 
 ${colors.bright}Examples:${colors.reset}
   node ide-sync/index.js sync
+  node ide-sync/index.js sync --ide codex
   node ide-sync/index.js sync --ide cursor
   node ide-sync/index.js validate --strict
   node ide-sync/index.js sync --dry-run --verbose

package/.aios-core/infrastructure/scripts/tool-resolver.js

@@ -8,7 +8,7 @@ const glob = require('glob');
  *
  * Features:
  * - Map-based caching for performance (<5ms cached lookups)
- * - Search path priority: expansion pack → common → core
+ * - Search path priority: squad → common → core
  * - Glob-based file resolution
  * - Schema validation
  * - Health checking (tool_call, command, http methods)
@@ -25,7 +25,7 @@ class ToolResolver {
     this.basePaths = [
       'aios-core/tools',
       'common/tools',
-      // Expansion pack paths added dynamically during resolution
+      // Squad paths added dynamically during resolution
     ];
   }
 
@@ -34,7 +34,7 @@ class ToolResolver {
    *
    * @param {string} toolName - Tool identifier (e.g., 'clickup', 'github-cli')
    * @param {object} context - Resolution context (optional)
-   * @param {string} context.expansionPack - Specific expansion pack to search
+   * @param {string} context.expansionPack - Specific squad to search
    * @returns {object} Tool definition with schema_version detected
    * @throws {Error} If tool not found or validation fails
    */
@@ -45,7 +45,7 @@ class ToolResolver {
       return this.cache.get(cacheKey);
     }
 
-    // 2. Build search paths (expansion pack → core priority)
+    // 2. Build search paths (squad → core priority)
     const searchPaths = [];
     if (context.expansionPack) {
       searchPaths.push(`expansion-packs/${context.expansionPack}/tools`);

package/.aios-core/infrastructure/scripts/validate-paths.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const FORBIDDEN_ABSOLUTE_PATTERNS = [
+  /\/Users\/[^\s/'"]+/g,
+  /\/home\/[^\s/'"]+/g,
+  /[A-Za-z]:\\Users\\[^\s\\'"]+/g,
+];
+
+function getDefaultOptions() {
+  const projectRoot = process.cwd();
+  return {
+    projectRoot,
+    skillsDir: path.join(projectRoot, '.codex', 'skills'),
+    requiredFiles: [
+      path.join(projectRoot, 'AGENTS.md'),
+      path.join(projectRoot, '.aios-core', 'product', 'templates', 'ide-rules', 'codex-rules.md'),
+    ],
+    quiet: false,
+    json: false,
+  };
+}
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const args = new Set(argv);
+  return {
+    quiet: args.has('--quiet') || args.has('-q'),
+    json: args.has('--json'),
+  };
+}
+
+function listSkillFiles(skillsDir) {
+  if (!fs.existsSync(skillsDir)) return [];
+  return fs.readdirSync(skillsDir, { withFileTypes: true })
+    .filter(entry => entry.isDirectory() && entry.name.startsWith('aios-'))
+    .map(entry => path.join(skillsDir, entry.name, 'SKILL.md'))
+    .filter(file => fs.existsSync(file));
+}
+
+function collectAbsolutePathViolations(content, filePath) {
+  const errors = [];
+  const lines = content.split('\n');
+  lines.forEach((line, index) => {
+    for (const pattern of FORBIDDEN_ABSOLUTE_PATTERNS) {
+      const matches = line.match(pattern) || [];
+      for (const match of matches) {
+        errors.push(`${filePath}:${index + 1} forbidden absolute path "${match}"`);
+      }
+    }
+  });
+  return errors;
+}
+
+function validateSkillPathConventions(content, filePath) {
+  const errors = [];
+  if (!content.includes('.aios-core/development/agents/')) {
+    errors.push(`${filePath} missing canonical source path ".aios-core/development/agents/"`);
+  }
+  if (!content.includes('.aios-core/development/scripts/generate-greeting.js')) {
+    errors.push(`${filePath} missing canonical greeting script path`);
+  }
+  return errors;
+}
+
+function validatePaths(options = {}) {
+  const resolved = { ...getDefaultOptions(), ...options };
+  const errors = [];
+  const checkedFiles = [];
+
+  const skillFiles = listSkillFiles(resolved.skillsDir);
+  const filesToCheck = [...resolved.requiredFiles, ...skillFiles];
+
+  for (const file of filesToCheck) {
+    if (!fs.existsSync(file)) {
+      errors.push(`Missing required file: ${path.relative(resolved.projectRoot, file)}`);
+      continue;
+    }
+
+    let content;
+    try {
+      content = fs.readFileSync(file, 'utf8');
+    } catch (error) {
+      errors.push(`Unable to read file: ${path.relative(resolved.projectRoot, file)} (${error.message})`);
+      continue;
+    }
+    checkedFiles.push(file);
+    errors.push(...collectAbsolutePathViolations(content, path.relative(resolved.projectRoot, file)));
+
+    if (file.endsWith('SKILL.md')) {
+      errors.push(...validateSkillPathConventions(content, path.relative(resolved.projectRoot, file)));
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    checked: checkedFiles.length,
+    errors,
+  };
+}
+
+function formatHumanReport(result) {
+  if (result.ok) {
+    return `✅ Path validation passed (${result.checked} files checked)`;
+  }
+  return [
+    `❌ Path validation failed (${result.errors.length} issue(s))`,
+    ...result.errors.map(error => `- ${error}`),
+  ].join('\n');
+}
+
+function main() {
+  const args = parseArgs();
+  const result = validatePaths(args);
+
+  if (!args.quiet) {
+    if (args.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatHumanReport(result));
+    }
+  }
+
+  if (!result.ok) {
+    process.exitCode = 1;
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  validatePaths,
+  parseArgs,
+  getDefaultOptions,
+  listSkillFiles,
+  collectAbsolutePathViolations,
+  validateSkillPathConventions,
+};