@ryuenn3123/agentic-senior-core 2.0.0 → 2.0.2

package/.agent-context/skills/backend/compatibility-manifest.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": "compatibility-manifest-v1",
+  "artifactType": "skill-domain",
+  "domain": "backend",
+  "ides": ["cursor", "windsurf", "copilot", "gemini", "claude", "codex", "cline"],
+  "nodeMin": "18",
+  "platforms": ["windows", "linux", "macos"]
+}

package/.agent-context/skills/cli/compatibility-manifest.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": "compatibility-manifest-v1",
+  "artifactType": "skill-domain",
+  "domain": "cli",
+  "ides": ["cursor", "windsurf", "copilot", "gemini", "claude", "codex", "cline"],
+  "nodeMin": "18",
+  "platforms": ["windows", "linux", "macos"]
+}

package/.agent-context/skills/distribution/compatibility-manifest.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": "compatibility-manifest-v1",
+  "artifactType": "skill-domain",
+  "domain": "distribution",
+  "ides": ["cursor", "windsurf", "copilot", "gemini", "claude", "codex", "cline"],
+  "nodeMin": "18",
+  "platforms": ["windows", "linux", "macos"]
+}

package/.agent-context/skills/frontend/compatibility-manifest.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": "compatibility-manifest-v1",
+  "artifactType": "skill-domain",
+  "domain": "frontend",
+  "ides": ["cursor", "windsurf", "copilot", "gemini", "claude", "codex", "cline"],
+  "nodeMin": "18",
+  "platforms": ["windows", "linux", "macos"]
+}

package/.agent-context/skills/fullstack/compatibility-manifest.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": "compatibility-manifest-v1",
+  "artifactType": "skill-domain",
+  "domain": "fullstack",
+  "ides": ["cursor", "windsurf", "copilot", "gemini", "claude", "codex", "cline"],
+  "nodeMin": "18",
+  "platforms": ["windows", "linux", "macos"]
+}

package/.agent-context/skills/review-quality/compatibility-manifest.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": "compatibility-manifest-v1",
+  "artifactType": "skill-domain",
+  "domain": "review-quality",
+  "ides": ["cursor", "windsurf", "copilot", "gemini", "claude", "codex", "cline"],
+  "nodeMin": "18",
+  "platforms": ["windows", "linux", "macos"]
+}

package/.agent-context/state/onboarding-report.json

