Add Github issue support to Claude Code

claude-code/.claude/commands/implement-gh-issue.md

@@ -0,0 +1,59 @@
+# Implement GitHub Issue
+
+Implement a feature based on a GitHub issue implementation plan.
+
+## Issue: $ARGUMENTS
+
+## Execution process
+
+1. **Load the implementation plan**
+
+- Look for the implementation plan in `docs/implementation-plans/gh-issue-{issue-number-or-name}.md`
+- If no plan exists, inform the user they need to run `/plan-gh-issue` first
+- Read and understand the context and requirements from the plan
+- Follow all instructions in the implementation plan document
+- Ensure you have all needed context to implement the requirements fully
+- Do more web and code base search as necessary
+
+1. **Plan the implementation**
+
+- Think before you execute the plan. Create a comprehensive plan addressing all requirements.
+- Break down complex tasks into smaller, manageable steps using your TODO tools.
+- Use the TodoWrite tool to create and track your implementation plan.
+- Identify implementation patterns from existing code to follow as specified in the plan.
+
+1. **Execute the plan**
+
+- Implement the requirements from the implementation plan document
+- Write the code necessary following the architectural patterns identified
+- Reference the specific files and examples mentioned in the plan
+- Follow the ordered task list provided in the implementation blueprint
+
+1. **Validate**
+
+- Run each validation gate specified in the plan
+- Execute test commands, linting, and quality checks as documented
+- Fix any failures
+- Re-run until all validation gates pass
+
+1. **Complete**
+
+- Ensure all checklist items from the plan are done
+- Run final validation suite
+- Report completion status
+- Read the implementation plan again to ensure you've implemented everything
+
+1. **Reference the implementation plan**
+
+- You can always reference the implementation plan document again
+- The plan contains all the research and context needed for successful implementation
+
+## Usage
+
+Use this command by providing the same identifier used in `/plan-gh-issue`:
+
+- `/implement-gh-issue 123` (for issue number 123)
+- `/implement-gh-issue feature-name` (for issues saved by name)
+- `/implement-gh-issue https://github.com/owner/repo/issues/123` (will extract issue number)
+
+The command will automatically locate the corresponding implementation plan file.

claude-code/.claude/commands/plan-gh-issue.md

@@ -0,0 +1,92 @@
+# Generate Implementation Plan from GitHub Issue
+
+## Issue: $ARGUMENTS
+
+Generate a complete implementation plan for a GitHub issue based on thorough
+research. **Start by researching the issue** from the provided GitHub issue URL
+or issue description to understand what needs to be done, how examples provide
+help, and any other considerations.
+
+**Important**: The implementation plan will be used by another Claude Code agent for
+implementation. Include all necessary context since the implementing agent only gets
+access to what you document here. The agent has access to the codebase and web search
+capabilities, so include specific URLs and code references.
+
+## Research Process
+
+### 0. Issue Analysis
+
+- Research the GitHub issue using web search if URL provided, or analyze the provided issue description
+- Extract the feature description, examples, documentation references, and considerations
+- Use this as the foundation for all subsequent research
+
+### 1. Codebase Analysis
+
+- Search for similar patterns/features in the workspace
+- Identify files to reference in the requirements document
+- Note existing conventions and architectural patterns to follow
+- Check test patterns and validation approaches
+
+### 2. External Research
+
+- Find relevant library documentation using web search (include specific URLs)
+- Look for implementation examples and best practices
+- Identify common pitfalls and gotchas
+- Research integration patterns and similar implementations
+
+### 3. Context Gathering
+
+- Identify specific patterns to mirror and their locations
+- Document integration requirements and dependencies
+- Note any version-specific considerations
+
+## Requirements Document Structure
+
+### Critical Context to Include
+
+- **Documentation URLs**: Link to specific sections found through web search
+- **Code Examples**: Real snippets from the codebase showing patterns to follow
+- **Architectural Patterns**: Existing approaches that should be mirrored
+- **Integration Points**: How this feature connects with existing code
+- **Gotchas**: Library quirks, version issues, common mistakes
+
+### Implementation Blueprint
+
+- Start with high-level approach and pseudocode
+- Reference specific files for patterns to follow
+- Include comprehensive error handling strategies
+- Provide ordered task list for step-by-step implementation
+- Document validation and testing approach
+
+### Validation Gates
+
+Define specific commands and criteria for validation:
+
+- Test commands (e.g., `npm test`, `dotnet test`, `python -m pytest`)
+- Linting and code quality checks
+- Performance benchmarks if applicable
+- Integration test requirements
+
+## Output Requirements
+
+Save the implementation plan as `docs/implementation-plans/gh-issue-{issue-number-or-name}.md`.
+The plan should be structured, clear, and detailed enough for another Claude Code agent
+to implement without needing further clarification.
+
+## Quality Checklist
+
+Before finishing, verify the requirements include:
+
+- [ ] All necessary context for autonomous implementation
+- [ ] Validation gates that are executable
+- [ ] References to existing patterns and conventions
+- [ ] Clear, ordered implementation path
+- [ ] Comprehensive error handling documentation
+- [ ] Main flow and alternate scenarios covered
+- [ ] Specific code examples and file references
+- [ ] Research from external sources with URLs
+
+**Quality Score**: Rate the requirements document on a scale from 1-10 for confidence
+in successful single-pass implementation using Claude Code. Explain the score and
+suggest improvements if below 8.
+

