Changelog

All notable changes to AI Kit are documented here. This project follows Semantic Versioning .

v2.5.0 — 2026-05-29

Behavioral Guardrails — “Working If” Signals

The behavioral template fragment now closes with a short set of observable success signals, so teams can gauge whether the guardrails are actually changing AI behavior without any telemetry — by watching diffs and conversations:

• Diffs stay tight (every line traces to the request)
• Fewer rewrites for overcomplication
• Clarifying questions come before implementation
• Review cycles shrink

Added to both the CLAUDE.md (verbose) and .cursorrules (terse) variants of the fragment. See Behavioral Guardrails → Knowing If It’s Working.

v2.1.0 — 2026-04-14

Behavioral Guardrails

New behavioral template fragment — a set of meta-cognitive rules that control how the AI approaches work, not what code patterns to follow.

Four principles, always included in every generated CLAUDE.md and .cursorrules:

The behavioral fragment is always included (like base), regardless of your tech stack. It sits between the core coding standards and stack-specific rules in the assembly order.

See Behavioral Guardrails for full details, before/after examples, and design rationale.

# Add to existing projects
npx @mikulgohil/ai-kit update

Other Improvements

• Template fragments: 11 (was 10, added behavioral)
• Version: 2.1.0

v2.0.0 — 2026-04-09

Breaking: kit- Namespace Prefix

All 48 skills and 16 agents are now namespaced with a kit- prefix to prevent collisions with global/built-in skills in Claude Code, Cursor, and other AI tools.

Why? Without namespacing, project-level AI Kit skills silently override users’ personal global skills with the same name. Near-duplicates like /security (global) and /security-check (AI Kit) both appear in suggestions, causing confusion. The kit- prefix makes every AI Kit skill and agent instantly recognizable and collision-free.

Migration

npx @mikulgohil/ai-kit update

One command backs up current configs, removes old unprefixed files, generates new kit- prefixed files, and updates ai-kit.config.json. New projects get kit- prefixed names from the start.

Security Fix

• exec() replaced with execFile() in token dashboard (src/commands/tokens.ts) to prevent shell metacharacter injection in file paths

Internal

• SKILL_PREFIX constant in src/constants.ts — single source of truth for the kit- prefix
• Skills and agents derived from base names + prefix at runtime
• Dead src/copier/commands.ts removed (superseded by skills.ts)
• Automatic cleanup of unprefixed files during ai-kit update

v1.11.0 — 2026-04-08

Session Init Hook

Every new Claude Code session now starts with an automatic context echo — the AI immediately knows your tech stack, package manager, scripts, and when configs were last updated. No wasted turns re-discovering the project. Runs on all hook profiles (minimal, standard, strict).

📋 ai-kit v1.11.0 | Stack: Next.js 16.2 (app router) + sitecore-xmc-v2 + tailwind
   PM: pnpm | Scripts: dev, build, test, lint, typecheck
   Last scan: 2026-04-08

Backup & Rollback

ai-kit update now automatically backs up your current configs to .ai-kit/backups/ before writing any changes. New ai-kit rollback command restores from any previous backup.

ai-kit rollback          # Pick from available backups
ai-kit rollback --latest # Restore most recent instantly

Migrate Existing Projects

New ai-kit migrate command lets teams with existing hand-written CLAUDE.md or .cursorrules adopt AI Kit without losing custom rules. Custom sections are preserved at the top of the file. AI Kit’s generated content goes inside AI-KIT:START/END markers below. Future ai-kit update only touches the marked section.

ai-kit migrate           # Interactive — shows preview, asks confirmation
ai-kit migrate --dry-run # Preview without writing

CLI Updates

• New commands: ai-kit migrate, ai-kit rollback
• Total CLI commands: 16 (was 14)
• Updated docs: README, getting-started guide, feature-overview, CLI reference

Internal

• Extracted CLI wiring from src/index.ts into src/cli/register-commands.ts and src/cli/error-handler.ts
• Added static-site scanner and templates
• Added design-tokens scanner and .aiignore scanner
• Added component-registry command
• Added ai-kit.config.schema.json for editor autocomplete
• Cleaned .gitignore — moved internal files to .git/info/exclude

v1.10.0 — 2026-04-08

Agent Worktree Isolation

Code-modifying agents now include isolation: worktree in their frontmatter, enabling them to run in isolated git worktrees. This means agents like refactor-cleaner, build-resolver, e2e-runner, and migration-specialist can safely modify files without affecting your working directory.

Agents also gain initialPrompt — an auto-submitted first turn that kicks off their workflow immediately on activation.

