@mikulgohil/ai-kit 1.3.2 → 1.4.0

package/commands/release-notes.md

@@ -0,0 +1,212 @@
+# Release Notes Generator
+
+> **Role**: You are a release manager who writes clear, stakeholder-friendly release notes. You translate developer commit messages into language that product managers, QA engineers, and end users can understand — while preserving technical accuracy for the engineering team.
+> **Goal**: Read the git history since the last release tag, categorize all changes, identify affected components and breaking changes, and generate formatted release notes with a migration guide when needed.
+
+## Mandatory Steps
+
+You MUST follow these steps in order. Do not skip any step.
+
+1. **Find the Last Release Tag** — Run `git tag --sort=-version:refname --list 'v*'` to find the most recent version tag. If `$ARGUMENTS` specifies a tag or range (e.g., `v1.2.0..v1.3.0`), use that range instead.
+2. **Get the Commit Log** — Run `git log [last-tag]..HEAD --oneline --no-merges` for a summary. Run `git log [last-tag]..HEAD --format="%H|%an|%s" --no-merges` for structured data with hashes and authors.
+3. **Get Changed Files** — Run `git diff [last-tag]..HEAD --stat` for an overview, and `git diff [last-tag]..HEAD --name-status` for added/modified/deleted classification.
+4. **Read Key Changes** — For any commit that appears to be a feature or breaking change, read the actual diff: `git show [commit-hash] --stat` and examine the changed files if needed for context.
+5. **Categorize Commits** — Group commits into:
+   - **Features** (`feat:`): New capabilities visible to users
+   - **Bug Fixes** (`fix:`): Corrected behavior
+   - **Performance** (`perf:`): Speed or resource improvements
+   - **Breaking Changes** (`!` suffix, `BREAKING CHANGE:` footer, or major API changes)
+   - **Deprecations**: Features marked for future removal
+   - **Internal** (`refactor:`, `chore:`, `test:`, `ci:`): Not user-facing but worth noting
+6. **Map Component Impact** — Identify which components, pages, or modules were affected by the changes. Group related commits by the component they modified.
+7. **Detect Breaking Changes** — Specifically look for:
+   - Removed or renamed exports
+   - Changed function signatures (added required params, changed return types)
+   - Removed or renamed component props
+   - Changed environment variables
+   - Changed API request/response shapes
+   - Database migration requirements
+8. **Write Migration Guide** — If breaking changes exist, write step-by-step migration instructions with before/after code examples.
+9. **Determine Version** — Based on the changes, recommend a semantic version: major (breaking), minor (features), or patch (fixes only).
+10. **Produce the Release Notes** — Generate the output in the exact format specified below.
+
+## Analysis Checklist
+
+### Commit Parsing
+- Conventional commit prefix detection (feat, fix, refactor, perf, chore, docs, test, ci)
+- Breaking change indicators (! suffix, BREAKING CHANGE footer, removed exports)
+- Scope extraction from `type(scope): message`
+- Non-conventional commits — infer type from diff content
+- Co-author attribution from `Co-authored-by:` trailers
+
+### User-Facing Translation
+- Technical commit → user-friendly description
+- "feat(cart): add quantity stepper" → "You can now adjust item quantities directly in the cart"
+- "fix(auth): handle expired token refresh" → "Fixed an issue where users were unexpectedly logged out"
+- "perf(images): add lazy loading" → "Improved page load speed by loading images on demand"
+
+### Impact Assessment
+- Which user-facing features are affected?
+- Which pages or routes have changed behavior?
+- Are there visual changes that need screenshots?
+- Are there configuration changes that ops/DevOps needs to know about?
+
+## Output Format
+
+You MUST structure your response exactly as follows:
+
+```
+## Release Notes — v[X.Y.Z]
+
+**Release Date**: [YYYY-MM-DD]
+**Previous Version**: v[previous]
+**Version Bump**: [major | minor | patch]
+**Total Changes**: X commits by Y contributors
+
+---
+
+## What's New
+
+### [Feature Name]
+[1-2 sentence user-friendly description of the feature]
+- **Component**: `[ComponentName]`
+- **Commits**: `abc1234`, `def5678`
+- **Author**: @developer
+
+### [Another Feature]
+[Description]
+- **Component**: `[ComponentName]`
+- **Commits**: `ghi9012`
+
+---
+
+## Bug Fixes
+
+- **[Component/Area]**: [User-friendly description of what was broken and how it's fixed]
+  - `fix(cart): handle zero quantity edge case` — `abc1234`
+- **[Component/Area]**: [Description]
+  - `fix(auth): refresh expired tokens silently` — `def5678`
+
+---
+
+## Performance Improvements
+
+- **[Component/Area]**: [What improved and expected impact]
+  - `perf(images): add lazy loading to product grid` — `ghi9012`
+
+---
+
+## Breaking Changes
+
+> **Action Required**: The following changes require updates to your code.
+
+### 1. [Breaking Change Title]
+**What changed**: [Clear description of the old behavior vs new behavior]
+**Why**: [Reason for the change]
+**Affected files**: [List of files consumers need to update]
+
+**Before**:
+```tsx
+// Old usage
+<Button type="primary" onClick={handleClick}>Submit</Button>
+```
+
+**After**:
+```tsx
+// New usage — `type` renamed to `variant`
+<Button variant="primary" onClick={handleClick}>Submit</Button>
+```
+
+### 2. [Another Breaking Change]
+[Same format as above]
+
+---
+
+## Component Changes
+
+| Component | Type of Change | Summary |
+|-----------|---------------|---------|
+| Button | Breaking | `type` prop renamed to `variant` |
+| OrderForm | Feature | Added address autocomplete |
+| Cart | Bug fix | Quantity calculation corrected |
+| ProductGrid | Performance | Lazy loading added |
+| AuthProvider | Internal | Token refresh logic refactored |
+
+---
+
+## Migration Guide
+
+> [Only include this section if there are breaking changes. Otherwise omit entirely.]
+
+### Step 1: Update Button `type` prop to `variant`
+
+Find all instances of `<Button type=` and replace with `<Button variant=`:
+
+```bash
+# Find affected files
+grep -r '<Button type=' src/
+
+# Each file: replace type= with variant=
+# Before
+<Button type="primary">Submit</Button>
+<Button type="secondary">Cancel</Button>
+
+# After
+<Button variant="primary">Submit</Button>
+<Button variant="secondary">Cancel</Button>
+```
+
+### Step 2: [Next migration step]
+[Instructions]
+
+---
+
+## Internal Changes
+
+> These changes don't affect end users but are noted for the engineering team.
+
+- **Refactoring**: [Description] — `abc1234`
+- **Testing**: [Description] — `def5678`
+- **CI/CD**: [Description] — `ghi9012`
+- **Dependencies**: [Updated packages and versions]
+
+---
+
+## Contributors
+
+- @developer-1 (X commits)
+- @developer-2 (Y commits)
+
+---
+
+## Full Commit Log
+
+| Hash | Type | Scope | Message | Author |
+|------|------|-------|---------|--------|
+| abc1234 | feat | cart | Add quantity stepper | @dev-1 |
+| def5678 | fix | auth | Handle expired token | @dev-2 |
+```
+
+## Self-Check
+
+Before responding, verify:
+- [ ] You identified the correct last release tag
+- [ ] You read ALL commits since the last tag (none left out)
+- [ ] Every commit is categorized (features, fixes, breaking, internal)
+- [ ] Breaking changes include before/after code examples
+- [ ] Migration guide has step-by-step instructions (if breaking changes exist)
+- [ ] Descriptions are user-friendly, not raw commit messages
+- [ ] Component changes table maps every change to its component
+- [ ] Version bump recommendation matches the changes (major if breaking, minor if features, patch if fixes only)
+
+## Constraints
+
+- Do NOT use raw commit messages as release notes — translate them into user-friendly language.
+- Do NOT skip the migration guide if there are breaking changes — this is the most important section for consumers.
+- Do NOT inflate the version bump — only recommend major if there are actual breaking changes.
+- Do NOT include merge commits — use `--no-merges` in all git log commands.
+- Do NOT omit the full commit log table — it serves as an audit trail.
+- If there are no commits since the last tag, report "No changes since [last-tag]" and stop.
+- If there are no tags at all, use the initial commit as the baseline and note "First release — no previous version."
+
+Target: $ARGUMENTS

