@mikulgohil/ai-kit 1.11.0 → 2.1.0

package/guides/figma-workflow.md

@@ -14,7 +14,7 @@ Developer:  Spends 2 hours manually fixing tokens and spacing
 ## The Right Way (With ai-kit)
 
 ```
-Developer:  /figma-to-code
+Developer:  /kit-figma-to-code
 AI:         Asks targeted questions → extracts Figma context via MCP →
             maps to project tokens → reuses existing components →
             generates clean code → verifies visually
@@ -67,7 +67,7 @@ A good link looks like:
 https://www.figma.com/design/ABC123/MyProject?node-id=1234-5678
 ```
 
-### Step 2: Use /figma-to-code
+### Step 2: Use /kit-figma-to-code
 
 Run the slash command. It will:
 1. Ask what you're building (component, page, update)
@@ -101,8 +101,8 @@ The output should use correct design tokens, reuse existing components, and foll
 
 | Scenario | Tool |
 |----------|------|
-| Single component from Figma | `/figma-to-code` in Claude Code |
-| Quick design token extraction | `/design-tokens` in Claude Code |
+| Single component from Figma | `/kit-figma-to-code` in Claude Code |
+| Quick design token extraction | `/kit-design-tokens` in Claude Code |
 | Full page with 5+ components | `figma-code-cli` pipeline |
 | Sitecore component + YML items | `figma-code-cli` (4-gate pipeline) |
 | Brand implementation from scratch | `figma-code-cli` + reference ssd-figma-code |
@@ -120,7 +120,7 @@ The output should use correct design tokens, reuse existing components, and foll
 
 4. **Skipping mobile verification** — Never assume mobile is just "desktop but smaller". Check mobile designs in Figma separately.
 
-5. **Not reading design tokens first** — Run `/design-tokens` before starting Figma work. Know what tokens are available.
+5. **Not reading design tokens first** — Run `/kit-design-tokens` before starting Figma work. Know what tokens are available.
 
 ---
 

package/guides/getting-started.md

@@ -1,5 +1,7 @@
 # Getting Started with AI Kit
 
+> **Upgrading from v1.x?** All skills and agents now use a `kit-` prefix (e.g., `/kit-review` instead of `/review`). Run `ai-kit update` to migrate automatically.
+
 ## What Just Happened?
 
 `ai-kit init` scanned your project and generated AI configuration files tailored to your tech stack. Here's what was created:
@@ -19,10 +21,10 @@
 ## First Thing to Do
 
 ### If you use Claude Code:
-Run the `/prompt-help` command. It's an interactive prompt builder that asks you all the right questions before generating a perfect prompt.
+Run the `/kit-prompt-help` command. It's an interactive prompt builder that asks you all the right questions before generating a perfect prompt.
 
 ```
-/prompt-help
+/kit-prompt-help
 ```
 
 ### If you use Cursor:
@@ -33,36 +35,36 @@ Open any file and use Cmd+K or the chat panel. The `.cursorrules` file is automa
 ### Getting Started
 | Skill | What it does |
 |-------|-------------|
-| `/prompt-help` | Interactive prompt builder — **start here** |
-| `/understand` | Explain code in detail |
-| `/token-tips` | Token usage optimization |
+| `/kit-prompt-help` | Interactive prompt builder — **start here** |
+| `/kit-understand` | Explain code in detail |
+| `/kit-token-tips` | Token usage optimization |
 
 ### Building
 | Skill | What it does |
 |-------|-------------|
-| `/new-component` | Scaffold a new component |
-| `/new-page` | Create a new page/route |
-| `/api-route` | Scaffold an API route |
-| `/figma-to-code` | Implement Figma designs |
+| `/kit-new-component` | Scaffold a new component |
+| `/kit-new-page` | Create a new page/route |
+| `/kit-api-route` | Scaffold an API route |
+| `/kit-figma-to-code` | Implement Figma designs |
 
 ### Quality & Review
 | Skill | What it does |
 |-------|-------------|
-| `/review` | Deep code review |
-| `/fix-bug` | Guided bug fix workflow |
-| `/test` | Generate tests |
-| `/quality-gate` | Run ALL quality checks at once |
-| `/security-check` | Security vulnerability scan |
-| `/accessibility-audit` | WCAG 2.1 AA audit |
+| `/kit-review` | Deep code review |
+| `/kit-fix-bug` | Guided bug fix workflow |
+| `/kit-test` | Generate tests |
+| `/kit-quality-gate` | Run ALL quality checks at once |
+| `/kit-security-check` | Security vulnerability scan |
+| `/kit-accessibility-audit` | WCAG 2.1 AA audit |
 
 ### Session & Learning (NEW in v1.2.0)
 | Skill | What it does |
 |-------|-------------|
