Development lifecycle commands for GitHub issues and testing workflows

version
1.0.0

Install

/plugin install dev-lifecycle@my-claude-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add rmakowiak/my-claude-marketplace.

Contents

Discovered from source

Commands 13

Commit and Manage Pull Request (GitHub)

Create a commit on a GitHub issue branch and manage the associated pull request. Follow the Instructions to commit changes, then create or update the PR.

Variables

files: $1 (optional - if not provided, stages all changes)

Instructions

1. Validate Branch

  • IMPORTANT: Check current branch with git branch --show-current
  • Verify the branch follows the pattern: <issue_number>/<issue_type>-<slug>
  • If branch is main or doesn't match the pattern, ERROR and stop:
    • "Cannot run issue:commit on branch '<branch_name>'. Must be on an issue branch with format: <issue_number>/<issue_type>-"
  • Extract the issue number from the branch name (the part before the /)

2. Create Commit

  • Generate commit message elements:
    • changes_class: Extract from branch (feat/fix/chore from the <issue_type> part)
    • changes_description: Brief description of changes (present tense, 50 chars max, no period)
  • Commit message format: <changes_class>: <commit_message>
    • IMPORTANT: Do NOT include issue number in commit message
    • Examples:
      • feat: add conversation history endpoint
      • fix: resolve chat validation error
      • chore: update API documentation
  • Stage changes:
    • IF files is provided: git add <files>
    • ELSE: git add -A
  • Run git diff HEAD to understand changes
  • Run git commit -m "<generated_commit_message>" to create commit

3. Check for Existing PR

  • Use gh pr list --head <current_branch_name> to check if PR exists
  • If PR exists:
    • Push the commit: git push origin <branch_name>
    • Fetch the issue details: gh issue view <issue_number>
    • Update PR description to include a summary of all work done so far
    • Use gh pr edit <pr_number> --body "<updated_description>"
  • If NO PR exists:
    • Push the branch: git push -u origin <branch_name>
    • Fetch the issue details: gh issue view <issue_number>
    • Create PR with:
      • Title format: #<issue_number>: <issue_title>
      • Body should include:
        • Brief summary of changes (1-2 paragraphs)
        • Link to issue: Resolves #<issue_number>
      • Use gh pr create --title "<title>" --body "<body>"

4. PR Description Format

When creating or updating PR description, use this format:

## Summary

<1-2 paragraph summary of what was implemented and why>

## Changes

<bulleted list of key changes made>
- Change 1
- Change 2
- Change 3

## Testing

<brief note on how to test the changes>

---

Resolves #<issue_number>

Report

After committing and managing PR, report:

  1. The commit message used
  2. Whether a new PR was created or an existing PR was updated
  3. The PR number and URL
  4. The issue number linked

Example for new PR:

āœ… Committed: feat: add conversation history endpoint
šŸ†• Created PR #45: #123: Add conversation history
šŸ”— https://github.com/<owner>/<repo>/pull/45
šŸ“Ž Resolves: #123

Example for existing PR:

āœ… Committed: feat: update conversation list UI
šŸ“¤ Pushed to existing PR #45: #123: Add conversation history
šŸ”— https://github.com/<owner>/<repo>/pull/45
šŸ“ Updated PR description with latest changes

Create GitHub Issue (GitHub)

Create a new GitHub issue using the exact specified markdown Issue Format. Follow the Instructions to create the issue and use the Relevant Files to focus on the right files.

Variables

issue_description: $1

Instructions

  • IMPORTANT: Read CLAUDE.md for project context, architecture patterns, and conventions.
  • IMPORTANT: You're creating a GitHub issue to track work based on the Issue Request that will add value to the application.
  • IMPORTANT: The Issue Request describes the work that will be done but remember we're not implementing it yet, we're creating the GitHub issue that will be used to track and implement the work based on the Issue Format below.
  • Research the codebase to understand existing patterns, architecture, and conventions before planning the issue:
    • Explore similar features already implemented
    • Understand the file structure and module organization
    • Identify existing patterns to follow
    • Find relevant test files and patterns
  • IMPORTANT: Replace every in the Issue Format with the requested value. Add as much detail as needed to implement the work successfully.
  • Use your reasoning model: THINK HARD about the requirements, design, technical approach, and implementation details.
  • Follow existing patterns and conventions in the codebase. Don't reinvent the wheel.
  • Design for extensibility and maintainability.
  • If you need a new library, mention it in the Technical Tasks section with installation command.
  • Don't use decorators. Keep it simple.
  • Respect requested files in the Relevant Files section.
  • Start your research by reading the CLAUDE.md and README.md files.
  • After creating the issue body, use the GitHub CLI to create the issue:
    • Use gh issue create with the formatted body
    • Add appropriate labels based on the issue type (e.g., "feature", "bug", "chore", "frontend", "backend", "fullstack")
    • Add any relevant feature area labels, try to choose from existing first, if does not work, create new label
  • After creation, report the issue number and URL

Relevant Files

