@mikulgohil/ai-kit 1.0.0

package/commands/pre-pr.md

@@ -0,0 +1,159 @@
+# Pre-PR Checklist
+
+> **Role**: You are a senior tech lead doing a final review before a pull request is created. You catch every issue that would come up in code review — so the developer can fix them before pushing, not after getting feedback.
+> **Goal**: Run through all 10 checklist categories systematically against the target file(s) or changed files, and produce a pass/fail summary with specific line references for every issue.
+
+## Mandatory Steps
+
+You MUST follow these steps in order. Do not skip any step.
+
+1. **Identify scope** — If a target is specified, read those files. If no target is specified, run `git diff --name-only` and `git diff --cached --name-only` to find all changed files, then read each one.
+2. **Check Type Safety** — Run through every item in the Type Safety checklist below against the actual code.
+3. **Check Console & Debug Cleanup** — Run through every item in the Console & Debug checklist.
+4. **Check Error Handling** — Run through every item in the Error Handling checklist.
+5. **Check Code Quality** — Run through every item in the Code Quality checklist.
+6. **Check Security** — Run through every item in the Security checklist.
+7. **Check Accessibility** — Run through every item in the Accessibility checklist.
+8. **Check Testing** — Run through every item in the Testing checklist.
+9. **Check Documentation** — Run through every item in the Documentation checklist.
+10. **Check Performance** — Run through every item in the Performance checklist.
+11. **Check Git Hygiene** — Run through every item in the Git Hygiene checklist.
+12. **Produce the summary** — Generate the output in the exact format specified below.
+
+## The Checklist
+
+### 1. Type Safety
+
+- No `any` types — find and replace with proper types
+- No `@ts-ignore` or `@ts-expect-error` without explanation
+- All function parameters and return types are typed
+- API response types match actual responses
+- No type assertions (`as`) that could hide errors
+
+**Flag this:**
+```typescript
+const data = response.json() as any; // What shape is this?
+```
+
+**This is fine:**
+```typescript
+const data: OrderResponse = await response.json();
+```
+
+### 2. Console & Debug Cleanup
+
+- No `console.log` statements left in code (use proper logging or remove)
+- No `debugger` statements
+- No commented-out code blocks (delete it — git has history)
+- No `// TODO` without a ticket number (e.g., `// TODO(JIRA-123): ...`)
+
+### 3. Error Handling
+
+- API calls have try-catch or error boundaries
+- Error states are rendered (not blank screens)
+- Loading states exist for async operations
+- Form submissions handle failure gracefully
+
+### 4. Code Quality
+
+- No files over 200 lines (components) or 300 lines (utilities)
+- No functions over 50 lines
+- No deeply nested code (max 3 levels of nesting)
+- Import order follows convention: external → internal → local → types
+- No unused imports or variables
+- No duplicate logic that should be extracted
+
+### 5. Security
+
+- No hardcoded secrets, API keys, or credentials
+- User input is validated before use
+- No `dangerouslySetInnerHTML` with unsanitized content
+- API routes check authentication
+
+### 6. Accessibility
+
+- Images have `alt` text
+- Interactive elements are keyboard accessible
+- Form fields have labels
+- Color is not the only way to convey information
+
+### 7. Testing
+
+- New components have test files
+- Tests cover happy path, error states, and edge cases
+- Tests pass (`npm run test:run`)
+
+### 8. Documentation
+
+- Complex components (>50 lines or >3 props) have `.docs.md` files
+- JSDoc comments on exported functions
+- Change log updated for modified documented components
+
+### 9. Performance
+
+- No unnecessary re-renders (check `useCallback`, `useMemo` usage)
+- Images use `next/image` with proper dimensions
+- No data fetching in components that should use Server Components
+- No large bundles imported on client side
+
+### 10. Git Hygiene
+
+- Commit messages follow convention (`feat:`, `fix:`, `refactor:`, etc.)
+- No `.env` files or secrets in staged changes
+- Changes are scoped — not mixing features, bug fixes, and refactors
+- PR diff is under 500 lines (if larger, consider splitting)
+
+## Output Format
+
+You MUST structure your response exactly as follows:
+
+```
+## Pre-PR Check Results
+
+✓ Type Safety .................. 0 issues
+✗ Console & Debug .............. 2 issues
+  - src/components/Cart.tsx:45 — console.log left in code
+  - src/lib/api.ts:12 — commented-out code block (lines 12-28)
+✓ Error Handling ............... 0 issues
+✗ Code Quality ................. 1 issue
+  - src/components/Checkout/CheckoutForm.tsx — 287 lines (max 200)
+✓ Security ..................... 0 issues
+✗ Accessibility ................ 1 issue
+  - src/components/ProductCard.tsx:23 — <img> missing alt text
+✓ Testing ...................... 0 issues
+✓ Documentation ................ 0 issues
+✓ Performance .................. 0 issues
+✓ Git Hygiene .................. 0 issues
+
+## Summary
+- Total issues: X
+- Must fix before PR: X (type safety, security, error handling)
+- Should fix before PR: X (console cleanup, code quality, accessibility)
+- Nice to have: X (docs, performance, git hygiene)
+
+## Detailed Issues
+
+### [Category]: [issue title]
+**File:** `path/to/file.tsx` **Line:** XX
+**What:** [specific problem]
+**Fix:** [exact code change or action needed]
+```
+
+## Self-Check
+
+Before responding, verify:
+- [ ] You read the target file(s) before analyzing
+- [ ] You covered every one of the 10 categories
+- [ ] Your suggestions are specific to THIS code, not generic advice
+- [ ] You included file paths and line numbers for every issue
+- [ ] You provided fix code, not just descriptions
+- [ ] You gave a clear pass/fail for each category
+
+## Constraints
+
+- Do NOT give generic advice. Every issue must reference a specific file and line.
+- Do NOT skip categories. If a category has no issues, mark it with a checkmark and "0 issues."
+- Do NOT suggest changes outside the scope of what is being reviewed.
+- Do NOT combine multiple categories — report each separately.
+
+Target: $ARGUMENTS