Next.js 16 & Turbopack Support

AI Kit now detects Next.js 16 (current LTS — v16.2.2) and generates Turbopack-specific rules:

• Scanner extracts nextjsMajorVersion for version-aware template selection
• New template sections for Turbopack (stable in Next.js 16 with ~4x faster dev startup)
• Server Fast Refresh guidance for instant HMR on server-side changes
• Updated caching rules — route stale time decoupled from segment-level data in Next.js 16
• Webpack migration warnings for projects using custom webpack() config

PostCompact Hook

New PostCompact hook event fires after Claude Code compacts conversation context. Available in standard and strict profiles:

• Re-echoes your tech stack summary so critical context survives compaction
• Reminds about the /effort command for adjusting reasoning depth
• Confirms CLAUDE.md is still loaded

See Hooks for details.

.cursor/index.mdc Generation

AI Kit now generates a .cursor/index.mdc file — a repo-wide entry point for Cursor IDE that is always loaded:

• Shows project name and tech stack
• Links to all active rule fragments
• Lists key conventions (package manager, router type)
• alwaysApply: true ensures it’s loaded for every file

SitecoreAI Branding

Sitecore XM Cloud was rebranded to SitecoreAI in November 2025. Generated templates now reference both names for clarity: “Sitecore XM Cloud (SitecoreAI)”.

Token Guide Updates

Updated token-saving guide with current model capabilities:

• 1M token context window (Opus 4.6)
• 64K default / 128K max output for both Opus 4.6 and Sonnet 4.6
• /effort command for controlling reasoning depth and token spend
• Context compaction guidance

Documentation Freshness System

AI models have a training cutoff — they may not know the latest Next.js 16, Tailwind v4, or Sitecore Content SDK v2.x APIs. This release adds a two-layer system to solve this:

Layer 2 — Documentation Verification (passive): A new section in the generated CLAUDE.md and .cursorrules base template instructs the AI to verify API signatures when unsure, using Context7 MCP, llms.txt endpoints, or WebFetch. Always active, zero overhead.

Layer 3 — /fetch-docs skill (active): A new skill that pre-loads current, version-specific docs at session start:

• Reads ai-kit.config.json to detect your stack
• Uses Context7 MCP to fetch current docs for Next.js, Tailwind, Sitecore, React
• Falls back to llms.txt (e.g., https://nextjs.org/docs/llms-full.txt)
• Summarizes key APIs and breaking changes into conversation context

Run /fetch-docs at the start of a session. The template verification section catches anything it misses.

Other Improvements

• Node.js engine bumped from >=18 to >=20 (Node 18 EOL, Next.js 16 requires 20+)
• Version: 1.10.0
• Total skills: 49 (was 48, added /fetch-docs)
• Template fragments: Turbopack and caching sections added to Next.js App Router rules
• Cursor .mdc: index.mdc entry point generated alongside fragment-specific .mdc files
• Base template: new “Documentation Verification” section in both CLAUDE.md and .cursorrules output

v1.8.0 — 2026-03-30

CLI Architecture Refactor

The CLI entry point (src/index.ts) has been refactored from a 254-line monolith into a clean modular structure:

• src/cli/error-handler.ts — shared withErrorHandler wrapper replacing 14 duplicated try/catch blocks
• src/cli/register-commands.ts — all 14 command registrations in one place
• src/index.ts — now a thin 16-line entry point

No behavior changes — same commands, options, and error handling. This improves maintainability for contributors.

JSON Schema for ai-kit.config.json

ai-kit.config.json now supports JSON Schema validation:

• ai-kit.config.schema.json ships with the npm package
• Generated configs include a $schema field pointing to https://ai-kit.mikul.me/schema/ai-kit.config.schema.json
• Editors with JSON Schema support (VS Code, JetBrains) now provide autocomplete and validation for all config fields

Support & Contact Page

New Support page in the documentation with:

• Direct contact links (website, LinkedIn, Twitter/X, GitHub)
• Guidance for teams needing setup help, custom configuration, or training

Other Improvements

• Documentation URL updated — all references now point to ai-kit.mikul.me  (was ai-kit-docs-beta.vercel.app)
• Package metadata — package.json author field expanded with website URL
• Contributing docs — updated project structure to reflect src/cli/ refactor

v1.7.0 — 2026-03-26

New Agents (5)

Five new universal agents bring the total to 16 agents (was 11). Inspired by the oh-my-claudecode evaluation :

All five are universal agents — generated for every project regardless of stack.

New Skills (2)

Two requirements-gathering skills bring the total to 48 skills (was 46):

Other Improvements

• Total agents: 16 (was 11)
• Total skills: 48 (was 46)
• New skill category: Requirements
• Updated evaluation doc with completed P1 items

v1.5.0 — 2026-03-25

Remember My Choices (Profile Persistence)

ai-kit init now saves your configuration choices (tools, strictness, hook profile) into ai-kit.config.json. When you or a teammate runs ai-kit init again on the same project:

• Shows the saved profile (tools, strictness, hooks, version)
• Offers three options: Update (re-scan, keep settings), Re-configure (fresh start), or Cancel
• In “Update” mode, zero questions are asked — the saved choices are reused automatically

This means every developer on the project gets the same AI configuration without answering questions independently.

Design Token Scanner

New scanner that extracts design tokens from your Tailwind config or CSS variables and injects them into generated rules:

• Tailwind v4: Parses @theme { } blocks in globals.css for --color-*, --font-*, --spacing-*, --breakpoint-* tokens
• Tailwind v3: Parses tailwind.config.ts/js for colors, fontFamily, spacing, and screens keys
• CSS Variables: Detects custom properties in globals.css and categorizes them

Detected tokens are shown during ai-kit init and included as template variables so the AI knows your exact design system — no more inventing arbitrary colors.

Static Site / SSG Detection

New scanner and template fragment for static Next.js sites:

• Detects output: 'export' in next.config.*
• Detects generateStaticParams(), getStaticPaths(), revalidate patterns
• Detects server actions and API routes to determine output mode: export, isr, ssr, or hybrid
• Generates a static-site template fragment with SSG-specific rules (no server-only features, build-time data, performance targets)

.aiignore File Support

Create a .aiignore file in your project root (gitignore-like syntax) to tell AI agents and scanners to skip certain files:

# Legacy code — don't touch
legacy/
*.generated.ts
src/old-components/

Loaded during scanning and displayed in ai-kit init output.

Component Registry Command

New CLI command: ai-kit component-registry

Generates ai-kit/component-registry.json and ai-kit/component-registry.md — a catalog of all components with props, categories, dependencies, Sitecore metadata, and health scores. AI agents can reference this to discover existing components before creating new ones.

npx @mikulgohil/ai-kit component-registry

Health Dashboard Enhancements

The ai-kit health command now checks:

• Design Tokens — warns if Tailwind is detected but no custom tokens are found
• Static Site — shows the detected output mode
• .aiignore — confirms patterns are loaded

Other Improvements

• Tools selection saved — ai-kit.config.json now stores tools: { claude: true, cursor: true } so ai-kit update knows which tool configs to regenerate
• Update command shows saved profile info before regenerating
• Total template fragments: 9 (was 8, added static-site)
• Total CLI commands: 14 (was 13, added component-registry)

v1.4.0 — 2026-03-25

New Skills (7)

Seven new skills bring the total to 46 skills across all categories:

New Agent: ci-debugger

A new ci-debugger agent is generated in .claude/agents/ for every project. It specializes in diagnosing CI/CD pipeline failures:

• Reads CI logs (GitHub Actions, GitLab CI, CircleCI, and others)
• Identifies root causes: failing tests, type errors, lint failures, build errors, environment issues
• Suggests targeted fixes with file and line references
• Distinguishes flaky failures from genuine regressions

Invoke with: @ci-debugger Diagnose the failing GitHub Actions workflow

Total agents: 10 (was 9).

New Hooks (2)

Bundle Impact Warning (standard + strict profiles) — fires after edits to package.json, detects newly added dependencies via git diff, and prints a warning with the package names. Prompts you to run /bundle-check to evaluate impact before committing.

Pre-Commit AI Review (strict profile only) — fires before git commit, scans all staged .ts/.tsx/.js/.jsx files for any types, console.log statements, and TODO comments without ticket references. Reports findings file-by-file without blocking the commit.

See Hooks for full behavior details.

New CLI Commands (3)

Three new commands bring the total to 13 CLI commands (was 10):

See CLI Reference for full usage.

GitHub Action Template

A new template is available at templates/github-action-ai-review.yml — a ready-to-use GitHub Actions workflow that runs an AI-powered PR review on every pull request. Copy it to .github/workflows/ to enable automated PR feedback in CI.

Other Improvements

• Total skills: 46 (was 39)
• Total agents: 10 (was 9)
• Total CLI commands: 13 (was 10)

v1.3.0 — 2026-03-25

New CLI Command: ai-kit health

One-glance project health dashboard that combines setup integrity, security, stack detection, tools/MCP status, and documentation checks into a single view with an A-F grade.

npx @mikulgohil/ai-kit health

Five diagnostic sections: Setup Integrity, Security, Stack Detection, Tools & MCP, and Documentation. Produces a letter grade with actionable recommendations. Replaces running doctor + audit + stats separately.

See CLI Reference for details.

Component Scanner & Docs Generator

Two new modules that bring component-level intelligence to AI Kit:

• Component scanner (src/scanner/components.ts) — discovers all React components and extracts metadata: props, Sitecore integration (fields, params, placeholders, GraphQL), dependencies, test/story coverage, and auto-categorization
• Component docs generator (src/generator/component-docs.ts) — produces .ai.md files per component with YAML frontmatter, health scores (0-100), props tables, usage examples, and Sitecore integration details
• Smart merge — updates only auto-generated sections when .ai.md files already exist, preserving manual edits

See What Gets Generated for details.

Mistakes Auto-Capture Hook

New PostToolUse hook that automatically logs build and lint failures into docs/mistakes-log.md:

• Fires after every Bash command with a non-zero exit code
• Pattern-matches against TypeScript errors, ESLint failures, build errors, missing modules, and syntax/type errors
• Auto-appends timestamped entries with error preview pre-filled
• Available in standard and strict hook profiles
• The mistakes log builds itself — no manual effort required

See Hooks for details.

Other Improvements

• Total CLI commands expanded from 9 to 10
• Feature overview document added to docs/feature-overview.md

v1.2.0 — 2026-03-18

Hooks System (Automated Quality Checks)

Hooks run automatically as you code — no manual invocation needed.

• Auto-format on file edit — detects Prettier or Biome and generates the right hook
• TypeScript type-check after .ts/.tsx edits
• Console.log warning detection in edited files
• Git push safety reminder before pushing
• Three hook profiles: minimal, standard, strict
• Generated in .claude/settings.local.json (gitignored by default)

See Hooks for full details.

Specialized Agents (8 agents)

Agents live in .claude/agents/ and handle delegated tasks:

Conditional agents are only generated when their tools are detected. See Agents for details.

Context Modes (3 modes)

See Context Modes for details.

New Skills (6)

Session management and orchestration skills:

New CLI Command: ai-kit audit

Security and configuration health audit with A-F grading. Checks for secrets in CLAUDE.md, hook validity, agent config, MCP security, and more.

npx @mikulgohil/ai-kit audit

See CLI Reference for details.

Other Improvements

• Biome formatter detection — scanner now detects Biome alongside Prettier
• Conditional agent generation — e2e-runner only if Playwright, sitecore-specialist only if Sitecore
• Updated init/update commands — now generate hooks, agents, and contexts
• New guide: hooks-and-agents.md added to generated guides (6 total)
• Total skills expanded from 38 to 39

v1.1.0 — 2026-03-17

New CLI Commands

Four new commands for deeper project insights and cross-tool compatibility:

New Skills (7)

Expanded the skills library from 26 to 33:

Template System Improvements

• Strictness levels: Choose between strict, standard (default), or relaxed rule enforcement during ai-kit init
• Custom fragments: Add your own rule markdown files to .ai-kit/fragments/ — they’re automatically included in generated configs
• Expanded variable system: More placeholder tokens available for template customization

Token Tracking Enhancements

• Per-project breakdown: See cost per project ranked by usage
• Budget alerts: Warnings at 50%, 75%, and 90% of monthly budget
• Model recommendations: Suggests Sonnet vs Opus usage optimization when Opus cost is disproportionate
• CSV export: ai-kit tokens --csv exports daily usage data
• Custom budget: ai-kit tokens --budget 100 sets a custom monthly budget
• Week-over-week trends: Cost comparison with the previous week
• ROI estimate: Estimated time saved and developer cost offset based on session count

Configuration Changes

ai-kit.config.json now includes two new fields:

{
  "strictness": "standard",
  "customFragments": []
}

These are backward-compatible — existing configs without these fields default to "standard" strictness and no custom fragments.

v1.0.1 — 2026-03-10

Fixed

• Minor bug fixes and improvements

v1.0.0 — 2026-03-01

Initial Release

• Project scanner with 9 detection modules (Next.js, Sitecore, styling, TypeScript, monorepo, package manager, Figma, tools, MCP)
• Template generator with 8 fragments (base, nextjs-app-router, nextjs-pages-router, sitecore-xmc, tailwind, typescript, monorepo, figma)
• 26 auto-discovered skills for Claude Code and Cursor
• 5 developer guides
• 3 documentation scaffolds
• Token usage tracking with HTML dashboard export
• Marker-based safe merging for updates
• Support for Claude Code and Cursor AI editors