-| `/save-session` | Save current session for later resumption |
-| `/resume-session` | Pick up where you left off |
-| `/checkpoint` | Snapshot all quality check results |
-| `/orchestrate` | Coordinate multiple agents on complex tasks |
-| `/harness-audit` | Check AI configuration health |
+| `/kit-save-session` | Save current session for later resumption |
+| `/kit-resume-session` | Pick up where you left off |
+| `/kit-checkpoint` | Snapshot all quality check results |
+| `/kit-orchestrate` | Coordinate multiple agents on complex tasks |
+| `/kit-harness-audit` | Check AI configuration health |
 
 ## Hooks (Automated Checks)
 
@@ -83,24 +85,24 @@ Specialized AI assistants live in `.claude/agents/` and can be delegated to:
 
 | Agent | Specialization |
 |-------|---------------|
-| `planner` | Implementation planning |
-| `code-reviewer` | Quality review |
-| `security-reviewer` | Security audit |
-| `build-resolver` | Fix build errors |
-| `e2e-runner` | Playwright E2E tests |
-| `doc-updater` | Documentation sync |
-| `refactor-cleaner` | Dead code cleanup |
-| `sitecore-specialist` | Sitecore XM Cloud patterns |
+| `kit-planner` | Implementation planning |
+| `kit-code-reviewer` | Quality review |
+| `kit-security-reviewer` | Security audit |
+| `kit-build-resolver` | Fix build errors |
+| `kit-e2e-runner` | Playwright E2E tests |
+| `kit-doc-updater` | Documentation sync |
+| `kit-refactor-cleaner` | Dead code cleanup |
+| `kit-sitecore-specialist` | Sitecore XM Cloud patterns |
 
 ## Tips
 
-1. **Always start with `/prompt-help`** if you're unsure how to ask for something
+1. **Always start with `/kit-prompt-help`** if you're unsure how to ask for something
 2. **Be specific about files** — mention paths like `src/components/Header.tsx`
 3. **Don't start from scratch** — ask the AI to read existing code first
 4. **One task per conversation** — keep conversations focused
 5. **Review AI output** — always read what it generates before accepting
-6. **Use `/checkpoint`** before and after major changes to track quality
-7. **Use `/save-session`** before ending a long session
+6. **Use `/kit-checkpoint`** before and after major changes to track quality
+7. **Use `/kit-save-session`** before ending a long session
 
 ## CLI Commands
 

package/guides/hooks-and-agents.md

@@ -44,30 +44,30 @@ Agents are specialized AI assistants that can be delegated to for specific tasks
 
 | Agent | What It Does |
 |-------|-------------|
-| **planner** | Breaks down features into implementation plans |
-| **code-reviewer** | Deep code review for quality, patterns, and security |
-| **security-reviewer** | Focused security audit (XSS, CSRF, OWASP Top 10) |
-| **build-resolver** | Diagnoses and fixes build/type errors |
-| **e2e-runner** | Generates and runs Playwright E2E tests |
-| **doc-updater** | Syncs documentation with code changes |
-| **refactor-cleaner** | Finds and removes dead code |
-| **sitecore-specialist** | Sitecore XM Cloud patterns and debugging |
+| **kit-planner** | Breaks down features into implementation plans |
+| **kit-code-reviewer** | Deep code review for quality, patterns, and security |
+| **kit-security-reviewer** | Focused security audit (XSS, CSRF, OWASP Top 10) |
+| **kit-build-resolver** | Diagnoses and fixes build/type errors |
+| **kit-e2e-runner** | Generates and runs Playwright E2E tests |
+| **kit-doc-updater** | Syncs documentation with code changes |
+| **kit-refactor-cleaner** | Finds and removes dead code |
+| **kit-sitecore-specialist** | Sitecore XM Cloud patterns and debugging |
 
 ### How to Use Agents
 
 In Claude Code, agents are automatically available for delegation. You can also invoke them directly:
 
 ```
-@planner Plan the implementation for adding dark mode support
-@code-reviewer Review the changes in src/components/Header.tsx
-@e2e-runner Write E2E tests for the checkout flow
+@kit-planner Plan the implementation for adding dark mode support
+@kit-code-reviewer Review the changes in src/components/Header.tsx
+@kit-e2e-runner Write E2E tests for the checkout flow
 ```
 
 ### Conditional Agents
 
 Some agents are only generated when their tools are detected:
