@mikulgohil/ai-kit 1.1.0 → 1.3.0

package/commands/quality-gate.md

@@ -0,0 +1,82 @@
+# Quality Gate — Comprehensive Quality Checks
+
+Run all quality checks and present a pass/fail summary.
+
+## Checks
+
+### TypeScript Type Check
+```bash
+npx tsc --noEmit --pretty
+```
+**Pass criteria**: zero errors
+
+### Lint (ESLint)
+```bash
+npx eslint . --max-warnings 0 --format compact
+```
+**Pass criteria**: zero errors, zero warnings
+
+### Format (Prettier or Biome)
+```bash
+npx prettier --check "**/*.{ts,tsx,js,jsx,json,css,scss,md}"
+# or
+npx @biomejs/biome check .
+```
+**Pass criteria**: all files formatted
+
+### Unit Tests
+```bash
+npm test -- --run --reporter=verbose
+```
+**Pass criteria**: all tests pass
+
+### Build
+```bash
+npm run build
+```
+**Pass criteria**: build succeeds without errors
+
+### Bundle Size (if @next/bundle-analyzer available)
+Check for significant size increases compared to main branch.
+
+### Accessibility (if axe-core available)
+```bash
+npx playwright test --grep @a11y
+```
+**Pass criteria**: no critical or serious violations
+
+### Security
+```bash
+npm audit --production --audit-level=high
+```
+**Pass criteria**: no high or critical vulnerabilities
+
+Check for common issues:
+- `console.log` statements in production code
+- Hardcoded secrets or API keys
+- `any` types in TypeScript
+
+## Output Format
+
+```
+┌─────────────┬────────┬─────────────────────────┐
+│ Check       │ Status │ Details                 │
+├─────────────┼────────┼─────────────────────────┤
+│ TypeScript  │ ✓ PASS │ 0 errors                │
+│ Lint        │ ✓ PASS │ 0 warnings              │
+│ Format      │ ✓ PASS │ All files formatted     │
+│ Tests       │ ✓ PASS │ 42/42 passed (87% cov)  │
+│ Build       │ ✓ PASS │ 12.3s                   │
+│ Bundle      │ ⚠ WARN │ +15KB from main         │
+│ A11y        │ ✓ PASS │ 0 violations            │
+│ Security    │ ✓ PASS │ 0 high/critical         │
+│ Console.log │ ✗ FAIL │ 3 files have console.log│
+└─────────────┴────────┴─────────────────────────┘
+
+Result: 8/9 passed — fix console.log before merge
+```
+
+## Gate Policy
+- **All PASS**: safe to merge
+- **Any WARN**: merge with acknowledgment
+- **Any FAIL**: fix before merge (no exceptions in strict mode)

package/commands/resume-session.md

@@ -0,0 +1,40 @@
+# Resume Session — Restore Previous Context
+
+Restore context from a saved session and continue where you left off.
+
+## Process
+
+### 1. Find the Session
+- Look in `ai-kit/sessions/` for saved session files
+- List available sessions sorted by date (most recent first)
+- If user specifies a topic, filter by filename
+- Otherwise, offer the most recent session
+
+### 2. Read and Summarize
+Read the session file and present:
+- **What was done**: summary of previous work
+- **What's pending**: remaining checklist items
+- **Key decisions**: important context from last time
+- **Files involved**: which files were being worked on
+
+### 3. Verify Current State
+Before resuming work, check:
+- Are the files from the session still in the expected state?
+- Have other changes been made since the session was saved?
+- Is the build currently passing?
+- Are there any uncommitted changes that might conflict?
+
+### 4. Resume
+- Pick up from the first unchecked item in the pending list
+- Reference previous decisions to maintain consistency
+- Update the session file as work progresses
+
+## If No Sessions Found
+- Check `ai-kit/sessions/` directory exists
+- Suggest running `/save-session` at the end of future sessions
+- Offer to start fresh by creating a new session
+
+## Tips
+- Always verify file state before making changes — the codebase may have evolved
+- If significant time has passed, re-read modified files for context
+- Update the session file when work is complete

package/commands/save-session.md

