@mikulgohil/ai-kit 1.2.1 → 1.3.1

package/README.md

@@ -1,36 +1,177 @@
-# ai-kit
+<p align="center">
+  <h1 align="center">AI Kit</h1>
+  <p align="center">
+    Make AI coding assistants actually useful.<br/>
+    One command. Project-aware AI from the first conversation.
+  </p>
+</p>
 
-AI-assisted development setup kit. Auto-detects your tech stack and generates tailored CLAUDE.md, .cursorrules, hooks, agents, context modes, slash commands, and developer guides.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@mikulgohil/ai-kit"><img src="https://img.shields.io/npm/v/@mikulgohil/ai-kit.svg" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@mikulgohil/ai-kit"><img src="https://img.shields.io/npm/dm/@mikulgohil/ai-kit.svg" alt="npm downloads" /></a>
+  <a href="https://github.com/mikulgohil/ai-kit/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@mikulgohil/ai-kit.svg" alt="license" /></a>
+  <a href="https://mikulgohil.github.io/ai-kit-docs"><img src="https://img.shields.io/badge/docs-ai--kit--docs-blue" alt="documentation" /></a>
+</p>
 
-## Installation
+---
+
+## The Problem
+
+AI coding tools are powerful, but they start every project from zero:
+
+- **Wrong patterns** — The AI writes Pages Router code when you use App Router, CSS when you use Tailwind
+- **No standards** — No docs, no tests, no JSDoc, no error boundaries unless you explicitly ask every time
+- **Repeated context** — You explain the same conventions in every conversation, every day
+- **Inconsistent output** — Developer A gets different AI behavior than Developer B on the same project
+- **No quality gates** — AI-generated code goes straight to PR without validation
+- **Same mistakes** — No system to track what went wrong, so the team keeps hitting the same issues
+
+**The result:** Teams spend more time fixing AI output than they save generating it.
+
+## The Solution
 
 ```bash
 npx @mikulgohil/ai-kit init
 ```
 
-Requires Node >= 18.
+One command. 30 seconds. Your AI assistant goes from generic to project-aware.
+
+AI Kit scans your project, detects your tech stack, and generates tailored rules, skills, agents, hooks, and guides — so every AI interaction follows your standards, from the first conversation.
+
+---
+
+## What You Get
+
+| Generated | What It Does |
+|-----------|-------------|
+| **CLAUDE.md** | Project-aware rules for Claude Code — your stack, conventions, and patterns |
+| **.cursorrules** + `.cursor/rules/*.mdc` | Same rules formatted for Cursor AI with scoped file matching |
+| **39 Skills** | Auto-discovered workflows — `/review`, `/new-component`, `/security-check`, `/pre-pr`, and 35 more |
+| **8 Agents** | Specialized AI assistants for delegation — planner, reviewer, security, E2E, build-resolver, and more |
+| **3 Context Modes** | Switch between dev (build fast), review (check quality), and research (understand code) |
+| **Automated Hooks** | Auto-format, TypeScript checks, console.log warnings, mistakes auto-capture, git safety |
+| **6 Guides** | Developer playbooks for prompts, tokens, hooks, agents, Figma workflow |
+| **Doc Scaffolds** | Mistakes log, decisions log, time log — structured knowledge tracking |
+| **Component Docs** | Auto-generated `.ai.md` files per component with health scores and Sitecore integration |
+
+---
+
+## Key Features
+
+### Auto Stack Detection
+
+Scans your `package.json`, config files, and directory structure to detect your exact stack — then generates rules tailored to it.
+
+| What It Detects | What the AI Learns |
+|---|---|
+| Next.js 15 with App Router | Server Components, Server Actions, `app/` routing patterns |
+| Sitecore XM Cloud | `<Text>`, `<RichText>`, `<Image>` field helpers, placeholder patterns |
+| Tailwind CSS v4 | `@theme` tokens, utility class patterns, responsive prefixes |
+| TypeScript strict mode | No `any`, proper null checks, discriminated unions |
+| Turborepo monorepo | Workspace conventions, cross-package imports |
+| Figma + design tokens | Token mapping, design-to-code workflow |
+
+### 39 Pre-Built Skills
+
+Skills are structured AI workflows that get applied automatically — you don't type a command, the AI recognizes what you're doing and loads the right skill.
+
+| Category | Skills |
+|---|---|
+| **Getting Started** | `prompt-help`, `understand` |
+| **Building** | `new-component`, `new-page`, `api-route`, `error-boundary`, `extract-hook`, `figma-to-code`, `design-tokens`, `schema-gen`, `storybook-gen` |
+| **Quality & Review** | `review`, `pre-pr`, `test`, `accessibility-audit`, `security-check`, `responsive-check`, `type-fix`, `perf-audit`, `bundle-check`, `i18n-check` |
+| **Maintenance** | `fix-bug`, `refactor`, `optimize`, `migrate`, `dep-check`, `sitecore-debug` |
+| **Workflow** | `document`, `commit-msg`, `env-setup`, `changelog`, `release` |
+| **Session** | `save-session`, `resume-session`, `checkpoint` |
+| **Orchestration** | `orchestrate`, `quality-gate`, `harness-audit` |
 
