---

name: github-workflow description: This skill should be used when the user asks to "create a PR", "address review comments", "resolve review threads", "retrigger Q review", "/q review", "respond to Amazon Q", "/codex review", "respond to Codex", "handle reviewer findings", "merge PR", "push changes", "check CI status", or mentions PR workflow, code review, reviewer bots, or GitHub Actions checks.

GitHub Development Workflow

This skill provides standardized guidance for the complete GitHub development workflow, including branch management, PR creation, CI monitoring, and reviewer bot interaction.

Development Workflow Overview

Follow this 10-step workflow for all feature development and bug fixes:

Step 1: CREATE WORKTREE + BRANCH
  Use git worktree for isolated development:
    git worktree add .worktrees/<name> -b fix/<name>
  Or for simple changes:
    git checkout -b feat/<name> or fix/<name>
       ↓
Step 2: IMPLEMENT CHANGES
  - Write code
  - Write new unit tests for new functionality
  - Update existing tests if behavior changed
  - **For bug fixes**: MUST add a regression test (unit test or E2E check)
    that would have caught the bug. This prevents the same bug from
    recurring. Update E2E_TEST_CASES.md acceptance criteria if applicable.
  - Write/update E2E test cases if needed
       ↓
Step 3: LOCAL VERIFICATION
  - npm run build
  - npm run test
  - Deploy and verify (if applicable)
       ↓
Step 4: COMMIT AND CREATE PR
  - git add && git commit -m "type(scope): description"
  - git push -u origin <branch-name>
  - Create PR via GitHub MCP or gh CLI
  - Include checklist in PR description (see template below)
       ↓
Step 5: WAIT FOR PR CHECKS
  - Monitor GitHub Actions checks
  - If FAIL → Return to Step 2
  - If PASS → Update PR checklist, proceed to Step 6
       ↓
Step 6: ADDRESS REVIEWER BOT FINDINGS
  - Review all bot comments (Amazon Q, Codex, etc.)
  - Fix issues or document design decisions
  - Reply DIRECTLY to each comment thread
  - RESOLVE each conversation
  - Retrigger review: /q review, /codex review
       ↓
Step 7: ITERATE UNTIL NO FINDINGS
  - Check for new bot findings
  - If new findings → Return to Step 6
  - If no findings → Update PR checklist, proceed to Step 8
       ↓
Step 8: DEPLOY TO STAGING
  - Deploy changes to test/staging environment
  - Verify deployment succeeds
  - Update PR checklist
       ↓
Step 9: EXECUTE E2E TESTS (MANDATORY)
  - Use test/select-e2e-tests.sh to determine required tests
  - Use test/select-e2e-tests.sh --all for full test suite
  - Use Chrome DevTools MCP server for browser automation
  - Run tests based on change category (see E2E Test Selection below)
  - If ANY test FAILS → Return to Step 2
    - Fix bugs or add missing test cases
    - Push fixes and repeat from Step 5
  - If ALL tests PASS → Update PR checklist, proceed to Step 10
       ↓
Step 10: READY FOR MERGE (DO NOT MERGE)
  - All CI checks passed
  - All reviewer comments addressed
  - Staging deployment verified
  - E2E tests passed
  - Update PR checklist to show all items complete
  - STOP HERE: Report status to user
  - User decides when to merge

Git Worktree Usage

Use git worktrees to work on features, bug fixes, docs, or any git commits/PRs in an isolated workspace without affecting the current branch.

When to Use Worktrees

Scenario	Use Worktree?
Bug fix while another branch has uncommitted work	Yes
Feature development alongside existing work	Yes
Parallel work on multiple PRs	Yes
Quick single-file edit on current branch	No
Docs-only change on current branch	No

Step 1: Create Worktree

# Ensure .worktrees/ is in .gitignore (one-time setup)
git check-ignore -q .worktrees || echo ".worktrees/" >> .gitignore

# Create worktree with new branch from main
git fetch origin main
git worktree add .worktrees/<name> -b <branch-type>/<name> origin/main
cd .worktrees/<name>

# Install dependencies (worktrees don't share node_modules)
npm install

Branch naming: feat/<name>, fix/<name>, refactor/<name>, docs/<name>

Step 2: Work in the Worktree

# All git operations happen in the worktree directory
cd .worktrees/<name>

# Build, test, commit as usual
npm run build && npm run test
git add <files> && git commit -m "type(scope): description"
git push -u origin <branch-name>

Important: The shared .venv/ (Python) lives in the main repo. Run Python tests with the full path:

/path/to/main-repo/.venv/bin/python -m pytest docker/test_*.py -v

Step 3: Copy Local Files (if needed)

Gitignored files (deploy scripts, local config) don't exist in worktrees:

cp /path/to/main-repo/deploy-staging.local.sh .worktrees/<name>/
cp /path/to/main-repo/CLAUDE.local.md .worktrees/<name>/

Step 4: Cleanup After Merge

# Remove worktree after PR is merged
git worktree remove .worktrees/<name>

# Or force-remove if there are uncommitted changes
git worktree remove --force .worktrees/<name>

# Delete the branch
git branch -d <branch-type>/<name>

Quick Reference

git worktree list                              # List all worktrees
git worktree add .worktrees/foo -b fix/foo     # Create new worktree
git worktree remove .worktrees/foo             # Remove worktree

E2E Test Selection

Run test/select-e2e-tests.sh to automatically determine which tests to run based on changed files.

Test Categories by Change Type

Change Category	Files Changed	Required Tests
Core (always)	Any	TC-003, TC-004, TC-005
Auth/Lambda@Edge	lib/lambda-edge/, edge-stack.ts	+ TC-011, TC-012, TC-013, TC-018
Compute/Docker	docker/, compute-stack.ts	+ TC-006, TC-007, TC-008, TC-009, TC-010
ECS/Persistence	compute-stack.ts, EFS config	+ TC-014, TC-021
Sandbox AWS	security-stack.ts, sandbox role	+ TC-017
MCP Config	config/config.toml, MCP settings	+ TC-015, TC-016
User Config	user-config-stack.ts, lambda/user-config/	+ TC-019, TC-020

Quick Reference: All Test Cases

TC#	Name	When to Run
TC-001	Deploy Infrastructure	Manual deployment only
TC-002	Create Test User	First-time setup only
TC-003	Login via Chrome DevTools	Always
TC-004	Verify Conversation List	Always
TC-005	Start New Conversation	Always
TC-006	Execute Flask Todo App	Docker/runtime changes
TC-007	Verify Runtime Accessible	Docker/runtime changes
TC-008	Verify In-App Routing	Docker/runtime changes
TC-009	Verify Web App Subdomain	Docker/runtime changes
TC-010	Verify VS Code URL Rewriting	Docker/patch-fix.js changes
TC-011	Cross-User Access Denied	Auth/authorization changes
TC-012	Unauthenticated Access Denied	Auth changes
TC-013	Main App Access Works	Auth changes (regression)
TC-014	Resume After ECS Task Recycling	ECS/persistence changes
TC-015	AWS Docs MCP Server	MCP config changes
TC-016	Chrome DevTools MCP Server	MCP/runtime image changes
TC-017	Sandbox AWS Access	Sandbox credentials changes
TC-018	Logout Functionality	Auth/patch-fix.js changes
TC-019	Secrets Page User Isolation	User config changes
TC-020	Settings Pages User Isolation	User config changes
TC-021	Secrets Persist After ECS Task Recycling	ECS/persistence changes

Using the Test Selector

# From repo root, compare against main branch
./test/select-e2e-tests.sh

# Compare against specific branch
./test/select-e2e-tests.sh origin/main

# Example output:
# Required E2E Tests for this PR:
# ================================
# Core tests (always required):
#   TC-003: Login via Chrome DevTools
#   TC-004: Verify Conversation List
#   TC-005: Start New Conversation
#
# Additional tests based on changes:
#   TC-007: Verify Runtime Accessible (docker/ changes)
#   TC-014: Resume After ECS Task Recycling (compute-stack changes)
#   TC-021: Secrets Persist After ECS Task Recycling (docker/ changes)

PR Description Template

When creating a PR, include this checklist in the description. Update it as each step completes:

## Test plan

- [ ] Build passes (`npm run build`)
- [ ] Unit tests pass (`npm run test`)
- [ ] CI checks pass
- [ ] Reviewer bot findings addressed (no new findings)
- [ ] Deployed to staging
- [ ] **E2E tests pass** (run `./test/select-e2e-tests.sh` for required tests)
  - [ ] TC-003: Login
  - [ ] TC-004: Conversation List
  - [ ] TC-005: New Conversation
  - [ ] (add change-specific tests from selector output)

## Checklist

- [ ] New unit tests written for new functionality
- [ ] E2E test cases updated if needed
- [ ] Documentation updated if needed

Update PR Checklist Command

After completing each step, update the PR description:

# Get current PR body
gh pr view {pr_number} --json body --jq '.body' > /tmp/pr_body.md

# Edit the checklist (mark items as [x])
# Then update the PR
gh pr edit {pr_number} --body "$(cat /tmp/pr_body.md)"

Or use the GitHub MCP tool to update the PR body directly.

PR Check Monitoring

Monitor CI Status

# Watch all checks until completion
gh pr checks {pr_number} --watch --interval 30