@@ -0,0 +1,65 @@
+# Save Session — Persist Current Context
+
+Save the current session state so it can be resumed later.
+
+## What to Capture
+
+### 1. Session Summary
+- What was the goal of this session?
+- What was accomplished?
+- How far through the work are we?
+
+### 2. Files Modified
+List every file that was created, modified, or deleted:
+```markdown
+- `src/components/Header.tsx` — added mobile navigation
+- `src/hooks/useAuth.ts` — created new auth hook
+- `tests/header.spec.ts` — added E2E tests
+```
+
+### 3. Decisions Made
+Document architectural and design decisions:
+```markdown
+- Chose Context API over Zustand for auth state (simpler, no extra dep)
+- Used Server Component for header (no client interactivity needed)
+- Deferred dark mode to follow-up PR
+```
+
+### 4. Pending Work
+What remains to be done:
+```markdown
+- [ ] Add unit tests for useAuth hook
+- [ ] Update Storybook stories for Header
+- [ ] Fix mobile nav animation on iOS Safari
+```
+
+### 5. Current State
+- Are there uncommitted changes?
+- Is the build passing?
+- Any known issues or blockers?
+
+## Save Location
+Write to `ai-kit/sessions/[YYYY-MM-DD]-[HH-MM]-[topic].md`
+
+## Format
+```markdown
+# Session: [Topic]
+**Date**: YYYY-MM-DD HH:MM
+**Duration**: approximate
+**Status**: in-progress | paused | completed
+
+## Summary
+[What was accomplished]
+
+## Files Modified
+[List with descriptions]
+
+## Decisions
+[Key choices and rationale]
+
+## Pending
+[Checklist of remaining work]
+
+## Notes
+[Anything else relevant for resumption]
+```

package/commands/search-first.md

@@ -0,0 +1,60 @@
+# Search First
+
+> **Role**: You are a senior developer who always researches before coding. You search documentation, existing patterns, and APIs before writing any implementation.
+> **Goal**: Research the topic thoroughly, then provide an implementation grounded in actual docs and existing codebase patterns.
+
+## Mandatory Steps
+
+You MUST follow these steps in order. Do not skip any step.
+
+1. **Understand the Request** — What exactly is being asked? Identify the feature, bug, or task.
+
+2. **Search the Codebase First** — Before writing any code:
+   - Find existing implementations of similar patterns
+   - Check for utility functions, hooks, or helpers that already solve part of the problem
+   - Look at how similar components/pages are structured in the project
+   - Check the project's component library for reusable pieces
+
+3. **Check Documentation** — For unfamiliar APIs or patterns:
+   - **Sitecore**: Check JSS/Content SDK docs for field types, helpers, Layout Service API
+   - **Next.js**: Check App Router docs for Server Components, Server Actions, Middleware, ISR
+   - **Tailwind**: Check utility class names, responsive prefixes, config extensions
+   - Search for the specific API, hook, or function signature
+
+4. **Identify the Pattern** — Based on research:
+   - What existing pattern in the codebase most closely matches what we need?
+   - What adjustments are needed for this specific use case?
+   - Are there gotchas or breaking changes in the library version being used?
+
+5. **Implement with Confidence** — Write code that follows discovered patterns:
+   - Match the style and conventions of the existing codebase
+   - Use the correct API signatures from documentation
+   - Reference where the pattern was found
+
+## Output Format
+
+```
+## Research Summary
+
+### Existing Patterns Found
+[List of similar implementations in the codebase with file paths]
+
+### Documentation References
+[Key API details, function signatures, or configuration options]
+
+### Approach
+[How this implementation follows discovered patterns]
+
+### Implementation
+[The actual code, following codebase conventions]
+```
+
+## Rules
+
+- NEVER write code before searching the codebase for existing patterns
+- NEVER guess API signatures — look them up
+- NEVER assume a library API works a certain way — verify it
+- Always reference where you found the pattern or API details
+- If documentation is sparse, check the library source code or types
+
+Target: $ARGUMENTS

package/commands/server-action.md

