chore: enhance Claude Code slash commands with inst-ai integration

balzss · claude · balzss · commit b689318ca754 · 2025-10-13T15:46:21.000+02:00
Add inst-ai tool integration and improve PR workflow: - Add /plan command: Generate implementation plans from Jira issues with codebase analysis - Add /ticket command: Create Jira tickets from Slack thread URLs - Update /pr command to auto-assign PRs to creator - Add commit handling: automatically use /commit for uncommitted changes - Add squashing analysis: evaluate commit history and recommend squashing when appropriate - Include guidelines for when to squash vs keep commits separate These commands streamline the workflow for analyzing issues, creating tickets, and managing pull requests while following InstUI conventions. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/.claude/commands/plan.md b/.claude/commands/plan.md
@@ -0,0 +1,199 @@
+---
+description: Generate implementation plan from Jira issue using inst-ai
+---
+
+Generate a comprehensive implementation plan by analyzing Jira issues and codebase using inst-ai tool with InstUI conventions.
+
+## Requirements
+
+- Optional Jira issue key (e.g., INST-1234) or description
+- inst-ai tool must be installed globally (`npm install -g github:instructure/inst-ai-tool`)
+- Configuration must be set up (see inst-ai documentation)
+
+## Process
+
+1. **Get issue context**:
+
+   **If Jira issue key provided**:
+   - Run `inst-ai jira read <issue-key> --format xml --include-comments`
+   - Parse the issue details:
+     - Summary and description
+     - Acceptance criteria
+     - Comments and discussion
+     - **Look for entry point file paths** in description/comments (likely included by user)
+
+   **If plain text description provided**:
+   - Use the description as issue context
+   - Will need to identify entry point files manually
+
+2. **Identify entry point files**:
+
+   **First, check if entry point is in Jira ticket**:
+   - Look for file paths in ticket description
+   - Check comments for mentioned components/files
+   - Common patterns: `packages/ui-*/src/*/index.tsx`
+
+   **If entry point NOT found in ticket**:
+   - **Claude Code aids file selection** (inst-ai's interactive selector doesn't work in Claude CLI)
+   - Analyze issue context to identify relevant components
+   - Use `Glob` tool to search for potential files:
+     - Search component packages: `packages/ui-{component}/src/*/index.tsx`
+     - Search by feature area based on issue description
+   - Present 3-5 most relevant options to user
+   - Ask user to select or provide custom path
+   - **Pass selected file path explicitly to inst-ai**: `inst-ai plan <issue-key> -e <file-path>`
+
+   **Example searches**:
+   ```
+   # For Button-related issues
+   Glob: packages/ui-button/**/index.tsx
+
+   # For Select component
+   Glob: packages/ui-select/**/index.tsx
+
+   # For broad changes
+   Glob: packages/*/src/*/index.tsx
+   ```
+
+3. **Scan codebase**:
+   - Use `inst-ai scan -e <file-path> --format xml --include-docs`
+   - Can specify multiple entry points: `-e file1.tsx file2.tsx`
+   - Include docs to understand context: `--include-docs`
+   - Analyze:
+     - Component structure and dependencies
+     - Related files and imports
+     - Testing files
+     - Theme files
+     - Documentation
+
+4. **Generate implementation plan**:
+   - Combine Jira issue context with code analysis
+   - Create structured plan with:
+     - **Issue Summary**: What needs to be done
+     - **Affected Components**: List of files/components to modify
+     - **Dependencies**: Related code that may be impacted
+     - **Implementation Steps**: Detailed, actionable tasks:
+       1. Update component props/logic
+       2. Update theme variables (if needed)
+       3. Update tests
+       4. Update documentation
+     - **Testing Strategy**:
+       - Unit tests (Vitest)
+       - Component tests (Cypress)
+       - Visual regression tests (if UI changes)
+       - Accessibility verification
+     - **Breaking Change Assessment**:
+       - Evaluate if changes are breaking (see CLAUDE.md)
+       - If breaking: document clearly with `BREAKING CHANGE:` in commit
+       - Prefer non-breaking alternatives when possible
+     - **Documentation Updates**:
+       - Component README updates
+       - API documentation
+       - Migration guide (if breaking)
+
+5. **Save session**:
+   - Plan is automatically saved to `.inst-ai/sessions` (configured in inst-ai.config.mjs)
+   - Session includes:
+     - Issue context
+     - Scanned files
+     - Generated plan
+     - Timestamp and metadata
+
+6. **Present plan to user**:
+   - Show complete implementation plan
+   - Highlight breaking changes if any
+   - List all affected files
+   - Ask for user review and approval
+   - **DO NOT start implementation without explicit user confirmation**
+
+7. **Ready to implement**:
+   - Once approved, work through plan step-by-step
+   - Mark tasks as completed using TodoWrite tool
+   - Create commits following InstUI conventions (use `/commit`)
+   - Create PR when done (use `/pr`)
+
+## Important Notes
+
+- **Entry point files are critical** - they determine what code gets analyzed
+- **Multiple entry points are supported** - use when changes span multiple components
+- **inst-ai interactive mode won't work** - Claude Code must handle all file selection
+- **Always pass file paths explicitly** to inst-ai CLI (don't rely on interactive selector)
+- **Parse Jira tickets carefully** - entry points are often mentioned in descriptions/comments
+- **Consider dependencies** - changes may affect multiple components
+- **Breaking changes require extra care** - see CLAUDE.md for breaking change guidelines
+- **Plans are saved** - can reference later from `.inst-ai/sessions`
+
+## Example Workflows
+
+### With Jira issue (entry point in ticket)
+
+```bash
+# 1. Fetch Jira issue
+inst-ai jira read INST-1234 --format xml --include-comments
+
+# 2. Entry point found in ticket: packages/ui-button/src/Button/index.tsx
+# 3. Generate plan
+inst-ai plan INST-1234 -e packages/ui-button/src/Button/index.tsx --include-docs
+
+# 4. Review plan, then implement
+```
+
+### With Jira issue (entry point NOT in ticket)
+
+```bash
+# 1. Fetch Jira issue
+inst-ai jira read INST-1234 --format xml
+
+# 2. Issue is about "Button component accessibility"
+# 3. Claude Code searches for relevant files
+# Glob: packages/ui-button/**/index.tsx
+
+# 4. Present options to user:
+#    - packages/ui-button/src/Button/index.tsx
+#    - packages/ui-button/src/Button/README.md
+
+# 5. User selects: packages/ui-button/src/Button/index.tsx
+# 6. Generate plan
+inst-ai plan INST-1234 -e packages/ui-button/src/Button/index.tsx --include-docs
+```
+
+### With plain description
+
+```bash
+# 1. User provides: "Add dark mode support to Select component"
+# 2. Claude Code identifies component: ui-select
+# 3. Search for entry points
+# Glob: packages/ui-select/**/index.tsx
+
+# 4. Generate plan
+inst-ai plan "Add dark mode support to Select component" -e packages/ui-select/src/Select/index.tsx --include-docs
+```
+
+### Multiple entry points
+
+```bash
+# Changes span Button and ButtonGroup
+inst-ai plan INST-1234 -e packages/ui-button/src/Button/index.tsx packages/ui-button/src/ButtonGroup/index.tsx --include-docs
+```
+
+## Error Handling
+
+- If Jira issue not found, verify issue key and permissions
+- If entry point file doesn't exist, re-search and confirm path with user
+- If inst-ai is not installed, provide installation instructions
+- If configuration is missing, direct user to run `inst-ai config validate`
+- If plan generation fails, check:
+  - Entry point file is valid TypeScript/TSX
+  - File is not too large (check token warning threshold in config)
+  - Dependencies can be resolved
+
+## InstUI-Specific Considerations
+
+- **Component structure**: `/packages/ui-[name]/src/[Component]/`
+- **Co-located tests**: `Component.test.tsx` next to component
+- **Theme files**: `theme.ts` defines theme variables
+- **Props files**: `props.ts` defines component API
+- **README files**: Component documentation in component directory
+- **Visual regression tests**: Must add test page in `/regression-test`
+- **Functional components**: All new code uses hooks, never class components
+- **No hardcoded text**: All user-facing text from props (i18n support)
diff --git a/.claude/commands/pr.md b/.claude/commands/pr.md
@@ -20,14 +20,35 @@ All PRs must include:
 
 ## Process
 
-1. Run `git status` to check current branch and remote tracking
-2. Run `git log master..HEAD` to see all commits that will be in the PR
-3. Run `git diff master...HEAD` to see full diff from base branch
-4. Analyze changes across ALL commits (not just latest)
-5. Draft PR summary covering all changes
-6. **If Jira ticket number is unknown, ask the user for it before creating the PR**
-7. Push to remote if needed: `git push -u origin <branch>`
-8. Create PR with `gh pr create --title "title" --body "$(cat <<'EOF'
+1. **Check for uncommitted changes**: Run `git status`
+   - **If uncommitted changes exist**: Use `/commit` command to create a commit first
+   - Ask user to confirm before creating the commit
+
+2. **Analyze commit history**: Run `git log master..HEAD --oneline` to see all commits
+   - **If no commits exist**: Inform user there are no changes to create a PR for
+   - **If multiple commits exist**: Analyze whether they should be squashed
+     - Squash if commits are:
+       - Multiple small fixes/adjustments to the same feature
+       - Follow-up commits fixing issues in previous commits (typos, lint errors, etc.)
+       - All part of the same logical change (e.g., implementation + tests + docs)
+     - Keep separate if commits are:
+       - Distinct logical changes or features
+       - Different types of work (e.g., refactoring vs new feature)
+       - Already well-organized and clear
+   - **If squashing is recommended**:
+     - Present the analysis to user
+     - Draft a single comprehensive commit message covering all changes
+     - Ask for confirmation before squashing
+     - Squash with: `git reset --soft master && git commit -m "$(cat <<'EOF'...EOF)"`
+
+3. Run `git status` to check current branch and remote tracking
+4. Run `git log master..HEAD` to see all commits that will be in the PR
+5. Run `git diff master...HEAD` to see full diff from base branch
+6. Analyze changes across ALL commits (not just latest)
+7. Draft PR summary covering all changes
+8. **If Jira ticket number is unknown, ask the user for it before creating the PR**
+9. Push to remote if needed: `git push -u origin <branch>`
+10. Create PR with `gh pr create --title "title" --assignee @me --body "$(cat <<'EOF'
 ## Summary
 - Bullet point 1
 - Bullet point 2
@@ -42,11 +63,13 @@ Fixes INST-XXXX (or omit this section if not applicable)
 🤖 Generated with [Claude Code](https://claude.com/claude-code)
 EOF
 )"`
-9. Return the PR URL
+11. Return the PR URL
 
 **Important**:
 - Base branch is usually `master` (not main)
 - Analyze ALL commits in the branch, not just the latest one
+- PRs are typically squashed when merged, so having a single well-crafted commit is preferred
 - Use markdown checklists for test plan
 - Include AI attribution footer
 - Always confirm Jira ticket number with user if not found in commits or branch name
+- Always ask for user confirmation before squashing commits or creating the PR
diff --git a/.claude/commands/ticket.md b/.claude/commands/ticket.md
@@ -0,0 +1,96 @@
+---
+description: Create Jira ticket from Slack thread URL using inst-ai
+---
+
+Create a Jira ticket from a Slack conversation using inst-ai tool with InstUI conventions.
+
+## Requirements
+
+- Slack thread URL is required as argument
+- inst-ai tool must be installed globally (`npm install -g github:instructure/inst-ai-tool`)
+- Configuration must be set up (see inst-ai documentation)
+
+## Process
+
+1. **Extract Slack conversation**:
+   - Run `inst-ai slack "<slack-url>" --format xml --include-metadata --include-codesandbox`
+   - This extracts the conversation in LLM-friendly XML format with full context
+
+2. **Analyze the conversation**:
+   - Parse the Slack conversation to identify:
+     - The core issue or request
+     - Relevant technical details
+     - Any mentioned components or file paths
+     - User expectations and requirements
+     - Screenshots or CodeSandbox links
+
+3. **Draft Jira ticket**:
+   - **Summary**: Brief, clear title describing the issue (max 100 chars)
+   - **Description**: Detailed description including:
+     - What: Clear description of the issue/feature
+     - Why: Context from the Slack conversation
+     - Where: Affected components/files (if identified)
+     - How to reproduce: Steps if it's a bug
+     - Expected behavior: What should happen
+     - Additional context: Links to Slack thread, screenshots, etc.
+   - **Issue Type**: Determine appropriate type:
+     - `Bug`: Something is broken or not working as intended
+     - `Task`: Work that needs to be done (improvements, updates)
+     - `Story`: New feature or functionality
+   - **Component Detection**:
+     - Analyze conversation for component mentions (e.g., "Button", "Select", "Modal")
+     - Map to package paths (e.g., ui-button, ui-select)
+     - Include in ticket description
+
+4. **Use inst-ai templates**:
+   - Templates are located in `.inst-ai/templates/jira` (configured in inst-ai.config.mjs)
+   - Common templates: `bugReport`, `featureRequest`
+   - Use `--template <name>` flag when appropriate
+   - Templates ensure consistent ticket formatting
+
+5. **Present draft to user**:
+   - Show the complete ticket draft
+   - Display summary, description, issue type, components
+   - Ask user to confirm or request modifications
+   - **DO NOT create ticket without explicit user confirmation**
+
+6. **Create ticket**:
+   - Once confirmed, use `inst-ai jira create` with the drafted content
+   - If using a template: `inst-ai jira create --template bugReport --content '<json-data>'`
+   - If custom: `inst-ai jira create --summary "..." --description "..." --type Bug`
+   - Include link to original Slack thread in description
+
+7. **Return ticket URL**:
+   - Display the created Jira ticket URL
+   - Confirm successful creation
+
+## Important Notes
+
+- **Always analyze the full Slack thread** - don't miss important context from replies
+- **Include Slack thread URL in ticket** - for future reference and traceability
+- **Component detection is optional** - skip with `--no-component-detection` for non-code issues
+- **Use dry-run for testing** - `inst-ai ticket "<url>" --dry-run-jira` previews without creating
+- **Handle CodeSandbox content** - if conversation includes CodeSandbox, extract and reference it
+- **Ask for clarification** - if conversation is unclear, ask user before creating ticket
+
+## Example Workflow
+
+```bash
+# Extract Slack conversation
+inst-ai slack "https://instructure.slack.com/archives/C123/p456" --format xml --include-metadata --include-codesandbox
+
+# After analysis, create ticket with confirmation
+inst-ai jira create --summary "Button: Click handler not firing on mobile" \
+  --description "Issue reported in Slack thread..." \
+  --type Bug
+
+# Or use template
+inst-ai jira create --template bugReport --content '{"summary":"...","description":"...","issueType":"Bug"}'
+```
+
+## Error Handling
+
+- If Slack URL is invalid or inaccessible, inform user and ask for correct URL
+- If inst-ai is not installed, provide installation instructions
+- If configuration is missing, direct user to run `inst-ai config validate`
+- If ticket creation fails, show error and suggest using `--dry-run-jira` to debug
diff --git a/.gitignore b/.gitignore
@@ -31,3 +31,5 @@ tsconfig.build.tsbuildinfo
 .claude/commands/*
 !.claude/commands/commit.md
 !.claude/commands/pr.md
+!.claude/commands/ticket.md
+!.claude/commands/plan.md
