@mikulgohil/ai-kit 1.8.1 → 1.10.0

package/README.md

@@ -74,6 +74,7 @@ Scans your `package.json`, config files, and directory structure to detect your
 |---|---|
 | Next.js 15 with App Router | Server Components, Server Actions, `app/` routing patterns |
 | Sitecore XM Cloud | `<Text>`, `<RichText>`, `<Image>` field helpers, placeholder patterns |
+| Optimizely SaaS CMS | Visual Builder, Optimizely Graph, `@remkoj` SDK, component factory |
 | Tailwind CSS v4 | `@theme` tokens, utility class patterns, responsive prefixes |
 | TypeScript strict mode | No `any`, proper null checks, discriminated unions |
 | Turborepo monorepo | Workspace conventions, cross-package imports |

package/agents/build-resolver.md

@@ -2,6 +2,8 @@
 name: build-resolver
 description: Build error resolution agent — diagnoses and fixes Next.js, TypeScript, and Sitecore build errors.
 tools: Read, Edit, Glob, Grep, Bash
+isolation: worktree
+initialPrompt: Run the build command from package.json and diagnose any errors found.
 ---
 
 # Build Error Resolver

package/agents/e2e-runner.md

@@ -2,6 +2,8 @@
 name: e2e-runner
 description: Playwright E2E test agent — generates and runs Playwright tests using Page Object Model for Next.js applications.
 tools: Read, Write, Edit, Glob, Grep, Bash
+isolation: worktree
+initialPrompt: Analyze existing test coverage and identify critical user flows that need E2E tests.
 ---
 
 # E2E Test Runner

package/agents/migration-specialist.md

@@ -1,7 +1,9 @@
 ---
 name: migration-specialist
 description: Migration specialist agent — framework upgrades, breaking change detection, codemods, dependency migration, and incremental adoption strategies.
-tools: Read, Glob, Grep, Bash
+tools: Read, Edit, Glob, Grep, Bash
+isolation: worktree
+initialPrompt: Audit the current dependency versions and identify available upgrades with breaking changes.
 ---
 
 # Migration Specialist

package/agents/refactor-cleaner.md

@@ -2,6 +2,8 @@
 name: refactor-cleaner
 description: Dead code cleanup and refactoring agent — finds unused exports, cleans imports, and removes dead code.
 tools: Read, Edit, Glob, Grep, Bash
+isolation: worktree
+initialPrompt: Scan for dead code and unused exports in this project using Knip or manual analysis.
 ---
 
 # Refactor & Cleanup Agent

package/commands/fetch-docs.md

