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..a52732281b 100644 --- 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 ` -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 ` +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 new file mode 100644 index 0000000000..b3d8b3c6af --- /dev/null +++ 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 "" --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 ` 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 ''` + - 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 "" --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 index f8d4b3f934..89f24b038a 100644 --- 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