diff --git a/.claude/commands/plan.md b/.claude/commands/plan.md new file mode 100644 index 0000000000..5779bc8fa1 --- /dev/null +++ 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 --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 -e ` + + **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 --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 index 6d9ebb8c78..f4e03e315d 100644 --- a/.claude/commands/pr.md +++ b/.claude/commands/pr.md @@ -20,14 +20,44 @@ 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 ` -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' +chore: add new feature + +Add comprehensive feature implementation with tests and documentation. + +🤖 Generated with [Claude Code](https://claude.com/claude-code) + +Co-Authored-By: Claude +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 ` +10. Create PR with `gh pr create --title "title" --assignee @me --body "$(cat <<'EOF' ## Summary - Bullet point 1 - Bullet point 2 @@ -42,11 +72,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/slack.md b/.claude/commands/slack.md new file mode 100644 index 0000000000..c3928233e1 --- /dev/null +++ b/.claude/commands/slack.md @@ -0,0 +1,101 @@ +--- +description: Analyze Slack support threads and optionally create tickets or generate responses +--- + +Handle Slack support threads interactively - fetch thread content, analyze it, and ask the user whether to create a Jira ticket or generate a response. + +## 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 "" --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 understand: + - The core topic or question + - Whether it's a support request, bug report, feature request, or general question + - Relevant technical details and context + - Any mentioned components or file paths + - User expectations and requirements + - Screenshots or CodeSandbox links + +3. **Present analysis to user**: + - Show a summary of the Slack thread: + - Main topic/question + - Type of conversation (question, bug, feature request, etc.) + - Key participants and dates + - Important technical details + - Display relevant excerpts from the conversation + +4. **Ask user for action**: + - Present two options: + 1. **Create Jira ticket** - If this is an actionable item (bug, feature request, task) + 2. **Generate response** - If this is a question or discussion that needs a reply + - Use the AskUserQuestion tool to get the user's choice + +5. **Execute chosen action**: + + ### If user chooses "Create Jira ticket": + - Draft a Jira ticket: + - **Summary**: Brief, clear title (max 100 chars) + - **Description**: Include: + - 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 + - Link to original Slack thread + - **Issue Type**: Determine type (Bug, Task, or Story) + - Show draft to user for confirmation + - **DO NOT create ticket without explicit user confirmation** + - Create ticket using `inst-ai jira create` + - Return the created Jira ticket URL + + ### If user chooses "Generate response": + - Analyze the question/discussion thoroughly + - Research the codebase if needed to provide accurate information + - Generate a helpful, accurate response that: + - Directly addresses the question or discussion point + - Includes relevant code examples if applicable + - References appropriate documentation + - Provides clear next steps or recommendations + - Present the response to the user + - User can then copy/paste to Slack or ask for modifications + +## Important Notes + +- **Detect conversation type** - Questions shouldn't automatically become tickets +- **Always analyze the full thread** - Don't miss context from replies +- **Include Slack URL in tickets** - For traceability +- **Research before responding** - Use codebase knowledge for accurate answers +- **Ask for clarification** - If conversation is unclear, ask user for guidance + +## Example Workflow + +```bash +# Extract Slack conversation +inst-ai slack "https://instructure.slack.com/archives/C123/p456" --format xml --include-metadata --include-codesandbox + +# Based on analysis, either: + +# Option 1: Create ticket (after user confirms) +inst-ai jira create --summary "Button: Click handler not firing on mobile" \ + --description "Issue reported in Slack: ..." \ + --type Bug + +# Option 2: Generate response for user to post +# (Claude generates response based on analysis and codebase research) +``` + +## 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 troubleshooting steps diff --git a/.claude/commands/ticket.md b/.claude/commands/ticket.md new file mode 100644 index 0000000000..31cb348c31 --- /dev/null +++ b/.claude/commands/ticket.md @@ -0,0 +1,157 @@ +--- +description: Create Jira ticket from Slack thread, GitHub issue, or text description +--- + +Create a Jira ticket from multiple sources using inst-ai tool with InstUI conventions. + +## Requirements + +- Input source is required as argument: + - Slack thread URL (e.g., `https://instructure.slack.com/archives/C123/p456`) + - GitHub issue URL (e.g., `https://github.com/instructure/instructure-ui/issues/123`) + - Textual description (plain text describing the issue) +- inst-ai tool must be installed globally (`npm install -g github:instructure/inst-ai-tool`) +- GitHub CLI (`gh`) must be installed for GitHub issue fetching +- Configuration must be set up (see inst-ai documentation) + +## Process + +### 1. Determine Input Type + +Analyze the input to determine its type: +- **Slack URL**: Contains `slack.com/archives/` +- **GitHub URL**: Contains `github.com/.../issues/` +- **Text description**: Everything else + +### 2. Extract Content Based on Type + +#### For Slack URLs: +- Run `inst-ai slack "" --format xml --include-metadata --include-codesandbox` +- This extracts the conversation in LLM-friendly XML format with full context + +#### For GitHub URLs: +- Extract owner, repo, and issue number from URL +- Use `gh issue view --repo / --json title,body,labels,comments` +- Parse the JSON response to get issue details + +#### For Text Descriptions: +- Use the provided text directly as the issue description +- No fetching needed + +### 3. Analyze the Content + +Parse the extracted content to identify: +- The core issue or request +- Relevant technical details +- Any mentioned components or file paths +- User expectations and requirements +- Screenshots, CodeSandbox links, or other attachments +- For GitHub issues: existing labels and comments + +### 4. Draft Jira Ticket + +- **Summary**: Brief, clear title describing the issue (max 100 chars) + - For GitHub issues: Use the original issue title or adapt it + - For Slack/text: Create a concise, descriptive title + +- **Description**: Detailed description including: + - What: Clear description of the issue/feature + - Why: Context from the source (Slack conversation, GitHub discussion, or provided text) + - Where: Affected components/files (if identified) + - How to reproduce: Steps if it's a bug + - Expected behavior: What should happen + - Additional context: Links to source (Slack thread, GitHub issue), 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 + - For GitHub issues: Consider existing labels to determine type + +- **Component Detection**: + - Analyze content for component mentions (e.g., "Button", "Select", "Modal") + - Map to package paths (e.g., ui-button, ui-select) + - Include in ticket description + +### 5. Use inst-ai Templates (Optional) + +- Templates are located in `.inst-ai/templates/jira` (configured in inst-ai.config.mjs) +- Common templates: `bugReport`, `featureRequest` +- Use `--template ` flag when appropriate +- Templates ensure consistent ticket formatting + +### 6. Present Draft to User + +- Show the complete ticket draft +- Display summary, description, issue type, components +- Show the source (Slack URL, GitHub issue URL, or text) +- Ask user to confirm or request modifications +- **DO NOT create ticket without explicit user confirmation** + +### 7. Create Ticket + +Once confirmed, use `inst-ai jira create` with the drafted content: +- If using a template: `inst-ai jira create --template bugReport --content ''` +- If custom: `inst-ai jira create --summary "..." --description "..." --type Bug` +- **Always include link to original source in description** (Slack thread or GitHub issue) + +### 8. Return Ticket URL + +- Display the created Jira ticket URL +- Confirm successful creation +- Show the mapping: source → Jira ticket + +## Important Notes + +- **Always analyze full content** - For Slack threads: don't miss context from replies. For GitHub: include comments. +- **Include source URL in ticket** - Always link back to Slack thread or GitHub issue for traceability +- **Component detection is optional** - Skip for non-code issues +- **Use dry-run for testing** - `inst-ai jira create --dry-run` previews without creating +- **Handle attachments** - Extract and reference CodeSandbox links, screenshots, etc. +- **Ask for clarification** - If content is unclear or ambiguous, ask user before creating ticket +- **Detect input type automatically** - Parse the input to determine if it's Slack, GitHub, or text + +## Example Workflows + +### From Slack Thread + +```bash +# Extract Slack conversation +inst-ai slack "https://instructure.slack.com/archives/C123/p456" --format xml --include-metadata --include-codesandbox + +# After analysis, create ticket +inst-ai jira create --summary "Button: Click handler not firing on mobile" \ + --description "Issue reported in Slack: https://instructure.slack.com/archives/C123/p456\n\n..." \ + --type Bug +``` + +### From GitHub Issue + +```bash +# Fetch GitHub issue +gh issue view 123 --repo instructure/instructure-ui --json title,body,labels,comments + +# After analysis, create ticket +inst-ai jira create --summary "Add dark mode support to Modal component" \ + --description "Feature request from GitHub: https://github.com/instructure/instructure-ui/issues/123\n\n..." \ + --type Story +``` + +### From Text Description + +```bash +# User provides text directly, create ticket after drafting +inst-ai jira create --summary "Select component: Dropdown not closing on blur" \ + --description "User reported issue:\n\nThe Select component dropdown remains open..." \ + --type Bug +``` + +## Error Handling + +- **Invalid Slack URL**: Inform user and ask for correct URL +- **Invalid GitHub URL**: Inform user and ask for correct URL or issue number +- **GitHub CLI not installed**: Provide installation instructions (`gh` is required) +- **inst-ai not installed**: Provide installation instructions (`npm install -g github:instructure/inst-ai-tool`) +- **Configuration missing**: Direct user to run `inst-ai config validate` +- **Ticket creation fails**: Show error and suggest using `--dry-run` to debug +- **Ambiguous text input**: Ask user for clarification or more details diff --git a/.gitignore b/.gitignore index 80d8c8ce41..d4ba9a0167 100644 --- a/.gitignore +++ b/.gitignore @@ -32,6 +32,9 @@ tsconfig.build.tsbuildinfo .claude/commands/* !.claude/commands/commit.md !.claude/commands/pr.md +!.claude/commands/ticket.md +!.claude/commands/plan.md +!.claude/commands/slack.md # Playwright MCP .playwright-mcp