@@ -0,0 +1,93 @@
+# Server Action
+
+> **Role**: You are a Next.js App Router specialist. You scaffold Server Actions with proper validation, error handling, and revalidation.
+> **Goal**: Create a type-safe Server Action following Next.js best practices.
+
+## Mandatory Steps
+
+1. **Determine Use Case** — Ask if not clear:
+   - Form submission (use `<form action={...}>`)
+   - Programmatic mutation (call from event handler or other Server Action)
+   - Data revalidation only (on-demand ISR trigger)
+
+2. **Detect Existing Patterns** — Search the codebase for:
+   - Existing Server Actions in `app/**/actions.ts` files
+   - Zod schemas in use for validation
+   - Existing revalidation patterns (`revalidatePath`, `revalidateTag`)
+
+3. **Generate the Server Action** — Following this pattern:
+
+```typescript
+'use server';
+
+import { revalidatePath } from 'next/cache';
+import { z } from 'zod';
+
+const Schema = z.object({
+  // Define input shape
+});
+
+type ActionResult = {
+  success: boolean;
+  error?: string;
+  data?: unknown;
+};
+
+export async function myAction(formData: FormData): Promise<ActionResult> {
+  const parsed = Schema.safeParse({
+    field: formData.get('field'),
+  });
+
+  if (!parsed.success) {
+    return { success: false, error: parsed.error.issues[0].message };
+  }
+
+  try {
+    // Perform mutation (database, API call, etc.)
+
+    revalidatePath('/affected-route');
+    return { success: true };
+  } catch (error) {
+    return { success: false, error: 'Something went wrong. Please try again.' };
+  }
+}
+```
+
+4. **Generate the Form Component** (if form-based):
+
+```typescript
+'use client';
+
+import { useActionState } from 'react';
+import { myAction } from './actions';
+
+export function MyForm() {
+  const [state, formAction, isPending] = useActionState(myAction, null);
+
+  return (
+    <form action={formAction}>
+      {/* form fields */}
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Submitting...' : 'Submit'}
+      </button>
+      {state?.error && <p role="alert">{state.error}</p>}
+    </form>
+  );
+}
+```
+
+5. **Wire Up Revalidation** — Choose the right strategy:
+   - `revalidatePath('/path')` for specific route revalidation
+   - `revalidateTag('tag')` for cache tag-based revalidation
+   - Both for comprehensive cache busting
+
+## Rules
+
+- Always use `'use server'` directive
+- Always validate input with Zod — never trust form data
+- Return structured results — never throw errors from Server Actions
+- Keep Server Actions in dedicated `actions.ts` files, colocated with the route
+- Use `useActionState` for form state, not manual useState + useEffect
+- Do not access `cookies()` or `headers()` unless necessary — they opt into dynamic rendering
+
+Target: $ARGUMENTS

package/commands/sitecore-debug.md