claude-code/README.md

@@ -20,9 +20,10 @@ Then, copy the following files to your project:
 ```text
 claude-code/.claude/commands/generate-plan.md   # Prompt template to create requirements documents.
 claude-code/.claude/commands/implement-plan.md  # Prompt template to implement requirements.
-claude-code/implementation-plans/.gitkeep       # Folder to store the requirements documents.
+claude-code/docs/implementation-plans/.gitkeep          # Folder to store the requirements documents.
 claude-code/src/.gitkeep                        # Source folder (optional)
 claude-code/CLAUDE.md                           # General instructions for the project
+claude-code/TASK.md                             # The template for the initial feature description
 ```
 
 If you're using this on a completely new repository I recommend setting up the
@@ -45,19 +46,31 @@ CLAUDE.md file. You'll need to provide the following:
 I recommend writing short and concise instructions for the LLM. This helps
 keep enough space available in the context window for actual work.
 
-**Tip**: Unsure of what to write in the `CLAUDE.md` file for your project? 
-You can ask Claude Code to generate the file for you. Use the `/init` 
+**Tip**: Unsure of what to write in the `CLAUDE.md` file for your project?
+You can ask Claude Code to generate the file for you. Use the `/init`
 command inside Claude Code to get an initial set of instructions based on
 what your project looks like.
 
-### Writing the work item instructions
+### Writing work item instructions
 
