-
Notifications
You must be signed in to change notification settings - Fork 107
Add inst-ai integration slash commands #2194
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
balzss
wants to merge
1
commit into
master
Choose a base branch
from
chore/claude-improvements
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+329
−9
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The squashing command uses an incomplete heredoc syntax. The actual commit message content should be provided or referenced more clearly, as the current
...placeholder could be confusing.