package/commands/scaffold-spec.md

@@ -0,0 +1,167 @@
+# Scaffold with Spec
+
+> **Role**: You are a senior engineer who scaffolds production-ready components from specifications. You don't just create empty files — you read the spec, understand the requirements, examine existing project patterns, and generate a complete component package with types, tests, stories, and documentation that matches the codebase conventions.
+> **Goal**: Read a specification (Jira ticket, Confluence page, or inline description from `$ARGUMENTS`), analyze existing component patterns in the project, and generate a complete component package including the component file, TypeScript types, test file, Storybook story, and an `.ai.md` documentation file.
+
+## Mandatory Steps
+
+You MUST follow these steps in order. Do not skip any step.
+
+1. **Read the Spec** — Parse `$ARGUMENTS` for the component specification. This may be:
+   - A Jira ticket number (fetch details via `gh` or Jira CLI)
+   - A Confluence page URL (fetch content)
+   - An inline description (e.g., "ProductCard with image, title, price, and add-to-cart button")
+   If the spec is unclear, ask for clarification before proceeding.
+2. **Extract Requirements** — From the spec, identify:
+   - Component name and purpose
+   - Required props and their types
+   - Visual states (default, hover, active, disabled, loading, error, empty)
+   - User interactions (clicks, form input, keyboard shortcuts)
+   - Data dependencies (API calls, context, props from parent)
+   - Responsive behavior (mobile, tablet, desktop)
+   - Accessibility requirements (ARIA labels, keyboard nav, screen reader text)
+3. **Study Existing Patterns** — Read 2-3 existing components in the project to learn:
+   - File naming convention (PascalCase? kebab-case? index.ts barrel?)
+   - Component structure (function declaration vs arrow function, export style)
+   - Props pattern (interface vs type, Props suffix, destructuring style)
+   - Test patterns (testing library, render helpers, common assertions)
+   - Story patterns (CSF format version, arg types, decorators)
+   - Documentation pattern (JSDoc, .docs.md, .ai.md)
+4. **Determine File Structure** — Based on project patterns, decide the file layout:
+   ```
+   src/components/[ComponentName]/
+   ├── [ComponentName].tsx        # Component implementation
+   ├── [ComponentName].types.ts   # Props and type definitions
+   ├── [ComponentName].test.tsx   # Unit tests
+   ├── [ComponentName].stories.tsx # Storybook stories
+   └── [ComponentName].ai.md     # AI context documentation
+   ```
+   Adjust to match the project's actual structure (e.g., flat files, index.ts barrels, co-located tests).
+5. **Generate the Component** — Write the component implementation with:
+   - Proper TypeScript types for all props
+   - All visual states implemented (or marked with TODO for complex states)
+   - Accessibility attributes (aria-label, role, tabIndex)
+   - Semantic HTML elements
+   - Proper use of Server vs Client Component based on requirements
+6. **Generate Types** — Create the types file with:
+   - Props interface with JSDoc comments on each prop
+   - Any enum or union types for prop options
+   - Any shared types used by the component
+7. **Generate Tests** — Create the test file covering:
+   - Renders without crashing (smoke test)
+   - Renders all required elements
+   - Each interactive behavior (click, submit, keyboard)
+   - Each visual state (loading, error, empty, disabled)
+   - Accessibility (role, aria attributes, keyboard navigation)
+8. **Generate Story** — Create the Storybook story with:
+   - Default story with realistic data
+   - One story per visual state (loading, error, empty, disabled)
+   - Interactive story demonstrating user interactions
+   - ArgTypes for all configurable props
+9. **Generate AI Documentation** — Create the `.ai.md` file with:
+   - Component purpose and when to use it
+   - Props reference table
+   - Usage examples
+   - Related components
+   - Decisions made during scaffolding
+10. **Produce the Summary** — List all generated files with explanations.
+
+## Analysis Checklist
+
+### Spec Interpretation
+- What is the component's primary responsibility?
+- What data does it need (props, context, API)?
+- What are all the visual states?
+- What user interactions does it support?
+- What are the edge cases (empty data, long text, many items)?
+
+### Pattern Matching
+- Does the project use CSS Modules, Tailwind, styled-components, or another styling approach?
+- Are components co-located with tests or are tests in a separate directory?
+- Does the project use barrel exports (index.ts)?
+- What test utilities does the project provide (custom render, mock providers)?
+- What Storybook version and CSF format does the project use?
+
+### Quality Gates
+- Does the component handle all states from the spec?
+- Are all props properly typed with JSDoc descriptions?
+- Do tests cover the happy path, error states, and edge cases?
+- Is the component accessible (keyboard nav, screen reader, ARIA)?
+- Does the code match the project's existing patterns exactly?
+
+## Output Format
+
+You MUST structure your response exactly as follows:
+
+```
+## Scaffold Summary
+
+**Component**: [ComponentName]
+**Source**: [Jira ticket / Confluence page / inline spec]
+**Pattern Reference**: [Existing component used as pattern source, e.g., "Based on Button.tsx structure"]
+
+## Generated Files
+
+### 1. `src/components/[ComponentName]/[ComponentName].tsx`
+**Purpose**: Main component implementation
+**Key decisions**:
+- [e.g., "Used Client Component because it handles click events"]
+- [e.g., "Used `forwardRef` to support parent ref access"]
+
+### 2. `src/components/[ComponentName]/[ComponentName].types.ts`
+**Purpose**: TypeScript type definitions
+**Props**:
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| title | string | Yes | Card heading text |
+| onAction | () => void | No | Click handler for primary action |
+
+### 3. `src/components/[ComponentName]/[ComponentName].test.tsx`
+**Purpose**: Unit tests
+**Coverage**:
+- [X] Smoke test (renders without crashing)
+- [X] Renders title and description
+- [X] Click handler fires on button click
+- [X] Disabled state prevents interaction
+- [X] Loading state shows skeleton
+- [X] Empty state displays fallback message
+- [X] Keyboard navigation (Enter/Space triggers action)
+
+### 4. `src/components/[ComponentName]/[ComponentName].stories.tsx`
+**Purpose**: Storybook stories for visual testing
+**Stories**: Default, Loading, Error, Empty, Disabled, WithLongContent
+
+### 5. `src/components/[ComponentName]/[ComponentName].ai.md`
+**Purpose**: AI context for future modifications
+
+## What to Do Next
+1. Review the generated files and adjust styling to match designs
+2. Replace placeholder data with real API integration
+3. Run `pnpm run test:run` to verify tests pass
+4. Run `pnpm run storybook` to verify stories render
+5. [Any spec-specific follow-up tasks]
+```
+
+## Self-Check
+
+Before responding, verify:
+- [ ] You read the spec thoroughly and extracted all requirements
+- [ ] You studied 2-3 existing components to match project patterns
+- [ ] The generated component handles all visual states from the spec
+- [ ] Props are properly typed with JSDoc comments
+- [ ] Tests cover rendering, interactions, states, and accessibility
+- [ ] Stories cover all visual variations
+- [ ] The file structure matches the project's existing convention
+- [ ] You used the project's actual styling approach (Tailwind, CSS Modules, etc.)
+
+## Constraints
+
+- Do NOT generate files in a structure that differs from the project's existing pattern — study existing components first.
+- Do NOT use placeholder prop types like `any` — derive proper types from the spec.
+- Do NOT generate empty test or story files — every generated file must have meaningful content.
+- Do NOT assume a styling approach — check the project for Tailwind, CSS Modules, styled-components, etc.
+- Do NOT create the component as a Server Component if it handles user interactions (clicks, form input).
+- If the spec is ambiguous, ask for clarification rather than guessing. List specific questions.
+- If the project has a component generator script or template, use it instead of manual scaffolding.
+
+Target: $ARGUMENTS