Focus on the following files:

  • CLAUDE.md - Contains project context, architecture, patterns, and conventions.
  • README.md - Contains the project overview and setup instructions.
  • apps/api/src/** - Contains the backend codebase.
  • apps/ui/src/** - Contains the frontend codebase.
  • apps/api/*.http - Contains HTTP request examples for manual testing.
  • test/** - Contains tests

Ignore all other files in the codebase.

Issue Format

The GitHub issue body should be formatted as follows:

# <Issue Title>

**Type:** <Feature|Bug|Chore>
**Dependencies:** <list of issue numbers this depends on, or "None">

---

## User Story

**As a** <type of user>
**I want to** <action/goal>
**So that** <benefit/value>

---

## Scope

<describe the scope of work in 2-3 sentences, what will be done>

### What's Included
<bulleted list of specific features/functionality that will be implemented>
- Item 1
- Item 2
- Item 3

### What's NOT Included
<bulleted list of related features that are explicitly out of scope for this issue>
- Item 1
- Item 2
- Item 3

---

## Technical Tasks

<organize tasks by area/phase with clear h3 headers. Be specific and detailed. Include code examples where helpful. Break down into logical sections like "Backend - API Changes", "Frontend - Components", "Database Changes", "Testing", etc.>

### <Task Area 1>

- [ ] Task 1
  <optional: include code snippet or technical details>
- [ ] Task 2
- [ ] Task 3

### <Task Area 2>

- [ ] Task 1
- [ ] Task 2

### Update .http File

- [ ] Add relevant HTTP examples to test the changes manually
  ```http
  ### Example Request
  GET http://localhost:3001/api/...

Acceptance Criteria

<list specific, testable criteria that must be met for the issue to be considered complete. Be precise and measurable.>

<Category 1>

  • Criterion 1
  • Criterion 2

<Category 2>

  • Criterion 1
  • Criterion 2

Testing Checklist

<Test Category 1>

  1. Test Name

    • Step 1
    • Step 2
    • Expected result
  2. Test Name

    • Step 1
    • Step 2
    • Expected result

<Test Category 2>

  1. Test Name
    • Step 1
    • Step 2
    • Expected result

E2E Test Cases

<Feature Area 1>

  1. Test Case Name

    • Setup: Initial state/preconditions (e.g., user logged in, specific data exists)
    • Steps:
      1. User action (e.g., Navigate to /dashboard)
      2. System response (e.g., Dashboard loads with data)
      3. User action (e.g., Click "Add Meal" button)
      4. System response (e.g., Modal opens)
    • Expected Result: What should happen at the end of the flow
    • Assertions: Specific checks to make (e.g., meal appears in list, API called with correct data, UI updates)
  2. Test Case Name

    • Setup: ...
    • Steps: ...
    • Expected Result: ...
    • Assertions: ...

<Feature Area 2>

  1. Test Case Name
    • Setup, Steps, Expected Result, Assertions...

Error Scenarios

  1. Error Case Name
    • Setup: Preconditions that trigger the error
    • Steps: Actions that cause the error
    • Expected Result: How the error should be handled
    • Assertions: Error messages, UI state, etc.

Definition of Done

  • All technical tasks completed
  • All acceptance criteria met
  • Manual testing completed
  • Code follows existing patterns
  • No regressions introduced
  • .http file updated (if applicable)
  • Error handling implemented
  • Loading states implemented (if UI changes)

Notes

Design Decisions

Decision 1

  • Rationale

Decision 2

  • Rationale

Alternative Approaches Considered

Approach 1

  • Pros: ...
  • Cons: ...
  • Decision: ...

User Experience Flow

<if applicable, document the user flow in a step-by-step manner>

1. User action
2. System response
3. User action
4. System response

Future Enhancements (Out of Scope)

  • Enhancement 1
  • Enhancement 2
  • Enhancement 3

<add any additional sections relevant to this issue, such as:>

  • Accessibility Considerations
  • Performance Considerations
  • Security Considerations
  • Data Migration Notes
  • API Contract Changes
  • etc.

Review Points

When reviewing this issue, check:

  1. <Question 1>
  2. <Question 2>
  3. <Question 3> <list key questions/checkpoints for code review>

## Issue Request

$1

## Report

After creating the GitHub issue, report:
1. The GitHub issue number
2. The GitHub issue URL
3. The labels applied
4. Any related issues it was linked to

Example:

āœ… Created GitHub Issue #123: Add conversation history
šŸ”— URL: https://github.com/<owner>/<repo>/issues/123
šŸ·ļø  Labels: feature, backend, chat
šŸ“Ž Related: #456, #789

Implement GitHub Issue (GitHub)

Fetch a GitHub issue and implement it. Follow the Instructions to implement the issue then Report the completed work.

Variables

issue_number: $1

Instructions

  • IMPORTANT: First, fetch the GitHub issue using gh issue view {issue_number} to get the full issue details.
  • IMPORTANT: Before starting implementation, create and switch to a new branch:
    • Branch naming format: <issue_number>/<issue_type>-<slug>
      • issue_number: The GitHub issue number from $1 (e.g., "123")
      • issue_type: One of: feat, fix, chore (use "feat" for Feature issues, "fix" for Bug issues, "chore" for Chore issues)
      • slug: 2-4 words from the issue title, kebab-case, max 40 chars total for slug
      • Example: "123/feat-conversation-history" or "45/fix-chat-validation"
    • Use git checkout -b <branch_name> to create and switch to the branch
    • Confirm the branch was created successfully with git branch --show-current
  • IMPORTANT: Read CLAUDE.md for project context, architecture patterns, and conventions.
  • Read the issue carefully, understand all requirements, technical tasks, and acceptance criteria.
  • Think hard about the implementation approach and follow existing patterns in the codebase.
  • Implement all technical tasks listed in the issue.
  • Ensure all acceptance criteria are met.
  • Follow the testing checklist if provided.
  • Update the .http file if the issue involves API changes (per CLAUDE.md guidelines).
  • Use the TodoWrite tool to track progress through the implementation.
  • Mark tasks as complete in the GitHub issue as you finish them (use gh issue comment to add progress updates).
  • IMPORTANT: Run E2E tests as guardrails throughout implementation:
    • After each significant implementation milestone, run relevant E2E tests: pnpm test:e2e
    • If tests fail, fix the implementation before proceeding to the next task
    • Use E2E tests to validate the implementation matches requirements
    • Before marking the issue as complete, run the full E2E test suite
    • Ensure all relevant E2E tests pass
    • If E2E tests need to be updated due to intentional behavior changes, update them and document why
    • If new E2E tests are specified in the issue, implement them as part of the work
  • IMPORTANT: After implementation, update CLAUDE.md if any project-relevant changes were made:
    • New features added to "Current Features" section
    • New architectural patterns or conventions introduced
    • New key file locations or module structures
    • Changes to tech stack or dependencies
    • New development guidelines or best practices
    • Do NOT update if changes are purely bug fixes or minor refactors

Report

After implementation, provide:

  • Branch name used for implementation
  • Summary of the work completed in a concise bullet point list
  • Files and total lines changed with git diff --stat
  • Status of all acceptance criteria (which ones are met)
  • E2E test results (pass/fail, any tests updated or added)
  • Any notes or decisions made during implementation
  • Changes made to CLAUDE.md (if any) and why
  • Suggest next steps or related issues to tackle

GitHub Issue Review

Follow the Instructions below to review work done against a GitHub issue to ensure implemented features match requirements. Use the issue to understand the requirements and then use the git diff if available to understand the changes made. Capture screenshots of critical functionality paths as documented in the Instructions section. If there are issues, report them if not then report success.

Variables

issue_number: $1 (optional - if not provided, extract from current branch) run_id: generate a random 8 character hex string review_image_dir: <absolute path to codebase>/agents/<run_id>/review_img/

Instructions

1. Determine Issue Number

  • Check current branch with git branch --show-current
  • IF issue_number parameter is provided:
    • Use the provided issue number
  • ELSE:
    • Verify branch follows pattern: <issue_number>/<issue_type>-<slug>
    • If branch is main or doesn't match pattern, ERROR and stop:
      • "Cannot run issue:review on branch '<branch_name>'. Must provide issue number or be on an issue branch with format: <issue_number>/<issue_type>-"
    • Extract issue number from branch name (the part before the /)

2. Analyze Changes

  • Run git diff origin/main to see all changes made in current branch. Continue even if there are no changes related to the issue.
  • Fetch the GitHub issue using gh issue view {issue_number} to get the full issue details.
  • Read the issue to understand requirements

3. Setup Review Environment

  • IMPORTANT: Execute .claude/commands/issue/review/prepare_review_env.md to start the review environment
  • This will start both API and UI on review-specific ports using Docker Compose

4. Validate Implementation

  • IMPORTANT: If the work can be validated by UI validation then (if not skip the section):
    • Look for corresponding e2e test files in tests that mirror the feature name.
    • IF tests are found:
      • Use e2e test files only as navigation guides for screenshot locations, not for other purposes
    • ELSE:
      • Try to navigate yourself around the app
    • IMPORTANT: To be clear, we're not testing. We know the functionality works. We're reviewing the implementation against the issue to make sure it matches what was requested.
    • IMPORTANT: Take screen shots along the way to showcase the new functionality and any issues you find
      • Capture visual proof of working features through targeted screenshots
      • Navigate to the application and capture screenshots of only the critical paths based on the isue
      • Compare implemented changes with isue requirements to verify correctness
      • Do not take screenshots of the entire process, only the critical points.
      • IMPORTANT: Aim for 1-5 screenshots to showcase that the new functionality works as specified.
      • If there is a review issue, take a screenshot of the issue and add it to the review_issues array. Describe the issue, resolution, and severity.
      • Number your screenshots in the order they are taken like 01_<descriptive name>.png, 02_<descriptive name>.png, etc.
      • IMPORTANT: Be absolutely sure to take a screen shot of the critical point of the new functionality
      • IMPORTANT: Copy all screenshots to the provided review_image_dir
      • IMPORTANT: Store the screenshots in the review_image_dir and be sure to use full absolute paths.
      • Focus only on critical functionality paths - avoid unnecessary screenshots
      • Ensure screenshots clearly demonstrate that features work as specified
      • Use descriptive filenames that indicate what part of the change is being verified

5. Issue Severity Guidelines

  • Think hard about the impact of the issue on the feature and the user
  • Guidelines:
    • skippable - the issue is non-blocker for the work to be released but is still a problem
    • tech_debt - the issue is non-blocker for the work to be released but will create technical debt that should be addressed in the future
    • blocker - the issue is a blocker for the work to be released and should be addressed immediately. It will harm the user experience or will not function as expected.

6. Output Results

  • IMPORTANT: Return ONLY the JSON array with test results
  • IMPORTANT: Output your result in JSON format based on the Report section below.
  • IMPORTANT: Do not include any additional text, explanations, or markdown formatting
  • We'll immediately run JSON.parse() on the output, so make sure it's valid JSON
  • Ultra think as you work through the review process. Focus on the critical functionality paths and the user experience. Don't report issues if they are not critical to the feature.

7. Cleanup

  • After review is complete, execute .claude/commands/issue/review/cleanup_review_env.md to shutdown the review environment

Report

  • IMPORTANT: Return results exclusively as a JSON array based on the Output Structure section below.
  • success should be true if there are NO BLOCKING issues (implementation matches isue for critical functionality)
  • success should be false ONLY if there are BLOCKING issues that prevent the work from being released
  • review_issues can contain issues of any severity (skippable, tech_debt, or blocker)
  • screenshots should ALWAYS contain paths to screenshots showcasing the new functionality, regardless of success status. Use full absolute paths.
  • This allows subsequent agents to quickly identify and resolve blocking errors while documenting all issues

Output Structure

{
    success: "boolean - true if there are NO BLOCKING issues (can have skippable/tech_debt issues), false if there are BLOCKING issues",
    review_summary: "string - 2-4 sentences describing what was built and whether it matches the isue. Written as if reporting during a standup meeting. Example: 'The natural language query feature has been implemented with drag-and-drop file upload and interactive table display. The implementation matches the spec requirements for SQL injection protection and supports both CSV and JSON formats. Minor UI improvements could be made but all core functionality is working as isueified.'",
    review_issues: [
        {
            "review_issue_number": "number - the issue number based on the index of this issue",
            "screenshot_path": "string - /absolute/path/to/screenshot_that_shows_review_issue.png",
            "issue_description": "string - description of the issue",
            "issue_resolution": "string - description of the resolution",
            "issue_severity": "string - severity of the issue between 'skippable', 'tech_debt', 'blocker'"
        },
        ...
    ],
    screenshots: [
        "string - /absolute/path/to/screenshot_showcasing_functionality.png",
        "string - /absolute/path/to/screenshot_showcasing_functionality.png",
        "...",
    ]
}

Review Environment Quick Start

TL;DR

# Run automated review
/issue:review 79                    # With issue number
/issue:review                       # Auto-extract from branch

# Manual control
docker compose -f docker-compose.yml up -d --build    # Start
docker compose -f docker-compose.yml ps               # Status
docker compose -f docker-compose.yml logs -f          # Logs
docker compose -f docker-compose.yml down             # Stop

Ports

ServiceDevReview
API30013501
UI30003500

URLs

  • Review UI: http://localhost:3500
  • Review API: http://localhost:3501
  • Health Check: http://localhost:3501/health

Branch Format

<issue_number>/<issue_type>-<slug>

Examples:
79/feat-conversation-history
123/fix-auth-bug
456/chore-update-deps

Common Commands

Check if review env is running:

docker compose -f docker-compose.yml ps

View API logs:

docker compose -f docker-compose.yml logs -f api-review

View UI logs:

docker compose -f docker-compose.yml logs -f ui-review

Restart a service:

docker compose -f docker-compose.yml restart api-review

Rebuild after dependency changes:

docker compose -f docker-compose.yml up -d --build

Clean everything:

docker compose -f docker-compose.yml down -v
docker builder prune -f

Troubleshooting

Port in use:

lsof -ti:3500 3501 | xargs kill -9

Service not starting:

docker compose -f docker-compose.yml logs api-review

Changes not reflecting:

docker compose -f docker-compose.yml restart api-review ui-review

Start fresh:

docker compose -f docker-compose.yml down -v
docker compose -f docker-compose.yml up -d --build

Environment

Make sure .env exists with:

LLM_API_KEY=your-key
LLM_PROVIDER=openai

Output

Review creates directory:

agents/<run_id>/review_img/
ā”œā”€ā”€ 01_description.png
ā”œā”€ā”€ 02_description.png
└── ...

And outputs JSON:

{
  "success": true/false,
  "review_summary": "...",
  "review_issues": [...],
  "screenshots": [...]
}

See Also

  • README.md - Comprehensive documentation
  • prepare_review_env.md - Setup script details
  • cleanup_review_env.md - Teardown script details
  • /REVIEW_SETUP.md - Full migration guide

Issue Review Environment

This directory contains scripts for setting up and managing an isolated review environment using Docker Compose.

Overview

The review environment runs the application on separate ports from development:

  • API Review Port: 3501 (vs dev port 3001)
  • UI Review Port: 3500 (vs dev port 3000)

This allows you to:

  • Review changes in isolation without affecting your dev environment
  • Run automated reviews with screenshots
  • Test features on specific branches

Architecture

Docker Compose Setup

  • docker-compose.review.yml - Orchestrates both API and UI services
  • Dockerfile.review.api - API container configuration
  • Dockerfile.review.ui - UI container configuration

Package Scripts

Both API and UI have dev:review scripts that run on review ports:

  • apps/api/package.json - dev:review runs on port 3501
  • apps/ui/package.json - dev:review runs on port 3500

Usage

Manual Control

Start review environment:

docker compose -f docker-compose.yml up -d --build

Check status:

docker compose -f docker-compose.yml ps

View logs:

docker compose -f docker-compose.yml logs -f

Stop environment:

docker compose -f docker-compose.yml down

Stop and remove volumes:

docker compose -f docker-compose.yml down -v

Automated Review

The issue:review command automatically manages the environment:

With issue number:

/issue:review 79

Auto-extract from branch:

# On branch 79/feat-conversation-history
/issue:review

Scripts

prepare_review_env.md

  • Checks for running containers
  • Builds and starts Docker Compose services
  • Waits for services to be healthy
  • Verifies API and UI are accessible

cleanup_review_env.md

  • Stops and removes containers
  • Verifies ports are freed
  • Optional: Clean build cache

Environment Variables

API (Port 3501)

NODE_ENV=development
PORT=3501
API_URL=http://localhost:3501
UI_URL=http://localhost:3500

UI (Port 3500)

NODE_ENV=development
PORT=3500
NEXT_PUBLIC_API_URL=http://localhost:3501

Volume Mounts

Both services mount source code for hot-reload:

  • ./apps/api → /app/apps/api
  • ./apps/ui → /app/apps/ui
  • ./packages → /app/packages

Node modules are kept in the container for performance.

Troubleshooting

Port already in use:

# Check what's using the port
lsof -ti:3500
lsof -ti:3501

# Kill the process
kill -9 $(lsof -ti:3500)
kill -9 $(lsof -ti:3501)

Containers won't start:

# Check logs
docker compose -f docker-compose.yml logs

# Rebuild from scratch
docker compose -f docker-compose.yml down -v
docker compose -f docker-compose.yml up -d --build

Changes not reflected:

# Restart specific service
docker compose -f docker-compose.yml restart api-review
docker compose -f docker-compose.yml restart ui-review

Development Notes

  • Hot reload is enabled for both services
  • Containers persist until explicitly stopped
  • Separate from dev environment (ports 3000/3001)
  • Build cache is preserved between runs
  • Use .dockerignore to optimize build context

File Structure

.
ā”œā”€ā”€ docker-compose.review.yml       # Main orchestration
ā”œā”€ā”€ Dockerfile.review.api           # API container
ā”œā”€ā”€ Dockerfile.review.ui            # UI container
ā”œā”€ā”€ .dockerignore                   # Build context optimization
└── .claude/commands/issue/review/
    ā”œā”€ā”€ README.md                   # This file
    ā”œā”€ā”€ prepare_review_env.md       # Startup script
    └── cleanup_review_env.md       # Shutdown script

Cleanup Review Environment

Shutdown and cleanup the review environment Docker containers.

Instructions

1. Stop Review Containers

  • Stop and remove containers: pnpm docker-compose:down
  • OPTIONAL: Remove volumes if needed: pnpm docker-compose:down -- -v

2. Verify Cleanup

  • Check that containers are stopped: pnpm docker-compose:ps
  • Confirm ports are freed:
    • Port 3501 (API): lsof -ti:3501 should return nothing
    • Port 3500 (UI): lsof -ti:3500 should return nothing

3. Optional: Clean Build Cache

  • If you want to clean up Docker build cache (saves space):
    • docker builder prune -f

Notes

  • Use pnpm docker-compose:down instead of docker compose commands directly
  • Available commands: docker-compose:up, docker-compose:down, docker-compose:logs, docker-compose:restart, docker-compose:ps
  • This stops both API and UI review containers
  • Does not affect the main development environment (ports 3000/3001)
  • Volumes are preserved by default (use -- -v flag to remove)
  • Build cache is preserved by default (use builder prune to clean)

GitHub Issue Review Fix

Follow the Instructions below to fix issues identified during GitHub issue review. This command takes the JSON output from /github-issue:review and systematically fixes the identified issues based on their severity.

Variables

review_json: $1 (required - JSON string containing review results)

Instructions

1. Parse Review Input

  • Parse the provided review_json input
  • Validate it matches the expected structure:
    • success: boolean
    • review_summary: string
    • review_issues: array of issue objects
    • screenshots: array of screenshot paths
  • If parsing fails, ERROR and stop: "Invalid review JSON provided. Expected JSON matching review output structure."

2. Analyze Issues

  • Extract all issues from review_issues array
  • Group issues by severity:
    • blocker - Must be fixed immediately
    • tech_debt - Should be fixed but not blocking
    • skippable - Optional improvements
  • If there are no issues, output: "No issues found in review. All functionality matches requirements." and STOP.

3. Prioritize and Plan Fixes

  • Create a fix plan prioritizing in this order:
    1. All blocker issues first
    2. Then tech_debt issues
    3. Finally skippable issues if time permits
  • For each issue to fix:
    • Read the issue_description to understand the problem
    • Read the issue_resolution to understand the expected fix
    • View the screenshot_path if provided to see visual evidence of the issue
    • IMPORTANT: Use the TodoWrite tool to track each issue fix as a separate task

4. Fix Issues Systematically

For each issue in priority order:

  • Mark the todo as in_progress
  • Display to user:
    Fixing review issue #{review_issue_number} [{issue_severity}]
    Description: {issue_description}
    Resolution: {issue_resolution}
    
  • View the screenshot at screenshot_path to understand the visual context (if provided)
  • Locate the relevant code files based on the issue description
  • Implement the fix according to the issue_resolution
  • If the fix requires changes across multiple files, make all necessary changes
  • Mark the todo as completed when done

5. Verify Fixes

  • After fixing all blocker issues, inform the user:
    • "Fixed {count} blocker issue(s)"
    • List each fixed issue with its number and description
  • After fixing tech_debt issues, inform the user:
    • "Fixed {count} tech debt issue(s)"
    • List each fixed issue with its number and description
  • If skippable issues were addressed, inform the user similarly

6. Summary and Next Steps

  • Output a summary:
    Issue Review Fix Complete
    
    Fixed {total} issue(s):
    - {blocker_count} blocker(s)
    - {tech_debt_count} tech debt issue(s)
    - {skippable_count} skippable issue(s)
    
    Original Review Summary:
    {review_summary}
    
    Next Steps:
    - Run /issue:review again to verify all fixes
    - If successful, proceed with /issue:commit
    

7. Error Handling

  • If unable to fix an issue:
    • Document the reason in a comment
    • Inform the user which issue could not be fixed and why
    • Continue with remaining issues
  • If critical errors occur that prevent fixes:
    • Report the error clearly
    • Suggest manual intervention if needed

Guidelines

  • Fix issues incrementally and verify each fix works
  • Do not introduce new issues while fixing existing ones
  • Maintain code style and patterns consistent with the codebase
  • If an issue resolution is unclear, ask the user for clarification before proceeding
  • Use the screenshots as visual reference to understand the problem context
  • Focus on high-quality fixes rather than quick patches
  • Update tests if needed to cover the fixes

Prepare Review Environment

Set up the review environment using Docker Compose to run API and UI on review-specific ports.

Variables

API_PORT: 3501 UI_PORT: 3500

Instructions

1. Check for Running Containers

  • Check if review containers are already running: docker compose -f docker-compose.review.yml ps
  • If containers are running, skip to step 3

2. Start Review Environment

  • Build and start containers: pnpm docker-compose:up
  • Wait for services to be ready:
    • Check API health: Wait until curl -f http://localhost:3501/health succeeds (retry up to 30 seconds)
    • Check UI availability: Wait until curl -f http://localhost:3500 succeeds (retry up to 30 seconds)

3. Verify Environment

  • Confirm API is running: curl http://localhost:3501/health
  • Confirm UI is running: curl http://localhost:3500
  • Display container status: pnpm docker-compose:ps

Notes

  • API runs on port 3501 externally (3001 internally in Docker)
  • UI runs on port 3500 externally (3000 internally in Docker)
  • Services communicate via Docker private network (app-network)
  • UI connects to API at http://api:3001 (Docker hostname)
  • Both services run with hot-reload enabled via volume mounts
  • Use pnpm docker-compose:logs to view logs
  • Use pnpm docker-compose:down to shutdown when done

Update GitHub Issue (GitHub)

Update an existing GitHub issue to match the standard Issue Format. This command fetches the current issue content, incorporates your update request, and brings it to the standards defined in github-issue:create.

Variables

issue_number: $1

Instructions

  • IMPORTANT: Read CLAUDE.md for project context, architecture patterns, and conventions.
  • IMPORTANT: You're updating an existing GitHub issue to improve its structure, add missing details, or incorporate new requirements.
  • Fetch the existing issue using gh issue view $1 --json title,body,labels,state
  • Parse the existing issue content to understand:
    • Current title and description
    • What sections already exist
    • What details are already documented
    • What's missing or incomplete
  • Ask the user what updates they want to make to the issue (if not already provided in context)
  • Research the codebase to understand existing patterns, architecture, and conventions:
    • Explore similar features already implemented
    • Understand the file structure and module organization
    • Identify existing patterns to follow
    • Find relevant test files and patterns
  • IMPORTANT: Merge the existing content with your updates and ensure ALL sections from the Issue Format are present and complete.
  • IMPORTANT: Replace every in the Issue Format with concrete values. Add as much detail as needed to implement the work successfully.
  • Use your reasoning model: THINK HARD about the requirements, design, technical approach, and implementation details.
  • Follow existing patterns and conventions in the codebase. Don't reinvent the wheel.
  • Design for extensibility and maintainability.
  • If you need a new library, mention it in the Technical Tasks section with installation command.
  • Don't use decorators. Keep it simple.
  • Respect requested files in the Relevant Files section.
  • Start your research by reading the CLAUDE.md and README.md files.
  • After creating the updated issue body, use the GitHub CLI to update the issue:
    • Use gh issue edit $1 --body "<updated_body>" or use a temp file: gh issue edit $1 --body-file <temp_file>
    • Update labels if needed using gh issue edit $1 --add-label "label1,label2"
    • Update title if needed using gh issue edit $1 --title "new title"
  • After updating, report what changed and show the issue URL

Relevant Files

Focus on the following files:

  • CLAUDE.md - Contains project context, architecture, patterns, and conventions.
  • README.md - Contains the project overview and setup instructions.
  • apps/api/src/** - Contains the backend codebase.
  • apps/ui/src/** - Contains the frontend codebase.
  • apps/api/*.http - Contains HTTP request examples for manual testing.
  • test/** - Contains tests

Ignore all other files in the codebase.

Issue Format

The GitHub issue body should be formatted as follows (same as issue:create):

# <Issue Title>

**Type:** <Feature|Bug|Chore>
**Dependencies:** <list of issue numbers this depends on, or "None">

---

## User Story

**As a** <type of user>
**I want to** <action/goal>
**So that** <benefit/value>

---

## Scope

<describe the scope of work in 2-3 sentences, what will be done>

### What's Included
<bulleted list of specific features/functionality that will be implemented>
- Item 1
- Item 2
- Item 3

### What's NOT Included
<bulleted list of related features that are explicitly out of scope for this issue>
- Item 1
- Item 2
- Item 3

---

## Technical Tasks

<organize tasks by area/phase with clear h3 headers. Be specific and detailed. Include code examples where helpful. Break down into logical sections like "Backend - API Changes", "Frontend - Components", "Database Changes", "Testing", etc.>

### <Task Area 1>

- [ ] Task 1
  <optional: include code snippet or technical details>
- [ ] Task 2
- [ ] Task 3

### <Task Area 2>

- [ ] Task 1
- [ ] Task 2

### Update .http File

- [ ] Add relevant HTTP examples to test the changes manually
  ```http
  ### Example Request
  GET http://localhost:3001/api/...

Acceptance Criteria

<list specific, testable criteria that must be met for the issue to be considered complete. Be precise and measurable.>

<Category 1>

  • Criterion 1
  • Criterion 2

<Category 2>

  • Criterion 1
  • Criterion 2

Testing Checklist

<Test Category 1>

  1. Test Name

    • Step 1
    • Step 2
    • Expected result
  2. Test Name

    • Step 1
    • Step 2
    • Expected result

<Test Category 2>

  1. Test Name
    • Step 1
    • Step 2
    • Expected result

E2E Test Cases

<Feature Area 1>

  1. Test Case Name

    • Setup: Initial state/preconditions (e.g., user logged in, specific data exists)
    • Steps:
      1. User action (e.g., Navigate to /dashboard)
      2. System response (e.g., Dashboard loads with data)
      3. User action (e.g., Click "Add Meal" button)
      4. System response (e.g., Modal opens)
    • Expected Result: What should happen at the end of the flow
    • Assertions: Specific checks to make (e.g., meal appears in list, API called with correct data, UI updates)
  2. Test Case Name

    • Setup: ...
    • Steps: ...
    • Expected Result: ...
    • Assertions: ...

<Feature Area 2>

  1. Test Case Name
    • Setup, Steps, Expected Result, Assertions...

Error Scenarios

  1. Error Case Name
    • Setup: Preconditions that trigger the error
    • Steps: Actions that cause the error
    • Expected Result: How the error should be handled
    • Assertions: Error messages, UI state, etc.

Definition of Done

  • All technical tasks completed
  • All acceptance criteria met
  • Manual testing completed
  • Code follows existing patterns
  • No regressions introduced
  • .http file updated (if applicable)
  • Error handling implemented
  • Loading states implemented (if UI changes)

Notes

Design Decisions

Decision 1

  • Rationale

Decision 2

  • Rationale

Alternative Approaches Considered

Approach 1

  • Pros: ...
  • Cons: ...
  • Decision: ...

User Experience Flow

<if applicable, document the user flow in a step-by-step manner>

1. User action
2. System response
3. User action
4. System response

Future Enhancements (Out of Scope)

  • Enhancement 1
  • Enhancement 2
  • Enhancement 3

<add any additional sections relevant to this issue, such as:>

  • Accessibility Considerations
  • Performance Considerations
  • Security Considerations
  • Data Migration Notes
  • API Contract Changes
  • etc.

Review Points

When reviewing this issue, check:

  1. <Question 1>
  2. <Question 2>
  3. <Question 3> <list key questions/checkpoints for code review>

## Update Strategy

When updating the issue:

1. **Preserve Existing Content**: Keep all valuable information from the original issue
2. **Fill Gaps**: Add missing sections from the standard format
3. **Enhance Details**: Add more specificity to vague sections
4. **Maintain Consistency**: Ensure the updated issue follows the standard format exactly
5. **Update Labels**: Add or update labels to match the issue type and scope
6. **Preserve Checkboxes**: Keep checkbox states (checked/unchecked) from the original

## Report

After updating the GitHub issue, report:
1. The GitHub issue number
2. The GitHub issue URL
3. What sections were added/updated
4. What labels were changed (if any)
5. A summary of the key changes made

Example:

āœ… Updated GitHub Issue #123: Add conversation history
šŸ”— URL: https://github.com/<owner>/<repo>/issues/123
šŸ“ Changes:
   - Added complete User Story section
   - Enhanced Technical Tasks with code examples
   - Added missing E2E Test Cases section
   - Updated scope to clarify included/excluded features
šŸ·ļø  Labels: Added "frontend", kept existing "feature", "chat"

Resolve Failed E2E Test

Fix a specific failing E2E test using the provided failure details.

Variables

test_failure_json: $1

Instructions

  1. Analyze the E2E Test Failure

    • Review the JSON data in the Test Failure Input, paying attention to:
      • test_name: The name of the failing test
      • test_path: The path to the test file (you will need this for re-execution)
      • error: The specific error that occurred
      • screenshots: Any captured screenshots showing the failure state
    • Understand what the test is trying to validate from a user interaction perspective
  2. Understand Test Execution

    • Read .claude/commands/test/test_e2e.md to understand how E2E tests are executed
    • Read the test file specified in the test_path field from the JSON
    • Note the test steps, user story, and success criteria
  3. Reproduce the Failure

    • IMPORTANT: Use the test_path from the JSON to re-execute the specific E2E test
    • Follow the execution pattern from .claude/commands/test/test_e2e.md
    • Observe the browser behavior and confirm you can reproduce the exact failure
    • Compare the error you see with the error reported in the JSON
  4. Fix the Issue

    • Based on your reproduction, identify the root cause
    • Make minimal, targeted changes to resolve only this E2E test failure
    • Consider common E2E issues:
      • Element selector changes
      • Timing issues (elements not ready)
      • UI layout changes
      • Application logic modifications
    • Ensure the fix aligns with the user story and test purpose
  5. Validate the Fix

    • Re-run the same E2E test step by step using the test_path to confirm it now passes
    • IMPORTANT: The test must complete successfully before considering it resolved
    • Do NOT run other tests or the full test suite
    • Focus only on fixing this specific E2E test

Test Failure Input

$1

Report

Provide a concise summary of:

  • Root cause identified (e.g., missing element, timing issue, incorrect selector)
  • Specific fix applied
  • Confirmation that the E2E test now passes after your fix

Resolve Failed Test

Fix a specific failing test using the provided failure details.

Variables

test_failure_json: $1

Instructions

  1. Analyze the Test Failure

    • Review the test name, purpose, and error message from the Test Failure Input
    • Understand what the test is trying to validate
    • Identify the root cause from the error details
  2. Context Discovery

    • Check recent changes: git diff origin/main --stat --name-only
    • If a relevant spec exists in specs/*.md, read it to understand requirements
    • Focus only on files that could impact this specific test
  3. Reproduce the Failure

    • IMPORTANT: Use the execution_command provided in the test data
    • Run it to see the full error output and stack trace
    • Confirm you can reproduce the exact failure
  4. Fix the Issue

    • Make minimal, targeted changes to resolve only this test failure
    • Ensure the fix aligns with the test purpose and any spec requirements
    • Do not modify unrelated code or tests
  5. Validate the Fix

    • Re-run the same execution_command to confirm the test now passes
    • Do NOT run other tests or the full test suite
    • Focus only on fixing this specific test

Test Failure Input

$1

Report

Provide a concise summary of:

  • Root cause identified
  • Specific fix applied
  • Confirmation that the test now passes

Application Validation Test Suite

Execute comprehensive validation tests for both frontend and backend components, returning results in a standardized JSON format for automated processing.

Purpose

Proactively identify and fix issues in the application before they impact users or developers. By running this comprehensive test suite, you can:

  • Detect syntax errors, type mismatches, and import failures
  • Identify broken tests or security vulnerabilities
  • Verify build processes and dependencies
  • Ensure the application is in a healthy state

Variables

TEST_COMMAND_TIMEOUT: 5 minutes

Instructions

  • Execute each test in the sequence provided below
  • Capture the result (passed/failed) and any error messages
  • IMPORTANT: Return ONLY the JSON array with test results
    • IMPORTANT: Do not include any additional text, explanations, or markdown formatting
    • We'll immediately run JSON.parse() on the output, so make sure it's valid JSON
  • If a test passes, omit the error field
  • If a test fails, include the error message in the error field
  • Execute all tests even if some fail
  • Error Handling:
    • If a command returns non-zero exit code, mark as failed and immediately stop processing tests
    • Capture stderr output for error field
    • Timeout commands after TEST_COMMAND_TIMEOUT
    • IMPORTANT: If a test fails, stop processing tests and return the results thus far
  • Some tests may have dependencies (e.g., server must be stopped for port availability)
  • API health check is required
  • Test execution order is important - dependencies should be validated first
  • All file paths are relative to the project root
  • Always run pwd and cd before each test to ensure you're operating in the correct directory for the given test

Test Execution Sequence

Backend Tests

  1. TS Syntax Check

    • Preparation Command: None
    • Command: pnpm run typechec
    • test_name: "typecheck"
    • test_purpose: "Validates TS syntax by compiling source files to bytecode, catching syntax errors like missing colons, invalid indentation, or malformed statements"
  2. TS Quality Check

    • Preparation Command: None
    • Command: pnpm run lint
    • test_name: "linting"`
    • test_purpose: "Validates TS code quality, identifies unused imports, style violations, and potential bugs"`
  3. All Tests

    • Preparation Command: None
    • Command: pnpm run test
    • test_name: "tests"
    • test_purpose: "Validates all backend functionality including file processing, SQL security, LLM integration, and API endpoints"
  4. All Builds

  • Preparation Command: None
  • Command: pnpm run build
  • test_name: "build"
  • test_purpose: "Validates all backend functionality including file processing, SQL security, LLM integration, and API endpoints"

Report

  • IMPORTANT: Return results exclusively as a JSON array based on the Output Structure section below.
  • Sort the JSON array with failed tests (passed: false) at the top
  • Include all tests in the output, both passed and failed
  • The execution_command field should contain the exact command that can be run to reproduce the test
  • This allows subsequent agents to quickly identify and resolve errors

Output Structure

[
  {
    "test_name": "string",
    "passed": boolean,
    "execution_command": "string",
    "test_purpose": "string",
    "error": "optional string"
  },
  ...
]

Example Output

[
  {
    "test_name": "all_backend_tests",
    "passed": true,
    "execution_command": "cd app/server && uv run pytest tests/ -v --tb=short",
    "test_purpose": "Validates all backend functionality including file processing, SQL security, LLM integration, and API endpoints"
  }
]

Sponsors

Details

Marketplace
rmakowiak/my-claude-marketplace
Source
plugins/dev-lifecycle
Category
Development
Keywords
github, issues, testing, workflow, development