@mikulgohil/ai-kit 1.6.1 → 1.8.0

package/ai-kit.config.schema.json

@@ -0,0 +1,284 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://ai-kit.mikul.me/schema/ai-kit.config.schema.json",
+  "title": "AI Kit Configuration",
+  "description": "Configuration file generated by @mikulgohil/ai-kit. Auto-detected project settings, templates, commands, and tooling preferences.",
+  "type": "object",
+  "required": [
+    "version",
+    "scanResult",
+    "generatedAt",
+    "templates",
+    "commands",
+    "guides",
+    "agents",
+    "contexts",
+    "hooks",
+    "hookProfile",
+    "strictness",
+    "customFragments",
+    "tools"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Pointer to the JSON Schema for editor validation and autocompletion."
+    },
+    "version": {
+      "type": "string",
+      "description": "The ai-kit version that generated this configuration."
+    },
+    "scanResult": {
+      "$ref": "#/definitions/ProjectScan",
+      "description": "Auto-detected project metadata from the scan phase."
+    },
+    "generatedAt": {
+      "type": "string",
+      "description": "ISO 8601 timestamp of when this configuration was generated."
+    },
+    "templates": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of template identifiers selected for this project."
+    },
+    "commands": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Slash commands generated for the project."
+    },
+    "guides": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Developer guides generated for the project."
+    },
+    "agents": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "AI agent configurations generated for the project."
+    },
+    "contexts": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Context mode files generated for the project."
+    },
+    "hooks": {
+      "type": "boolean",
+      "description": "Whether Claude Code hooks are enabled."
+    },
+    "hookProfile": {
+      "type": "string",
+      "enum": ["minimal", "standard", "strict"],
+      "description": "The hook strictness profile controlling which hooks are generated."
+    },
+    "strictness": {
+      "type": "string",
+      "enum": ["strict", "standard", "relaxed"],
+      "description": "Overall strictness level for generated rules and guidelines."
+    },
+    "teamProfile": {
+      "type": "string",
+      "enum": ["solo-dev", "small-team", "enterprise"],
+      "description": "Optional team size profile that tailors generated content."
+    },
+    "customFragments": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "User-provided custom rule fragments merged into generated output."
+    },
+    "tools": {
+      "type": "object",
+      "description": "Which AI coding tools to generate configuration files for.",
+      "required": ["claude", "cursor"],
+      "properties": {
+        "claude": {
+          "type": "boolean",
+          "description": "Generate CLAUDE.md and related Claude Code configuration."
+        },
+        "cursor": {
+          "type": "boolean",
+          "description": "Generate .cursorrules and related Cursor configuration."
+        }
+      }
+    }
+  },
+  "definitions": {
+    "ProjectScan": {
+      "type": "object",
+      "description": "Result of the automatic project scan, capturing framework, CMS, styling, tooling, and other detected metadata.",
+      "required": [
+        "framework",
+        "cms",
+        "styling",
+        "typescript",
+        "monorepo",
+        "figma",
+        "designTokens",
+        "staticSite",
+        "aiIgnorePatterns",
+        "tools",
+        "mcpServers",
+        "packageManager",
+        "projectName",
+        "projectPath",
+        "scripts"
+      ],
+      "properties": {
+        "framework": {
+          "type": "string",
+          "enum": ["nextjs", "react", "unknown"]
+        },
+        "nextjsVersion": {
+          "type": "string"
+        },
+        "routerType": {
+          "type": "string",
+          "enum": ["app", "pages", "hybrid"]
+        },
+        "cms": {
+          "type": "string",
+          "enum": ["sitecore-xmc-v2", "sitecore-xmc", "sitecore-jss", "none"]
+        },
+        "sitecorejssVersion": {
+          "type": "string"
+        },
+        "sitecoreContentSdkVersion": {
+          "type": "string"
+        },
+        "styling": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["tailwind", "css-modules", "styled-components", "scss"]
+          }
+        },
+        "tailwindVersion": {
+          "type": "string"
+        },
+        "typescript": {
+          "type": "boolean"
+        },
+        "typescriptStrict": {
+          "type": "boolean"
+        },
+        "monorepo": {
+          "type": "boolean"
+        },
+        "monorepoTool": {
+          "type": "string",
+          "enum": ["turborepo", "nx", "lerna", "pnpm-workspaces"]
+        },
+        "figma": {
+          "type": "object",
+          "required": ["detected", "figmaMcp", "figmaCodeCli", "designTokens", "tokenFormat", "visualTests"],
+          "properties": {
+            "detected": { "type": "boolean" },
+            "figmaMcp": { "type": "boolean" },
+            "figmaCodeCli": { "type": "boolean" },
+            "designTokens": { "type": "boolean" },
+            "tokenFormat": {
+              "type": "string",
+              "enum": ["tailwind-v4", "tailwind-v3", "css-variables", "none"]
+            },
+            "visualTests": { "type": "boolean" }
+          }
+        },
+        "designTokens": {
+          "type": "object",
+          "required": ["detected", "colors", "spacing", "fonts", "breakpoints", "source"],
+          "properties": {
+            "detected": { "type": "boolean" },
+            "colors": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "spacing": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "fonts": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "breakpoints": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "source": {
+              "type": "string",
+              "enum": ["tailwind-config", "css-variables", "theme-inline", "none"]
+            }
+          }
+        },
+        "staticSite": {
+          "type": "object",
+          "required": ["isStatic", "hasGenerateStaticParams", "hasRevalidate", "hasStaticExport"],
+          "properties": {
+            "isStatic": { "type": "boolean" },
+            "outputMode": {
+              "type": "string",
+              "enum": ["export", "isr", "ssr", "hybrid"]
+            },
+            "hasGenerateStaticParams": { "type": "boolean" },
+            "hasRevalidate": { "type": "boolean" },
+            "hasStaticExport": { "type": "boolean" }
+          }
+        },
+        "aiIgnorePatterns": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "tools": {
+          "type": "object",
+          "required": [
+            "playwright",
+            "storybook",
+            "eslint",
+            "prettier",
+            "biome",
+            "axeCore",
+            "snyk",
+            "knip",
+            "bundleAnalyzer"
+          ],
+          "properties": {
+            "playwright": { "type": "boolean" },
+            "storybook": { "type": "boolean" },
+            "eslint": { "type": "boolean" },
+            "prettier": { "type": "boolean" },
+            "biome": { "type": "boolean" },
+            "axeCore": { "type": "boolean" },
+            "snyk": { "type": "boolean" },
+            "knip": { "type": "boolean" },
+            "bundleAnalyzer": { "type": "boolean" }
+          }
+        },
+        "mcpServers": {
+          "type": "object",
+          "required": ["playwright", "figma", "github", "context7", "perplexity"],
+          "properties": {
+            "playwright": { "type": "boolean" },
+            "figma": { "type": "boolean" },
+            "github": { "type": "boolean" },
+            "context7": { "type": "boolean" },
+            "perplexity": { "type": "boolean" }
+          }
+        },
+        "packageManager": {
+          "type": "string",
+          "enum": ["npm", "pnpm", "yarn", "bun"]
+        },
+        "projectName": {
+          "type": "string"
+        },
+        "projectPath": {
+          "type": "string"
+        },
+        "scripts": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/commands/clarify-requirements.md

@@ -0,0 +1,87 @@
+# Quick Requirements Clarification
+
+> **Role**: You are a senior developer who catches ambiguity before it becomes rework.
+> **Goal**: Quickly identify gaps, ambiguities, and assumptions in a task description, then produce a clear, actionable brief — in under 5 minutes.
+
+## Mandatory Steps
+
+You MUST follow these steps in order. Do not skip any step.
+
+1. **Get the Task** — If no task is specified in `$ARGUMENTS`, ask: "What's the task? Paste the ticket, message, or describe what you need to do." Do not proceed without input.
+2. **Read and Analyze** — Read the task description carefully. Identify what's clear and what's ambiguous.
+3. **Ask Targeted Questions** — Ask only the questions that matter for THIS task. Do not ask generic questions. Maximum 5 questions.
+4. **Summarize and Confirm** — Present a clear brief and ask for confirmation.
+
+## Analysis Framework
+
+For the given task, quickly assess:
+
+| Dimension | Question to ask yourself |
+|-----------|------------------------|
+| **What** | Is the expected behavior specific enough to implement? |
+| **Where** | Are the files/components/routes clearly identified? |
+| **Who** | Is it clear who the users are and what they see? |
+| **When** | Are trigger conditions and timing specified? |
+| **Edge cases** | What happens with empty, error, or boundary states? |
+| **Scope** | Is it clear what's NOT included? |
+
+Only ask the developer about dimensions that are genuinely ambiguous. If something is clear, don't ask about it.
+
+## Question Guidelines
+
+- Ask a **maximum of 5 questions** — pick the highest-impact gaps only
+- Make questions **multiple choice** when possible (faster to answer)
+- Provide your **best guess** with each question so the developer can just confirm
+- Group related questions together
+
+Example:
+> I have 3 quick questions before I start:
+> 1. Should the error message appear as a toast or inline below the field? (I'm guessing inline based on the existing pattern in `LoginForm.tsx`)
+> 2. Does "update the list" mean optimistic update or wait for server response?
+> 3. Should this work for admin users too, or just regular users?
+
+## Output Format
+
+After clarification, produce:
+
+```
+## Task Brief: [Title]
+
+### What
+[1-2 sentences: exactly what to build/fix/change]
+
+### Acceptance Criteria
+- [ ] [Specific, testable criterion]
+- [ ] [Specific, testable criterion]
+- [ ] [Specific, testable criterion]
+
+### Scope
+- Files to touch: [list]
+- Out of scope: [what NOT to do]
+
+### Edge Cases to Handle
+- [Case 1]: [behavior]
+- [Case 2]: [behavior]
+```
+
+Then say: **"Ready to start, or anything to adjust?"**
+
+## Self-Check
+
+Before presenting the brief, verify:
+- [ ] You asked no more than 5 questions
+- [ ] Every acceptance criterion is testable (pass/fail, not subjective)
+- [ ] Files to touch are identified with actual paths
+- [ ] At least one edge case is covered
+- [ ] The brief is short enough to read in 30 seconds
+
+## Constraints
+
+- Do NOT ask more than 5 questions — prioritize ruthlessly
+- Do NOT turn this into a long interview — that's what `/deep-interview` is for
+- Do NOT ask obvious questions that the task description already answers
+- Do NOT write code — this command is for clarification only
+- Keep the total interaction under 5 minutes
+- If the task is already clear, say so and produce the brief immediately
+
+Target: $ARGUMENTS

package/commands/deep-interview.md

@@ -0,0 +1,129 @@
+# Deep Interview — Requirements Gathering
+
+> **Role**: You are a senior technical product manager and requirements analyst who uses Socratic questioning to extract precise, complete requirements from vague or incomplete requests.
+> **Goal**: Guide the developer through a structured interview that transforms a vague idea into a detailed, actionable specification — before any code is written.
+
+## Mandatory Steps
+
+You MUST follow these steps in order. Do not skip any step.
+
+1. **Get the Initial Request** — If no topic is specified in `$ARGUMENTS`, ask: "What are you trying to build or solve? Give me the rough idea, even if it's vague." Do not proceed without an initial input.
+2. **Clarify the Problem** — Ask the problem-space questions below. Do not move to solutions until the problem is fully understood.
+3. **Define the Scope** — Ask scope questions to establish boundaries.
+4. **Identify Users & Stakeholders** — Understand who this is for and who cares.
+5. **Explore Edge Cases** — Systematically surface non-obvious scenarios.
+6. **Validate Assumptions** — Repeat back your understanding and ask: "What did I get wrong?"
+7. **Generate the Specification** — Produce the output document.
+
+## Problem-Space Questions
+
+Ask these one at a time. Wait for answers before proceeding. Adapt follow-ups based on responses.
+
+### Understanding the Problem
+1. What problem are you solving? (Not what you want to build — what pain exists today?)
+2. Who experiences this problem? How often?
+3. What happens if we don't solve this? What's the cost of inaction?
+4. Has this been attempted before? What happened?
+5. What does success look like? How will you measure it?
+
+### Understanding the Context
+6. What existing systems or code does this interact with?
+7. Are there hard constraints? (deadline, budget, tech stack, regulatory)
+8. What's the simplest version that would be valuable? (MVP scope)
+9. What's explicitly out of scope for now?
+10. Are there similar features in the codebase we should be consistent with?
+
+### Understanding the Users
+11. Who are the primary users? What's their technical level?
+12. What's the user's workflow before and after this feature?
+13. Are there different user roles with different needs?
+14. What's the expected scale? (users, data volume, request frequency)
+
+## Edge Case Exploration
+
+After the main questions, systematically probe:
+
+- **Empty states** — What happens when there's no data?
+- **Error states** — What happens when things go wrong? (network, validation, permissions)
+- **Boundary conditions** — Maximum values, minimum values, concurrent access
+- **Accessibility** — Keyboard navigation, screen readers, color contrast
+- **Performance** — What happens under load? What's acceptable latency?
+- **Security** — Authentication, authorization, data exposure risks
+- **Internationalization** — Multiple languages, timezones, number formats
+
+## Output Format
+
+After the interview, generate this specification document:
+
+```
+## Feature Specification: [Title]
+
+### Problem Statement
+[2-3 sentences describing the problem, not the solution]
+
+### Success Criteria
+- [ ] [Measurable criterion 1]
+- [ ] [Measurable criterion 2]
+- [ ] [Measurable criterion 3]
+
+### User Stories
+- As a [role], I want to [action] so that [benefit]
+- As a [role], I want to [action] so that [benefit]
+
+### Scope
+**In scope:**
+- [Feature/behavior 1]
+- [Feature/behavior 2]
+
+**Out of scope:**
+- [Explicitly excluded item 1]
+- [Explicitly excluded item 2]
+
+### Requirements
+#### Functional
+1. [Specific, testable requirement]
+2. [Specific, testable requirement]
+
+#### Non-Functional
+- Performance: [specific targets]
+- Accessibility: [specific standards]
+- Security: [specific requirements]
+
+### Edge Cases
+| Scenario | Expected Behavior |
+|----------|-------------------|
+| [Edge case 1] | [What should happen] |
+| [Edge case 2] | [What should happen] |
+
+### Technical Considerations
+- [Integration points, dependencies, constraints]
+- [Patterns to follow from existing codebase]
+
+### Open Questions
+- [Anything still unresolved after the interview]
+```
+
+Then ask: **"Should I save this to `docs/specs/[feature-name].md`, or would you like to refine it first?"**
+
+## Self-Check
+
+Before generating the specification, verify:
+- [ ] You understood the problem before jumping to solutions
+- [ ] You asked about users, not just technology
+- [ ] You explored at least 3 edge cases
+- [ ] Every requirement is specific and testable (not "should be fast" but "response under 200ms")
+- [ ] Scope boundaries are explicit — what's in AND what's out
+- [ ] You validated your understanding with the developer
+- [ ] Open questions are captured, not silently assumed
+
+## Constraints
+
+- Do NOT suggest solutions during the interview — focus on understanding the problem first
+- Do NOT skip edge case exploration — this is where the most valuable requirements hide
+- Do NOT accept "it should just work" — push for specific, testable criteria
+- Do NOT assume technical decisions — ask about constraints, don't infer them
+- Ask one question at a time — do not overwhelm with a wall of questions
+- Adapt your questions based on answers — this is a conversation, not a form
+- If the developer says "I don't know", help them think through it — don't just move on
+
+Target: $ARGUMENTS