-- **e2e-runner** — only if Playwright is installed
-- **sitecore-specialist** — only if Sitecore XM Cloud is detected
+- **kit-e2e-runner** — only if Playwright is installed
+- **kit-sitecore-specialist** — only if Sitecore XM Cloud is detected
 
 ---
 
@@ -99,17 +99,17 @@ New skills help you persist context across sessions:
 
 | Skill | What It Does |
 |-------|-------------|
-| `/save-session` | Save current session state and decisions |
-| `/resume-session` | Restore context from a previous session |
-| `/checkpoint` | Run all quality checks and record results |
+| `/kit-save-session` | Save current session state and decisions |
+| `/kit-resume-session` | Restore context from a previous session |
+| `/kit-checkpoint` | Run all quality checks and record results |
 
 ### Quality & Orchestration
 
 | Skill | What It Does |
 |-------|-------------|
-| `/quality-gate` | Run all checks: types, lint, format, tests, a11y, security |
-| `/orchestrate` | Coordinate multiple agents for complex tasks |
-| `/harness-audit` | Check AI configuration health |
+| `/kit-quality-gate` | Run all checks: types, lint, format, tests, a11y, security |
+| `/kit-orchestrate` | Coordinate multiple agents for complex tasks |
+| `/kit-harness-audit` | Check AI configuration health |
 
 ---
 

package/guides/prompt-playbook.md

@@ -1,6 +1,6 @@
 # Prompt Playbook
 
-Quick reference for writing effective AI prompts. When in doubt, use `/prompt-help` instead.
+Quick reference for writing effective AI prompts. When in doubt, use `/kit-prompt-help` instead.
 
 ## The Golden Rule
 

package/guides/token-saving-tips.md

@@ -8,7 +8,7 @@ Tokens = cost. Here's how to use fewer tokens while getting better results.
 |-------|-----------|-----|
 | Pasting entire files into chat | 🔴 Very High | Point AI to file paths instead |
 | Long back-and-forth conversations | 🔴 Very High | Start new conversations per task |
-| Vague prompts that need clarification | 🟡 Medium | Use `/prompt-help` to get it right first time |
+| Vague prompts that need clarification | 🟡 Medium | Use `/kit-prompt-help` to get it right first time |
 | Asking AI to read the whole codebase | 🔴 Very High | Be specific about which files |
 | Not using existing patterns | 🟡 Medium | Reference existing files: "follow the pattern in X" |
 
@@ -26,11 +26,11 @@ Each new message includes ALL previous context. A 20-message conversation sends
 ### 3. Be Specific Upfront
 ```
 ❌ "Make a form" → AI asks 5 questions → 10 messages → 5000 tokens wasted
-✅ Use /prompt-help → 1 structured prompt → done in 2 messages
+✅ Use /kit-prompt-help → 1 structured prompt → done in 2 messages
 ```
 
 ### 4. Use Slash Commands