-Before you start using Claude Code to write code, you'll need to come up with
-an initial set of instructions for the requirements generation. Create a new
-file `TASK.md` in the root of the repository with the following content:
+After you've configured the instructions for your project you can start to work on
+implementing features. I included two methods for this in the repository:
+
+1. Planning work with Github Issues
+2. Planning work with TASK.md on your local computer
+
+**IMPORTANT:** If you plan to work with Github Issues you need to have [the Github MCP
+server](https://docs.anthropic.com/en/docs/claude-code/mcp) or the [Github
+CLI](https://cli.github.com/) installed.
+
+#### Planning work with TASK.md on your local computer
+
+The process of implementing a feature using the context engineering approach starts with
+generating an implementation plan. If you want to work locally without GitHub you can
+edit the `TASK.md` file in the root of the repository with the following content:
 
 ```text
-# Feature
+# Feature: <Feature Name>
 
 <Describe the feature that you want to implement here.>
 
@@ -80,31 +93,29 @@ things here that the agent is missing a lot.>
 I prefer to keep the `TASK.md` file checked in as a reminder to myself of what
 I need to provide as input for generating requirements.
 
-### Generate a requirements document
+#### Generate an implementation plan
 
-After you've created the requirements document, you can start to generate
-requirements. Start Claude Code with `claude` and then issue the following
-command:
+After you've created the work item in `TASK.md`, you can start to generate an implementation plan.
+Start Claude Code with `claude` and then issue the following command:
 
 ```bash
 /generate-plan TASK.md
 ```
 
-It will take a few minutes for Claude Code to write the full requirements
-document. You can continue to iterate on the requirements manually or by
-opening Claude Code in the terminal inside VSCode. The agent will automatically
-focus on the requirements document when you have it open in VSCode alongside
-Claude Code in the built-in terminal.
+It will take a few minutes for Claude Code to write the full implementation plan.
+You can continue to iterate on the implementation plan file in the same chat session.
 
 The generated requirements document will be stored in the `docs/implementation-plans`
 directory.
 
-Once you're happy with the requirements, you can start to generate code.
+Once you're happy with the plan, you can start to generate code. If you find that
+the generated plan gets too large, you can split the file into multiple separate
+planning documents. You can even ask Claude Code to do this for you.
 
-### Generating code
+#### Generating code
 
-Use the following command in the Claude Code terminal to kick off the
-implementation of the generated requirements document.
+Open the generated implementation plan, and use the following command in the Claude Code
+terminal to kick off the implementation of the generated requirements document.
 
 ```bash
 /implement-plan docs/implementation-plans/<your-plan-doc.md>
@@ -113,15 +124,69 @@ implementation of the generated requirements document.
 This will again take a few minutes to complete. This is a great time to get
 hydrated, take a bio break, and talk to a colleague.
 
+### Planning work with Github Issues
+
+If you prefer to use Github Issues as the basis for your feature implementation instead
+of the local `TASK.md` file you can use the `/plan-gh-issue "{issue-number}"`
+prompt in the Copilot Chat Window. Replace `{issue-number}` with the actual issue number.
+
+The `plan-gh-issue` prompt relies on the content of the referenced issue on GitHub. You
+also need to have [the Github MCP
+Server](https://docs.anthropic.com/en/docs/claude-code/mcp) installed. Alternatively
+Claude Code will use the [Github CLI](https://cli.github.com/) to access your repository
+information.
+
+**Tip:** If you don't know the issue number, use the issue title. Claude Code will find
+the issue in your Github repository.
+
+During testing I've found that creating a detailed issue description is important to get
+the best results. I therefore recommend that you write issues following a similar
+structure to the one displayed below.
+
+```text
+<Describe the feature that you want to implement here.>
+
+## Examples
+
+<Insert examples here. You can provide them inline, or list files located in
+the `examples` folder if you have longer examples.>
+
+## Documentation
+
+<Refer to any relevant documentation such as input from a client or online
+documentation for libraries you want to use in the implementation later.>
+
+## Other considerations
+
+<Provide other considerations that are relevant to the feature. You can list
+things here that the agent is missing a lot.>
+```
+
+Make sure to give the issue a clear title to help Claude Code come up with the
+correct implementation plan.
+
+When you execute the `/plan-gh-issue "{issue-number}"` prompt, the implementation plan
+will be posted as comment to your issue so you can edit and refine the plan on Github.
+As with all prompts, you can continue to iterate in the chat window.
+
+After generating the plan, you can implement the GitHub issue with the prompt
+`/implement-gh-issue "{issue-number}"`. Replace `{issue-number}` with the actual
+issue number.
+
 ### Reviewing code
 
 Once you have the code it's important to verify that the code is to your liking.
-You can do this by [configuring Claude Code as a
-PR reviewer](https://docs.anthropic.com/en/docs/claude-code/github-actions).
+You can ask Claude Code to review the code for you.
 
 I recommend manually reviewing your code because the AI can't catch every
 problem in your code.
 
+**Note:** The AI doesn't always produce the output you want. At least not completely.
+This is okay! Just continue to iterate in the chat session. If you're working on
+something really large, you can also commit the changes and
+[rebase](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) them later to clean
+up the history so you can go back and forth.
+
 ## Tips and tricks
 
 ### :bulb: Break up tasks into smaller pieces
@@ -166,3 +231,13 @@ This template uses a single `CLAUDE.md` file in the root but you can add more
 detail by putting a `CLAUDE.md` file within your project directories. For
 example, you can provide specific instructions for your web frontend by placing
 a `CLAUDE.md` in the web frontend directory.
+
+### :bulb: Not using GitHub? Don't worry, this works with other source control providers too
+
+I know that not everyone is using GitHub. Just modify the prompt template a bit, and
+install the correct MCP server. You may need to change the tool configuration a bit in
+the prompt. Refer to the [Claude Code MCP Server
+Documentation](https://docs.anthropic.com/en/docs/claude-code/mcp) for more information.
+
+- Gitlab MCP server: https://hub.docker.com/r/mcp/gitlab
+- Azure DevOps MCP server: https://github.com/microsoft/azure-devops-mcp