implement-issue

Automatically implement a GitHub issue by pulling it down, solving it with the appropriate specialist agent, and creating a PR with the solution.

Usage

/implement-issue {issue_number_or_url_or_file}

Examples

• /implement-issue 5 - Implement GitHub issue #5 or local issue file /issues/5.md
• /implement-issue https://github.com/owner/repo/issues/5 - Implement issue from GitHub URL
• /implement-issue issues/5.md - Implement local issue file

Description

This command automates the entire workflow from issue to implementation:

1. Fetches the issue details from GitHub or reads from local /issues/{number}.md
2. Analyzes the issue to determine the appropriate specialist agent
3. Creates a feature branch for the implementation (if using Git/GitHub)
4. Invokes the specialist agent to solve the issue
5. Validates that the project builds and tests pass
6. Commits the changes and pushes to remote (if using Git/GitHub)
7. Creates a pull request linking back to the issue (if using GitHub)
8. Updates the local issue file status to 'completed' (if using local files)

Workflow

1. Issue Retrieval

• First, check if GitHub is available by testing gh auth status
• If GitHub is available:
  • Fetch issue details using gh issue view {number}
• If GitHub is NOT available or input is a file path:
  • Read the issue from /issues/{number}.md
  • Parse YAML frontmatter for metadata
• Parse issue body for implementation requirements
• Extract recommended specialist agent if specified
• Identify success criteria and dependencies

2. Branch Creation

• If using GitHub:
  • Create branch named issue-{number}-{slug}
  • Switch to the new branch
  • Ensure branch is up to date with main
• If using local files only:
  • Skip branch creation (work in current branch)

3. Agent Selection

The command looks for agent recommendations in the issue body:

• Pattern: @agent-{name} or "handled by {agent}"
• Falls back to analyzing issue labels and content
• Maps issue types to appropriate specialists

4. Implementation

• Invoke the selected specialist agent with:
  • Issue description as context
  • Success criteria as requirements
  • Any code references or examples
• Agent performs the implementation autonomously

5. Validation

Before creating the PR, validate:

• All changes are syntactically correct
• Project builds successfully (if build command exists)
• All tests pass (if test command exists)
• Linting passes (if lint command exists)
• No merge conflicts with main branch

6. Commit and Push

• Stage all changes
• Create descriptive commit message referencing the issue
• If using GitHub:
  • Push branch to remote repository
• If using local files:
  • Commit to current branch

7. Completion

• If using GitHub:
  • Create PR with:
    • Title: "Fix #{issue_number}: {issue_title}"
    • Body: MUST include a reference to the source issue at the top
      • Example: ## Resolves\nCloses #{issue_number}\n\n{summary_of_changes}
      • Or: ## Related Issue\nImplements #{issue_number}\n\n{summary_of_changes}
      • Include summary of changes and test results
    • Labels: Inherits from issue
    • Reviewers: Auto-assigned if configured
  • After PR is created, update the issue with a link to the PR:
    • Use gh issue comment {issue_number} to add a comment linking to the PR
    • Example: gh issue comment {issue_number} --body "Implementation PR created: #{pr_number}"
• If using local files:
  • Update /issues/{number}.md frontmatter: set status: in_review (or completed if no PR workflow)
  • Add completion timestamp to frontmatter: completed_at: {timestamp}
  • Add pull_request: {pr_number_or_branch} to frontmatter if tracking locally
  • Add a "Pull Request" section to the issue body with a link to the PR or branch
  • If issue has a parent, update parent's subtask checklist

Local Issue File Format

When implementing from local files, the issue file contains metadata in YAML frontmatter:

---
number: 5
title: "Create plugin validation system"
labels:
  - feature
  - testing
priority: High
agent: test-automator
dependencies: []
status: open
created_at: 2024-10-01T10:00:00Z
---

## Task Overview
Implement a validation system for plugins...

## Success Criteria
- [ ] Plugin validation logic implemented
- [ ] Unit tests added
- [ ] Integration tests passing

## Recommended Specialist
@agent-test-automator

After implementation, the frontmatter is updated:

---
number: 5
title: "Create plugin validation system"
status: in_review
completed_at: 2024-10-02T15:30:00Z
implemented_by: agent-test-automator
pull_request: 42
---

## Task Overview
Implement a validation system for plugins...

## Success Criteria
- [x] Plugin validation logic implemented
- [x] Unit tests added
- [x] Integration tests passing

## Pull Request
Implementation completed in PR #42: https://github.com/owner/repo/pull/42

## Recommended Specialist
@agent-test-automator

Agent Mapping

Issue Labels/Keywords	Selected Agent
security	@agent-security-master
performance	@agent-performance-optimizer
architecture	@agent-architect
documentation	@agent-code-documentor
test, testing	@agent-test-automator
refactor	@agent-refactorer
modernize, upgrade	@agent-code-modernizer
build, ci/cd	@agent-build-master
config, configuration	@agent-configuration-manager
bug, fix	@agent-debugger
error, exception	@agent-exception-handling-master
logging, logs	@agent-logging-master
tooling, dx	@agent-toolsmith
i18n, localization	@agent-internationalization-specialist
a11y, accessibility	@agent-accessibility-specialist

Error Handling

The command handles various failure scenarios:

• Issue not found: Prompts for valid issue number
• No specialist identified: Asks user to specify
• Build/test failures: Reports errors and asks for guidance
• Merge conflicts: Attempts automatic resolution or asks for help
• PR creation failure: Provides manual instructions

Options

• --no-tests: Skip test validation
• --no-build: Skip build validation
• --draft: Create PR as draft
• --agent {name}: Override agent selection
• --branch {name}: Use custom branch name

Example Output

GitHub Workflow

Implementing issue #5: Create plugin validation system
✓ Fetched issue details from GitHub
✓ Created branch: issue-5-plugin-validation
✓ Selected agent: @agent-test-automator
✓ Implementation in progress...
✓ Build successful
✓ Tests passing (15/15)
✓ Changes committed
✓ Branch pushed to remote
✓ Pull request created: #24
✓ Updated issue #5 with PR link

View PR: https://github.com/owner/repo/pull/24

Local File Workflow

Implementing issue #5: Create plugin validation system
✓ Read issue from /issues/5.md
✓ Selected agent: @agent-test-automator
✓ Implementation in progress...
✓ Build successful
✓ Tests passing (15/15)
✓ Changes committed
✓ Updated /issues/5.md status to in_review
✓ Added PR reference to issue file

Issue completed at: 2024-10-02T15:30:00Z
Implementation branch: issue-5-plugin-validation

Requirements

• For GitHub workflow:
  • GitHub CLI (gh) must be installed and authenticated
  • Git repository with GitHub remote
• For local file workflow:
  • Issues stored in /issues/{number}.md with YAML frontmatter
• Issues must be well-formed with clear requirements
• Appropriate specialist agents must be available

Notes

• This command embodies the full DevOps cycle
• Reduces manual work from hours to minutes
• Ensures consistent quality through validation
• Maintains traceability between issues and PRs