@mikulgohil/ai-kit 1.8.0 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +208 -141
  2. package/dist/index.js +78 -7
  3. package/dist/index.js.map +1 -1
  4. package/package.json +9 -2
  5. package/templates/claude-md/optimizely-saas.md +384 -0
  6. package/templates/cursorrules/optimizely-saas.md +20 -0
package/README.md CHANGED
@@ -1,46 +1,36 @@
1
- # AI Kit
1
+ <p align="center">
2
+ <strong style="font-size: 2em;">AI Kit</strong>
3
+ </p>
4
+
5
+ <h3 align="center">Make AI coding assistants actually useful.</h3>
6
+
7
+ <p align="center">
8
+ One command. Project-aware AI from the first conversation.
9
+ </p>
10
+
11
+ <p align="center">
12
+ <a href="https://www.npmjs.com/package/@mikulgohil/ai-kit"><img src="https://img.shields.io/npm/v/@mikulgohil/ai-kit.svg?style=flat-square&color=blue" alt="npm version" /></a>
13
+ <a href="https://www.npmjs.com/package/@mikulgohil/ai-kit"><img src="https://img.shields.io/npm/dm/@mikulgohil/ai-kit.svg?style=flat-square&color=green" alt="npm downloads" /></a>
14
+ <a href="https://github.com/mikulgohil/ai-kit/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@mikulgohil/ai-kit.svg?style=flat-square" alt="license" /></a>
15
+ <a href="https://github.com/mikulgohil/ai-kit"><img src="https://img.shields.io/github/stars/mikulgohil/ai-kit?style=flat-square&color=yellow" alt="GitHub stars" /></a>
16
+ </p>
17
+
18
+ <p align="center">
19
+ <a href="https://ai-kit.mikul.me">Documentation</a> &nbsp;&middot;&nbsp;
20
+ <a href="https://ai-kit.mikul.me/getting-started">Getting Started</a> &nbsp;&middot;&nbsp;
21
+ <a href="https://ai-kit.mikul.me/cli-reference">CLI Reference</a> &nbsp;&middot;&nbsp;
22
+ <a href="https://ai-kit.mikul.me/slash-commands">Skills</a> &nbsp;&middot;&nbsp;
23
+ <a href="https://ai-kit.mikul.me/agents">Agents</a> &nbsp;&middot;&nbsp;
24
+ <a href="https://ai-kit.mikul.me/changelog">Changelog</a>
25
+ </p>
2
26
 