@@ -196,6 +196,64 @@ You MUST structure your response exactly as follows:
 [how to verify the fix worked]
 ```
 
+### 6. Content SDK v2.x Issues
+
+**Symptoms:** Components work with JSS but break after migrating to Content SDK v2.x.
+
+```
+[ ] Are imports updated from @sitecore-jss/sitecore-jss-nextjs to @sitecore-content-sdk/nextjs?
+    Check: All import statements in component files
+    Fix: Update import paths throughout the component
+
+[ ] Is useSitecoreContext imported from the correct package?
+    Check: import { useSitecoreContext } from '@sitecore-content-sdk/nextjs'
+    Common mistake: Still importing from JSS package after migration
+
+[ ] Are field types updated to Content SDK v2.x types?
+    Check: Field<string> instead of TextField, ImageField stays the same
+    Fix: Update type imports and interface definitions
+
+[ ] Is the component factory using Content SDK registration?
+    Check: Component registration follows v2.x patterns
+    Fix: Update componentFactory to use Content SDK APIs
+```
+
+### 7. Experience Edge Connectivity
+
+```
+[ ] Is the GraphQL endpoint correct?
+    Check: GRAPH_QL_ENDPOINT=https://edge.sitecorecloud.io/api/graphql/v1
+    Common mistake: Using CM GraphQL endpoint instead of Edge
+
+[ ] Is the API key valid for Experience Edge?
+    Check: API key must be published and have Edge access
+    Test: curl -H "sc_apikey: YOUR_KEY" https://edge.sitecorecloud.io/api/graphql/v1
+
+[ ] Are queries using the correct search predicates?
+    Check: _path, _language, _templatename fields
+    Common mistake: Using item paths without /sitecore/content/ prefix
+
+[ ] Is pagination handled correctly?
+    Check: Using first/after parameters, checking hasNext in pageInfo
+    Fix: Add pageInfo { hasNext endCursor } to query and loop until !hasNext
+```
+
+### 8. Image Optimization Issues
+
+```
+[ ] Is the Sitecore CDN domain configured in next.config.js?
+    Check: images.remotePatterns includes the Sitecore media domain
+    Fix: Add { protocol: 'https', hostname: '*.sitecorecloud.io' } to remotePatterns
+
+[ ] Is the image src extracted correctly from the field?
+    Check: field.value.src contains the full URL
+    Common mistake: Using field.value directly instead of field.value.src
+
+[ ] Are width and height provided to next/image?
+    Check: Width and height from field.value or explicit dimensions
+    Fix: Extract width/height from ImageField or provide defaults
+```
+
 ## Self-Check
 
 Before responding, verify:

package/contexts/dev.md

@@ -0,0 +1,35 @@
+# Development Mode
+
+You are in **development mode**. Focus on building features efficiently.
+
+## Behavior
+
+- **Build first, polish later** — get working code, then refine
+- Suggest patterns from the existing codebase rather than inventing new ones
+- Run type checks after making changes (`tsc --noEmit`)
+- Consider Server vs Client Components — default to Server Components unless interactivity is needed
+- For data fetching, check if Sitecore layout service or GraphQL is the right source
+- Auto-run the dev server if it's not already running
+
+## When Writing Code
+
+- Follow existing file naming conventions in the project
+- Match the component structure already used (functional components, hooks pattern)
+- Use existing design tokens and utility classes (Tailwind, SCSS variables)
+- Import from existing shared utilities before creating new ones
+- Add `"use client"` directive only when the component needs client-side interactivity
+
+## Priorities
+
+1. Working correctly
+2. Type-safe
+3. Following project patterns
+4. Readable
+5. Performant (optimize later if needed)
+
+## Don't
+
+- Don't refactor unrelated code while building a feature
+- Don't add tests during initial development (do it after the feature works)
+- Don't over-engineer — solve the current problem, not hypothetical future ones
+- Don't block on perfect naming — good enough is fine, rename later if needed

package/contexts/research.md

@@ -0,0 +1,56 @@
+# Research Mode
+
+You are in **research mode**. Focus on understanding and discovery — do not make changes.
+
+## Behavior
+
+- **Read broadly** before forming conclusions
+- Map the full picture: components, data flow, dependencies, patterns
+- Summarize findings clearly before suggesting any changes
+- Use Context7 MCP for up-to-date library documentation
+- Use Perplexity MCP for web research on patterns and solutions
+
+## Investigation Process
+
+1. **Scope**: Define what you're investigating and why
+2. **Explore**: Read relevant files, trace data flow, check dependencies
+3. **Map**: Create a mental model of how the system works
+4. **Report**: Summarize findings with evidence (file references)
+5. **Recommend**: Suggest next steps (but don't implement yet)
+
+## What to Document
+
+- Architecture overview of the area being investigated
+- Data flow: where data originates, transforms, and is consumed
+- Dependency map: what depends on what
+- Patterns in use: design patterns, naming conventions, file structure
+- Potential issues: tech debt, inconsistencies, security concerns
+- External resources: relevant docs, articles, or prior art
+
+## Output Format
+
+```markdown
+## Research: [Topic]
+
+### Summary
+[2-3 sentence overview]
+
+### Findings
+- [Finding with file:line references]
+
+### Architecture
+[Brief description of how the system/feature works]
+
+### Recommendations
+- [Actionable next steps, prioritized]
+
+### References
+- [Links to docs, articles, or related code]
+```
+
+## Don't
+
+- Don't make code changes in research mode
+- Don't propose solutions before understanding the problem fully
+- Don't limit investigation to obvious files — follow the dependency chain
+- Don't skip reading test files — they reveal intent and edge cases

package/contexts/review.md

@@ -0,0 +1,49 @@
+# Review Mode
+
+You are in **review mode**. Focus on quality, correctness, and standards compliance.
+
+## Review Checklist
+
+### Security (CRITICAL)
+- [ ] No XSS vectors (dangerouslySetInnerHTML, unsanitized user input)
+- [ ] No hardcoded secrets or API keys
+- [ ] API routes validate and sanitize input
+- [ ] Authentication checks on protected routes
+- [ ] CSRF protection on forms
+
+### Accessibility (HIGH)
+- [ ] Semantic HTML elements (nav, main, article, button vs div)
+- [ ] ARIA labels on interactive elements without visible text
+- [ ] Keyboard navigation works (tab order, focus management)
+- [ ] Color contrast meets WCAG 2.1 AA (4.5:1 for text)
+- [ ] Images have alt text, decorative images use `alt=""`
+
+### TypeScript (HIGH)
+- [ ] No `any` types — use `unknown` with type guards or proper types
+- [ ] Null/undefined handled explicitly
+- [ ] Function return types specified for public APIs
+- [ ] Enums replaced with `as const` objects where appropriate
+
+### React Patterns (MEDIUM)
+- [ ] Hooks rules followed (no conditional hooks)
+- [ ] useEffect dependencies are complete and correct
+- [ ] Memoization justified (not premature optimization)
+- [ ] Component props interface is minimal and well-typed
+- [ ] Event handlers don't create unnecessary closures in render
+
+### Performance (MEDIUM)
+- [ ] No unnecessary re-renders (check context usage, prop stability)
+- [ ] Large dependencies dynamically imported
+- [ ] Images use next/image with proper sizing
+- [ ] API calls have appropriate caching headers
+- [ ] No N+1 query patterns in data fetching
+
+### Sitecore (when applicable)
+- [ ] JSS field helpers used correctly
+- [ ] Experience Editor compatibility maintained
+- [ ] GraphQL queries are efficient and paginated
+
+## Output Format
+
+Rate each finding as: **CRITICAL** / **HIGH** / **MEDIUM** / **LOW**
+Include file:line references and suggested fixes.