@mikulgohil/ai-kit 1.3.0 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikulgohil/ai-kit",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "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.",
   "type": "module",
   "bin": {
@@ -45,10 +45,14 @@
   ],
   "author": "Mikul Gohil",
   "license": "MIT",
+  "homepage": "https://mikulgohil.github.io/ai-kit-docs",
   "repository": {
     "type": "git",
     "url": "https://github.com/mikulgohil/ai-kit.git"
   },
+  "bugs": {
+    "url": "https://github.com/mikulgohil/ai-kit/issues"
+  },
   "engines": {
     "node": ">=18.0.0"
   },