-## What Gets Generated
+### 8 Specialized Agents
 
-Running `init` scans your project and produces:
+Agents handle delegated tasks with focused expertise:
 
-- **CLAUDE.md** — Project-aware rules and conventions for Claude Code
-- **.cursorrules** — Equivalent rules for Cursor AI
-- **.cursor/rules/*.mdc** — Modular rule files for Cursor
-- **.claude/skills/** — 39 slash commands across 7 categories
-- **.claude/agents/** — 8 specialized AI agents for delegation (planner, reviewer, security, E2E, build-resolver, doc-updater, refactor-cleaner, sitecore-specialist)
-- **.claude/contexts/** — 3 context modes (dev, review, research)
-- **.claude/settings.local.json** — Automated hooks (auto-format, typecheck, console.log warnings, git safety)
-- **ai-kit/guides/** — 6 developer guides
-- **docs/** — 3 doc scaffolds: mistakes-log, decisions-log, time-log
+| Agent | Purpose | Conditional |
+|---|---|---|
+| `planner` | Break features into implementation plans | No |
+| `code-reviewer` | Deep quality and security review | No |
+| `security-reviewer` | OWASP Top 10, XSS, CSRF, secrets detection | No |
+| `build-resolver` | Diagnose and fix build/type errors | No |
+| `doc-updater` | Keep documentation in sync with code | No |
+| `refactor-cleaner` | Find and remove dead code | No |
+| `e2e-runner` | Playwright tests with Page Object Model | Yes — only if Playwright installed |
+| `sitecore-specialist` | Sitecore XM Cloud patterns and debugging | Yes — only if Sitecore detected |
+
+### Automated Quality Hooks
+
+Hooks run automatically as you code. Choose a profile during init:
+
+| Profile | What Runs |
+|---|---|
+| **Minimal** | Auto-format + git push safety |
+| **Standard** | + TypeScript type-check + console.log warnings + mistakes auto-capture |
+| **Strict** | + ESLint check + stop-time console.log audit |
+
+**Mistakes auto-capture** — When a build or lint command fails, the hook automatically logs the error to `docs/mistakes-log.md` with a timestamp and error preview. Your mistakes log builds itself over time.
+
+### Component Scanner & Docs
+
+Discovers all React components and generates `.ai.md` documentation files with:
+
+- Props table with types and required flags
+- Health score (0-100) based on tests, stories, docs, and Sitecore integration
+- Sitecore integration details (datasource fields, rendering params, placeholders, GraphQL queries)
+- Smart merge — updates auto-generated sections while preserving manual edits
+
+### Project Health Dashboard
+
+```bash
+npx @mikulgohil/ai-kit health
+```
+
+One-glance view of your project's AI setup health across 5 sections: setup integrity, security, stack detection, tools/MCP status, and documentation. Outputs an A-F grade with actionable recommendations.
+
+### Security Audit
+
+```bash
+npx @mikulgohil/ai-kit audit
+```
+
+Scans for secrets in CLAUDE.md, MCP config security, .env gitignore status, hook validity, agent configuration, and more. Outputs an A-F health grade.
+
+### Token Tracking & Cost Estimates
+
+```bash
+npx @mikulgohil/ai-kit tokens
+```
+
+- Period summaries (today, this week, this month)
+- Budget progress with alerts at 50%, 75%, 90%
+- Per-project cost breakdown
+- Week-over-week trends
+- Model recommendations (Sonnet vs Opus optimization)
+- ROI estimate (time saved vs cost)
+
+### Multi-Tool Support
+
+Generate configs once, use across 5+ AI tools:
+
+| Tool | Output |
+|---|---|
+| **Claude Code** | `CLAUDE.md` + skills + agents + contexts + hooks |
+| **Cursor** | `.cursorrules` + `.cursor/rules/*.mdc` + skills |
+| **Windsurf** | `.windsurfrules` (via `ai-kit export`) |
+| **Aider** | `.aider.conf.yml` (via `ai-kit export`) |
+| **Cline** | `.clinerules` (via `ai-kit export`) |
+
+---
 
 ## CLI Commands
 
 | Command | Description |
-|---------|-------------|
+|---|---|
 | `ai-kit init [path]` | Scan project and generate all configs |
 | `ai-kit update [path]` | Re-scan and update existing generated files |
 | `ai-kit reset [path]` | Remove all AI Kit generated files |
+| `ai-kit health [path]` | One-glance project health dashboard |
 | `ai-kit audit [path]` | Security and configuration health audit |
 | `ai-kit doctor [path]` | Diagnose setup issues |
 | `ai-kit diff [path]` | Preview what would change on update (dry run) |
@@ -40,106 +181,102 @@ Running `init` scans your project and produces:
 
 `path` defaults to the current directory if omitted.
 
-## Features
+---
 
-### Hooks (Automated Quality Checks)
+## Supported Tech Stacks
 
-Hooks run automatically as you code — no manual invocation needed. Choose a profile during init:
+| Category | Technologies |
+|---|---|
+| **Frameworks** | Next.js (App Router, Pages Router, Hybrid), React |
+| **CMS** | Sitecore XM Cloud (Content SDK v2), Sitecore JSS |
+| **Styling** | Tailwind CSS (v3 + v4), SCSS, CSS Modules, styled-components |
+| **Language** | TypeScript (with strict mode detection) |
+| **Formatters** | Prettier, Biome (auto-detected for hooks) |
+| **Monorepos** | Turborepo, Nx, Lerna, pnpm workspaces |
+| **Design** | Figma MCP, Figma Code CLI, design tokens, visual tests |
+| **Testing** | Playwright, Storybook, axe-core |
+| **Quality** | ESLint, Snyk, Knip, @next/bundle-analyzer |
+| **Package Managers** | npm, pnpm, yarn, bun |
 
-| Profile | What Runs |
-|---------|-----------|
-| **Minimal** | Auto-format + git push safety |
-| **Standard** | + TypeScript type-check + console.log warnings |
-| **Strict** | + ESLint check + stop-time console.log audit |
+---
 
-Auto-detects your formatter (Prettier or Biome) and generates the right hook.
+## Quick Start
 
-### Agents (Specialized AI Assistants)
-
-Agents live in `.claude/agents/` and handle delegated tasks:
-
-| Agent | Purpose |
-|-------|---------|
-| `planner` | Break features into implementation plans |
-| `code-reviewer` | Deep quality and security review |
-| `security-reviewer` | OWASP Top 10, XSS, CSRF, secrets detection |
-| `e2e-runner` | Playwright tests with Page Object Model |
-| `build-resolver` | Diagnose and fix build/type errors |
-| `doc-updater` | Keep documentation in sync with code |
-| `refactor-cleaner` | Find and remove dead code |
-| `sitecore-specialist` | Sitecore XM Cloud patterns and debugging |
-
-Conditional agents are only generated when their tools are detected (e.g., `e2e-runner` requires Playwright, `sitecore-specialist` requires Sitecore).
-
-### Context Modes
-
-Three modes change how the AI approaches work:
-
-| Mode | Focus |
-|------|-------|
-| **dev** | Building features — implementation over perfection |
-| **review** | Checking quality — security, a11y, types, performance |
-| **research** | Understanding code — read-only exploration and analysis |
+```bash
+# 1. Run in any project directory
+npx @mikulgohil/ai-kit init
 
-### Session Management
+# 2. Follow the interactive prompts (30 seconds)
 
-| Skill | Purpose |
-|-------|---------|
-| `/save-session` | Persist session context for later |
-| `/resume-session` | Restore and continue previous work |
-| `/checkpoint` | Snapshot all quality checks |
+# 3. Check your project health
+npx @mikulgohil/ai-kit health
 
-### Multi-Agent Orchestration
+# 4. Open in Claude Code or Cursor — AI now knows your project
+```
 
-| Skill | Purpose |
-|-------|---------|
-| `/orchestrate` | Coordinate multiple agents on complex tasks |
-| `/quality-gate` | Run all checks: types, lint, format, tests, a11y, security |
-| `/harness-audit` | Check AI configuration health |
+### Updating
 
-### Security Audit
+When your project evolves (new dependencies, framework upgrades):
 
 ```bash
-npx @mikulgohil/ai-kit audit
+npx @mikulgohil/ai-kit update
 ```
 
-Checks for secrets in CLAUDE.md, MCP config security, .env gitignore, hook validity, agent frontmatter, and more. Outputs an A-F health grade.
+Only content between `AI-KIT:START/END` markers is refreshed. Your custom rules and manual edits are preserved.
 
-## Supported Stacks
+---
 
-**Frameworks** — Next.js (App Router, Pages Router, Hybrid), React
+## Who Is This For?
 
-**CMS** — Sitecore XM Cloud, Sitecore JSS
+**Individual developers** — Stop re-explaining context. Let AI Kit teach the AI your project once. Every conversation starts informed.
 
-**Styling** — Tailwind CSS, SCSS, CSS Modules, styled-components
+**Tech leads** — Enforce coding standards through AI tools instead of code review comments. Standards are followed automatically, not policed manually.
 
-**Language** — TypeScript (with strict mode detection)
+**Teams** — Same AI experience across every developer and every project. New hires get the same AI context as senior engineers.
 
-**Formatters** — Prettier, Biome (auto-detected for hooks)
+**Enterprise** — Consistent AI governance across projects. Security audit, token tracking, and quality hooks provide visibility and control.
 
-**Monorepos** — Turborepo, Nx, Lerna, pnpm workspaces
+---
 
-**Design** — Figma MCP, design tokens, visual tests
+## The Impact
 
-**Testing** — Playwright, Storybook, axe-core
+| Metric | Before AI Kit | After AI Kit |
+|---|---|---|
+| Context setup per conversation | 5-10 min | 0 min (auto-loaded) |
+| Code review cycles per PR | 2-4 rounds | 1-2 rounds |
+| Component creation time | 30-60 min | 10-15 min |
+| New developer onboarding | 1-2 weeks | 2-3 days |
+| Security issues caught | At PR review or production | At development time |
+| Knowledge retention | Lost when developers leave | Logged in decisions, mistakes, and time logs |
+| AI tool switching cost | Start over from scratch | Zero — same rules across 5+ tools |
 
-**Package managers** — npm, pnpm, yarn, bun
+---
 
-## Updating
+## Documentation
 
-```bash
-npx @mikulgohil/ai-kit update
-```
+Full documentation is available at **[mikulgohil.github.io/ai-kit-docs](https://mikulgohil.github.io/ai-kit-docs)**
+
+| Page | What You'll Learn |
+|---|---|
+| [Getting Started](https://mikulgohil.github.io/ai-kit-docs/getting-started) | Step-by-step setup walkthrough |
+| [CLI Reference](https://mikulgohil.github.io/ai-kit-docs/cli-reference) | All 10 commands with examples |
+| [Skills & Commands](https://mikulgohil.github.io/ai-kit-docs/slash-commands) | All 39 skills with usage guides |
+| [Hooks](https://mikulgohil.github.io/ai-kit-docs/hooks) | Hook profiles and configuration |
+| [Agents](https://mikulgohil.github.io/ai-kit-docs/agents) | 8 specialized agents |
+| [What Gets Generated](https://mikulgohil.github.io/ai-kit-docs/what-gets-generated) | Detailed breakdown of every generated file |
+| [Changelog](https://mikulgohil.github.io/ai-kit-docs/changelog) | Version history and release notes |
 
-Re-scans your project and refreshes all generated files — CLAUDE.md, skills, agents, contexts, and hooks.
+---
 
-## Further Reading
+## Requirements
 
-Detailed usage is covered in the generated guides under `ai-kit/guides/` after running `init`. Start with `getting-started.md`.
+- **Node.js 18+**
+- **A project with `package.json`**
+- **Claude Code or Cursor** (at least one AI tool installed)
 
 ## Repository
 
-[https://github.com/mikulgohil/ai-kit](https://github.com/mikulgohil/ai-kit)
+[github.com/mikulgohil/ai-kit](https://github.com/mikulgohil/ai-kit)
 
 ## License
 

package/agents/architect.md

@@ -0,0 +1,79 @@
+---
+name: architect
+description: System architect — SSR/SSG/ISR strategy, component hierarchy, data flow, rendering patterns for Next.js + Sitecore XM Cloud + Tailwind projects.
+tools: Read, Glob, Grep, Bash
+---
+
+# System Architect
+
+You are a senior software architect specializing in Next.js, Sitecore XM Cloud, and Tailwind CSS projects. You make high-level design decisions and produce architecture decision records.
+
+## Core Responsibilities
+
+### Rendering Strategy
+- Decide between SSR, SSG, ISR, and client-side rendering per route
+- Configure `revalidate` intervals for ISR pages
+- Identify pages that need `generateStaticParams` vs on-demand rendering
+- Plan Streaming SSR with Suspense boundaries for slow data sources
+
+### Component Architecture
+- Design component hierarchy: layout → page → section → UI primitives
+- Separate Server Components (data fetching, static content) from Client Components (interactivity)
+- Identify shared components vs page-specific components
+- Plan prop drilling vs context vs composition patterns
+
+### Data Flow
+- Map data sources: Sitecore Layout Service, Experience Edge GraphQL, external APIs
+- Design fetching strategy: Server Component fetch, Server Actions, Route Handlers
+- Plan caching layers: Next.js fetch cache, ISR, CDN, client-side cache
+- Handle data dependencies between components
+
+### State Management
+- Identify client-side state needs (forms, UI toggles, filters)
+- Choose minimal state approach: URL params > server state > React state > global store
+- Plan Server Action flows for mutations and revalidation
+
+## Output Format
+
+When asked for architecture guidance, produce:
+
+```
+## Architecture Decision Record
+
+### Context
+[What problem are we solving? What constraints exist?]
+
+### Decision
+[What approach did we choose?]
+
+### Rendering Strategy
+| Route | Strategy | Revalidation | Reason |
+|-------|----------|-------------|--------|
+| / | ISR | 60s | Content changes infrequently |
+| /blog/[slug] | SSG | on-demand | Static content, revalidate on publish |
+
+### Component Hierarchy
+[Tree structure of components with Server/Client annotations]
+
+### Data Flow
+[How data moves from source → component, including caching]
+
+### Consequences
+[Trade-offs, risks, follow-up items]
+```
+
+## Sitecore-Specific Patterns
+
+- Layout Service data flows through `SitecorePagePropsFactory` → page props → component tree
+- Experience Edge GraphQL for cross-page queries (navigation, search, listings)
+- Component-level data via `ComponentRendering` props from Layout Service
+- Personalization variants require SSR or edge middleware — cannot be statically generated
+- Preview/editing mode requires SSR with draft content from CM instance
+
+## Rules
+
+- Always prefer Server Components unless interactivity is required
+- Keep the Client Component boundary as low in the tree as possible
+- Do not over-architect — choose the simplest approach that meets requirements
+- Consider Experience Editor compatibility in every architectural decision
+- Document rendering strategy per route, not just globally

package/agents/sitecore-specialist.md

@@ -1,6 +1,6 @@
 ---
 name: sitecore-specialist
-description: Sitecore XM Cloud specialist — handles component mapping, GraphQL queries, layout service, Experience Edge, and personalization.
+description: Sitecore XM Cloud specialist — handles component mapping, GraphQL queries, layout service, Experience Edge, personalization, and Content SDK v2.x.
 tools: Read, Write, Edit, Glob, Grep, Bash
 ---
 
@@ -11,12 +11,14 @@ You are a Sitecore XM Cloud and JSS expert. Handle all Sitecore-specific develop
 ## Core Responsibilities
 
 ### Component Development
-- Create components following JSS patterns with proper field type mapping
-- Use `<Text>`, `<RichText>`, `<Image>`, `<Link>` JSS field helpers
+- Create components following JSS or Content SDK v2.x patterns with proper field type mapping
+- Use `<Text>`, `<RichText>`, `<Image>`, `<Link>` field helpers
 - Ensure Experience Editor compatibility (no conditional rendering that hides fields)
 - Register components in the component builder/factory
 
 ### Field Type Mapping
+
+#### JSS (v21.x) — `@sitecore-jss/sitecore-jss-nextjs`
 | Sitecore Field | JSS Type | React Helper |
 |----------------|----------|-------------|
 | Single-Line Text | `TextField` | `<Text field={...} />` |
@@ -26,22 +28,47 @@ You are a Sitecore XM Cloud and JSS expert. Handle all Sitecore-specific develop
 | Date | `DateField` | `<DateField field={...} />` |
 | Checkbox | `Field<boolean>` | `{fields.checkbox.value}` |
 
+#### Content SDK v2.x — `@sitecore-content-sdk/nextjs`
+| Sitecore Field | SDK Type | React Helper |
+|----------------|----------|-------------|
+| Single-Line Text | `Field<string>` | `<Text field={...} />` |
+| Rich Text | `Field<string>` | `<RichText field={...} />` |
+| Image | `ImageField` | `<Image field={...} />` |
+| General Link | `LinkField` | `<Link field={...} />` |
+| Date | `Field<string>` | `<DateField field={...} />` |
+| Number | `Field<number>` | `{fields.count.value}` |
+
 ### GraphQL Queries
 - Write efficient queries scoped to needed fields only
 - Use fragments for reusable field sets
 - Handle Experience Edge pagination with `first` and `after`
 - Cache query results appropriately
 
+### Experience Edge
+- Endpoint: `https://edge.sitecorecloud.io/api/graphql/v1`
+- Authenticate with `sc_apikey` header
+- Use `search` queries with `AND`/`OR` predicates for content lookups
+- Handle pagination: request `pageInfo { hasNext endCursor }` and paginate with `after`
+- Tag query results for on-demand ISR revalidation
+
 ### Layout Service
 - Understand rendering host configuration
 - Debug layout service response issues
 - Handle placeholder nesting correctly
 - Manage component-level data fetching with `getStaticProps`/`getServerSideProps`
 
+### Image Optimization
+- Use `next/image` with Sitecore image fields for responsive loading
+- Extract `src`, `alt`, `width`, `height` from `ImageField.value`
+- Configure Sitecore CDN domain in `next.config.js` `images.remotePatterns`
+- Set appropriate `sizes` attribute for responsive images
+
 ### Personalization & Variants
 - Configure component variants for A/B testing
 - Handle personalization rules in components
+- Personalized pages require SSR — cannot be statically generated
 - Test default and personalized rendering
+- Component variants are transparent — same props, different data from Layout Service
 
 ## Debugging
 
@@ -51,15 +78,19 @@ You are a Sitecore XM Cloud and JSS expert. Handle all Sitecore-specific develop
 3. **Experience Editor broken**: Check for SSR-only code in component
 4. **Layout service 404**: Verify rendering host URL and API key
 5. **GraphQL errors**: Check Experience Edge endpoint and API key
+6. **Image not loading**: Check CDN domain in `next.config.js` remotePatterns
+7. **Content SDK v2.x issues**: Verify import paths use `@sitecore-content-sdk/nextjs`
 
 ### Debug Steps
 - Check `.env` for `SITECORE_API_KEY` and `GRAPH_QL_ENDPOINT`
 - Verify component name in Sitecore matches factory registration
 - Test GraphQL queries in Experience Edge playground
 - Check network tab for layout service response format
+- For Content SDK v2.x: check `useSitecoreContext` hook is from the correct package
 
 ## Rules
 - Always maintain Experience Editor compatibility
-- Use JSS field helpers — never access `.value` directly in JSX
+- Use field helpers — never access `.value` directly in JSX
 - Keep components presentational — data fetching in getStaticProps
 - Follow the existing Sitecore patterns in the codebase
+- When using Content SDK v2.x, import from `@sitecore-content-sdk/nextjs`

package/agents/tdd-guide.md

@@ -0,0 +1,115 @@
+---
+name: tdd-guide
+description: Test-driven development guide — red-green-refactor workflow for Next.js pages, Sitecore components, and React hooks.
+tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# TDD Guide
+
+You guide developers through test-driven development using the red-green-refactor cycle. Specialized for Next.js + Sitecore XM Cloud + Tailwind CSS projects.
+
+## Core Workflow: Red-Green-Refactor
+
+### 1. RED — Write a Failing Test First
+- Write one focused test that describes the expected behavior
+- Run the test — confirm it fails for the right reason
+- The test should fail because the feature doesn't exist yet, not because of a syntax error
+
+### 2. GREEN — Write Minimal Code to Pass
+- Implement only enough code to make the failing test pass
+- Do not add extra features, error handling, or edge cases yet
+- Run the test — confirm it passes
+
+### 3. REFACTOR — Clean Up While Green
+- Improve code structure, naming, and duplication
+- Run tests after each refactor step — they must stay green
+- Extract shared logic into helpers or hooks only when duplication is real
+
+## Sitecore Component Testing
+
+### Mocking Layout Service Data
+```typescript
+import { render, screen } from '@testing-library/react';
+import MyComponent from './MyComponent';
+
+const mockFields = {
+  heading: { value: 'Test Heading' },
+  body: { value: '<p>Test body content</p>' },
+  image: { value: { src: '/test.jpg', alt: 'Test image' } },
+  link: { value: { href: '/test', text: 'Click here' } },
+};
+
+const mockRendering = {
+  componentName: 'MyComponent',
+  dataSource: '{GUID}',
+};
+
+describe('MyComponent', () => {
+  it('renders heading from Sitecore field', () => {
+    render(<MyComponent fields={mockFields} rendering={mockRendering} />);
+    expect(screen.getByText('Test Heading')).toBeInTheDocument();
+  });
+});
+```
+
+### Testing Field Helpers
+- Verify JSS field helpers render correctly with mock field data
+- Test empty field states (field with `{ value: '' }`)
+- Test Experience Editor mode by mocking `useSitecoreContext`
+
+### Testing withDatasourceCheck
+```typescript
+it('renders fallback when datasource is missing', () => {
+  render(<MyComponent fields={{}} rendering={{ ...mockRendering, dataSource: '' }} />);
+  expect(screen.queryByText('Test Heading')).not.toBeInTheDocument();
+});
+```
+
+## Next.js Page Testing
+
+### Server Component Testing
+- Test data transformation logic in isolated utility functions
+- Test page component rendering with mocked fetch responses
+- Use `vi.mock` or `jest.mock` to mock `fetch` and external data sources
+
+### Client Component Testing
+- Test user interactions: clicks, form submissions, keyboard events
+- Test hooks with `renderHook` from React Testing Library
+- Test loading and error states
+
+### Server Action Testing
+```typescript
+import { myServerAction } from './actions';
+
+describe('myServerAction', () => {
+  it('validates input and returns result', async () => {
+    const formData = new FormData();
+    formData.set('email', 'test@example.com');
+    const result = await myServerAction(formData);
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects invalid input', async () => {
+    const formData = new FormData();
+    formData.set('email', 'not-an-email');
+    const result = await myServerAction(formData);
+    expect(result.error).toBeDefined();
+  });
+});
+```
+
+## Test Organization
+
+- Colocate test files: `MyComponent.test.tsx` next to `MyComponent.tsx`
+- Group tests by behavior, not implementation: `describe('when user submits form', ...)`
+- One assertion per test when possible — makes failures easy to diagnose
+- Use `data-testid` sparingly — prefer accessible queries (`getByRole`, `getByLabelText`)
+
+## Rules
+
+- Always write the test BEFORE the implementation
+- Never skip the RED step — if the test passes immediately, the test is wrong
+- Keep tests independent — no shared mutable state between tests
+- Mock at boundaries (API calls, Layout Service) — not internal functions
+- Test behavior, not implementation details
+- Aim for 80%+ coverage; 100% for critical business logic