3
- **Make AI coding assistants actually useful.**
4
- One command. Project-aware AI from the first conversation.
5
-
6
- [![npm version](https://img.shields.io/npm/v/@mikulgohil/ai-kit.svg)](https://www.npmjs.com/package/@mikulgohil/ai-kit)
7
- [![npm downloads](https://img.shields.io/npm/dm/@mikulgohil/ai-kit.svg)](https://www.npmjs.com/package/@mikulgohil/ai-kit)
8
- [![license](https://img.shields.io/npm/l/@mikulgohil/ai-kit.svg)](https://github.com/mikulgohil/ai-kit/blob/main/LICENSE)
9
-
10
- > **[Read the full documentation](https://ai-kit.mikul.me)** | [Getting Started](https://ai-kit.mikul.me/getting-started) | [CLI Reference](https://ai-kit.mikul.me/cli-reference) | [Skills & Commands](https://ai-kit.mikul.me/slash-commands) | [Hooks](https://ai-kit.mikul.me/hooks) | [Agents](https://ai-kit.mikul.me/agents) | [Changelog](https://ai-kit.mikul.me/changelog)
27
+ ---
11
28
 
12
29
  ```bash
13
30
  npx @mikulgohil/ai-kit init
14
31
  ```
15
32
 
16
- ---
17
-
18
- ## Problems AI Kit Solves
19
-
20
- Every team using AI coding assistants hits these problems. AI Kit solves each one.
21
-
22
- | # | Problem | How AI Kit Solves It |
23
- |---|---------|---------------------|
24
- | 1 | **AI forgets everything each session** — Every new chat starts from zero. No memory of project rules, patterns, or past decisions. | Generates a persistent `CLAUDE.md` with project rules, conventions, and stack details. The AI knows your project from the first prompt, every time. |
25
- | 2 | **AI generates wrong framework patterns** — Writes Pages Router code when you use App Router. Uses CSS when you use Tailwind. Creates default exports when your project uses named exports. | Auto-detects your exact stack (framework, router, CMS, styling, TypeScript config) and generates rules specific to your setup. The AI can't use the wrong patterns. |
26
- | 3 | **Developers write bad prompts** — Vague or incorrect prompts lead to wrong code, wasted time, and rework. Junior developers waste the most time. | Ships **46 pre-built skills** so developers don't write prompts from scratch — just run `/review`, `/security-check`, `/new-component`, `/refactor`, etc. |
27
- | 4 | **Same mistakes happen repeatedly** — No system to track what went wrong, so the team keeps hitting the same build failures and lint errors. | Generates a **mistakes log** (`docs/mistakes-log.md`) with **auto-capture hook** that logs every build/lint failure automatically. The AI references it to avoid repeating them. |
28
- | 5 | **Every developer gets different AI behavior** — No consistency in how the team uses AI tools, leading to inconsistent code quality and style. | One `ai-kit init` command generates the same rules for the entire team — everyone's AI follows identical project standards. Commit the generated files to the repo. |
29
- | 6 | **No quality checks on AI-generated code** — AI output goes straight to PR without type checking, linting, or security review. | Automated **hooks** run formatting, type-checking, linting, and git safety checks in real-time as the AI writes code. **Quality gate** runs everything before merge. |
30
- | 7 | **AI generates insecure code** — No guardrails for secrets exposure, XSS, SQL injection, or other vulnerabilities. AI doesn't scan its own output. | Built-in **security audit** scans for exposed secrets, OWASP risks, and misconfigurations. **Security review agent** catches issues at development time, not production. |
31
- | 8 | **AI can't handle multi-file reasoning** — Changes to one component break related files. AI loses context across linked models and shared types. | **10 specialized agents** with focused expertise — planner, code-reviewer, build-resolver, doc-updater, refactor-cleaner — each maintains context for their domain. |
32
- | 9 | **No decision trail** — Nobody remembers why a technical decision was made 3 months ago. Knowledge walks out the door when developers leave. | Auto-scaffolds a **decisions log** (`docs/decisions-log.md`) to capture what was decided, why, and by whom — fully searchable and traceable. |
33
- | 10 | **Onboarding takes too long** — New developers spend days understanding the project and its AI setup before they can contribute. | AI Kit generates developer guides and project-aware configurations — new team members get productive AI assistance from day one with zero manual setup. |
34
- | 11 | **Context gets repeated every conversation** — You explain the same conventions in every session: import order, naming, component structure, testing patterns. | All conventions are encoded in the generated rules file. The AI reads them automatically at session start. You explain once, it remembers forever. |
35
- | 12 | **AI doesn't improve over time** — The AI makes the same wrong suggestions regardless of past feedback, team patterns, or previous failures. | The system **learns as you use it** — mistakes log, decisions log, and updated rules mean the AI gets smarter with every session. Mistakes auto-capture builds the log organically. |
36
- | 13 | **Complex tasks need multiple manual AI passes** — Developers manually coordinate review + test + docs updates across separate conversations. | **Multi-agent orchestration** runs multiple specialized agents in parallel — review, test, document, and refactor in one command with `/orchestrate`. |
37
- | 14 | **Switching AI tools means starting over** — Moving from Cursor to Claude Code (or vice versa) loses all configuration and project context. | Generates configs for **5+ AI tools** (Claude Code, Cursor, Windsurf, Aider, Cline) from a single source — switch tools without losing project knowledge. |
38
- | 15 | **AI creates components without tests, docs, or types** — Every AI-generated file needs manual follow-up to add what was missed. | Skills like `/new-component` enforce a structured workflow: asks 10 questions, reads existing patterns, generates component + types + tests + docs together. |
39
- | 16 | **No visibility into AI usage costs** — Management has no idea how many tokens the team is consuming or which projects cost the most. | Built-in **token tracking** provides daily/weekly/monthly usage summaries, per-project cost breakdown, budget alerts, and ROI estimates. |
40
- | 17 | **Cursor copies entire modules instead of targeted edits** — AI bloats the repo with unnecessary file duplication, especially in CMS and monorepo setups. | Generated rules include explicit instructions for editing patterns — update in place, respect package boundaries, follow existing structure. Rules prevent over-generation. |
41
- | 18 | **No component-level AI awareness** — AI doesn't know which components have tests, stories, Sitecore integration, or documentation gaps. | **Component scanner** discovers all React components and generates `.ai.md` docs with health scores, props tables, Sitecore field mappings, and dependency trees. |
42
- | 19 | **Setup is manual and error-prone** — Configuring AI assistants requires deep knowledge of each tool's config format. Most teams skip it entirely. | **Zero manual configuration** — one command auto-detects your stack and generates everything. Update with one command when the project evolves. |
43
- | 20 | **AI hallucinates framework-specific APIs** — Generates incorrect hook usage, wrong data fetching patterns, or non-existent component APIs for your framework version. | Stack-specific template fragments include exact API patterns for your detected framework version (e.g., Next.js 15 App Router patterns, Sitecore Content SDK v2 patterns). |
33
+ > **48 pre-built skills** &nbsp;·&nbsp; **16 specialized agents** &nbsp;·&nbsp; **5+ AI tools supported** &nbsp;·&nbsp; **30-second setup**
44
34
 
45
35
  ---
46
36
 
@@ -64,13 +54,13 @@ npx @mikulgohil/ai-kit health
64
54
  |---|---|
65
55
  | `CLAUDE.md` | Project-aware rules for Claude Code — your stack, conventions, and patterns |
66
56
  | `.cursorrules` + `.cursor/rules/*.mdc` | Same rules formatted for Cursor AI with scoped file matching |
67
- | 46 Skills | Auto-discovered workflows — `/review`, `/new-component`, `/security-check`, `/pre-pr`, and 42 more |
68
- | 10 Agents | Specialized AI assistants — planner, reviewer, security, E2E, build-resolver, ci-debugger, and more |
69
- | 3 Context Modes | Switch between dev (build fast), review (check quality), and research (understand code) |
70
- | Automated Hooks | Auto-format, TypeScript checks, console.log warnings, mistakes auto-capture, git safety |
71
- | 6 Guides | Developer playbooks for prompts, tokens, hooks, agents, Figma workflow |
72
- | Doc Scaffolds | Mistakes log, decisions log, time log — structured knowledge tracking |
73
- | Component Docs | Auto-generated `.ai.md` per component with health scores and Sitecore integration |
57
+ | **48 Skills** | Auto-discovered workflows — `/review`, `/new-component`, `/security-check`, `/pre-pr`, and more |
58
+ | **16 Agents** | Specialized AI assistants — planner, reviewer, security, architect, build-resolver, and more |
59
+ | **3 Context Modes** | Switch between dev (build fast), review (check quality), and research (understand code) |
60
+ | **Automated Hooks** | Auto-format, TypeScript checks, console.log warnings, mistakes auto-capture, git safety |
61
+ | **6 Guides** | Developer playbooks for prompts, tokens, hooks, agents, Figma workflow |
62
+ | **Doc Scaffolds** | Mistakes log, decisions log, time log — structured knowledge tracking |
63
+ | **Component Docs** | Auto-generated `.ai.md` per component with health scores and Sitecore integration |
74
64
 
75
65
  ---
76
66
 
@@ -84,50 +74,77 @@ Scans your `package.json`, config files, and directory structure to detect your
84
74
  |---|---|
85
75
  | Next.js 15 with App Router | Server Components, Server Actions, `app/` routing patterns |
86
76
  | Sitecore XM Cloud | `<Text>`, `<RichText>`, `<Image>` field helpers, placeholder patterns |
77
+ | Optimizely SaaS CMS | Visual Builder, Optimizely Graph, `@remkoj` SDK, component factory |
87
78
  | Tailwind CSS v4 | `@theme` tokens, utility class patterns, responsive prefixes |
88
79
  | TypeScript strict mode | No `any`, proper null checks, discriminated unions |
89
80
  | Turborepo monorepo | Workspace conventions, cross-package imports |
90
81
  | Figma + design tokens | Token mapping, design-to-code workflow |
91
82
 
92
- ### 46 Pre-Built Skills
83
+ <br />
84
+
85
+ ### 48 Pre-Built Skills
93
86
 
94
87
  Structured AI workflows applied automatically — the AI recognizes what you're doing and loads the right skill:
95
88
 
96
89
  | Category | Skills |
97
90
  |---|---|
98
- | Getting Started | `prompt-help`, `understand` |
99
- | Building | `new-component`, `new-page`, `api-route`, `error-boundary`, `extract-hook`, `figma-to-code`, `design-tokens`, `schema-gen`, `storybook-gen`, `scaffold-spec` |
100
- | Quality & Review | `review`, `pre-pr`, `test`, `accessibility-audit`, `security-check`, `responsive-check`, `type-fix`, `perf-audit`, `bundle-check`, `i18n-check`, `test-gaps` |
101
- | Maintenance | `fix-bug`, `refactor`, `optimize`, `migrate`, `dep-check`, `sitecore-debug`, `upgrade` |
102
- | Workflow | `document`, `commit-msg`, `env-setup`, `changelog`, `release`, `pr-description`, `standup`, `learn-from-pr`, `release-notes` |
103
- | Session | `save-session`, `resume-session`, `checkpoint` |
104
- | Orchestration | `orchestrate`, `quality-gate`, `harness-audit` |
91
+ | **Getting Started** | `prompt-help`, `understand` |
92
+ | **Building** | `new-component`, `new-page`, `api-route`, `error-boundary`, `extract-hook`, `figma-to-code`, `design-tokens`, `schema-gen`, `storybook-gen`, `scaffold-spec` |
93
+ | **Quality & Review** | `review`, `pre-pr`, `test`, `accessibility-audit`, `security-check`, `responsive-check`, `type-fix`, `perf-audit`, `bundle-check`, `i18n-check`, `test-gaps` |
94
+ | **Maintenance** | `fix-bug`, `refactor`, `optimize`, `migrate`, `dep-check`, `sitecore-debug`, `upgrade` |
95
+ | **Workflow** | `document`, `commit-msg`, `env-setup`, `changelog`, `release`, `pr-description`, `standup`, `learn-from-pr`, `release-notes` |
96
+ | **Session** | `save-session`, `resume-session`, `checkpoint` |
97
+ | **Orchestration** | `orchestrate`, `quality-gate`, `harness-audit` |
105
98
 
106
- ### 10 Specialized Agents
99
+ <br />
107
100
 
108
- | Agent | Purpose | Conditional |
109
- |---|---|---|
110
- | `planner` | Break features into implementation plans | No |
111
- | `code-reviewer` | Deep quality and security review | No |
112
- | `security-reviewer` | OWASP Top 10, XSS, CSRF, secrets detection | No |
113
- | `build-resolver` | Diagnose and fix build/type errors | No |
114
- | `doc-updater` | Keep documentation in sync with code | No |
115
- | `refactor-cleaner` | Find and remove dead code | No |
116
- | `tdd-guide` | Test-driven development guidance and workflow | No |
117
- | `ci-debugger` | CI/CD failure debugger — analyzes logs and suggests fixes | No |
118
- | `e2e-runner` | Playwright tests with Page Object Model | Yes — Playwright only |
119
- | `sitecore-specialist` | Sitecore XM Cloud patterns and debugging | Yes — Sitecore only |
101
+ ### 16 Specialized Agents
102
+
103
+ | Agent | Purpose |
104
+ |---|---|
105
+ | `@planner` | Break features into implementation plans with dependencies and risk assessment |
106
+ | `@code-reviewer` | Deep quality review — patterns, performance, types, and conventions |
107
+ | `@security-reviewer` | OWASP Top 10, XSS, CSRF, secrets detection, and auth flow analysis |
108
+ | `@build-resolver` | Diagnose and fix build errors, type conflicts, and dependency issues |
109
+ | `@doc-updater` | Keep documentation in sync with code changes automatically |
110
+ | `@refactor-cleaner` | Find and remove dead code, unused imports, and unnecessary complexity |
111
+ | `@tdd-guide` | Test-driven development workflow — red, green, refactor with guidance |
112
+ | `@ci-debugger` | Analyze CI/CD failures, parse logs, and suggest targeted fixes |
113
+ | `@e2e-runner` | Playwright tests with Page Object Model and smart selectors |
114
+ | `@sitecore-specialist` | XM Cloud patterns, Content SDK v2, Experience Edge, and field helpers |
115
+ | `@architect` | SSR/SSG/ISR strategy, component hierarchy, data flow, and rendering patterns |
116
+ | `@data-scientist` | ML pipelines, model evaluation, data analysis, and experiment tracking |
117
+ | `@performance-profiler` | Core Web Vitals, bundle analysis, runtime profiling, and rendering optimization |
118
+ | `@migration-specialist` | Framework upgrades, breaking change detection, codemods, and incremental adoption |
119
+ | `@dependency-auditor` | Vulnerability scanning, outdated packages, license compliance, and bundle impact |
120
+ | `@api-designer` | REST/GraphQL API design, schema validation, versioning, and error handling |
121
+
122
+ <br />
120
123
 
121
124
  ### Automated Quality Hooks
122
125
 
123
126
  | Profile | What Runs Automatically |
124
127
  |---|---|
125
- | Minimal | Auto-format + git push safety |
126
- | Standard | + TypeScript type-check + console.log warnings + mistakes auto-capture + bundle impact warning |
127
- | Strict | + ESLint check + stop-time console.log audit + pre-commit AI review + bundle impact warning |
128
+ | **Minimal** | Auto-format + git push safety |
129
+ | **Standard** | + TypeScript type-check + console.log warnings + mistakes auto-capture + bundle impact warning |
130
+ | **Strict** | + ESLint check + stop-time console.log audit + pre-commit AI review + bundle impact warning |
128
131
 
129
132
  **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.
130
133
 
134
+ <br />
135
+
136
+ ### Multi-Tool Support
137
+
138
+ | Tool | Output |
139
+ |---|---|
140
+ | **Claude Code** | `CLAUDE.md` + skills + agents + contexts + hooks |
141
+ | **Cursor** | `.cursorrules` + `.cursor/rules/*.mdc` + skills |
142
+ | **Windsurf** | `.windsurfrules` (via `ai-kit export`) |
143
+ | **Aider** | `.aider.conf.yml` (via `ai-kit export`) |
144
+ | **Cline** | `.clinerules` (via `ai-kit export`) |
145
+
146
+ <br />
147
+
131
148
  ### Component Scanner & Docs
132
149
 
133
150
  Discovers all React components and generates `.ai.md` documentation:
@@ -136,6 +153,8 @@ Discovers all React components and generates `.ai.md` documentation:
136
153
  - Sitecore details: datasource fields, rendering params, placeholders, GraphQL queries
137
154
  - Smart merge — updates auto-generated sections while preserving manual edits
138
155
 
156
+ <br />
157
+
139
158
  ### Project Health Dashboard
140
159
 
141
160
  ```bash
@@ -144,6 +163,8 @@ npx @mikulgohil/ai-kit health
144
163
 
145
164
  One-glance view across 5 sections: setup integrity, security, stack detection, tools/MCP, and documentation. Outputs an A-F grade with actionable recommendations.
146
165
 
166
+ <br />
167
+
147
168
  ### Token Tracking & Cost Estimates
148
169
 
149
170
  ```bash
@@ -152,16 +173,6 @@ npx @mikulgohil/ai-kit tokens
152
173
 
153
174
  Period summaries, budget progress with alerts, per-project cost breakdown, week-over-week trends, model recommendations (Sonnet vs Opus), and ROI estimates.
154
175
 
155
- ### Multi-Tool Support
156
-
157
- | Tool | Output |
158
- |---|---|
159
- | Claude Code | `CLAUDE.md` + skills + agents + contexts + hooks |
160
- | Cursor | `.cursorrules` + `.cursor/rules/*.mdc` + skills |
161
- | Windsurf | `.windsurfrules` (via `ai-kit export`) |
162
- | Aider | `.aider.conf.yml` (via `ai-kit export`) |
163
- | Cline | `.clinerules` (via `ai-kit export`) |
164
-
165
176
  ---
166
177
 
167
178
  ## CLI Commands
@@ -171,48 +182,83 @@ Period summaries, budget progress with alerts, per-project cost breakdown, week-
171
182
  | `ai-kit init [path]` | Scan project and generate all configs |
172
183
  | `ai-kit update [path]` | Re-scan and update generated files (safe merge) |
173
184
  | `ai-kit reset [path]` | Remove all AI Kit generated files |
174
- | `ai-kit health [path]` | One-glance project health dashboard |
185
+ | `ai-kit health [path]` | One-glance A-F project health dashboard |
175
186
  | `ai-kit audit [path]` | Security and configuration health audit |
176
- | `ai-kit doctor [path]` | Diagnose setup issues |
187
+ | `ai-kit doctor [path]` | Diagnose setup issues and misconfigurations |
177
188
  | `ai-kit diff [path]` | Preview what would change on update (dry run) |
178
189
  | `ai-kit tokens` | Token usage summary and cost estimates |
179
- | `ai-kit stats [path]` | Project complexity metrics |
190
+ | `ai-kit stats [path]` | Project complexity metrics and analysis |
180
191
  | `ai-kit export [path]` | Export rules to Windsurf, Aider, Cline |
181
192
  | `ai-kit patterns [path]` | Generate pattern library from recurring code patterns |
182
193
  | `ai-kit dead-code [path]` | Find unused components and dead code |
183
194
  | `ai-kit drift [path]` | Detect drift between code and .ai.md docs |
195
+ | `ai-kit component-registry [path]` | Generate component catalog for AI discovery |
184
196
 
185
197
  ---
186
198
 
187
- ## Supported Tech Stacks
199
+ ## The Impact
188
200
 
189
- | Category | Technologies |
190
- |---|---|
191
- | Frameworks | Next.js (App Router, Pages Router, Hybrid), React |
192
- | CMS | Sitecore XM Cloud (Content SDK v2), Sitecore JSS |
193
- | Styling | Tailwind CSS (v3 + v4), SCSS, CSS Modules, styled-components |
194
- | Language | TypeScript (with strict mode detection) |
195
- | Formatters | Prettier, Biome (auto-detected for hooks) |
196
- | Monorepos | Turborepo, Nx, Lerna, pnpm workspaces |
197
- | Design | Figma MCP, Figma Code CLI, design tokens, visual tests |
198
- | Testing | Playwright, Storybook, axe-core |
199
- | Quality | ESLint, Snyk, Knip, @next/bundle-analyzer |
200
- | Package Managers | npm, pnpm, yarn, bun |
201
+ | Metric | Before AI Kit | After AI Kit |
202
+ |---|---|---|
203
+ | Context setup per conversation | 5-10 min | **0 min** (auto-loaded) |
204
+ | Code review cycles per PR | 2-4 rounds | **1-2 rounds** |
205
+ | Component creation time | 30-60 min | **10-15 min** |
206
+ | New developer onboarding | 1-2 weeks | **2-3 days** |
207
+ | Security issues caught | At PR review or production | **At development time** |
208
+ | Knowledge retention | Lost when developers leave | **Logged in decisions & mistakes** |
209
+ | AI tool switching cost | Start over from scratch | **Zero — same rules, 5+ tools** |
210
+ | AI-generated code quality | Inconsistent, needs fixing | **Follows project standards** |
201
211
 
202
212
  ---
203
213
 
204
- ## The Impact
214
+ <details>
215
+ <summary><strong>20 Problems AI Kit Solves</strong> (click to expand)</summary>
205
216
 
206
- | Metric | Before AI Kit | After AI Kit |
207
- |---|---|---|
208
- | Context setup per conversation | 5-10 min | 0 min (auto-loaded) |
209
- | Code review cycles per PR | 2-4 rounds | 1-2 rounds |
210
- | Component creation time | 30-60 min | 10-15 min |
211
- | New developer onboarding | 1-2 weeks | 2-3 days |
212
- | Security issues caught | At PR review or production | At development time |
213
- | Knowledge retention | Lost when developers leave | Logged in decisions and mistakes |
214
- | AI tool switching cost | Start over from scratch | Zero — same rules across 5+ tools |
215
- | AI-generated code quality | Inconsistent, needs manual fixing | Follows project standards automatically |
217
+ <br />
218
+
219
+ Every team using AI coding assistants hits these problems. AI Kit solves each one.
220
+
221
+ | # | Problem | How AI Kit Solves It |
222
+ |---|---------|---------------------|
223
+ | 1 | **AI forgets everything each session** — Every new chat starts from zero. | Generates a persistent `CLAUDE.md` with project rules, conventions, and stack details. The AI knows your project from the first prompt, every time. |
224
+ | 2 | **AI generates wrong framework patterns** — Writes Pages Router code when you use App Router. | Auto-detects your exact stack and generates rules specific to your setup. The AI can't use the wrong patterns. |
225
+ | 3 | **Developers write bad prompts** — Vague prompts lead to wrong code and rework. | Ships **48 pre-built skills** — just run `/review`, `/security-check`, `/new-component`, etc. |
226
+ | 4 | **Same mistakes happen repeatedly** — No system to track what went wrong. | Generates a **mistakes log** with **auto-capture hook** that logs every build/lint failure automatically. |
227
+ | 5 | **Every developer gets different AI behavior** — No consistency across the team. | One `ai-kit init` generates the same rules for everyone. Commit the files to the repo. |
228
+ | 6 | **No quality checks on AI-generated code** — AI output goes straight to PR. | Automated **hooks** run formatting, type-checking, linting, and git safety checks in real-time. |
229
+ | 7 | **AI generates insecure code** — No guardrails for secrets, XSS, SQL injection. | Built-in **security audit** + **security review agent** catches issues at development time. |
230
+ | 8 | **AI can't handle multi-file reasoning** — Changes to one component break others. | **16 specialized agents** with focused expertise, each maintaining context for their domain. |
231
+ | 9 | **No decision trail** — Nobody remembers why decisions were made 3 months ago. | Auto-scaffolds a **decisions log** to capture what was decided, why, and by whom. |
232
+ | 10 | **Onboarding takes too long** — New developers spend days understanding the project. | New team members get productive AI assistance from day one with zero manual setup. |
233
+ | 11 | **Context gets repeated every conversation** — Same conventions explained every session. | All conventions encoded in generated rules. The AI reads them automatically at session start. |
234
+ | 12 | **AI doesn't improve over time** — Same wrong suggestions regardless of past feedback. | Mistakes log, decisions log, and updated rules mean the AI gets smarter every session. |
235
+ | 13 | **Complex tasks need multiple manual AI passes** — Manual coordination across conversations. | **Multi-agent orchestration** runs specialists in parallel with `/orchestrate`. |
236
+ | 14 | **Switching AI tools means starting over** — Moving tools loses all configuration. | Generates configs for **5+ tools** from a single source — switch without losing context. |
237
+ | 15 | **AI creates components without tests, docs, or types** — Every file needs follow-up. | Skills like `/new-component` enforce structured workflows: component + types + tests + docs together. |
238
+ | 16 | **No visibility into AI usage costs** — No idea how many tokens the team consumes. | Built-in **token tracking** with daily/weekly/monthly summaries and cost breakdown. |
239
+ | 17 | **Cursor copies entire modules instead of targeted edits** — AI bloats the repo. | Generated rules include explicit instructions for editing patterns — update in place. |
240
+ | 18 | **No component-level AI awareness** — AI doesn't know which components have gaps. | **Component scanner** discovers all components and generates `.ai.md` docs with health scores. |
241
+ | 19 | **Setup is manual and error-prone** — Configuring AI assistants requires deep knowledge. | **Zero manual configuration** — one command auto-detects and generates everything. |
242
+ | 20 | **AI hallucinates framework-specific APIs** — Generates incorrect patterns for your version. | Stack-specific templates include exact API patterns for your detected framework version. |
243
+
244
+ </details>
245
+
246
+ ---
247
+
248
+ ## Supported Tech Stacks
249
+
250
+ | Category | Technologies |
251
+ |---|---|
252
+ | **Frameworks** | Next.js (App Router, Pages Router, Hybrid), React |
253
+ | **CMS** | Sitecore XM Cloud (Content SDK v2), Sitecore JSS |
254
+ | **Styling** | Tailwind CSS (v3 + v4), SCSS, CSS Modules, styled-components |
255
+ | **Language** | TypeScript (with strict mode detection) |
256
+ | **Formatters** | Prettier, Biome (auto-detected for hooks) |
257
+ | **Monorepos** | Turborepo, Nx, Lerna, pnpm workspaces |
258
+ | **Design** | Figma MCP, Figma Code CLI, design tokens, visual tests |
259
+ | **Testing** | Playwright, Storybook, axe-core |
260
+ | **Quality** | ESLint, Snyk, Knip, @next/bundle-analyzer |
261
+ | **Package Managers** | npm, pnpm, yarn, bun |
216
262
 
217
263
  ---
218
264
 
@@ -228,6 +274,23 @@ Period summaries, budget progress with alerts, per-project cost breakdown, week-
228
274
 
229
275
  ---
230
276
 
277
+ ## How AI Kit Compares
278
+
279
+ | Capability | AI Kit | Spec-Driven Tools |
280
+ |---|---|---|
281
+ | **Setup** | Auto-detect — zero config | Manual spec writing |
282
+ | **Stack awareness** | Scans package.json, configs, dirs | User describes stack |
283
+ | **Rules generation** | Auto-generated from stack | User-written specs |
284
+ | **Multi-tool support** | 5+ tools, single source | Varies |
285
+ | **Quality hooks** | Built-in (3 profiles) | Extension-dependent |
286
+ | **Security audit** | Built-in CLI command | Extension-dependent |
287
+ | **Token tracking** | Built-in with cost estimates | Not available |
288
+ | **Component awareness** | Auto-scanned with health scores | Not available |
289
+
290
+ > **AI Kit's philosophy**: Auto-detect everything possible, only ask for what can't be inferred.
291
+
292
+ ---
293
+
231
294
  ## Updating
232
295
 
233
296
  When your project evolves:
@@ -240,64 +303,68 @@ Only content between `AI-KIT:START/END` markers is refreshed. Your custom rules
240
303
 
241
304
  ---
242
305
 
306
+ ## Roadmap
307
+
308
+ | Feature | Description | Status |
309
+ |---|---|---|
310
+ | **Project Constitution** | `/constitution` — governance doc with coding standards, testing philosophy, performance budgets | Planned |
311
+ | **Spec-First Workflow** | `/specify` — structured feature specs with user stories and acceptance criteria before code | Planned |
312
+ | **Extension Catalog** | Community-contributed agents, skills, and templates. Install with `ai-kit extension install` | Planned |
313
+ | **Preset Bundles** | Curated bundles: `enterprise`, `startup`, `sitecore-xmc`, `fullstack`. Apply with `ai-kit preset apply` | Planned |
314
+ | **Setup Comparison** | `ai-kit compare` — gap analysis comparing your setup against other spec-driven tools | Planned |
315
+
316
+ ---
317
+
318
+ ## Requirements
319
+
320
+ - Node.js 18+
321
+ - A project with `package.json`
322
+ - Claude Code or Cursor (at least one AI tool)
323
+
324
+ ---
325
+
243
326
  ## Documentation
244
327
 
245
- **[ai-kit.mikul.me](https://ai-kit.mikul.me)**
328
+ Full documentation at **[ai-kit.mikul.me](https://ai-kit.mikul.me)**
246
329
 
247
330
  | Page | What You'll Learn |
248
331
  |---|---|
249
332
  | [Getting Started](https://ai-kit.mikul.me/getting-started) | Step-by-step setup walkthrough |
250
- | [CLI Reference](https://ai-kit.mikul.me/cli-reference) | All 13 commands with examples |
251
- | [Skills & Commands](https://ai-kit.mikul.me/slash-commands) | All 46 skills with usage guides |
333
+ | [CLI Reference](https://ai-kit.mikul.me/cli-reference) | All 14 commands with examples |
334
+ | [Skills & Commands](https://ai-kit.mikul.me/slash-commands) | All 48 skills with usage guides |
252
335
  | [What Gets Generated](https://ai-kit.mikul.me/what-gets-generated) | Detailed breakdown of every generated file |
253
336
  | [Hooks](https://ai-kit.mikul.me/hooks) | Hook profiles, mistakes auto-capture |
254
- | [Agents](https://ai-kit.mikul.me/agents) | 10 specialized agents |
337
+ | [Agents](https://ai-kit.mikul.me/agents) | 16 specialized agents |
255
338
  | [Changelog](https://ai-kit.mikul.me/changelog) | Version history and release notes |
256
339
 
257
340
  ---
258
341
 
259
- ## Roadmap
342
+ ## Need Expert Help?
260
343
 
261
- Features planned for upcoming releases, inspired by best practices from the spec-driven development ecosystem.
344
+ Whether you're rolling out AI-assisted development across your organization or need a tailored setup for a complex project — I can help.
262
345
 
263
- | Feature | Description | Status |
264
- |---|---|---|
265
- | **Project Constitution** | `/constitution` skill — generate a `PROJECT_PRINCIPLES.md` governance doc that defines coding standards, testing philosophy, performance budgets, and accessibility targets. AI agents reference it before every decision. | Planned |
266
- | **Spec-First Workflow** | `/specify` skill — create structured feature specs (`specs/<feature>.md`) with user stories, acceptance criteria, and edge cases *before* writing code. Planner agent references specs during implementation. | Planned |
267
- | **Extension Catalog** | Community-contributed agents, skills, and template fragments. Install with `ai-kit extension install <name>`. Standard manifest format for third-party contributions. | Planned |
268
- | **Preset Bundles** | Curated workflow bundles for common project types: `enterprise` (strict compliance), `startup` (fast iteration), `sitecore-xmc` (XM Cloud best practices), `fullstack` (full-stack Next.js). Apply with `ai-kit preset apply <name>`. | Planned |
269
- | **Setup Comparison** | `ai-kit compare` — gap analysis comparing your AI Kit setup against other spec-driven tools. Shows what's covered and what's missing. | Planned |
270
-
271
- See [plan.md](./plan.md) for detailed implementation plans.
346
+ | Service | Description |
347
+ |---|---|
348
+ | **Project Setup** | Custom AI Kit configuration tailored to your stack, conventions, and workflow |
349
+ | **Team Rollout** | Deploy AI Kit across your team with shared presets, skills, and agents |
350
+ | **Training & Workshops** | Help your developers get the most out of AI-assisted development |
351
+ | **Custom Extensions** | Build custom skills, agents, and hooks specific to your organization |
272
352
 
273
353
  ---
274
354
 
275
- ## How AI Kit Compares
355
+ ## Author
276
356
 
277
- | Capability | AI Kit | Spec-Driven Tools (e.g., Spec Kit) |
278
- |---|---|---|
279
- | **Setup** | Auto-detect — zero manual config | Manual spec writing required |
280
- | **Stack awareness** | Scans package.json, configs, directory structure | User describes stack in specs |
281
- | **Rules generation** | Auto-generated from detected stack | User-written specifications |
282
- | **Multi-tool support** | 5+ tools from single source | Varies by tool |
283
- | **Quality hooks** | Built-in (minimal/standard/strict profiles) | Extension-dependent |
284
- | **Security audit** | Built-in CLI command | Extension-dependent |
285
- | **Token tracking** | Built-in with cost estimates | Not available |
286
- | **Component awareness** | Auto-scanned with health scores | Not available |
287
- | **Extension ecosystem** | Coming soon | Community catalog available |
288
- | **Project principles** | Coming soon (`/constitution`) | Available (`/speckit.constitution`) |
289
- | **Spec-first workflow** | Coming soon (`/specify`) | Core feature |
357
+ **Mikul Gohil** — Senior developer and tech lead specializing in Sitecore, Next.js, and AI-assisted development workflows. Building tools that make development teams more productive.
290
358
 
291
- **AI Kit's philosophy**: Auto-detect everything possible, only ask for what can't be inferred. Spec-driven tools require manual specification upfront. Both approaches have merit — AI Kit is adding spec-first capabilities as an *optional* layer on top of auto-detection.
359
+ <p>
360
+ <a href="https://www.mikul.me">mikul.me</a> &nbsp;&middot;&nbsp;
361
+ <a href="https://github.com/mikulgohil">GitHub</a> &nbsp;&middot;&nbsp;
362
+ <a href="https://www.linkedin.com/in/mikulgohil">LinkedIn</a> &nbsp;&middot;&nbsp;
363
+ <a href="https://x.com/mikulgohil">Twitter / X</a>
364
+ </p>
292
365
 
293
366
  ---
294
367
 
295
- ## Requirements
296
-
297
- - Node.js 18+
298
- - A project with `package.json`
299
- - Claude Code or Cursor (at least one AI tool)
300
-
301
368
  ## License
302
369
 
303
370
  MIT — [github.com/mikulgohil/ai-kit](https://github.com/mikulgohil/ai-kit)
package/dist/index.js CHANGED
@@ -15,7 +15,7 @@ var GUIDES_DIR = path.join(PACKAGE_ROOT, "guides");
15
15
  var DOCS_SCAFFOLDS_DIR = path.join(PACKAGE_ROOT, "docs-scaffolds");
16
16
  var AGENTS_DIR = path.join(PACKAGE_ROOT, "agents");
17
17
  var CONTEXTS_DIR = path.join(PACKAGE_ROOT, "contexts");
18
- var VERSION = "1.8.0";
18
+ var VERSION = "1.9.0";
19
19
  var AI_KIT_CONFIG_FILE = "ai-kit.config.json";
20
20
  var GENERATED_FILES = {
21
21
  claudeMd: "CLAUDE.md",
@@ -34,6 +34,7 @@ var TEMPLATE_FRAGMENTS = [
34
34
  "nextjs-app-router",
35
35
  "nextjs-pages-router",
36
36
  "sitecore-xmc",
37
+ "optimizely-saas",
37
38
  "tailwind",
38
39
  "typescript",
39
40
  "monorepo",
@@ -153,6 +154,56 @@ function detectSitecore(pkg) {
153
154
  return { cms: "none" };
154
155
  }
155
156
 
157
+ // src/scanner/optimizely.ts
158
+ var OPTIMIZELY_PACKAGES = [
159
+ "@remkoj/optimizely-cms-react",
160
+ "@remkoj/optimizely-cms-nextjs",
161
+ "@remkoj/optimizely-cms-api",
162
+ "@remkoj/optimizely-cms-cli",
163
+ "@remkoj/optimizely-graph-client",
164
+ "@remkoj/optimizely-graph-cli",
165
+ "@remkoj/optimizely-graph-functions",
166
+ "@remkoj/optimizely-one-nextjs"
167
+ ];
168
+ var OPTIMIZELY_OFFICIAL_PACKAGES = [
169
+ "@optimizely/cms",
170
+ "@optimizely/graph",
171
+ "@optimizely/cms-react",
172
+ "@optimizely/cms-nextjs"
173
+ ];
174
+ function detectOptimizely(pkg) {
175
+ const deps = {
176
+ ...pkg.dependencies,
177
+ ...pkg.devDependencies
178
+ };
179
+ const foundPackages = [];
180
+ let version;
181
+ for (const pkgName of OPTIMIZELY_PACKAGES) {
182
+ if (deps[pkgName]) {
183
+ foundPackages.push(pkgName);
184
+ if (!version && (pkgName === "@remkoj/optimizely-cms-nextjs" || pkgName === "@remkoj/optimizely-cms-react")) {
185
+ version = deps[pkgName].replace(/[\^~>=<]/g, "");
186
+ }
187
+ }
188
+ }
189
+ for (const pkgName of OPTIMIZELY_OFFICIAL_PACKAGES) {
190
+ if (deps[pkgName]) {
191
+ foundPackages.push(pkgName);
192
+ if (!version) {
193
+ version = deps[pkgName].replace(/[\^~>=<]/g, "");
194
+ }
195
+ }
196
+ }
197
+ if (foundPackages.length === 0 && deps["@remkoj/optimizely-graph-functions"]) {
198
+ foundPackages.push("@remkoj/optimizely-graph-functions");
199
+ }
200
+ return {
201
+ optimizelySaas: foundPackages.length > 0,
202
+ optimizelyVersion: version || void 0,
203
+ optimizelyPackages: foundPackages
204
+ };
205
+ }
206
+
156
207
  // src/scanner/styling.ts
157
208
  import path3 from "path";
158
209
  function detectStyling(projectPath, pkg) {
@@ -709,6 +760,7 @@ async function scanProject(projectPath) {
709
760
  const projectName = pkg.name || path13.basename(projectPath);
710
761
  const nextjsResult = detectNextjs(projectPath, pkg);
711
762
  const sitecoreResult = detectSitecore(pkg);
763
+ const optimizelyResult = detectOptimizely(pkg);
712
764
  const stylingResult = detectStyling(projectPath, pkg);
713
765
  const tsResult = detectTypescript(projectPath);
714
766
  const monorepoResult = detectMonorepo(projectPath, pkg);
@@ -720,9 +772,14 @@ async function scanProject(projectPath) {
720
772
  const staticSiteResult = detectStaticSite(projectPath, pkg);
721
773
  const aiIgnorePatterns = loadAiIgnorePatterns(projectPath);
722
774
  const figmaDetected = figmaResult.figmaMcp || figmaResult.figmaCodeCli || figmaResult.designTokens;
775
+ const cmsResult = sitecoreResult.cms !== "none" ? sitecoreResult : optimizelyResult.optimizelySaas ? {
776
+ cms: "optimizely-saas",
777
+ optimizelyVersion: optimizelyResult.optimizelyVersion,
778
+ optimizelyPackages: optimizelyResult.optimizelyPackages
779
+ } : sitecoreResult;
723
780
  return {
724
781
  ...nextjsResult,
725
- ...sitecoreResult,
782
+ ...cmsResult,
726
783
  ...stylingResult,
727
784
  ...tsResult,
728
785
  ...monorepoResult,
@@ -817,7 +874,9 @@ function selectFragments(scan) {
817
874
  fragments.push("nextjs-pages-router");
818
875
  }
819
876
  }
820
- if (scan.cms !== "none") {
877
+ if (scan.cms === "optimizely-saas") {
878
+ fragments.push("optimizely-saas");
879
+ } else if (scan.cms !== "none") {
821
880
  fragments.push("sitecore-xmc");
822
881
  }
823
882
  if (scan.styling.includes("tailwind")) {
@@ -851,7 +910,11 @@ function buildVariables(scan) {
851
910
  techStack.push(`Next.js ${scan.nextjsVersion || ""}`);
852
911
  }
853
912
  if (scan.cms !== "none") {
854
- if (scan.cms === "sitecore-xmc-v2") {
913
+ if (scan.cms === "optimizely-saas") {
914
+ techStack.push(
915
+ `Optimizely SaaS CMS${scan.optimizelyVersion ? ` (SDK ${scan.optimizelyVersion})` : ""}`
916
+ );
917
+ } else if (scan.cms === "sitecore-xmc-v2") {
855
918
  techStack.push(
856
919
  `Sitecore XM Cloud${scan.sitecoreContentSdkVersion ? ` (Content SDK ${scan.sitecoreContentSdkVersion})` : " (Content SDK v2)"}`
857
920
  );
@@ -920,9 +983,13 @@ function buildCursorVariables(scan) {
920
983
  techStack.push(`Next.js ${scan.nextjsVersion || ""}`);
921
984
  }
922
985
  if (scan.cms !== "none") {
923
- techStack.push(
924
- scan.cms === "sitecore-xmc-v2" || scan.cms === "sitecore-xmc" ? "Sitecore XM Cloud" : "Sitecore JSS"
925
- );
986
+ if (scan.cms === "optimizely-saas") {
987
+ techStack.push("Optimizely SaaS CMS");
988
+ } else {
989
+ techStack.push(
990
+ scan.cms === "sitecore-xmc-v2" || scan.cms === "sitecore-xmc" ? "Sitecore XM Cloud" : "Sitecore JSS"
991
+ );
992
+ }
926
993
  }
927
994
  if (scan.typescript) techStack.push("TypeScript");
928
995
  if (scan.styling.includes("tailwind")) techStack.push("Tailwind CSS");
@@ -958,6 +1025,10 @@ var MDC_CONFIG = {
958
1025
  description: "Sitecore XM Cloud component patterns and field helpers",
959
1026
  globs: "src/components/**/*.{ts,tsx}"
960
1027
  },
1028
+ "optimizely-saas": {
1029
+ description: "Optimizely SaaS CMS patterns, Visual Builder, and Graph API",
1030
+ globs: "src/components/**/*.{ts,tsx}, src/gql/**/*.{ts,graphql}"
1031
+ },
961
1032
  tailwind: {
962
1033
  description: "Tailwind CSS conventions and utility patterns",
963
1034
  globs: "**/*.{tsx,jsx,css}"