package/commands/standup.md

@@ -0,0 +1,131 @@
+# Morning Standup Summary
+
+> **Role**: You are a team lead preparing a concise standup update. You extract meaningful work summaries from git history, identify what components were touched, flag any work in progress, and surface blockers from TODO comments and uncommitted changes.
+> **Goal**: Generate a structured standup report covering yesterday's completed work, current in-progress items, and any blockers or TODOs found in the codebase.
+
+## Mandatory Steps
+
+You MUST follow these steps in order. Do not skip any step.
+
+1. **Determine Time Range** — If `$ARGUMENTS` specifies a date range (e.g., "since Monday", "last 3 days"), use that. Otherwise default to `--since="yesterday"` for daily standup.
+2. **Get Recent Commits** — Run `git log --since="yesterday" --oneline --no-merges --all` to get all recent commits. Also run `git log --since="yesterday" --format="%h %an %s" --no-merges` to include author info.
+3. **Identify Changed Components** — Run `git diff --name-only HEAD~$(git rev-list --count --since="yesterday" HEAD)..HEAD 2>/dev/null || git diff --name-only HEAD~5..HEAD` to get all files changed in the time range. Group by directory/component.
+4. **Check Uncommitted Work** — Run `git status --short` to find any staged or unstaged changes that represent work in progress.
+5. **Read Uncommitted Changes** — Run `git diff --stat` for unstaged changes and `git diff --cached --stat` for staged changes. Read modified files to understand what is being worked on.
+6. **Scan for Blockers** — Search for TODO, FIXME, HACK, and XXX comments in recently changed files. Run a targeted search:
+   - `git diff HEAD~5..HEAD -U0` and look for added lines containing TODO/FIXME
+   - Check for any failing test indicators in recent commits
+7. **Check Branch Context** — Run `git branch --show-current` and `git log --oneline -1` to identify the current feature/task context.
+8. **Produce the Standup Report** — Generate the output in the exact format specified below.
+
+## Analysis Checklist
+
+### Commit Analysis
+- Group commits by feature/scope (from conventional commit prefixes or branch names)
+- Identify whether work was feature development, bug fixing, refactoring, or maintenance
+- Note any reverts or fix-up commits (indicates struggles or issues)
+- Count commits per author if multiple contributors
+
+### Work Classification
+- **Completed**: Commits with clear completion signals (feat:, fix: that close an issue)
+- **In Progress**: Uncommitted changes, WIP commits, partial implementations
+- **Blocked**: TODO/FIXME comments added recently, failing tests, unresolved merge conflicts
+
+### Component Mapping
+- Map changed files to their component/module names
+- Identify cross-cutting changes (shared utils, types, configs)
+- Note if changes span multiple features (might indicate scope creep)
+
+## Output Format
+
+You MUST structure your response exactly as follows:
+
+```
+## Standup Summary — [YYYY-MM-DD]
+
+**Branch**: `feature/JIRA-123-order-page`
+**Period**: [Yesterday | Last 3 days | Since Monday]
+**Commits**: X commits by [author(s)]
+
+---
+
+## Yesterday (Completed Work)
+
+### [Feature/Scope from commit prefix]
+- [Human-readable summary of what was done — not raw commit message]
+- [Another completed item]
+  - Commits: `abc1234`, `def5678`
+  - Files: `OrderForm.tsx`, `useOrder.ts`, `orders.api.ts`
+
+### [Bug Fixes]
+- Fixed [description of bug fix]
+  - Commits: `ghi9012`
+  - Files: `Cart.tsx`
+
+### [Maintenance/Refactoring]
+- [Description of refactoring or chore work]
+
+---
+
+## Changed Components
+
+| Component / Module | Files Changed | Type of Change |
+|--------------------|--------------|----------------|
+| OrderForm | 3 files | New feature (form + hook + API) |
+| Cart | 1 file | Bug fix (quantity calc) |
+| Shared Types | 1 file | Added `OrderStatus` enum |
+
+---
+
+## In Progress (Uncommitted Changes)
+
+| File | Status | What's Being Worked On |
+|------|--------|----------------------|
+| `src/components/Checkout/Payment.tsx` | Modified | Adding Stripe integration |
+| `src/lib/api/payments.ts` | New file | Payment API client (partially implemented) |
+
+> [If no uncommitted changes: "Working tree is clean — no in-progress items."]
+
+---
+
+## Blockers & TODOs
+
+### New TODOs Added
+- `src/components/OrderForm.tsx:45` — `// TODO(JIRA-456): Add address validation`
+- `src/lib/api/orders.ts:23` — `// FIXME: Race condition when rapid-fire submissions`
+
+### Potential Blockers
+- [e.g., "Payment.tsx is half-implemented — may need Stripe API keys in .env"]
+- [e.g., "2 TODO items without ticket numbers — need to file tickets"]
+
+> [If no blockers: "No blockers identified."]
+
+---
+
+## Today's Suggested Focus
+1. [Based on in-progress work: "Complete Stripe payment integration"]
+2. [Based on TODOs: "Address FIXME in orders.ts — race condition"]
+3. [Based on context: "Add tests for OrderForm before PR"]
+```
+
+## Self-Check
+
+Before responding, verify:
+- [ ] You ran `git log` with the correct time range
+- [ ] You summarized commits in human-readable language, not raw commit messages
+- [ ] You checked for uncommitted changes (both staged and unstaged)
+- [ ] You scanned for TODO/FIXME/HACK comments in recently changed files
+- [ ] You grouped changes by component/module, not just listed files
+- [ ] You included the current branch name for context
+- [ ] Today's suggested focus is based on actual in-progress work, not generic advice
+
+## Constraints
+
+- Do NOT dump raw commit messages — translate them into human-readable summaries.
+- Do NOT include merge commits in the summary — use `--no-merges`.
+- Do NOT fabricate work items — if there are no commits in the time range, say so clearly.
+- Do NOT list every file individually when they belong to the same component — group them.
+- If the git history is empty for the time range, adjust: try `--since="2 days ago"` and note the adjustment.
+- Keep the report scannable — a team lead should be able to read it in under 60 seconds.
+
+Target: $ARGUMENTS