@@ -0,0 +1,90 @@
+# Fetch Docs
+
+> **Role**: You are a documentation researcher. Your job is to fetch the latest, version-specific documentation for this project's tech stack and summarize it into the conversation context so all subsequent coding is informed by current APIs.
+> **Goal**: Pre-load current documentation for the detected frameworks so the AI doesn't rely on potentially outdated training data.
+
+## Mandatory Steps
+
+You MUST follow these steps in order. Do not skip any step.
+
+1. **Detect the Stack** — Read `ai-kit.config.json` (or `package.json` if config doesn't exist) to identify:
+   - Framework and version (e.g., Next.js 16.2.2)
+   - CMS and version (e.g., Sitecore Content SDK v2.x, Optimizely SaaS)
+   - Styling framework (e.g., Tailwind CSS v4)
+   - Any other key libraries in dependencies
+
+2. **Fetch Documentation** — For each detected framework, fetch current docs using the best available method:
+
+   **Next.js**:
+   - Primary: Use Context7 MCP → `resolve-library-id` for "next.js" → `query-docs` for the specific topic
+   - Fallback: WebFetch `https://nextjs.org/docs/llms-full.txt` (AI-optimized full docs)
+   - Focus on: App Router APIs, Server Components, Server Actions, Middleware, ISR, Turbopack (if v16+)
+
+   **Tailwind CSS**:
+   - Primary: Use Context7 MCP → `resolve-library-id` for "tailwindcss" → `query-docs`
+   - Focus on: v4 `@theme` syntax (if v4 detected), utility classes, responsive patterns, plugin API
+
+   **Sitecore XM Cloud / Content SDK**:
+   - Primary: Use Context7 MCP → `resolve-library-id` for "sitecore" → `query-docs`
+   - Fallback: Check project repo for `LLMs.txt` file
+   - Focus on: Component bindings, field helpers, Experience Edge GraphQL, personalization
+
+   **React**:
+   - Primary: Use Context7 MCP → `resolve-library-id` for "react" → `query-docs`
+   - Focus on: React 19 APIs (useActionState, use, Server Components), hooks rules
+
+   **Other libraries** (if specified in $ARGUMENTS):
+   - Use Context7 MCP → `resolve-library-id` → `query-docs`
+
+3. **Summarize Key APIs** — For each framework, produce a concise summary:
+   - Current stable version
+   - Key API changes since the AI's likely training cutoff
+   - API signatures for commonly used functions
+   - Breaking changes or deprecations to watch for
+   - Code examples from the official docs
+
+4. **Report What Was Loaded** — Print a summary table:
+
+## Output Format
+
+```
+## Documentation Loaded
+
+| Framework | Version | Source | Key APIs Fetched |
+|-----------|---------|--------|-----------------|
+| Next.js | 16.2.x | Context7 | App Router, Server Actions, Turbopack |
+| Tailwind | 4.x | Context7 | @theme syntax, utility classes |
+| Sitecore | SDK v2.x | LLMs.txt | Field helpers, Experience Edge |
+
+## Key API Reference
+
+### Next.js 16
+[Concise API reference with signatures and examples]
+
+### Tailwind CSS v4
+[Key patterns and syntax differences from v3]
+
+### Sitecore Content SDK v2.x
+[Component patterns and field helper usage]
+
+## What's New Since Training Cutoff
+[Notable changes the AI might not know about]
+```
+
+## Rules
+
+- ALWAYS check Context7 MCP first — it's the fastest and most reliable source
+- If Context7 is not available, use WebFetch against official docs
+- Keep summaries concise — focus on API signatures and patterns, not tutorials
+- Highlight breaking changes and deprecations prominently
+- If a specific library is passed as $ARGUMENTS, fetch docs for that library too
+- Do NOT skip any detected framework — even if you think you know the APIs
+
+## When to Use This Skill
+
+- At the **start of a coding session** — run once to pre-load context
+- Before **major framework upgrades** — fetch docs for both current and target versions
+- When you encounter **unexpected API behavior** — refresh docs for the specific library
+- When working with **niche libraries** (Sitecore, Optimizely) that models know less about
+
+Target: $ARGUMENTS

package/dist/index.js

@@ -15,7 +15,7 @@ var GUIDES_DIR = path.join(PACKAGE_ROOT, "guides");
 var DOCS_SCAFFOLDS_DIR = path.join(PACKAGE_ROOT, "docs-scaffolds");
 var AGENTS_DIR = path.join(PACKAGE_ROOT, "agents");
 var CONTEXTS_DIR = path.join(PACKAGE_ROOT, "contexts");
-var VERSION = "1.8.0";
+var VERSION = "1.10.0";
 var AI_KIT_CONFIG_FILE = "ai-kit.config.json";
 var GENERATED_FILES = {
   claudeMd: "CLAUDE.md",
@@ -34,6 +34,7 @@ var TEMPLATE_FRAGMENTS = [
   "nextjs-app-router",
   "nextjs-pages-router",
   "sitecore-xmc",
+  "optimizely-saas",
   "tailwind",
   "typescript",
   "monorepo",
@@ -117,13 +118,14 @@ function detectNextjs(projectPath, pkg) {
     return { framework: "unknown" };
   }
   const nextjsVersion = deps.next.replace(/[\^~>=<]/g, "");
+  const nextjsMajorVersion = parseInt(nextjsVersion.split(".")[0], 10) || void 0;
   const hasAppDir = dirExists(path2.join(projectPath, "app")) || dirExists(path2.join(projectPath, "src", "app"));
   const hasPagesDir = dirExists(path2.join(projectPath, "pages")) || dirExists(path2.join(projectPath, "src", "pages"));
   let routerType;
   if (hasAppDir && hasPagesDir) routerType = "hybrid";
   else if (hasAppDir) routerType = "app";
   else if (hasPagesDir) routerType = "pages";
-  return { framework: "nextjs", nextjsVersion, routerType };
+  return { framework: "nextjs", nextjsVersion, nextjsMajorVersion, routerType };
 }
 
 // src/scanner/sitecore.ts
@@ -153,6 +155,56 @@ function detectSitecore(pkg) {
   return { cms: "none" };
 }
 
+// src/scanner/optimizely.ts
+var OPTIMIZELY_PACKAGES = [
+  "@remkoj/optimizely-cms-react",
+  "@remkoj/optimizely-cms-nextjs",
+  "@remkoj/optimizely-cms-api",
+  "@remkoj/optimizely-cms-cli",
+  "@remkoj/optimizely-graph-client",
+  "@remkoj/optimizely-graph-cli",
+  "@remkoj/optimizely-graph-functions",
+  "@remkoj/optimizely-one-nextjs"
+];
+var OPTIMIZELY_OFFICIAL_PACKAGES = [
+  "@optimizely/cms",
+  "@optimizely/graph",
+  "@optimizely/cms-react",
+  "@optimizely/cms-nextjs"
+];
+function detectOptimizely(pkg) {
+  const deps = {
+    ...pkg.dependencies,
+    ...pkg.devDependencies
+  };
+  const foundPackages = [];
+  let version;
+  for (const pkgName of OPTIMIZELY_PACKAGES) {
+    if (deps[pkgName]) {
+      foundPackages.push(pkgName);
+      if (!version && (pkgName === "@remkoj/optimizely-cms-nextjs" || pkgName === "@remkoj/optimizely-cms-react")) {
+        version = deps[pkgName].replace(/[\^~>=<]/g, "");
+      }
+    }
+  }
+  for (const pkgName of OPTIMIZELY_OFFICIAL_PACKAGES) {
+    if (deps[pkgName]) {
+      foundPackages.push(pkgName);
+      if (!version) {
+        version = deps[pkgName].replace(/[\^~>=<]/g, "");
+      }
+    }
+  }
+  if (foundPackages.length === 0 && deps["@remkoj/optimizely-graph-functions"]) {
+    foundPackages.push("@remkoj/optimizely-graph-functions");
+  }
+  return {
+    optimizelySaas: foundPackages.length > 0,
+    optimizelyVersion: version || void 0,
+    optimizelyPackages: foundPackages
+  };
+}
+
 // src/scanner/styling.ts
 import path3 from "path";
 function detectStyling(projectPath, pkg) {
@@ -709,6 +761,7 @@ async function scanProject(projectPath) {
   const projectName = pkg.name || path13.basename(projectPath);
   const nextjsResult = detectNextjs(projectPath, pkg);
   const sitecoreResult = detectSitecore(pkg);
+  const optimizelyResult = detectOptimizely(pkg);
   const stylingResult = detectStyling(projectPath, pkg);
   const tsResult = detectTypescript(projectPath);
   const monorepoResult = detectMonorepo(projectPath, pkg);
@@ -720,9 +773,14 @@ async function scanProject(projectPath) {
   const staticSiteResult = detectStaticSite(projectPath, pkg);
   const aiIgnorePatterns = loadAiIgnorePatterns(projectPath);
   const figmaDetected = figmaResult.figmaMcp || figmaResult.figmaCodeCli || figmaResult.designTokens;
+  const cmsResult = sitecoreResult.cms !== "none" ? sitecoreResult : optimizelyResult.optimizelySaas ? {
+    cms: "optimizely-saas",
+    optimizelyVersion: optimizelyResult.optimizelyVersion,
+    optimizelyPackages: optimizelyResult.optimizelyPackages
+  } : sitecoreResult;
   return {
     ...nextjsResult,
-    ...sitecoreResult,
+    ...cmsResult,
     ...stylingResult,
     ...tsResult,
     ...monorepoResult,
@@ -817,7 +875,9 @@ function selectFragments(scan) {
       fragments.push("nextjs-pages-router");
     }
   }
-  if (scan.cms !== "none") {
+  if (scan.cms === "optimizely-saas") {
+    fragments.push("optimizely-saas");
+  } else if (scan.cms !== "none") {
     fragments.push("sitecore-xmc");
   }
   if (scan.styling.includes("tailwind")) {
@@ -851,7 +911,11 @@ function buildVariables(scan) {
     techStack.push(`Next.js ${scan.nextjsVersion || ""}`);
   }
   if (scan.cms !== "none") {
-    if (scan.cms === "sitecore-xmc-v2") {
+    if (scan.cms === "optimizely-saas") {
+      techStack.push(
+        `Optimizely SaaS CMS${scan.optimizelyVersion ? ` (SDK ${scan.optimizelyVersion})` : ""}`
+      );
+    } else if (scan.cms === "sitecore-xmc-v2") {
       techStack.push(
         `Sitecore XM Cloud${scan.sitecoreContentSdkVersion ? ` (Content SDK ${scan.sitecoreContentSdkVersion})` : " (Content SDK v2)"}`
       );
@@ -920,9 +984,13 @@ function buildCursorVariables(scan) {
     techStack.push(`Next.js ${scan.nextjsVersion || ""}`);
   }
   if (scan.cms !== "none") {
-    techStack.push(
-      scan.cms === "sitecore-xmc-v2" || scan.cms === "sitecore-xmc" ? "Sitecore XM Cloud" : "Sitecore JSS"
-    );
+    if (scan.cms === "optimizely-saas") {
+      techStack.push("Optimizely SaaS CMS");
+    } else {
+      techStack.push(
+        scan.cms === "sitecore-xmc-v2" || scan.cms === "sitecore-xmc" ? "Sitecore XM Cloud" : "Sitecore JSS"
+      );
+    }
   }
   if (scan.typescript) techStack.push("TypeScript");
   if (scan.styling.includes("tailwind")) techStack.push("Tailwind CSS");
@@ -958,6 +1026,10 @@ var MDC_CONFIG = {
     description: "Sitecore XM Cloud component patterns and field helpers",
     globs: "src/components/**/*.{ts,tsx}"
   },
+  "optimizely-saas": {
+    description: "Optimizely SaaS CMS patterns, Visual Builder, and Graph API",
+    globs: "src/components/**/*.{ts,tsx}, src/gql/**/*.{ts,graphql}"
+  },
   tailwind: {
     description: "Tailwind CSS conventions and utility patterns",
     globs: "**/*.{tsx,jsx,css}"
@@ -982,7 +1054,7 @@ var MDC_CONFIG = {
 function generateMdcFiles(scan) {
   const fragments = selectFragments(scan);
   const variables = buildCursorVariables(scan);
-  return fragments.map((fragment) => {
+  const mdcFiles = fragments.map((fragment) => {
     const config = MDC_CONFIG[fragment] || {
       description: fragment,
       globs: "**/*"
@@ -1005,6 +1077,42 @@ function generateMdcFiles(scan) {
 ${replaced}`
     };
   });
+  const techStack = [
+    scan.framework === "nextjs" ? `Next.js ${scan.nextjsVersion || ""}`.trim() : scan.framework,
+    scan.cms !== "none" ? scan.cms : null,
+    scan.styling.length > 0 ? scan.styling.join(", ") : null,
+    scan.typescript ? "TypeScript" : null,
+    scan.monorepo ? scan.monorepoTool : null
+  ].filter(Boolean).join(" + ");
+  const indexContent = [
+    "---",
+    `description: ${scan.projectName} \u2014 repo-wide project conventions and AI rules`,
+    "globs: **/*",
+    "alwaysApply: true",
+    "---",
+    "",
+    `<!-- Generated by ai-kit v${VERSION} -->`,
+    "",
+    `# ${scan.projectName}`,
+    "",
+    `**Tech Stack**: ${techStack}`,
+    "",
+    "## Active Rules",
+    ...fragments.map((f) => `- [\`${f}\`](./${f}.mdc) \u2014 ${MDC_CONFIG[f]?.description || f}`),
+    "",
+    "## Conventions",
+    "- Follow existing patterns in the codebase",
+    "- Match naming conventions already in use",
+    `- Package manager: \`${scan.packageManager}\``,
+    scan.routerType ? `- Router: ${scan.routerType === "app" ? "App Router" : scan.routerType === "pages" ? "Pages Router" : "Hybrid (App + Pages)"}` : "",
+    "",
+    "> Rules are auto-generated by [ai-kit](https://github.com/mikulgohil/ai-kit). Run `ai-kit update` to refresh."
+  ].filter((line) => line !== void 0).join("\n");
+  mdcFiles.unshift({
+    filename: "index.mdc",
+    content: indexContent
+  });
+  return mdcFiles;
 }
 
 // src/generator/config.ts
@@ -1032,6 +1140,7 @@ function generateHooks(scan, profile = "standard") {
   const hooks = {};
   const preToolUse = [];
   const postToolUse = [];
+  const postCompact = [];
   const stop = [];
   preToolUse.push({
     matcher: "Bash(git push*)",
@@ -1206,6 +1315,25 @@ function generateHooks(scan, profile = "standard") {
       ]
     });
   }
+  if (profile !== "minimal") {
+    postCompact.push({
+      matcher: "",
+      hooks: [
+        {
+          type: "command",
+          command: [
+            'echo "\u{1F504} Context was compacted. Key reminders:"',
+            'if [ -f "CLAUDE.md" ]; then echo "  \u2192 CLAUDE.md is loaded \u2014 project rules are preserved"; fi',
+            'if [ -f "ai-kit.config.json" ]; then',
+            `  STACK=$(node -e "try{const c=JSON.parse(require('fs').readFileSync('ai-kit.config.json','utf8'));console.log([c.scanResult.framework,c.scanResult.cms,c.scanResult.styling?.join(',')].filter(Boolean).join(' + '))}catch{}" 2>/dev/null)`,
+            '  if [ -n "$STACK" ]; then echo "  \u2192 Tech stack: $STACK"; fi',
+            "fi",
+            'echo "  \u2192 Run /effort to adjust reasoning depth if needed"'
+          ].join("\n")
+        }
+      ]
+    });
+  }
   if (profile === "strict") {
     stop.push({
       matcher: "",
@@ -1219,6 +1347,7 @@ function generateHooks(scan, profile = "standard") {
   }
   if (preToolUse.length > 0) hooks.PreToolUse = preToolUse;
   if (postToolUse.length > 0) hooks.PostToolUse = postToolUse;
+  if (postCompact.length > 0) hooks.PostCompact = postCompact;
   if (stop.length > 0) hooks.Stop = stop;
   return hooks;
 }
@@ -1280,7 +1409,9 @@ var AVAILABLE_SKILLS = [
   "harness-audit",
   // New skills (v1.7.0) — requirements clarification (inspired by OMC Deep Interview)
   "deep-interview",
-  "clarify-requirements"
+  "clarify-requirements",
+  // New skills (v1.10.0) — documentation freshness
+  "fetch-docs"
 ];
 var SKILL_DESCRIPTIONS = {
   "prompt-help": "Help developers write effective AI prompts with structured context",
@@ -1330,7 +1461,9 @@ var SKILL_DESCRIPTIONS = {
   "harness-audit": "Audit AI agent configuration \u2014 check CLAUDE.md, hooks, agents, skills, MCP servers",
   // New skills (v1.7.0) — requirements clarification
   "deep-interview": "Socratic requirements gathering \u2014 structured interview to transform vague ideas into detailed specifications",
-  "clarify-requirements": "Quick task clarification \u2014 identify gaps and ambiguities in under 5 minutes before coding"
+  "clarify-requirements": "Quick task clarification \u2014 identify gaps and ambiguities in under 5 minutes before coding",
+  // New skills (v1.10.0) — documentation freshness
+  "fetch-docs": "Pre-load current, version-specific docs for your tech stack using Context7 MCP \u2014 run at session start to prevent outdated API usage"
 };
 async function copySkills(targetDir) {
   const copied = [];