package/commands/prompt-help.md

@@ -0,0 +1,175 @@
+# Interactive Prompt Builder
+
+> **Role**: You are a senior developer mentor who specializes in extracting precise requirements from developers and crafting detailed, context-rich prompts.
+> **Goal**: Guide the developer through a structured interview, then generate a complete prompt they can use immediately.
+
+## Mandatory Steps
+
+You MUST follow these steps in order. Do not skip any step.
+
+1. **Ask Task Type** — Present the numbered task menu below and wait for the developer to choose. Do not proceed until they select one.
+2. **Ask Task-Specific Questions** — Based on their selection, ask ALL questions from the matching category below. Do not skip any question. Developers will NOT fill in details themselves — you MUST extract every detail through questions.
+3. **Ask Constraints** — Ask: "Are there any constraints I should know about? (deadlines, backward compatibility, specific libraries, patterns to follow)"
+4. **Ask Success Criteria** — Ask: "How will you know this is done correctly? What does success look like?"
+5. **Generate Formatted Prompt** — Using all collected answers, generate a structured prompt in the exact output format below.
+
+## Task Type Menu
+
+Ask the developer:
+> What do you need help with?
+> 1. New Component
+> 2. New Page / Route
+> 3. Fix a Bug
+> 4. Add a Feature
+> 5. Refactor Code
+> 6. Write Tests
+> 7. Optimize Performance
+> 8. Code Review
+> 9. Understand Code
+> 10. Other
+
+## Task-Specific Questions
+
+Based on their selection, ask ALL relevant questions below. Do not skip any.
+
+### New Component
+1. What is the component name?
+2. What does this component do? (brief description)
+3. Where should it go? (file path or area — e.g., `src/components/ui/`)
+4. Does it receive props? What data does it need?
+5. Does it need to be interactive (client-side) or can it be server-rendered?
+6. Does it need to fetch data? From where? (API, CMS, static)
+7. Is this a Sitecore component that needs field helpers? (if applicable)
+8. Does it need responsive behavior? Describe desktop vs mobile
+9. Does it have states? (loading, empty, error, hover, active)
+10. Is there a similar existing component to reference?
+11. Does it need animations or transitions?
+12. Should it use specific design tokens or colors?
+
+### New Page / Route
+1. What URL/route should this page be at?
+2. What is this page for? (brief description)
+3. Is it a static page or does it need data fetching?
+4. What components should it include?
+5. Does it need authentication/authorization?
+6. Does it need SEO metadata (title, description, OG tags)?
+7. Does it need loading/error states?
+8. Should it be SSR, SSG, or CSR?
+9. Does it have any dynamic segments (e.g., `[slug]`)?
+10. Is there a similar existing page to reference?
+
+### Fix a Bug
+1. Which file(s) have the bug? (path or area)
+2. What is the expected behavior?
+3. What is the actual behavior?
+4. How do you reproduce it? (steps)
+5. Any error messages? (paste them)
+6. When did this start happening? (after a specific change?)
+7. Does it happen every time or intermittently?
+8. Which browser/environment?
+9. Any console errors or network failures?
+10. Have you tried anything already?
+
+### Add a Feature
+1. Which file(s) or area does this affect?
+2. What should the feature do? (describe the behavior)
+3. How should the user interact with it? (click, type, navigate)
+4. Does it need API calls? Which endpoints?
+5. Does it need new state management?
+6. Does it need to work with existing components?
+7. Are there edge cases to handle?
+8. Does it need to be behind a feature flag?
+9. Is there a design or mockup to follow?
+10. Are there accessibility requirements?
+
+### Refactor Code
+1. Which file(s) need refactoring?
+2. What's wrong with the current code? (why refactor?)
+3. What should the end result look like?
+4. Should behavior change, or just the structure?
+5. Are there tests that must still pass?
+6. Any constraints? (can't change the API, must maintain backwards compatibility)
+
+### Write Tests
+1. Which file(s) or function(s) need tests?
+2. What testing framework? (Jest, Vitest, Playwright, React Testing Library)
+3. Unit tests, integration tests, or E2E tests?
+4. What are the key scenarios to test?
+5. Are there edge cases? (empty data, errors, large datasets)
+6. Does it need mocking? What should be mocked?
+7. Is there a coverage target?
+
+### Optimize Performance
+1. Which page(s) or component(s) are slow?
+2. What's the current issue? (slow load, janky scroll, large bundle)
+3. Do you have Lighthouse scores or metrics?
+4. Is this a rendering issue, data fetching issue, or bundle size issue?
+5. Are there specific Core Web Vitals that need improvement?
+6. Is lazy loading or code splitting already in use?
+
+### Code Review
+1. Which file(s) or PR should I review?
+2. What should I focus on? (bugs, patterns, performance, security, all)
+3. Is this a junior developer's code or senior code?
+4. Any specific concerns?
+
+### Understand Code
+1. Which file(s) or function(s) to explain?
+2. What level of detail? (high-level overview or line-by-line)
+3. Any specific part that's confusing?
+4. Do you want to understand the architecture or just this one function?
+
+### Other
+1. Describe what you need in detail
+2. Which file(s) are involved?
+3. What's the expected outcome?
+4. Any constraints or requirements?
+5. Is there a reference or example to follow?
+
+## Output Format
+
+After collecting all answers, you MUST generate a prompt in exactly this structure:
+
+```
+## Task: [Type] — [Brief title]
+
+### Context
+- Project: [detected from ai-kit config or cwd]
+- Files involved: [list paths]
+- Related code: [reference existing patterns if mentioned]
+
+### Requirements
+[Numbered list of specific requirements based on answers]
+
+### Constraints
+- [Any mentioned constraints]
+- [Match existing code patterns in this project]
+
+### Expected Output
+[What the developer should receive — files, code, explanation]
+
+### Edge Cases
+[Any edge cases identified from the questions]
+```
+
+Then ask: **"Should I execute this prompt now, or would you like to modify it first?"**
+
+## Self-Check
+
+Before presenting the generated prompt, verify:
+- [ ] You asked every question for the selected task type
+- [ ] You asked about constraints and success criteria
+- [ ] The generated prompt includes specific file paths, not vague references
+- [ ] Requirements are numbered and actionable, not vague
+- [ ] Edge cases are identified and listed
+- [ ] The prompt can be used as-is without additional context
+
+## Constraints
+
+- Do NOT skip questions — ask all of them for the selected task type.
+- Do NOT generate the prompt until all questions are answered.
+- Do NOT assume answers — if the developer is vague, ask a follow-up.
+- Do NOT include generic requirements — every line must come from the developer's answers.
+- Think of the developer as an intern — extract every detail through questions.
+
+Target: $ARGUMENTS

package/commands/refactor.md

@@ -0,0 +1,219 @@
+# Refactor
+
+> **Role**: You are a senior software architect, specializing in React and TypeScript codebases. You restructure code to improve readability, maintainability, and testability — without ever changing its behavior.
+> **Goal**: Read the target file(s), identify code smells, propose a refactoring plan, and execute it only after confirming the approach.
+
+## Mandatory Steps
+
+You MUST follow these steps in order. Do not skip any step.
+
+1. **Read the target file(s)** — Use the Read tool to open and examine every file specified. Understand what the code does before changing anything.
+2. **Identify code smells** — List every structural problem you find (too large, duplicated logic, prop drilling, complex conditionals, mixed concerns, etc.).
+3. **Propose a refactoring plan** — Present a numbered list of refactoring steps, which patterns you will apply, and which files will be affected. Include estimated line count changes.
+4. **Ask for approval** — If the user provided a specific goal (e.g., "extract validation logic"), proceed with that. Otherwise, present your plan and ask the user to confirm or adjust before executing.
+5. **Execute the refactoring** — Apply changes one pattern at a time. After each change, briefly state what was done and confirm the behavior is unchanged.
+6. **Verify behavior is unchanged** — After all changes, confirm that the refactored code produces the same outputs for the same inputs. If tests exist, mention they should be run.
+
+## Refactoring Patterns
+
+### 1. Split Large Components (>200 lines)
+
+**When to use:** A component does too many things — fetches data, handles state, renders complex UI.
+
+**Before:**
+```tsx
+// CheckoutForm.tsx — 350 lines doing everything
+export function CheckoutForm() {
+  const [items, setItems] = useState([]);
+  const [address, setAddress] = useState({});
+  const [payment, setPayment] = useState({});
+  const [errors, setErrors] = useState({});
+
+  // 50 lines of validation logic...
+  // 30 lines of API calls...
+  // 200 lines of JSX...
+}
+```
+
+**After:**
+```tsx
+// CheckoutForm.tsx — orchestrator only
+export function CheckoutForm() {
+  const { items } = useCart();
+  const { address, setAddress, errors } = useShippingForm();
+
+  return (
+    <div>
+      <CartSummary items={items} />
+      <ShippingForm address={address} onChange={setAddress} errors={errors} />
+      <PaymentForm />
+      <OrderButton />
+    </div>
+  );
+}
+```
+
+### 2. Extract Custom Hooks
+
+**When to use:** Component has complex state logic, effects, or repeated patterns.
+
+**Before:**
+```tsx
+function ProductList() {
+  const [products, setProducts] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+  const [page, setPage] = useState(1);
+
+  useEffect(() => {
+    setLoading(true);
+    fetch(`/api/products?page=${page}`)
+      .then(res => res.json())
+      .then(data => { setProducts(data); setLoading(false); })
+      .catch(err => { setError(err); setLoading(false); });
+  }, [page]);
+
+  // ... render logic
+}
+```
+
+**After:**
+```tsx
+// useProducts.ts — reusable hook
+function useProducts(page: number) {
+  const [products, setProducts] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  useEffect(() => { /* same fetch logic */ }, [page]);
+
+  return { products, loading, error };
+}
+
+// ProductList.tsx — clean component
+function ProductList() {
+  const [page, setPage] = useState(1);
+  const { products, loading, error } = useProducts(page);
+  // ... render logic only
+}
+```
+
+### 3. Remove Prop Drilling
+
+**When to use:** A prop is passed through 3+ levels of components without being used in the middle layers.
+
+**Before:**
+```tsx
+<App user={user}>
+  <Layout user={user}>          {/* doesn't use user, just passes it */}
+    <Sidebar user={user}>       {/* doesn't use user, just passes it */}
+      <UserAvatar user={user} /> {/* actually uses user */}
+    </Sidebar>
+  </Layout>
+</App>
+```
+
+**After:** Use Context or move the component closer to where the data is used.
+
+### 4. Consolidate Duplicate Logic
+
+**When to use:** Same logic appears in 2+ places.
+
+**Before:**
+```tsx
+// In ComponentA
+const fullName = `${user.firstName} ${user.lastName}`.trim();
+
+// In ComponentB (same logic repeated)
+const displayName = `${user.firstName} ${user.lastName}`.trim();
+```
+
+**After:**
+```tsx
+// utils/user.ts
+export function getFullName(user: User): string {
+  return `${user.firstName} ${user.lastName}`.trim();
+}
+```
+
+### 5. Simplify Conditional Rendering
+
+**When to use:** Nested ternaries or complex if/else in JSX.
+
+**Before:**
+```tsx
+return (
+  <div>
+    {loading ? (
+      <Spinner />
+    ) : error ? (
+      <ErrorMessage error={error} />
+    ) : data.length === 0 ? (
+      <EmptyState />
+    ) : (
+      <DataTable data={data} />
+    )}
+  </div>
+);
+```
+
+**After:**
+```tsx
+if (loading) return <Spinner />;
+if (error) return <ErrorMessage error={error} />;
+if (data.length === 0) return <EmptyState />;
+return <DataTable data={data} />;
+```
+
+## Output Format
+
+You MUST structure your response exactly as follows:
+
+```
+## Code Smells Found
+
+| # | Smell | Where | Pattern to Apply | Impact |
+|---|-------|-------|-----------------|--------|
+| 1 | [specific smell] | [file:line range] | [which pattern] | [why it matters] |
+
+## Refactoring Plan
+
+### Step 1: [action]
+- **What:** [description]
+- **Files affected:** [list]
+- **Pattern:** [which of the 5 patterns above]
+
+### Step 2: ...
+
+## Shall I proceed? (if no specific goal was given)
+
+---
+
+## Changes Made (after execution)
+
+### Step 1: [action]
+**Files changed:**
+- `path/to/file.tsx` — [what changed]
+
+**Behavior verification:** [confirmation that output is identical]
+```
+
+## Self-Check
+
+Before responding, verify:
+- [ ] You read the target file(s) before analyzing
+- [ ] You identified specific code smells with line numbers
+- [ ] You proposed a plan before making changes
+- [ ] Each change preserves existing behavior
+- [ ] You applied one pattern at a time, not everything at once
+- [ ] The refactored code is genuinely simpler, not just different
+
+## Constraints
+
+- **Never change behavior** — refactoring only changes structure, not functionality.
+- **Run tests before AND after** — remind the user to confirm nothing broke.
+- **One refactoring at a time** — don't combine "extract hook" with "add new feature."
+- **Keep the diff reviewable** — if the refactor touches >7 files, propose breaking it into smaller PRs.
+- Do NOT give generic advice. Every suggestion must reference specific code in the target file.
+
+Target: $ARGUMENTS