@mikulgohil/ai-kit 1.9.0 → 1.11.0

package/README.md

@@ -123,13 +123,17 @@ Structured AI workflows applied automatically — the AI recognizes what you're
 
 ### Automated Quality Hooks
 
-| Profile | What Runs Automatically |
+| Hook | What It Does |
 |---|---|
-| **Minimal** | Auto-format + git push safety |
-| **Standard** | + TypeScript type-check + console.log warnings + mistakes auto-capture + bundle impact warning |
-| **Strict** | + ESLint check + stop-time console.log audit + pre-commit AI review + bundle impact warning |
+| **Session Init** | Echoes project stack, package manager, available scripts, and last scan date at every session start — the AI has full context from the first prompt |
+| **Auto-format** | Formats files on edit via Prettier or Biome |
+| **TypeScript check** | Catches type errors after every edit (standard + strict) |
+| **Console.log warning** | Catches debug statements before commit (standard + strict) |
+| **Mistakes auto-capture** | Logs build/lint failures to `docs/mistakes-log.md` automatically (standard + strict) |
+| **Pre-commit review** | Checks for `any` types, console.logs, and TODOs without tickets in staged files (strict) |
+| **Context re-echo** | After context compaction in long sessions, re-echoes tech stack (standard + strict) |
 
-**Mistakes auto-capture** — When a build/lint command fails, the hook logs the error to `docs/mistakes-log.md` with timestamp and error preview. The mistakes log builds itself over time.
+Three strictness profiles: **Minimal** (format + git safety), **Standard** (+ typecheck + warnings + mistakes), **Strict** (+ ESLint + pre-commit review).
 
 <br />
 
@@ -180,7 +184,9 @@ Period summaries, budget progress with alerts, per-project cost breakdown, week-
 | Command | Description |
 |---|---|
 | `ai-kit init [path]` | Scan project and generate all configs |
-| `ai-kit update [path]` | Re-scan and update generated files (safe merge) |
+| `ai-kit update [path]` | Re-scan and update generated files (safe merge, auto-backup) |
+| `ai-kit migrate [path]` | Adopt ai-kit in a project with existing CLAUDE.md — preserves custom rules |
+| `ai-kit rollback [path]` | Restore configs from a previous backup created by `update` |
 | `ai-kit reset [path]` | Remove all AI Kit generated files |
 | `ai-kit health [path]` | One-glance A-F project health dashboard |
 | `ai-kit audit [path]` | Security and configuration health audit |
@@ -299,7 +305,25 @@ When your project evolves:
 npx @mikulgohil/ai-kit update
 ```
 
-Only content between `AI-KIT:START/END` markers is refreshed. Your custom rules and manual edits are preserved.
+Every update **automatically backs up** your current configs to `.ai-kit/backups/` before writing. Only content between `AI-KIT:START/END` markers is refreshed — your custom rules and manual edits are preserved.
+
+If something goes wrong, roll back instantly:
+
+```bash
+npx @mikulgohil/ai-kit rollback          # Pick from available backups
+npx @mikulgohil/ai-kit rollback --latest  # Restore most recent backup
+```
+
+### Migrating an Existing Project
+
+Already have a hand-written `CLAUDE.md`? Migrate without losing your custom rules:
+
+```bash
+npx @mikulgohil/ai-kit migrate              # Interactive — shows preview, asks confirmation
+npx @mikulgohil/ai-kit migrate --dry-run    # Preview changes without writing
+```
+
+Your custom sections are placed at the top of the file. AI Kit's generated rules go inside `AI-KIT:START/END` markers below. Future `ai-kit update` only touches the marked section — your rules are preserved forever.
 
 ---
 
@@ -317,7 +341,7 @@ Only content between `AI-KIT:START/END` markers is refreshed. Your custom rules
 
 ## Requirements
 
-- Node.js 18+
+- Node.js 20+
 - A project with `package.json`
 - Claude Code or Cursor (at least one AI tool)
 
@@ -330,7 +354,7 @@ Full documentation at **[ai-kit.mikul.me](https://ai-kit.mikul.me)**
 | Page | What You'll Learn |
 |---|---|
 | [Getting Started](https://ai-kit.mikul.me/getting-started) | Step-by-step setup walkthrough |
-| [CLI Reference](https://ai-kit.mikul.me/cli-reference) | All 14 commands with examples |
+| [CLI Reference](https://ai-kit.mikul.me/cli-reference) | All 16 commands with examples |
 | [Skills & Commands](https://ai-kit.mikul.me/slash-commands) | All 48 skills with usage guides |
 | [What Gets Generated](https://ai-kit.mikul.me/what-gets-generated) | Detailed breakdown of every generated file |
 | [Hooks](https://ai-kit.mikul.me/hooks) | Hook profiles, mistakes auto-capture |

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