@@ -1,13 +1,13 @@
 {
-  "cliVersion": "2.0.0",
-  "generatedAt": "2026-04-08T03:56:54.149Z",
+  "cliVersion": "2.0.1",
+  "generatedAt": "2026-04-08T14:58:53.636Z",
   "operationMode": "upgrade",
   "selectedProfile": "beginner",
   "selectedProfilePack": null,
   "selectedStack": "typescript.md",
   "selectedBlueprint": "api-nextjs.md",
   "ciGuardrailsEnabled": true,
-  "setupDurationMs": 86,
+  "setupDurationMs": 106,
   "selectedSkillDomains": [],
   "autoDetection": {
     "recommendedStack": "typescript.md",

package/.cursorrules

@@ -1,7 +1,7 @@
 # AGENTIC-SENIOR-CORE DYNAMIC GOVERNANCE RULESET
 
-Generated by Agentic-Senior-Core CLI v2.0.0
-Timestamp: 2026-04-08T03:56:54.094Z
+Generated by Agentic-Senior-Core CLI v2.0.2
+Timestamp: 2026-04-08T14:58:53.570Z
 Selected profile: beginner
 Selected policy file: .agent-context/policies/llm-judge-threshold.json
 

package/.windsurfrules

@@ -1,7 +1,7 @@
 # AGENTIC-SENIOR-CORE DYNAMIC GOVERNANCE RULESET
 
-Generated by Agentic-Senior-Core CLI v2.0.0
-Timestamp: 2026-04-08T03:56:54.094Z
+Generated by Agentic-Senior-Core CLI v2.0.2
+Timestamp: 2026-04-08T14:58:53.570Z
 Selected profile: beginner
 Selected policy file: .agent-context/policies/llm-judge-threshold.json
 

package/README.md

@@ -103,7 +103,7 @@ If you have an existing project and want to infuse it with Staff-level context:
 npx @ryuenn3123/agentic-senior-core init
 ```
 
-Use team defaults (V1.8 track) with profile packs:
+Use team defaults (V2.0 track) with profile packs:
 
 ```bash
 npx @ryuenn3123/agentic-senior-core init --profile-pack startup
@@ -128,6 +128,27 @@ agentic-senior-core skill fullstack --json
 
 When you run `init`, the CLI now auto-activates the matching skill packs for the chosen stack and blueprint, so the compiled governance context includes the relevant frontend, backend, fullstack, and CLI guidance by default.
 
+### Token Optimization Mode (Optional and User-Friendly)
+
+Use this mode when your AI session is shell-heavy and context usage is high.
+It is optional by design and works in two modes:
+- Native fallback mode (no external dependency required)
+- External proxy mode (auto-detected when available)
+
+Quick start:
+
+```bash
+agentic-senior-core optimize . --agent copilot --enable
+agentic-senior-core optimize . --show
+agentic-senior-core optimize . --disable
+
+# Auto-enable during project initialization
+npx @ryuenn3123/agentic-senior-core init --token-optimize --token-agent copilot
+```
+
+When enabled, the CLI writes `.agent-context/state/token-optimization.json`, regenerates compiled rules, and adds compact command guidance to `.cursorrules` and `.windsurfrules`.
+If an external token proxy is available, the CLI prints setup hints. If not, native fallback guidance stays active, so outside users are not forced to install extra tooling.
+
 ### Install and Setup Choices
 
 The CLI now supports a smaller decision surface for first-time setup:
@@ -139,6 +160,7 @@ The CLI now supports a smaller decision surface for first-time setup:
 | npm exec / npx | One-off setup on an existing repo |
 | npm install -g | Repeated local use from the shell |
 | `--preset` | Fast bootstrap with a curated stack and blueprint |
+| `optimize` | Optional token-aware shell output guidance with native fallback |
 
 ### Supported Stack Map
 
@@ -170,7 +192,7 @@ Use the stack that matches the project you are actually starting:
 ### Option 4: Clone and Play
 Want to poke around under the hood? Just clone the repo and `npx @ryuenn3123/agentic-senior-core init` locally. No runtime dependencies needed — everything uses native Node.js!
 
-### Upgrade Existing Governance Packs (V1.8)
+### Upgrade Existing Governance Packs (V1.x to V2.x)
 
 Yes, the upgrade flow still works. Use `--dry-run` first to preview changes, then apply with `--yes` when you are ready.
 
@@ -201,7 +223,8 @@ Our documentation has shifted into dedicated tracks to keep this README light:
 
 ## Core Capabilities
 
-- **Delivery Engine (CLI):** Interactive setup via GitHub source, bootstrap scripts, or `npx` after publish.
+- **Delivery Engine (CLI):** Interactive setup via GitHub source, bootstrap scripts, or `npx` after publish. Supported by a robust transactional installer with rollback protection.
+- **Verified Skill Marketplace:** Distribute and validate plugins securely with automated 4-dimension Trust Scoring and Evidence Bundles constraint validation.
 - **Dynamic Context Compiler:** Merges universal rules + selected stack + selected blueprint + optional CI guardrails into one dense, indexed rule file.
 - **Codebase Intelligence:** `.agent-context/state/` gives architecture/dependency boundaries so the agent understands high-risk areas.
 - **Override System:** `.agent-override.md` allows controlled enterprise exceptions without forking core rules.

package/bin/agentic-senior-core.js

@@ -11,6 +11,7 @@ import { CLI_VERSION } from '../lib/cli/constants.mjs';
 import { printUsage } from '../lib/cli/utils.mjs';
 import { runLaunchCommand } from '../lib/cli/commands/launch.mjs';
 import { runRollbackCommand } from '../lib/cli/commands/rollback.mjs';
+import { runOptimizeCommand, parseOptimizeArguments } from '../lib/cli/commands/optimize.mjs';
 import { runInitCommand, parseInitArguments } from '../lib/cli/commands/init.mjs';
 import { runUpgradeCommand, parseUpgradeArguments } from '../lib/cli/commands/upgrade.mjs';
 import { runSkillCommand } from '../lib/cli/skill-selector.mjs';
@@ -45,6 +46,12 @@ async function main() {
     return;
   }
 
+  if (commandArgument === 'optimize') {
+    const optimizeOptions = parseOptimizeArguments(commandArguments);
+    await runOptimizeCommand(optimizeOptions.targetDirectory, optimizeOptions);
+    return;
+  }
+
   if (commandArgument === 'init') {
     const initOptions = parseInitArguments(commandArguments);
     await runInitCommand(initOptions.targetDirectory, initOptions);

package/lib/cli/commands/init.mjs

@@ -35,6 +35,13 @@ import { compileDynamicContext, writeSelectedPolicy, writeOnboardingReport } fro
 import { runPreflightChecks } from '../preflight.mjs';
 import { createBackup } from '../backup.mjs';
 import { performRollback } from '../rollback.mjs';
+import {
+  createTokenOptimizationState,
+  detectRtkBinary,
+  normalizeAgentName,
+  writeTokenOptimizationState,
+} from '../token-optimization.mjs';
+import { evaluateSkillDomainCompatibility } from '../compatibility.mjs';
 
 export { REPO_ROOT } from '../constants.mjs';
 
@@ -48,6 +55,8 @@ export function parseInitArguments(commandArguments) {
     blueprint: undefined,
     ci: undefined,
     newbie: false,
+    tokenOptimize: false,
+    tokenAgent: 'copilot',
   };
 
   for (let argumentIndex = 0; argumentIndex < commandArguments.length; argumentIndex++) {
@@ -130,6 +139,29 @@ export function parseInitArguments(commandArguments) {
       continue;
     }
 
+    if (currentArgument === '--token-optimize') {
+      parsedInitOptions.tokenOptimize = true;
+      continue;
+    }
+
+    if (currentArgument === '--token-agent') {
+      parsedInitOptions.tokenAgent = commandArguments[argumentIndex + 1] || 'copilot';
+      parsedInitOptions.tokenOptimize = true;
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--token-agent=')) {
+      parsedInitOptions.tokenAgent = currentArgument.split('=')[1] || 'copilot';
+      parsedInitOptions.tokenOptimize = true;
+      continue;
+    }
+
+    if (currentArgument === '--no-token-optimize') {
+      parsedInitOptions.tokenOptimize = false;
+      continue;
+    }
+
     throw new Error(`Unknown option: ${currentArgument}`);
   }
 
@@ -137,11 +169,21 @@ export function parseInitArguments(commandArguments) {
     throw new Error('--newbie can only be combined with --profile beginner');
   }
 
+  parsedInitOptions.tokenAgent = normalizeAgentName(parsedInitOptions.tokenAgent);
+
   return parsedInitOptions;
 }
 
 export async function runInitCommand(targetDirectoryArgument, initOptions = {}) {
   const resolvedTargetDirectoryPath = path.resolve(targetDirectoryArgument || '.');
+
+  if (resolvedTargetDirectoryPath.toLowerCase() === 'c:\\windows' || resolvedTargetDirectoryPath.toLowerCase() === 'c:\\windows\\system32') {
+    console.error('\n[FATAL] Target directory resolved to a Windows system folder (C:\\Windows).');
+    console.error('If you are running Windows npm from inside WSL, this is caused by cmd.exe lacking UNC path support.');
+    console.error('Please install and use a native Linux Node.js/npm directly inside WSL to setup your project.');
+    process.exit(1);
+  }
+
   const setupStartedAt = Date.now();
   await ensureDirectory(resolvedTargetDirectoryPath);
 
@@ -287,6 +329,11 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
         )
       ];
 
+    const selectedSkillDomainNames = inferSkillDomainNamesFromSelection(
+      selectedResolvedStackFileName,
+      selectedResolvedBlueprintFileName
+    );
+
     const includeCiGuardrails = typeof initOptions.ci === 'boolean'
       ? initOptions.ci
       : typeof selectedPreset?.ci === 'boolean'
@@ -301,6 +348,33 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
 
     await copyGovernanceAssetsToTarget(resolvedTargetDirectoryPath);
 
+    if (initOptions.tokenOptimize) {
+      const detectedExternalProxy = detectRtkBinary();
+      const tokenOptimizationState = createTokenOptimizationState({
+        isEnabled: true,
+        selectedAgentName: initOptions.tokenAgent,
+        rtkDetection: detectedExternalProxy,
+      });
+
+      await writeTokenOptimizationState(resolvedTargetDirectoryPath, tokenOptimizationState);
+      console.log(
+        `Token optimization policy enabled for agent ${tokenOptimizationState.selectedAgent} (${tokenOptimizationState.preferredShellProxy}).`
+      );
+    }
+
+    const compatibilityWarnings = await evaluateSkillDomainCompatibility(
+      resolvedTargetDirectoryPath,
+      selectedSkillDomainNames
+    );
+
+    if (compatibilityWarnings.length > 0) {
+      console.log('\n[WARN] Compatibility checks reported potential issues for this environment:');
+      for (const compatibilityWarning of compatibilityWarnings) {
+        console.log(`- ${compatibilityWarning}`);
+      }
+      console.log('Installation will continue, but review these warnings before production use.');
+    }
+
     await compileDynamicContext({
       targetDirectoryPath: resolvedTargetDirectoryPath,
       selectedProfileName,
@@ -323,7 +397,8 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
       includeCiGuardrails,
       setupDurationMs,
       projectDetection,
-      selectedSkillDomains: inferSkillDomainNamesFromSelection(selectedResolvedStackFileName, selectedResolvedBlueprintFileName),
+      selectedSkillDomains: selectedSkillDomainNames,
+      compatibilityWarnings,
       operationMode: 'init',
     });
 
@@ -342,6 +417,9 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     console.log(`- Blocking severities: ${formatBlockingSeverities(selectedProfile.blockingSeverities)}`);
     console.log(`- Setup time: ${formatDuration(setupDurationMs)}`);
     console.log('- Generated files: .cursorrules, .windsurfrules, and .agent-context/state/onboarding-report.json');
+    if (initOptions.tokenOptimize) {
+      console.log(`- Token optimization policy: enabled for ${initOptions.tokenAgent}`);
+    }
     console.log('\nPlain-language summary:');
     console.log(`I prepared a ${selectedProfile.displayName.toLowerCase()} governance pack for a ${toTitleCase(selectedResolvedStackFileName)} project using the ${toTitleCase(selectedResolvedBlueprintFileName)} blueprint.`);
     console.log('Your AI tools will now receive one compiled rulebook plus the original source rules, and your review threshold is stored in .agent-context/policies/llm-judge-threshold.json.');

package/lib/cli/commands/launch.mjs

@@ -9,6 +9,7 @@ import { CLI_VERSION, INIT_PRESETS } from '../constants.mjs';
 import { askChoice, normalizeChoiceInput } from '../utils.mjs';
 import { runInitCommand } from './init.mjs';
 import { runSkillCommand } from '../skill-selector.mjs';
+import { runOptimizeCommand } from './optimize.mjs';
 
 export async function runLaunchCommand() {
   const userInterface = createInterface({ input: stdin, output: stdout });
@@ -25,6 +26,7 @@ export async function runLaunchCommand() {
         'Bootstrap scripts',
         'Preset starter',
         'Interactive init wizard',
+        'Enable token optimization',
         'Skill selector',
         'Exit',
       ],
@@ -69,6 +71,21 @@ export async function runLaunchCommand() {
       return;
     }
 
+    if (launchChoice === 'Enable token optimization') {
+      const selectedAgent = await askChoice(
+        'Choose your primary agent integration:',
+        ['copilot', 'claude', 'cursor', 'windsurf', 'gemini', 'codex', 'cline'],
+        userInterface
+      );
+
+      await runOptimizeCommand('.', {
+        targetDirectory: '.',
+        agent: selectedAgent,
+        enabled: true,
+      });
+      return;
+    }
+
     if (launchChoice === 'Skill selector') {
       await runSkillCommand([]);
       return;

package/lib/cli/commands/optimize.mjs

@@ -0,0 +1,171 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { ensureDirectory, formatDuration } from '../utils.mjs';
+import { compileDynamicContext, loadOnboardingReportIfExists } from '../compiler.mjs';
+import {
+  TOKEN_OPTIMIZATION_REPORT_FILE_NAME,
+  normalizeAgentName,
+  detectRtkBinary,
+  buildRtkInstallHint,
+  buildRtkHookCommand,
+  createTokenOptimizationState,
+  readTokenOptimizationState,
+  writeTokenOptimizationState,
+} from '../token-optimization.mjs';
+
+function normalizeMarkdownFileName(rawFileName, fallbackFileName) {
+  if (typeof rawFileName !== 'string' || rawFileName.trim().length === 0) {
+    return fallbackFileName;
+  }
+
+  const normalizedFileName = rawFileName.trim();
+  return normalizedFileName.endsWith('.md')
+    ? normalizedFileName
+    : `${normalizedFileName}.md`;
+}
+
+export function parseOptimizeArguments(commandArguments) {
+  const parsedOptimizeOptions = {
+    targetDirectory: '.',
+    agent: 'copilot',
+    enabled: true,
+    show: false,
+  };
+
+  for (let argumentIndex = 0; argumentIndex < commandArguments.length; argumentIndex++) {
+    const currentArgument = commandArguments[argumentIndex];
+
+    if (!currentArgument.startsWith('--')) {
+      parsedOptimizeOptions.targetDirectory = currentArgument;
+      continue;
+    }
+
+    if (currentArgument === '--agent') {
+      parsedOptimizeOptions.agent = commandArguments[argumentIndex + 1] || 'copilot';
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--agent=')) {
+      parsedOptimizeOptions.agent = currentArgument.split('=')[1] || 'copilot';
+      continue;
+    }
+
+    if (currentArgument === '--enable') {
+      parsedOptimizeOptions.enabled = true;
+      continue;
+    }
+
+    if (currentArgument === '--disable') {
+      parsedOptimizeOptions.enabled = false;
+      continue;
+    }
+
+    if (currentArgument === '--show') {
+      parsedOptimizeOptions.show = true;
+      continue;
+    }
+
+    throw new Error(`Unknown option: ${currentArgument}`);
+  }
+
+  parsedOptimizeOptions.agent = normalizeAgentName(parsedOptimizeOptions.agent);
+  return parsedOptimizeOptions;
+}
+
+export async function runOptimizeCommand(targetDirectoryArgument, optimizeOptions = {}) {
+  const optimizationStartedAt = Date.now();
+  const resolvedTargetDirectoryPath = path.resolve(targetDirectoryArgument || '.');
+
+  await ensureDirectory(resolvedTargetDirectoryPath);
+
+  const selectedAgentName = normalizeAgentName(optimizeOptions.agent || 'copilot');
+  const rtkDetection = detectRtkBinary();
+
+  if (optimizeOptions.show) {
+    const existingOptimizationState = await readTokenOptimizationState(resolvedTargetDirectoryPath);
+    console.log(
+      JSON.stringify(
+        {
+          targetDirectory: resolvedTargetDirectoryPath,
+          selectedAgent: selectedAgentName,
+          externalProxy: rtkDetection,
+          tokenOptimizationState: existingOptimizationState,
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+
+  const onboardingReport = await loadOnboardingReportIfExists(resolvedTargetDirectoryPath);
+  if (!onboardingReport) {
+    throw new Error(
+      'Token optimization requires an initialized repository. Run "agentic-senior-core init" first.'
+    );
+  }
+
+  const tokenOptimizationState = createTokenOptimizationState({
+    isEnabled: optimizeOptions.enabled,
+    selectedAgentName,
+    rtkDetection,
+  });
+
+  await writeTokenOptimizationState(resolvedTargetDirectoryPath, tokenOptimizationState);
+
+  const selectedProfileName = typeof onboardingReport.selectedProfile === 'string'
+    ? onboardingReport.selectedProfile
+    : 'balanced';
+  const selectedStackFileName = normalizeMarkdownFileName(onboardingReport.selectedStack, 'typescript.md');
+  const selectedBlueprintFileName = normalizeMarkdownFileName(onboardingReport.selectedBlueprint, 'api-nextjs.md');
+  const includeCiGuardrails = typeof onboardingReport.ciGuardrailsEnabled === 'boolean'
+    ? onboardingReport.ciGuardrailsEnabled
+    : true;
+
+  await compileDynamicContext({
+    targetDirectoryPath: resolvedTargetDirectoryPath,
+    selectedProfileName,
+    selectedStackFileName,
+    selectedBlueprintFileName,
+    includeCiGuardrails,
+  });
+
+  const optimizationDurationMs = Date.now() - optimizationStartedAt;
+  const tokenOptimizationReport = {
+    generatedAt: new Date().toISOString(),
+    targetDirectory: resolvedTargetDirectoryPath,
+    enabled: tokenOptimizationState.enabled,
+    selectedAgent: tokenOptimizationState.selectedAgent,
+    preferredShellProxy: tokenOptimizationState.preferredShellProxy,
+    externalProxy: tokenOptimizationState.externalProxy,
+    setupDurationMs: optimizationDurationMs,
+  };
+
+  const reportFilePath = path.join(
+    resolvedTargetDirectoryPath,
+    '.agent-context',
+    'state',
+    TOKEN_OPTIMIZATION_REPORT_FILE_NAME
+  );
+  await fs.writeFile(reportFilePath, JSON.stringify(tokenOptimizationReport, null, 2) + '\n', 'utf8');
+
+  console.log(`\nToken optimization ${tokenOptimizationState.enabled ? 'enabled' : 'disabled'}.`);
+  console.log(`- Target directory: ${resolvedTargetDirectoryPath}`);
+  console.log(`- Agent profile: ${tokenOptimizationState.selectedAgent}`);
+  console.log(`- Preferred shell proxy: ${tokenOptimizationState.preferredShellProxy}`);
+  console.log(`- Setup time: ${formatDuration(optimizationDurationMs)}`);
+  console.log('- Updated files: .cursorrules, .windsurfrules, .agent-context/state/token-optimization.json');
+
+  if (tokenOptimizationState.enabled) {
+    if (rtkDetection.isAvailable) {
+      console.log(`- External proxy detected: ${rtkDetection.version ? `v${rtkDetection.version}` : 'yes'}`);
+      console.log('- Recommended hook command:');
+      console.log(`  ${buildRtkHookCommand(tokenOptimizationState.selectedAgent)}`);
+    } else {
+      console.log('- External proxy not detected. Native fallback mode has been activated.');
+      console.log(`- Install hint: ${buildRtkInstallHint()}`);
+    }
+  }
+}

package/lib/cli/commands/rollback.mjs

@@ -15,6 +15,13 @@ export async function runRollbackCommand(commandArguments) {
   }
 
   const resolvedTargetDirectoryPath = path.resolve(targetDirectoryArgument);
+
+  if (resolvedTargetDirectoryPath.toLowerCase() === 'c:\\windows' || resolvedTargetDirectoryPath.toLowerCase() === 'c:\\windows\\system32') {
+    console.error('\n[FATAL] Target directory resolved to a Windows system folder (C:\\Windows).');
+    console.error('If you are running Windows npm from inside WSL, this is caused by cmd.exe lacking UNC path support.');
+    console.error('Please install and use a native Linux Node.js/npm directly inside WSL to setup your project.');
+    process.exit(1);
+  }
   
   try {
       await ensureDirectory(resolvedTargetDirectoryPath);

package/lib/cli/commands/upgrade.mjs

@@ -35,6 +35,8 @@ import {
 import { runPreflightChecks } from '../preflight.mjs';
 import { createBackup } from '../backup.mjs';
 import { performRollback } from '../rollback.mjs';
+import { inferSkillDomainNamesFromSelection } from '../skill-selector.mjs';
+import { evaluateSkillDomainCompatibility } from '../compatibility.mjs';
 
 export function parseUpgradeArguments(commandArguments) {
   const parsedUpgradeOptions = {
@@ -69,6 +71,14 @@ export function parseUpgradeArguments(commandArguments) {
 
 export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions = {}) {
   const resolvedTargetDirectoryPath = path.resolve(targetDirectoryArgument || '.');
+
+  if (resolvedTargetDirectoryPath.toLowerCase() === 'c:\\windows' || resolvedTargetDirectoryPath.toLowerCase() === 'c:\\windows\\system32') {
+    console.error('\n[FATAL] Target directory resolved to a Windows system folder (C:\\Windows).');
+    console.error('If you are running Windows npm from inside WSL, this is caused by cmd.exe lacking UNC path support.');
+    console.error('Please install and use a native Linux Node.js/npm directly inside WSL to setup your project.');
+    process.exit(1);
+  }
+
   const setupStartedAt = Date.now();
   await ensureDirectory(resolvedTargetDirectoryPath);
 
@@ -108,6 +118,23 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
       ? existingOnboardingReport.ciGuardrailsEnabled
       : true;
 
+    const selectedSkillDomainNames = inferSkillDomainNamesFromSelection(
+      selectedStackFileName,
+      selectedBlueprintFileName
+    );
+    const compatibilityWarnings = await evaluateSkillDomainCompatibility(
+      resolvedTargetDirectoryPath,
+      selectedSkillDomainNames
+    );
+
+    if (compatibilityWarnings.length > 0) {
+      console.log('\n[WARN] Compatibility checks reported potential issues for this environment:');
+      for (const compatibilityWarning of compatibilityWarnings) {
+        console.log(`- ${compatibilityWarning}`);
+      }
+      console.log('Upgrade will continue, but review these warnings before production use.');
+    }
+
     const currentRulesPath = path.join(resolvedTargetDirectoryPath, '.cursorrules');
     const currentRulesContent = await pathExists(currentRulesPath)
       ? await fs.readFile(currentRulesPath, 'utf8')
@@ -166,6 +193,8 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
         includeCiGuardrails,
         setupDurationMs,
         projectDetection,
+        selectedSkillDomains: selectedSkillDomainNames,
+        compatibilityWarnings,
         operationMode: 'upgrade',
       });
 

package/lib/cli/compatibility.mjs

@@ -0,0 +1,124 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { platform, version } from 'node:process';
+
+import { pathExists } from './utils.mjs';
+
+export const SKILL_COMPATIBILITY_MANIFEST_FILE_NAME = 'compatibility-manifest.json';
+
+export function getCurrentPlatformLabel() {
+  if (platform === 'win32') {
+    return 'windows';
+  }
+
+  if (platform === 'darwin') {
+    return 'macos';
+  }
+
+  return 'linux';
+}
+
+export function parseNodeMajorVersion(rawVersionString = version) {
+  const normalizedVersionString = String(rawVersionString || '').trim();
+  const numericVersion = normalizedVersionString.startsWith('v')
+    ? normalizedVersionString.slice(1)
+    : normalizedVersionString;
+
+  const majorSegment = numericVersion.split('.')[0];
+  const parsedMajorVersion = Number.parseInt(majorSegment, 10);
+  return Number.isNaN(parsedMajorVersion) ? null : parsedMajorVersion;
+}
+
+export function parseNodeMinimumMajor(rawNodeMinimum) {
+  const normalizedNodeMinimum = String(rawNodeMinimum || '').trim();
+  if (!normalizedNodeMinimum) {
+    return null;
+  }
+
+  const majorSegment = normalizedNodeMinimum.split('.')[0];
+  const parsedMajorVersion = Number.parseInt(majorSegment, 10);
+  return Number.isNaN(parsedMajorVersion) ? null : parsedMajorVersion;
+}
+
+export async function readSkillDomainCompatibilityManifest(targetDirectoryPath, skillDomainName) {
+  const compatibilityManifestPath = path.join(
+    targetDirectoryPath,
+    '.agent-context',
+    'skills',
+    skillDomainName,
+    SKILL_COMPATIBILITY_MANIFEST_FILE_NAME
+  );
+
+  if (!(await pathExists(compatibilityManifestPath))) {
+    return {
+      exists: false,
+      compatibilityManifestPath,
+      parsedManifest: null,
+    };
+  }
+
+  try {
+    const compatibilityManifestContent = await fs.readFile(compatibilityManifestPath, 'utf8');
+    return {
+      exists: true,
+      compatibilityManifestPath,
+      parsedManifest: JSON.parse(compatibilityManifestContent),
+    };
+  } catch (error) {
+    return {
+      exists: true,
+      compatibilityManifestPath,
+      parsedManifest: null,
+      parseError: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export async function evaluateSkillDomainCompatibility(targetDirectoryPath, skillDomainNames) {
+  const uniqueSkillDomainNames = Array.from(new Set(skillDomainNames || []));
+  const compatibilityWarnings = [];
+
+  const currentPlatformLabel = getCurrentPlatformLabel();
+  const currentNodeMajorVersion = parseNodeMajorVersion(version);
+
+  for (const skillDomainName of uniqueSkillDomainNames) {
+    const manifestResult = await readSkillDomainCompatibilityManifest(targetDirectoryPath, skillDomainName);
+
+    if (!manifestResult.exists) {
+      compatibilityWarnings.push(
+        `Domain ${skillDomainName} has no ${SKILL_COMPATIBILITY_MANIFEST_FILE_NAME}; compatibility cannot be verified.`
+      );
+      continue;
+    }
+
+    if (!manifestResult.parsedManifest) {
+      compatibilityWarnings.push(
+        `Domain ${skillDomainName} has invalid ${SKILL_COMPATIBILITY_MANIFEST_FILE_NAME}: ${manifestResult.parseError || 'Unknown parse error'}.`
+      );
+      continue;
+    }
+
+    const manifestPlatforms = Array.isArray(manifestResult.parsedManifest.platforms)
+      ? manifestResult.parsedManifest.platforms
+      : [];
+
+    if (manifestPlatforms.length > 0 && !manifestPlatforms.includes(currentPlatformLabel)) {
+      compatibilityWarnings.push(
+        `Domain ${skillDomainName} does not list platform ${currentPlatformLabel} in ${SKILL_COMPATIBILITY_MANIFEST_FILE_NAME}.`
+      );
+    }
+
+    const minimumNodeMajorVersion = parseNodeMinimumMajor(manifestResult.parsedManifest.nodeMin);
+    if (
+      typeof minimumNodeMajorVersion === 'number'
+      && typeof currentNodeMajorVersion === 'number'
+      && currentNodeMajorVersion < minimumNodeMajorVersion
+    ) {
+      compatibilityWarnings.push(
+        `Domain ${skillDomainName} requires Node.js >= ${minimumNodeMajorVersion}, current major version is ${currentNodeMajorVersion}.`
+      );
+    }
+  }
+
+  return compatibilityWarnings;
+}

package/lib/cli/compiler.mjs

@@ -21,6 +21,11 @@ import {
   buildSkillPackSection,
 } from './skill-selector.mjs';
 
+import {
+  readTokenOptimizationState,
+  buildTokenOptimizationGuidanceBlock,
+} from './token-optimization.mjs';
+
 export async function writeSelectedPolicy(targetDirectoryPath, selectedProfileName) {
   const policyFilePath = path.join(targetDirectoryPath, '.agent-context', 'policies', POLICY_FILE_NAME);
   const parsedPolicy = JSON.parse(await fs.readFile(policyFilePath, 'utf8'));
@@ -39,6 +44,7 @@ export async function writeOnboardingReport({
   setupDurationMs,
   projectDetection,
   selectedSkillDomains = [],
+  compatibilityWarnings = [],
   operationMode = 'init',
 }) {
   const onboardingReportPath = path.join(targetDirectoryPath, '.agent-context', 'state', 'onboarding-report.json');
@@ -59,6 +65,7 @@ export async function writeOnboardingReport({
     ciGuardrailsEnabled: includeCiGuardrails,
     setupDurationMs,
     selectedSkillDomains,
+    compatibilityWarnings,
     autoDetection: {
       recommendedStack: projectDetection.recommendedStackFileName,
       recommendedBlueprint: projectDetection.recommendedBlueprintFileName,
@@ -136,6 +143,13 @@ export async function buildCompiledRulesContent({
     );
   }
 
+  const tokenOptimizationState = await readTokenOptimizationState(resolvedTargetDirectoryPath);
+  if (tokenOptimizationState?.enabled) {
+    contextBlocks.push(
+      `## TOKEN OPTIMIZATION PROFILE\nSource: .agent-context/state/token-optimization.json\n\n${buildTokenOptimizationGuidanceBlock(tokenOptimizationState).trim()}`
+    );
+  }
+
   for (const selectedSkillDomainName of selectedSkillDomainNames) {
     const skillDomainEntry = skillPlatformIndex.domains?.[selectedSkillDomainName];
     if (!skillDomainEntry) {

package/lib/cli/token-optimization.mjs

@@ -0,0 +1,275 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { platform } from 'node:process';
+
+import { pathExists } from './utils.mjs';
+
+export const TOKEN_OPTIMIZATION_STATE_FILE_NAME = 'token-optimization.json';
+export const TOKEN_OPTIMIZATION_REPORT_FILE_NAME = 'token-optimization-report.json';
+
+const TOKEN_OPTIMIZATION_SCHEMA_VERSION = 'token-optimization-v1';
+const FALLBACK_AGENT_NAME = 'copilot';
+
+const SUPPORTED_AGENT_NAMES = new Set([
+  'copilot',
+  'claude',
+  'cursor',
+  'windsurf',
+  'gemini',
+  'codex',
+  'cline',
+]);
+
+const COMMAND_REWRITE_MAPPINGS = [
+  {
+    rawCommand: 'ls -la',
+    optimizedCommand: 'rtk ls .',
+    reason: 'Directory listings are grouped and compacted before entering the model context.',
+  },
+  {
+    rawCommand: 'tree',
+    optimizedCommand: 'rtk ls .',
+    reason: 'Large trees are summarized without losing high-signal structure.',
+  },
+  {
+    rawCommand: 'cat file.ext',
+    optimizedCommand: 'rtk read file.ext',
+    reason: 'File reads keep signatures and relevant lines while trimming boilerplate.',
+  },
+  {
+    rawCommand: 'rg pattern .',
+    optimizedCommand: 'rtk grep "pattern" .',
+    reason: 'Search hits are grouped and deduplicated for faster reasoning.',
+  },
+  {
+    rawCommand: 'git status',
+    optimizedCommand: 'rtk git status',
+    reason: 'Status output is condensed to actionable file changes.',
+  },
+  {
+    rawCommand: 'git diff',
+    optimizedCommand: 'rtk git diff',
+    reason: 'Diff noise is trimmed while preserving code-review context.',
+  },
+  {
+    rawCommand: 'git log -n 10',
+    optimizedCommand: 'rtk git log -n 10',
+    reason: 'History is converted to compact one-line summaries.',
+  },
+  {
+    rawCommand: 'npm test',
+    optimizedCommand: 'rtk test npm test',
+    reason: 'Test results emphasize failures and suppress repetitive pass logs.',
+  },
+  {
+    rawCommand: 'npm run build',
+    optimizedCommand: 'rtk err npm run build',
+    reason: 'Build runs return errors and warnings only for quicker remediation.',
+  },
+  {
+    rawCommand: 'tsc --noEmit',
+    optimizedCommand: 'rtk tsc',
+    reason: 'TypeScript diagnostics are grouped by file with less repetition.',
+  },
+  {
+    rawCommand: 'eslint .',
+    optimizedCommand: 'rtk lint',
+    reason: 'Lint output is grouped by rule and location to reduce token churn.',
+  },
+  {
+    rawCommand: 'docker ps',
+    optimizedCommand: 'rtk docker ps',
+    reason: 'Container state is summarized into compact rows.',
+  },
+  {
+    rawCommand: 'kubectl get pods',
+    optimizedCommand: 'rtk kubectl pods',
+    reason: 'Kubernetes output is condensed and stable for agent consumption.',
+  },
+];
+
+function parseRtkVersion(versionOutput) {
+  const versionMatch = versionOutput.match(/\d+\.\d+\.\d+/);
+  return versionMatch ? versionMatch[0] : null;
+}
+
+export function normalizeAgentName(rawAgentName = FALLBACK_AGENT_NAME) {
+  const normalizedAgentName = String(rawAgentName || '')
+    .trim()
+    .toLowerCase();
+
+  if (!normalizedAgentName) {
+    return FALLBACK_AGENT_NAME;
+  }
+
+  if (!SUPPORTED_AGENT_NAMES.has(normalizedAgentName)) {
+    throw new Error(
+      `Unsupported agent "${rawAgentName}". Supported values: ${Array.from(SUPPORTED_AGENT_NAMES).join(', ')}`
+    );
+  }
+
+  return normalizedAgentName;
+}
+
+export function detectRtkBinary() {
+  try {
+    const versionResult = spawnSync('rtk', ['--version'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    if (versionResult.status !== 0) {
+      return {
+        isAvailable: false,
+        version: null,
+        detectionError: (versionResult.stderr || versionResult.stdout || 'Unknown external proxy detection error').trim(),
+      };
+    }
+
+    const detectedVersion = parseRtkVersion(versionResult.stdout || '');
+    return {
+      isAvailable: true,
+      version: detectedVersion,
+      detectionError: null,
+    };
+  } catch (detectionError) {
+    return {
+      isAvailable: false,
+      version: null,
+      detectionError: detectionError instanceof Error ? detectionError.message : String(detectionError),
+    };
+  }
+}
+
+export function buildRtkInstallHint() {
+  if (platform === 'win32') {
+    return 'Install the external token optimizer binary for Windows, extract it, and ensure the executable is on PATH.';
+  }
+
+  if (platform === 'darwin') {
+    return 'Install the external token optimizer with Homebrew, then verify the executable is available in your shell.';
+  }
+
+  return 'Install the external token optimizer with the vendor installer, then verify it is available in your shell PATH.';
+}
+
+export function buildRtkHookCommand(selectedAgentName) {
+  const normalizedAgentName = normalizeAgentName(selectedAgentName);
+
+  if (normalizedAgentName === 'copilot') {
+    return 'rtk init -g --copilot';
+  }
+
+  if (normalizedAgentName === 'claude') {
+    return 'rtk init -g';
+  }
+
+  if (normalizedAgentName === 'cursor') {
+    return 'rtk init -g --agent cursor';
+  }
+
+  if (normalizedAgentName === 'windsurf') {
+    return 'rtk init --agent windsurf';
+  }
+
+  if (normalizedAgentName === 'gemini') {
+    return 'rtk init -g --gemini';
+  }
+
+  if (normalizedAgentName === 'codex') {
+    return 'rtk init -g --codex';
+  }
+
+  if (normalizedAgentName === 'cline') {
+    return 'rtk init --agent cline';
+  }
+
+  return 'rtk init -g --copilot';
+}
+
+export function createTokenOptimizationState({
+  isEnabled,
+  selectedAgentName,
+  rtkDetection,
+}) {
+  return {
+    schemaVersion: TOKEN_OPTIMIZATION_SCHEMA_VERSION,
+    enabled: Boolean(isEnabled),
+    selectedAgent: normalizeAgentName(selectedAgentName),
+    preferredShellProxy: rtkDetection.isAvailable ? 'external-proxy' : 'native-fallback',
+    externalProxy: {
+      detected: Boolean(rtkDetection.isAvailable),
+      version: rtkDetection.version,
+      detectionError: rtkDetection.detectionError,
+    },
+    commandRewriteMappings: COMMAND_REWRITE_MAPPINGS.map((mapping) => ({ ...mapping })),
+    generatedAt: new Date().toISOString(),
+  };
+}
+
+export async function readTokenOptimizationState(targetDirectoryPath) {
+  const stateFilePath = path.join(
+    targetDirectoryPath,
+    '.agent-context',
+    'state',
+    TOKEN_OPTIMIZATION_STATE_FILE_NAME
+  );
+
+  if (!(await pathExists(stateFilePath))) {
+    return null;
+  }
+
+  try {
+    const stateContent = await fs.readFile(stateFilePath, 'utf8');
+    const parsedState = JSON.parse(stateContent);
+    if (typeof parsedState.enabled !== 'boolean') {
+      return null;
+    }
+    return parsedState;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeTokenOptimizationState(targetDirectoryPath, tokenOptimizationState) {
+  const stateDirectoryPath = path.join(targetDirectoryPath, '.agent-context', 'state');
+  const stateFilePath = path.join(stateDirectoryPath, TOKEN_OPTIMIZATION_STATE_FILE_NAME);
+
+  await fs.mkdir(stateDirectoryPath, { recursive: true });
+  await fs.writeFile(stateFilePath, JSON.stringify(tokenOptimizationState, null, 2) + '\n', 'utf8');
+}
+
+export function buildTokenOptimizationGuidanceBlock(tokenOptimizationState) {
+  if (!tokenOptimizationState?.enabled) {
+    return [
+      'Token optimization mode is disabled for this repository.',
+      'Use native shell commands with manual output limiting when needed.',
+    ].join('\n');
+  }
+
+  const rewriteLines = (tokenOptimizationState.commandRewriteMappings || []).map(
+    (mapping) => `- ${mapping.rawCommand} => ${mapping.optimizedCommand} (${mapping.reason})`
+  );
+
+  const fallbackGuidance = [
+    '- Prefer command variants with bounded output (for example: git diff --stat, rg --max-count, and npm test -- --reporter=dot).',
+    '- Request only the lines or sections required for the current decision.',
+    '- If shell output is still large, summarize and continue iteratively instead of dumping full logs.',
+  ];
+
+  return [
+    `Token optimization mode is enabled for agent: ${tokenOptimizationState.selectedAgent}.`,
+    `Preferred shell proxy: ${tokenOptimizationState.preferredShellProxy}.`,
+    '',
+    'Apply command rewrites before running verbose shell commands:',
+    ...rewriteLines,
+    '',
+    'Important scope note:',
+    '- Shell rewrite hooks affect shell tool calls only.',
+    '- Built-in read/grep/glob style tools may bypass shell rewrites, so explicit compact shell commands should be preferred in high-volume sessions.',
+    '',
+    'Fallback behavior when external proxy is unavailable:',
+    ...fallbackGuidance,
+  ].join('\n');
+}

package/lib/cli/utils.mjs

@@ -25,8 +25,9 @@ export function printUsage() {
   console.log('');
   console.log('Usage:');
   console.log('  agentic-senior-core launch');
-  console.log('  agentic-senior-core init [target-directory] [--preset <name>] [--profile <beginner|balanced|strict>] [--profile-pack <name>] [--stack <name>] [--blueprint <name>] [--ci <true|false>] [--newbie]');
+  console.log('  agentic-senior-core init [target-directory] [--preset <name>] [--profile <beginner|balanced|strict>] [--profile-pack <name>] [--stack <name>] [--blueprint <name>] [--ci <true|false>] [--newbie] [--token-optimize] [--token-agent <name>]');
   console.log('  agentic-senior-core upgrade [target-directory] [--dry-run] [--yes]');
+  console.log('  agentic-senior-core optimize [target-directory] [--agent <copilot|claude|cursor|windsurf|gemini|codex|cline>] [--enable|--disable] [--show]');
   console.log('  agentic-senior-core rollback [target-directory]');
   console.log('  agentic-senior-core skill [domain] [--tier <standard|advance|expert|above>] [--json]');
   console.log('  agentic-senior-core --version');
@@ -41,8 +42,15 @@ export function printUsage() {
   console.log('  --stack      Override stack selection');
   console.log('  --blueprint  Override blueprint selection');
   console.log('  --ci         Override CI/CD guardrails (true|false)');
+  console.log('  --token-optimize  Enable token optimization policy during init');
+  console.log('  --token-agent     Set token optimization agent target (copilot, claude, cursor, windsurf, gemini, codex, cline)');
+  console.log('  --no-token-optimize  Disable token optimization even if token-agent is provided');
   console.log('  --dry-run    Preview upgrade without writing files');
   console.log('  --yes        Skip confirmation prompts for upgrade');
+  console.log('  --agent      Target agent integration for token optimization mode');
+  console.log('  --enable     Enable token optimization policy and rebuild compiled rules');
+  console.log('  --disable    Disable token optimization policy and rebuild compiled rules');
+  console.log('  --show       Print current token optimization state as JSON');
   console.log('  --tier       Choose a skill tier for the skill selector');
   console.log('  --json       Emit machine-readable skill selection output');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {

package/scripts/release-gate.mjs

@@ -16,6 +16,16 @@ const __dirname = dirname(__filename);
 const REPOSITORY_ROOT = resolve(__dirname, '..');
 
 const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
+const NODE_MIN_PATTERN = /^\d+(\.\d+)?$/;
+const SUPPORTED_COMPATIBILITY_PLATFORMS = new Set(['windows', 'linux', 'macos']);
+const REQUIRED_SKILL_DOMAINS = [
+  'backend',
+  'frontend',
+  'fullstack',
+  'cli',
+  'distribution',
+  'review-quality',
+];
 
 function readText(relativeFilePath) {
   const absolutePath = resolve(REPOSITORY_ROOT, relativeFilePath);
@@ -34,6 +44,32 @@ function pushResult(results, isPassed, checkName, details) {
   });
 }
 
+function validateCompatibilityManifestShape(parsedManifest, skillDomainName) {
+  const validationErrors = [];
+
+  if (!Array.isArray(parsedManifest.ides) || parsedManifest.ides.length === 0) {
+    validationErrors.push(`Domain ${skillDomainName} must define non-empty ides[]`);
+  }
+
+  if (!Array.isArray(parsedManifest.platforms) || parsedManifest.platforms.length === 0) {
+    validationErrors.push(`Domain ${skillDomainName} must define non-empty platforms[]`);
+  } else {
+    const unsupportedPlatformName = parsedManifest.platforms.find(
+      (platformName) => !SUPPORTED_COMPATIBILITY_PLATFORMS.has(platformName)
+    );
+
+    if (unsupportedPlatformName) {
+      validationErrors.push(`Domain ${skillDomainName} has unsupported platform: ${unsupportedPlatformName}`);
+    }
+  }
+
+  if (typeof parsedManifest.nodeMin !== 'string' || !NODE_MIN_PATTERN.test(parsedManifest.nodeMin)) {
+    validationErrors.push(`Domain ${skillDomainName} must define nodeMin as "18" or "18.0" style string`);
+  }
+
+  return validationErrors;
+}
+
 function runReleaseGate() {
   const results = [];
   const packageJsonPath = 'package.json';
@@ -100,6 +136,58 @@ function runReleaseGate() {
     pushResult(results, true, 'required-enterprise-file', `${requiredEnterpriseFile} is present`);
   }
 
+  let validatedCompatibilityManifestCount = 0;
+
+  for (const skillDomainName of REQUIRED_SKILL_DOMAINS) {
+    const compatibilityManifestPath = `.agent-context/skills/${skillDomainName}/compatibility-manifest.json`;
+    const compatibilityManifestContent = readText(compatibilityManifestPath);
+
+    if (!compatibilityManifestContent) {
+      pushResult(results, false, 'compatibility-manifest', `Missing ${compatibilityManifestPath}`);
+      continue;
+    }
+
+    let parsedCompatibilityManifest;
+    try {
+      parsedCompatibilityManifest = JSON.parse(compatibilityManifestContent);
+    } catch (compatibilityManifestParseError) {
+      const parseErrorMessage = compatibilityManifestParseError instanceof Error
+        ? compatibilityManifestParseError.message
+        : 'Unknown parse error';
+      pushResult(results, false, 'compatibility-manifest', `Invalid JSON in ${compatibilityManifestPath}: ${parseErrorMessage}`);
+      continue;
+    }
+
+    const compatibilityValidationErrors = validateCompatibilityManifestShape(
+      parsedCompatibilityManifest,
+      skillDomainName
+    );
+
+    if (compatibilityValidationErrors.length > 0) {
+      pushResult(results, false, 'compatibility-manifest', compatibilityValidationErrors.join('; '));
+      continue;
+    }
+
+    validatedCompatibilityManifestCount += 1;
+    pushResult(results, true, 'compatibility-manifest', `${compatibilityManifestPath} is valid`);
+  }
+
+  if (validatedCompatibilityManifestCount === REQUIRED_SKILL_DOMAINS.length) {
+    pushResult(
+      results,
+      true,
+      'compatibility-manifest-coverage',
+      `Validated ${validatedCompatibilityManifestCount}/${REQUIRED_SKILL_DOMAINS.length} required skill compatibility manifests`
+    );
+  } else {
+    pushResult(
+      results,
+      false,
+      'compatibility-manifest-coverage',
+      `Validated ${validatedCompatibilityManifestCount}/${REQUIRED_SKILL_DOMAINS.length} required skill compatibility manifests`
+    );
+  }
+
   const failureCount = results.filter((checkResult) => !checkResult.passed).length;
   const releaseGateReport = {
     generatedAt: new Date().toISOString(),

package/scripts/validate.mjs

@@ -31,6 +31,7 @@ const SKILLS_DIR = join(AGENT_CONTEXT_DIR, 'skills');
 const GENERATED_RULE_FILES = ['.cursorrules', '.windsurfrules'];
 const ALLOWED_SEVERITIES = new Set(['critical', 'high', 'medium', 'low']);
 const OVERRIDE_WARNING_WINDOW_DAYS = 30;
+const SUPPORTED_COMPATIBILITY_PLATFORMS = new Set(['windows', 'linux', 'macos']);
 
 const validationResult = {
   passed: 0,
@@ -59,7 +60,12 @@ async function collectFiles(directoryPath, fileExtensionMatcher) {
     const directoryEntries = await readdir(currentDirectoryPath, { withFileTypes: true });
 
     for (const directoryEntry of directoryEntries) {
-      if (directoryEntry.name === '.git' || directoryEntry.name === 'node_modules') {
+      if (
+        directoryEntry.name === '.git'
+        || directoryEntry.name === 'node_modules'
+        || directoryEntry.name === '.agentic-backup'
+        || directoryEntry.name === '.benchmarks'
+      ) {
         continue;
       }
 
@@ -313,6 +319,75 @@ async function validateSkillTierQuality() {
   }
 }
 
+async function validateSkillCompatibilityManifests() {
+  console.log('\nChecking skill compatibility manifests...');
+
+  const skillDomainEntries = await readdir(SKILLS_DIR, { withFileTypes: true });
+  const skillDomainDirectoryNames = skillDomainEntries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort((leftName, rightName) => leftName.localeCompare(rightName));
+
+  let validManifestCount = 0;
+
+  for (const skillDomainDirectoryName of skillDomainDirectoryNames) {
+    const compatibilityManifestPath = join(
+      SKILLS_DIR,
+      skillDomainDirectoryName,
+      'compatibility-manifest.json'
+    );
+
+    if (!(await fileExists(compatibilityManifestPath))) {
+      fail(`Missing compatibility manifest: .agent-context/skills/${skillDomainDirectoryName}/compatibility-manifest.json`);
+      continue;
+    }
+
+    let parsedCompatibilityManifest;
+    try {
+      parsedCompatibilityManifest = JSON.parse(await readTextFile(compatibilityManifestPath));
+    } catch (error) {
+      fail(`Invalid JSON compatibility manifest for ${skillDomainDirectoryName}: ${error.message}`);
+      continue;
+    }
+
+    if (!Array.isArray(parsedCompatibilityManifest.ides) || parsedCompatibilityManifest.ides.length === 0) {
+      fail(`Compatibility manifest for ${skillDomainDirectoryName} must include non-empty "ides" array`);
+      continue;
+    }
+
+    if (!Array.isArray(parsedCompatibilityManifest.platforms) || parsedCompatibilityManifest.platforms.length === 0) {
+      fail(`Compatibility manifest for ${skillDomainDirectoryName} must include non-empty "platforms" array`);
+      continue;
+    }
+
+    const unsupportedPlatform = parsedCompatibilityManifest.platforms.find(
+      (platformName) => !SUPPORTED_COMPATIBILITY_PLATFORMS.has(platformName)
+    );
+
+    if (unsupportedPlatform) {
+      fail(`Compatibility manifest for ${skillDomainDirectoryName} has unsupported platform: ${unsupportedPlatform}`);
+      continue;
+    }
+
+    if (
+      typeof parsedCompatibilityManifest.nodeMin !== 'string'
+      || !/^\d+(\.\d+)?$/.test(parsedCompatibilityManifest.nodeMin)
+    ) {
+      fail(`Compatibility manifest for ${skillDomainDirectoryName} must include string nodeMin (for example "18" or "18.0")`);
+      continue;
+    }
+
+    validManifestCount += 1;
+    pass(`Compatibility manifest validated: .agent-context/skills/${skillDomainDirectoryName}/compatibility-manifest.json`);
+  }
+
+  if (validManifestCount >= 6) {
+    pass(`Compatibility manifest coverage is valid (${validManifestCount} skill domains)`);
+  } else {
+    fail(`Compatibility manifest coverage is insufficient (${validManifestCount}/6 skill domains)`);
+  }
+}
+
 function stripMarkdownCodeBlocks(markdownText) {
   return markdownText.replace(/```[\s\S]*?```/g, '');
 }
@@ -702,6 +777,7 @@ async function main() {
   await validateMarkdownFiles();
   await validateRuleFiles();
   await validateSkillTierQuality();
+  await validateSkillCompatibilityManifests();
   await validateOverrideGovernance();
   await validateAgentsManifest();
   await validateCrossReferences();