# Quick status check
gh pr checks {pr_number}

Checks to Monitor

Check	Description	Action if Failed
CI / build-and-test	Build + unit tests	Fix code or update snapshots
Security Scan	SAST, npm audit	Fix security issues
Amazon Q Developer	Security review	Address findings, retrigger with /q review
Codex	AI code review	Address findings, retrigger with /codex review
Other review bots	Various checks	Address findings, retrigger per bot docs

Reviewer Bot Workflow

Multiple review bots can provide automated code review findings on PRs:

Bot	Trigger Command	Bot Username
Amazon Q Developer	/q review	amazon-q-developer[bot]
Codex	/codex review	codex[bot]
Other bots	See bot documentation	Varies

Handling Bot Review Findings

1. Review all comments - Read each finding carefully
2. Determine action:
   • If valid issue → Fix the code and push
   • If false positive → Reply explaining the design decision
3. Reply to each thread - Use direct reply, not general PR comment
4. Resolve each thread - Mark conversation as resolved
5. Retrigger review - Comment with appropriate trigger (e.g., /q review, /codex review)

Retrigger Bot Reviews

After addressing findings, trigger a new scan:

# Amazon Q Developer
gh pr comment {pr_number} --body "/q review"

# Codex
gh pr comment {pr_number} --body "/codex review"

Wait 60-90 seconds for the review to complete, then check for new comments.

Iteration Loop (CRITICAL)

Repeat until review bots find no more issues:

1. Address findings (fix code or explain design)
2. Reply to each comment thread
3. Resolve all threads
4. Trigger review command (/q review, /codex review, etc.)
5. Wait 60-90 seconds
6. Check for new findings
7. If new findings → repeat from step 1
8. Only proceed to merge when no new positive findings appear

This loop is essential - review bots may find new issues in your fixes.

Review Thread Management

Critical Rules

• Reply DIRECTLY to each comment thread - NOT a single general PR comment
• Resolve each conversation after replying
• Wrong approach: gh pr comment {pr} --body "Fixed all issues" (doesn't close threads)

Reply to Review Comments

# Get comment IDs
gh api repos/{owner}/{repo}/pulls/{pr}/comments \
  --jq '.[] | {id: .id, path: .path, body: .body[:50]}'

# Reply to specific comment
gh api repos/{owner}/{repo}/pulls/{pr}/comments \
  -X POST \
  -f body="Addressed in commit abc123 - <description of fix>" \
  -F in_reply_to=<comment_id>

Resolve Review Threads

# Get unresolved thread IDs
gh api graphql -f query='
query {
  repository(owner: "{owner}", name: "{repo}") {
    pullRequest(number: {pr}) {
      reviewThreads(first: 50) {
        nodes {
          id
          isResolved
          comments(first: 1) {
            nodes { body }
          }
        }
      }
    }
  }
}' --jq '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved == false) | .id'

# Resolve a thread
gh api graphql -f query='
mutation {
  resolveReviewThread(input: {threadId: "<thread_id>"}) {
    thread { isResolved }
  }
}'

Batch Resolve All Threads

Use the scripts/resolve-threads.sh script to resolve all unresolved threads at once:

./skills/github-workflow/scripts/resolve-threads.sh {owner} {repo} {pr_number}

Common Response Patterns

For Valid Issues

Addressed in commit {hash} - {description of fix}

Example:

Addressed in commit abc123 - Updated Lambda@Edge handler to use external file pattern

For False Positives

This is by design because {explanation}. The {feature} requires {justification}.

Example:

This is documentation for authorized operators. The commands require IAM permissions that only administrators have. IAM access controls prevent unauthorized access, not documentation obscurity.

For Documentation Concerns

The referenced file {filename} exists in the repository at {path}. This is a reference document, not executable code.

Quick Reference

Task	Command
Create PR	gh pr create --title "..." --body "..."
Watch checks	gh pr checks {pr} --watch
Get comments	gh api repos/{o}/{r}/pulls/{pr}/comments
Reply to comment	gh api ... -X POST -F in_reply_to=<id>
Resolve thread	GraphQL resolveReviewThread mutation
Trigger Q review	gh pr comment {pr} --body "/q review"
Trigger Codex review	gh pr comment {pr} --body "/codex review"
Check thread status	GraphQL query for reviewThreads

Additional Resources

Reference Files

For detailed commands and conventions, consult:

• references/review-commands.md - Complete gh CLI and GraphQL command reference
• references/commit-conventions.md - Branch naming and commit message conventions

Scripts

Utility scripts in scripts/:

• reply-to-comments.sh - Reply to a specific review comment
• resolve-threads.sh - Batch resolve all unresolved threads