diff --git a/.claude/commands/make-task-issue.md b/.claude/commands/make-task-issue.md index 4e2ae68..37093d8 100644 --- a/.claude/commands/make-task-issue.md +++ b/.claude/commands/make-task-issue.md @@ -3,16 +3,20 @@ description: "Create GitHub issues using templates with automatic project assign argument-hint: "[template-type] [issue-title]" allowed-tools: - Bash + - Read + - Glob + - Grep + - Write --- # Make Task Issue -Create a new GitHub issue using one of the available templates and automatically assign it to the repository's GitHub Project. +Create a new GitHub issue with comprehensive context gathering, requirement analysis, and solution design. This command guides you through a structured input process and enhances your input with AI-powered codebase analysis. ## Usage ``` -/make-task-issue [template-type] [issue-title] +/make-task-issue [template-type] ``` Or simply: @@ -20,6 +24,8 @@ Or simply: /make-task-issue ``` +**Note**: This command no longer accepts issue title as an argument. The title will be auto-generated based on your requirement input. + ## Available Templates The following issue templates are available in `.github/ISSUE_TEMPLATE/`: @@ -36,68 +42,333 @@ The following issue templates are available in `.github/ISSUE_TEMPLATE/`: ## Workflow -1. **Determine template type**: - - If `$1` (first argument) is provided and matches a template type, use it - - Otherwise, ask the user to select from available templates - -2. **Get issue title**: - - If `$2` (remaining arguments) is provided, use it as the title - - Otherwise, ask the user for the title - - Format title as: `{type}: {user-provided-title}` - -3. **Create the issue**: - - Use GitHub CLI: `gh issue create --template {template}.md --title "{formatted-title}"` - - The template will pre-fill the issue body structure - - User can edit the issue body in their editor before submission - -4. **Set issue type as "Task"**: - - After issue creation, set the GitHub issue type to "Task" - - Use GitHub API via gh CLI: `gh api repos/{owner}/{repo}/issues/{issue-number} -X PATCH -f type='Task'` - - This categorizes the issue as a "Task" type in GitHub's issue tracking system - - Note: The field name is `type` (not `issue_type`) and the value should be capitalized (e.g., 'Task', 'Bug', 'Feature') - - Issue types are an organization-level feature and may not be available in all repositories - -5. **Add to GitHub Project**: - - After issue creation, add the issue to the repository's linked GitHub Project - - Get the project linked to the repository using GraphQL (most efficient): - ```bash - gh api graphql -f query=' - { - repository(owner: "{owner}", name: "{repo}") { - projectsV2(first: 1) { - nodes { - id - number - title - } - } - } - }' - ``` - - Extract the project number from the response - - Add the issue to the project: - * Use: `gh project item-add {project-number} --owner {owner} --url {issue-url}` - - If no project is linked or command fails, show informative message but don't fail issue creation - - Note: This approach is more efficient than listing all organization projects as it queries only repository-linked projects +### 1. Determine Template Type +- If `$1` (first argument) is provided and matches a template type, use it +- Otherwise, ask the user to select from available templates -## Examples +### 2. Collect User Input (Editor-based) + +Create a temporary markdown file with a template structure **tailored to the issue type** and open it in the user's editor. + +**Template sections by type:** + +| Type | Section 3 | Section 4 | Notes | +|------|-----------|-----------|-------| +| feat, config, agent | Solution | Test Plan | Standard structure | +| fix | Solution | Test Plan | With bug-specific guidance | +| doc | Content Outline | Verification | Documentation-specific | +| test | Test Scope | Verification | Test-specific | +| perf | Solution | Verification | Performance-specific | +| refactor | Solution | Verification | Refactoring-specific | + +**All types share:** Context (REQUIRED), Requirement (REQUIRED), Reference (auto-generated) + +**Example template for `feat`:** +```markdown +# Issue Information + +## Context (REQUIRED) + + +## Requirement (REQUIRED) + + +## Solution (optional) + + +## Test Plan (optional) + +``` + +**Example template for `doc`:** +```markdown +# Issue Information + +## Context (REQUIRED) + + +## Requirement (REQUIRED) + + +## Content Outline (optional) + + +## Verification (optional) + +``` + +**Example template for `test`:** +```markdown +# Issue Information + +## Context (REQUIRED) + + +## Requirement (REQUIRED) + -### With arguments: +## Test Scope (optional) + + +## Verification (optional) + ``` -/make-task-issue feat implement dark mode + +**Implementation steps:** +- Use `Write` tool to create a temporary file (e.g., `/tmp/issue-input-{timestamp}.md`) +- **Select the appropriate template based on the issue type** (see table above) +- Use `Bash` with `${EDITOR:-vi}` to open the file for editing +- After user saves and closes, read the file content +- Parse the sections from the markdown (section names vary by type) +- **Validate required sections**: Check that Context and Requirement are filled (not empty or just whitespace) +- If validation fails, inform the user which sections are missing and re-open the editor +- Repeat until all required sections are filled + +### 3. AI Context Gathering and Enhancement + +After collecting user input, enhance it with AI analysis: + +**Context Gathering:** +- Use `Read`, `Glob`, `Grep` to search for related code based on user's Context and Requirement +- Look for: + - Related files or modules mentioned in the user input + - Similar patterns or existing implementations + - Dependencies or components that might be affected + - Relevant configuration files or documentation + +**Content Enhancement:** +- Analyze gathered context and present findings to the user +- If the Solution section is empty or brief, suggest approaches based on: + - Existing patterns found in the codebase + - Similar features or components + - Best practices observed in the project +- Present the enhanced content with clearly marked AI additions +- Ask user: "I've gathered additional context from the codebase. Here's what I found: [summary]. Would you like me to add this to the issue? Any changes needed?" +- Allow user to approve, modify, or reject the AI enhancements +- Iterate until user is satisfied + +### 4. Generate Issue Title + +Based on the Requirement section, generate a concise, descriptive title: + +**Title Generation Process:** +- Analyze the Requirement to extract the core intent +- Generate title in format: `{type}: {concise-summary-of-requirement}` +- Title should be: + - Concise (ideally under 80 characters) + - Action-oriented (use verbs like "add", "fix", "update", "refactor") + - Descriptive enough to understand the issue at a glance + +**Present to user:** +- Show the generated title +- Ask: "Here's the suggested issue title: '{generated-title}'. Would you like to use this or modify it?" +- Allow user to approve or provide their own title +- If user provides custom title, ensure it follows the `{type}: {description}` format + +### 5. Create Issue with Structured Body + +Generate the issue body using **type-specific section names**: + +**For feat, config, agent:** +```markdown +## Context +{user-provided context + AI enhancements if approved} + +## Requirement +{user-provided requirement} + +## Solution +{user-provided solution + AI suggestions if approved, or empty if not provided} + +## Test Plan +{user-provided test plan or empty if not provided} + +## Reference +{auto-generated references to related files found during context gathering, or empty} ``` -Creates a feature issue with title "feat: implement dark mode" -### Interactive mode: +**For doc:** +```markdown +## Context +{user-provided context + AI enhancements if approved} + +## Requirement +{user-provided requirement} + +## Content Outline +{user-provided content outline or empty if not provided} + +## Verification +{user-provided verification plan or empty if not provided} + +## Reference +{auto-generated references to related files, or empty} ``` + +**For test:** +```markdown +## Context +{user-provided context + AI enhancements if approved} + +## Requirement +{user-provided requirement} + +## Test Scope +{user-provided test scope or empty if not provided} + +## Verification +{user-provided verification plan or empty if not provided} + +## Reference +{auto-generated references to related files, or empty} +``` + +**For perf, refactor:** +```markdown +## Context +{user-provided context + AI enhancements if approved} + +## Requirement +{user-provided requirement} + +## Solution +{user-provided solution or empty if not provided} + +## Verification +{user-provided verification plan or empty if not provided} + +## Reference +{auto-generated references to related files, or empty} +``` + +**For fix:** +```markdown +## Context +{user-provided context (bug description, steps to reproduce, expected vs current behavior) + AI enhancements if approved} + +## Requirement +{what needs to be fixed} + +## Solution +{root cause analysis and fix approach, or empty if not provided} + +## Test Plan +{verification and regression testing plan, or empty if not provided} + +## Reference +{auto-generated references to related files, or empty} +``` + +**Create the issue:** +- Use `gh issue create` with `--title` and `--body` flags (NOT `--template`) +- Add appropriate label using `-l {type}` flag +- Generate body with the appropriate section names for the type +- Example: `gh issue create --title "{approved-title}" --body "{structured-body}" -l {type}` + +### 6. Set Issue Type as "Task" + +After issue creation: +- Set the GitHub issue type to "Task" +- Use GitHub API: `gh api repos/{owner}/{repo}/issues/{issue-number} -X PATCH -f type='Task'` +- Note: Issue types are an organization-level feature and may not be available in all repositories +- If this fails, show a warning but continue + +### 7. Add to GitHub Project + +Add the issue to the repository's linked GitHub Project: +- Get the project linked to the repository using GraphQL: + ```bash + gh api graphql -f query=' + { + repository(owner: "{owner}", name: "{repo}") { + projectsV2(first: 1) { + nodes { + id + number + title + } + } + } + }' + ``` +- Extract the project number from the response +- Add the issue: `gh project item-add {project-number} --owner {owner} --url {issue-url}` +- If no project is linked or command fails, show informative message but don't fail issue creation + +## Examples + +### Example 1: With template type specified +```bash +/make-task-issue feat +``` + +This will: +1. Use the "feat" template type +2. Open editor for you to fill in Context, Requirement, Solution, etc. +3. Gather additional context from codebase +4. Present AI enhancements for your approval +5. Auto-generate issue title based on your requirement +6. Create issue with structured body +7. Set issue type and add to project + +### Example 2: Fully interactive +```bash /make-task-issue ``` -Prompts for template selection and title + +This will: +1. Ask you to select a template type +2. Then follow the same workflow as Example 1 + +### Example User Input + +When the editor opens, you might fill it in like this: + +```markdown +## Context (REQUIRED) +Our application currently lacks support for dark mode, which many users have requested. Modern applications are expected to support user preferences for light/dark themes, and our competitors already offer this feature. + +## Requirement (REQUIRED) +Implement a dark mode theme that users can toggle. The theme preference should: +- Be persistent across sessions +- Apply to all pages and components +- Follow our existing design system color variables +- Default to system preference on first visit + +## Solution (optional) +Use CSS variables for theming with a context provider to manage theme state. Store preference in localStorage. + +## Constraints (optional) +- Must maintain WCAG AA contrast ratios in both themes +- Should not require refactoring existing component styles (use CSS variables) +- Must work with our existing Tailwind configuration + +## Test Plan (optional) +- Test theme toggle functionality +- Test persistence across page reloads +- Test system preference detection +- Verify contrast ratios meet accessibility standards +``` + +The AI might then find your design system config, suggest how to integrate with Tailwind, and generate a title like: +`feat: implement dark mode theme with persistent user preference` ## Implementation Notes -- Use `gh issue create` with `--template` flag to utilize existing templates -- Templates automatically apply correct labels (e.g., feat template applies "feat" label) +**Workflow characteristics:** +- This command now uses an **editor-based input** approach instead of templates +- The AI actively gathers context from your codebase to enhance the issue +- Issue titles are auto-generated for consistency +- **Type-specific sections**: Each issue type has sections optimized for its purpose + - feat, config, agent: Context, Requirement, Solution, Test Plan, Reference + - doc: Context, Requirement, Content Outline, Verification, Reference + - test: Context, Requirement, Test Scope, Verification, Reference + - perf, refactor: Context, Requirement, Solution, Verification, Reference + - fix: Context, Requirement, Solution, Test Plan, Reference (with bug-specific guidance) + +**Technical details:** +- Uses `gh issue create` with `--title` and `--body` flags (not `--template`) +- Labels are applied via `-l {type}` flag - Issue will be assigned to creator automatically via auto-assign workflow - All issues created via this command are set to "Task" type - Issues are automatically added to the repository's linked GitHub Project @@ -106,13 +377,19 @@ Prompts for template selection and title * Supports both organization and user projects * Uses `gh project item-add` to add issues to projects * Gracefully handles cases where no project is linked -- Issue type feature requires organization-level setup (default types: Task, Bug, Feature) + +**Relationship with `/plan-issue`:** +- `/make-task-issue` focuses on **problem definition**: gathering context, defining requirements, designing solutions +- `/plan-issue` focuses on **implementation planning**: breaking down well-defined issues into actionable steps +- Issues created with `/make-task-issue` are well-suited for `/plan-issue` to process ## Error Handling - If template type is invalid, show available templates and ask again +- If user input is missing required sections (Context, Requirement), re-open editor with a message - If `gh` CLI is not available, guide user to install it +- If editor cannot be opened, fall back to multi-line prompts - If issue type setting fails (e.g., feature not available), show warning but continue - If no GitHub Project is linked to repository, show informative message - If project assignment fails, show warning but don't fail issue creation -- Provide clear feedback on each step of the process (issue created, type set, project assigned) +- Provide clear feedback on each step of the process (input collected, context gathered, title generated, issue created, type set, project assigned) diff --git a/.claude/commands/plan-issue.md b/.claude/commands/plan-issue.md index 40b9aa6..47cb5bd 100644 --- a/.claude/commands/plan-issue.md +++ b/.claude/commands/plan-issue.md @@ -10,7 +10,9 @@ allowed-tools: # Plan Issue -Fetch a GitHub issue and create an interactive, detailed implementation plan with clear rationale for each decision. +Fetch a well-structured GitHub issue and create an interactive, detailed implementation plan with clear rationale for each decision. + +**Note**: This command works best with issues created using `/make-task-issue`, which provides structured Context, Requirement, and Solution sections. This command focuses on breaking down the problem into actionable implementation steps, not on defining the problem itself. ## Usage @@ -46,35 +48,52 @@ Extract and analyze: ### 3. Analyze Issue Content -Parse the issue body to understand: - -**Problem/Requirement Analysis:** -- What is the core problem or requirement? -- Why does this need to be solved? -- What is the expected outcome? -- Are there any constraints or considerations? - -**Context Gathering:** -- Review related files mentioned in the issue +**Expected Issue Structure:** +Issues created with `/make-task-issue` will have the following sections: +- **Context**: Background and why this is needed +- **Requirement**: What needs to be done and expected outcome +- **Solution**: Proposed approach (may be empty or brief) +- **Test Plan**: Success criteria (may be empty or brief) +- **Reference**: Related files or documentation + +**Parse the issue body to extract:** +- **Context section**: Understand the background and motivation +- **Requirement section**: Identify what needs to be implemented +- **Solution section**: Review any proposed approaches (if provided) +- **Test Plan section**: Note any existing success criteria (if provided) + +**Additional Context Gathering:** +- Review related files mentioned in the issue or Reference section - Check existing patterns in the codebase - Identify dependencies or related features +- Use Read/Glob/Grep to explore relevant code + +**Note**: If the issue doesn't have this structure (e.g., older issues or manually created issues), do your best to extract similar information from whatever structure exists. ### 4. Generate Initial Plan Create a structured implementation plan with the following sections: +**IMPORTANT - Separation of Concerns:** +- The issue already contains Context, Requirement, and Solution (from `/make-task-issue`) +- **DO NOT re-do problem definition work** - use what's already in the issue +- **FOCUS ON** breaking down the solution into actionable implementation steps +- Your job is to create a concrete execution plan, not to redefine the problem + #### Problem Analysis -- **What**: Clear statement of what needs to be solved -- **Why**: Explanation of why this is important -- **Context**: Relevant background information +- **What**: Summarize from the issue's Requirement section (don't rewrite it) +- **Why**: Reference the issue's Context section (don't re-analyze it) +- **Context**: Pull from the issue's Context and Reference sections #### Solution Approach -- **Strategy**: High-level approach to solving the problem -- **Architecture**: Key design decisions and their rationale +- **Strategy**: If the issue has a Solution section, elaborate on it; if not, propose one +- **Architecture**: Key design decisions and their rationale (build on issue's Solution if provided) - **Alternatives Considered**: Other approaches and why they weren't chosen - **Trade-offs**: What we're optimizing for and what we're accepting #### Implementation Steps +**This is the primary focus of this command.** Break down the work into concrete, actionable steps. + For each step, include: - **Step description**: What will be done - **Rationale**: Why this step is necessary @@ -83,9 +102,10 @@ For each step, include: - **Dependencies**: What needs to be done first #### Success Criteria -- How will we know the implementation is complete? -- What should be tested? -- What documentation needs to be updated? +- Start with what's in the issue's Test Plan section (if provided) +- Add specific implementation verification steps +- Include what should be tested +- Note what documentation needs to be updated ### 5. Interactive Step-by-Step Review @@ -203,11 +223,18 @@ After analyzing the issue, the command will generate a plan like: ## Best Practices ### Analysis -- Read the issue thoroughly before planning +- Read the issue thoroughly, especially Context, Requirement, and Solution sections +- **Respect the work already done** in `/make-task-issue` - don't redo problem definition - Look for existing patterns in the codebase - Consider edge cases and error handling - Think about testing requirements +### Separation of Concerns +- **Problem definition** happens in `/make-task-issue` (Context, Requirement, Solution, Test Plan) +- **Implementation planning** happens in `/plan-issue` (breaking down into steps) +- Don't waste time re-analyzing what's already well-defined in the issue +- Focus your energy on creating a concrete, actionable execution plan + ### Communication - Be transparent about reasoning - Explain trade-offs clearly @@ -225,3 +252,4 @@ After analyzing the issue, the command will generate a plan like: - Order steps logically with dependencies clear - Include both "what" and "why" for each step - Make success criteria measurable +- **Primary focus**: Implementation Steps section - make it detailed and comprehensive diff --git a/.github/ISSUE_TEMPLATE/agent.md b/.github/ISSUE_TEMPLATE/agent.md index 7f22eac..822c3d5 100644 --- a/.github/ISSUE_TEMPLATE/agent.md +++ b/.github/ISSUE_TEMPLATE/agent.md @@ -7,24 +7,16 @@ assignees: "" --- -## Requirement -**What agent rule/command needs to be created/updated:** +## Context -## Implementation Plan (optional) -**Rule/Command type:** +## Requirement -**Trigger conditions:** -**Expected behavior:** +## Solution -**Files to be modified:** -## Should be tested +## Test Plan -- [ ] Rule/command should be tested locally -- [ ] Edge cases should be covered -- [ ] Documentation should be updated (if applicable) -- [ ] Documentation should referenced properly ## Reference diff --git a/.github/ISSUE_TEMPLATE/config.md b/.github/ISSUE_TEMPLATE/config.md index 95aeb09..ff6b8e6 100644 --- a/.github/ISSUE_TEMPLATE/config.md +++ b/.github/ISSUE_TEMPLATE/config.md @@ -7,16 +7,16 @@ assignees: "" --- +## Context + + ## Requirement -## Implementation plan(optional) -**Dependencies (if applicable):** +## Solution -## Should be tested +## Test Plan -- [ ] Configuration tested locally -- [ ] CI/CD pipeline verified (if applicable) ## Reference diff --git a/.github/ISSUE_TEMPLATE/doc.md b/.github/ISSUE_TEMPLATE/doc.md index 74d49d4..62529e4 100644 --- a/.github/ISSUE_TEMPLATE/doc.md +++ b/.github/ISSUE_TEMPLATE/doc.md @@ -7,20 +7,20 @@ assignees: "" --- +## Context + + + ## Requirement + -## Implementation Plan (optional) -**Documentation type:** +## Content Outline + -**Content outline:** -**Files to be modified:** +## Verification + -## Should be tested -- [ ] Documentation reviewed for accuracy -- [ ] Examples tested and working -- [ ] Consistency with existing documentation maintained -- [ ] References and links properly connected -## Reference (optionla) +## Reference diff --git a/.github/ISSUE_TEMPLATE/feat.md b/.github/ISSUE_TEMPLATE/feat.md index a3230ee..4fbc86c 100644 --- a/.github/ISSUE_TEMPLATE/feat.md +++ b/.github/ISSUE_TEMPLATE/feat.md @@ -7,22 +7,16 @@ assignees: "" --- -## Requirement +## Context -**What feature needs to be implemented:** -## Implementation Plan (optional) +## Requirement -**Feature scope:** -**Key components:** +## Solution -**Files to be modified:** -## Should be tested +## Test Plan -- [ ] Feature tested locally -- [ ] Edge cases covered -- [ ] Documentation updated (if applicable) -## Reference (optional) +## Reference diff --git a/.github/ISSUE_TEMPLATE/fix.md b/.github/ISSUE_TEMPLATE/fix.md index 73ff0cd..5d2fc3b 100644 --- a/.github/ISSUE_TEMPLATE/fix.md +++ b/.github/ISSUE_TEMPLATE/fix.md @@ -7,32 +7,20 @@ assignees: "" --- -## Summary +## Context + -A clear and concise description of what needs to be fixed. -## Steps to Reproduce (if applicable) +## Requirement + -1. -2. -3. -## Expected Behavior +## Solution + -## Current Behavior -## Root Cause (optional) +## Test Plan + -## Implementation Plan (optional) -**Files to be modified:** - -**Approach:** - -## Should be tested - -- [ ] Fix verified locally -- [ ] Regression testing completed -- [ ] Edge cases covered - -## Reference (optional) +## Reference diff --git a/.github/ISSUE_TEMPLATE/perf.md b/.github/ISSUE_TEMPLATE/perf.md index c4df061..3c50e24 100644 --- a/.github/ISSUE_TEMPLATE/perf.md +++ b/.github/ISSUE_TEMPLATE/perf.md @@ -7,29 +7,20 @@ assignees: "" --- -## Requirement - -**What needs performance improvement:** - -**Current performance issue:** +## Context + -**Target performance goal:** -## Implementation Plan (optional) - -**Approach:** +## Requirement + -**Optimization strategy:** -**Files to be modified:** +## Solution + -**Breaking changes (if any):** -## Should be tested +## Verification + -- [ ] Performance benchmarks run -- [ ] Improvement verified and measured -- [ ] No regression in other areas -- [ ] Documentation updated with performance notes -## Reference (optional) +## Reference diff --git a/.github/ISSUE_TEMPLATE/refactor.md b/.github/ISSUE_TEMPLATE/refactor.md index 4da0f06..8806c6e 100644 --- a/.github/ISSUE_TEMPLATE/refactor.md +++ b/.github/ISSUE_TEMPLATE/refactor.md @@ -7,27 +7,20 @@ assignees: "" --- -## Requirement - -**What needs to be refactored:** +## Context + -**Why this refactoring is needed:** -## Implementation Plan (optional) - -**Scope:** +## Requirement + -**Approach:** -**Files to be modified:** +## Solution + -**Breaking changes (if any):** -## Should be tested +## Verification + -- [ ] Refactored code tested locally -- [ ] No functional changes verified -- [ ] All existing tests still passing -- [ ] Code quality metrics improved (if applicable) -## Reference (optional) +## Reference diff --git a/.github/ISSUE_TEMPLATE/test.md b/.github/ISSUE_TEMPLATE/test.md index f464581..d1491e3 100644 --- a/.github/ISSUE_TEMPLATE/test.md +++ b/.github/ISSUE_TEMPLATE/test.md @@ -7,27 +7,20 @@ assignees: "" --- -## Requirement +## Context + -**What tests need to be added/improved:** -## Implementation Plan (optional) +## Requirement + -**Test type:** -- [ ] Unit tests -- [ ] Integration tests -- [ ] E2E tests -- [ ] Performance tests -**Test scope:** +## Test Scope + -**Files to be modified:** -## Should be tested +## Verification + -- [ ] Tests written and passing -- [ ] Coverage improved (if applicable) -- [ ] Edge cases covered -- [ ] Test documentation added -## Reference (optional) +## Reference