-Commands include pre-built context. `/new-component Button` is more efficient than typing all the instructions manually.
+Commands include pre-built context. `/kit-new-component Button` is more efficient than typing all the instructions manually.
 
 ### 5. Point to Patterns
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikulgohil/ai-kit",
-  "version": "1.11.0",
+  "version": "2.1.0",
   "description": "AI-assisted development setup kit. Auto-detects your tech stack (Next.js, Sitecore XM Cloud, Optimizely SaaS CMS, Tailwind, TypeScript, Turborepo) and generates tailored CLAUDE.md, .cursorrules, hooks, agents, context modes, slash commands, design token rules, component registries, developer guides, and spec-first workflows. Migrate existing projects, auto-backup on update, and rollback support.",
   "type": "module",
   "bin": {

package/templates/claude-md/base.md

@@ -158,43 +158,43 @@ AI training data has a cutoff date. When working with framework APIs, **verify y
 ## Skills & Commands
 Available as auto-discovered skills (`.claude/skills/`, `.cursor/skills/`) and legacy commands (`.claude/commands/`).
 
-AI will auto-discover and apply these when your task matches. You can also invoke them manually with `/skill-name`.
+AI will auto-discover and apply these when your task matches. You can also invoke them manually with `/kit-skill-name`. All ai-kit skills use the `kit-` prefix to avoid conflicts with global or built-in skills.
 
 **Getting Started**
-- `/prompt-help` — Interactive prompt builder (start here if unsure how to ask)
-- `/understand` — Explain code in detail
+- `/kit-prompt-help` — Interactive prompt builder (start here if unsure how to ask)
+- `/kit-understand` — Explain code in detail
 
 **Building**
-- `/new-component` — Scaffold a new component with proper structure
-- `/new-page` — Scaffold a new page/route
-- `/api-route` — Scaffold an API route with validation, error handling, and auth
-- `/error-boundary` — Generate error boundaries, loading states, and fallback UI
-- `/extract-hook` — Extract component logic into a reusable custom hook
-- `/figma-to-code` — Structured Figma-to-code implementation workflow
-- `/design-tokens` — Design token management and mapping
+- `/kit-new-component` — Scaffold a new component with proper structure
+- `/kit-new-page` — Scaffold a new page/route
+- `/kit-api-route` — Scaffold an API route with validation, error handling, and auth
+- `/kit-error-boundary` — Generate error boundaries, loading states, and fallback UI
+- `/kit-extract-hook` — Extract component logic into a reusable custom hook
+- `/kit-figma-to-code` — Structured Figma-to-code implementation workflow
+- `/kit-design-tokens` — Design token management and mapping
 
 **Quality & Review**
-- `/review` — Deep code review following team standards
-- `/pre-pr` — Pre-PR checklist (type safety, console cleanup, a11y, security)
-- `/test` — Generate tests for a file or function
-- `/accessibility-audit` — WCAG 2.1 AA compliance check
-- `/security-check` — XSS, injection, secrets, and OWASP Top 10 review
-- `/responsive-check` — Responsive design audit (breakpoints, touch targets, overflow)
-- `/type-fix` — Fix TypeScript issues (replace `any`, add null checks, generate types)
+- `/kit-review` — Deep code review following team standards
+- `/kit-pre-pr` — Pre-PR checklist (type safety, console cleanup, a11y, security)
+- `/kit-test` — Generate tests for a file or function
+- `/kit-accessibility-audit` — WCAG 2.1 AA compliance check
+- `/kit-security-check` — XSS, injection, secrets, and OWASP Top 10 review
+- `/kit-responsive-check` — Responsive design audit (breakpoints, touch targets, overflow)
+- `/kit-type-fix` — Fix TypeScript issues (replace `any`, add null checks, generate types)
 
 **Maintenance**
-- `/fix-bug` — Guided bug fix workflow
-- `/refactor` — Safe refactoring (split components, extract hooks, remove duplication)
-- `/optimize` — Performance optimization review
-- `/migrate` — Guided migration helper (Next.js, Tailwind, Sitecore upgrades)
-- `/dep-check` — Dependency audit (unused, outdated, security, bundle size)
-- `/sitecore-debug` — Sitecore XM Cloud debugging (placeholders, fields, GraphQL)
+- `/kit-fix-bug` — Guided bug fix workflow
+- `/kit-refactor` — Safe refactoring (split components, extract hooks, remove duplication)
+- `/kit-optimize` — Performance optimization review
+- `/kit-migrate` — Guided migration helper (Next.js, Tailwind, Sitecore upgrades)
+- `/kit-dep-check` — Dependency audit (unused, outdated, security, bundle size)
+- `/kit-sitecore-debug` — Sitecore XM Cloud debugging (placeholders, fields, GraphQL)
 
 **Workflow**
-- `/document` — Generate documentation for existing code
-- `/commit-msg` — Generate conventional commit message from staged changes
-- `/env-setup` — Generate .env.example and validate environment variables
-- `/fetch-docs` — Pre-load current docs for your tech stack (run at session start)
+- `/kit-document` — Generate documentation for existing code
+- `/kit-commit-msg` — Generate conventional commit message from staged changes
+- `/kit-env-setup` — Generate .env.example and validate environment variables
+- `/kit-fetch-docs` — Pre-load current docs for your tech stack (run at session start)
 
 ## Scripts
 {{scripts}}

package/templates/claude-md/behavioral.md

@@ -0,0 +1,86 @@
+# Behavioral Guardrails
+
+Rules for how you approach work — not what code to write, but how to think about it.
+
+_Inspired by [Andrej Karpathy's LLM coding guidelines](https://github.com/forrestchang/andrej-karpathy-skills)._
+
+## Think Before Coding
+
+Do not assume. If a request is ambiguous, surface the ambiguity explicitly before writing code.
+
+### When You're Unsure
+- **State your interpretation** — "I'm reading this as X. Is that right?"
+- **Present alternatives** — "This could mean A or B — which do you want?"
+- **Push back when warranted** — "Doing X would break Y. Should I proceed anyway?"
+- **Ask, don't guess** — a 10-second question prevents 10 minutes of wrong output
+
+### Hidden Assumption Check
+Before starting any non-trivial change, briefly list the assumptions you're making:
+- What the user wants changed
+- What should NOT change
+- Which existing patterns to follow
+- What the success criteria are
+
+If any of these are unclear, ask before coding.
+
+## Simplicity First
+
+Write the minimum code that solves the stated problem. Nothing more.
+
+### Rules
+- No speculative features — don't add caching, retry logic, analytics, or configuration options unless specifically asked
+- No premature abstractions — if a pattern is used once, inline it. Three similar lines of code is better than a premature helper
+- No over-engineering — ask yourself: "Would a senior engineer say this is overcomplicated for what it does?" If yes, simplify
+- Match the existing abstraction level — if the codebase uses simple functions, don't introduce a Strategy pattern
+
+### The Senior Engineer Test
+After writing code, review it as if you're a senior engineer on the team:
+- Does this solve exactly what was asked?
+- Is there code here that wasn't requested?
+- Could this be simpler without losing functionality?
+
+If the answer to the last two questions is "yes" — simplify before presenting.
+
+## Surgical Changes
+
+Touch only what is necessary. Every changed line must trace back to the user's request.
+
+### Rules
+- **Do not "improve" adjacent code** — if you're fixing a bug in function A, don't refactor function B even if it's ugly
+- **Do not change formatting** — don't fix quotes, spacing, semicolons, or trailing commas in lines you didn't need to touch
+- **Do not add type annotations** — to existing code that wasn't part of the request
+- **Do not remove comments** — unless the comment describes code you're removing
+- **Match existing style** — if the file uses single quotes, use single quotes. If it uses 4-space indent, use 4-space indent
+- **Orphan cleanup only** — only remove imports, variables, or types that YOUR changes made unused. Never clean up pre-existing unused code unless asked
+
+### The Diff Test
+Before presenting changes, mentally review the diff:
+- Does every changed line relate to the task?
+- Would a reviewer question why any line was touched?
+
+If a line change can't be justified by the task, revert it.
+
+## Goal-Driven Execution
+
+Transform vague tasks into verifiable goals. Then work toward those goals with explicit checkpoints.
+
+### How to Apply
+1. **Convert tasks to goals** — "Fix the bug" becomes "Write a test that reproduces the bug, then make it pass"
+2. **Plan in steps** — break non-trivial work into 3-5 concrete steps with verification at each step
+3. **Verify, don't assume** — after each step, confirm it worked before proceeding to the next
+4. **State what done looks like** — before starting, define the success criteria:
+   - What should work after the change?
+   - What should NOT break?
+   - How can the developer verify?
+
+### When Stuck
+- If an approach fails, diagnose WHY before trying something different
+- If it fails twice with the same root cause, switch strategies
+- Present what you tried and what you learned — don't silently retry
+- Ask the developer for direction when genuinely blocked
+
+## Knowing When to Apply These Rules
+
+These behavioral guardrails are calibrated for **non-trivial work** — feature implementation, bug fixes, refactors, and architectural changes.
+
+For trivial tasks (typo fixes, one-line changes, obvious corrections), apply proportionally — a quick fix doesn't need a full assumption audit. Use judgment.

package/templates/cursorrules/behavioral.md

@@ -0,0 +1,30 @@
+# Behavioral Guardrails
+
+_Inspired by [Andrej Karpathy's LLM coding guidelines](https://github.com/forrestchang/andrej-karpathy-skills)._
+
+## Think Before Coding
+- If a request is ambiguous, state your interpretation and ask — don't guess
+- Present alternatives when multiple valid approaches exist
+- Push back when the requested change would break something
+- Before non-trivial changes: list assumptions (what changes, what doesn't, success criteria)
+
+## Simplicity First
+- Write the minimum code that solves the stated problem — nothing more
+- No speculative features (caching, config options, analytics) unless asked
+- No premature abstractions — three similar lines > premature helper
+- Match existing abstraction level — don't over-engineer beyond what the codebase does
+- The "senior engineer test": would they say this is overcomplicated? If yes, simplify
+
+## Surgical Changes
+- Every changed line must trace back to the user's request
+- Don't improve adjacent code, fix formatting, add types, or remove comments outside scope
+- Match existing style (quotes, indentation, patterns)
+- Only remove imports/variables that YOUR changes made unused — don't clean pre-existing debt
+- Review the diff: if a reviewer would question why a line was touched, revert it
+
+## Goal-Driven Execution
+- Convert tasks to verifiable goals ("fix bug" → "write test that reproduces it, then pass it")
+- Plan non-trivial work in 3-5 steps with verification at each step
+- Define success criteria before starting: what works, what must not break, how to verify
+- If an approach fails twice with the same root cause, switch strategies
+- When stuck, present what you tried and ask — don't silently retry