nextjs-pr-workflow

What I do

I implement a complete Next.js PR creation workflow by extending framework skills:

Identify Target Branch: Determine which branch PR should merge into (configurable, not hardcoded)
Run Next.js Quality Checks: Execute npm run lint, npm run build, and npm run test using linting-workflow framework
Identify Tracking: Check for JIRA tickets or git issue references
Create Pull Request: Use pr-creation-workflow framework with git-semantic-commits for PR title formatting
Add JIRA Comments: Use git-issue-updater framework for consistent JIRA ticket updates

Critical Requirement: All tests MUST pass (npm run test) before PR creation. This is a blocking step.

When to use me

Use this workflow when:

Completing implementation of a PLAN.md file
Finishing new feature implementation in Next.js apps
Ready to create a PR after development is complete
Need to ensure code quality before submitting changes
Following the standard practice of linting, building, and testing before PR
All tests must pass before PR can be created (blocking requirement)

Frameworks Used:

pr-creation-workflow: For PR creation logic and quality checks
linting-workflow: For Next.js linting (npm run lint)
jira-git-integration: For JIRA ticket management and comments

Prerequisites

Next.js project with npm run lint, npm run build, and npm run test scripts
Git repository initialized and on a feature branch
Active Atlassian/JIRA account (if using JIRA integration)
Write access to repository
PLAN.md file with implementation details
All existing tests must pass before using this workflow

Steps

Step 1: Check Project Structure

Verify this is a Next.js project and check for required scripts:

# Verify package.json exists and has required scripts
jq -r '.scripts.lint and .scripts.build and .scripts.test' package.json

Required scripts: lint, build, and test. If any script is missing, the workflow cannot proceed.

Step 2: Identify Target Branch

Ask user which branch PR should merge into. Note: This is not necessarily dev - different projects use different conventions.

Use: Ask user or detect default from git symbolic-ref

Step 3: Run Quality Checks via Linting Workflow

Use linting-workflow framework with JavaScript/TypeScript language detection:

Framework: ESLint
Package manager: npm/yarn/pnpm
Run npm run lint (or yarn lint / pnpm lint)
Apply auto-fix with npm run lint -- --fix
Handle errors with re-running

Step 3.5: Run Tests (BLOCKING STEP)

Before proceeding to PR creation, all tests must pass:

# Run test suite
npm run test

# Or with coverage
npm run test -- --coverage

Behavior:

If tests pass: Continue to PR creation
If tests fail: Do NOT create PR. User must fix failing tests first
Error message: "Tests failed. Please fix test failures before creating PR. Run: npm run test"

Test Requirements:

All unit tests must pass
All integration tests must pass
No skipped tests (unless documented)
Coverage threshold (if configured) must be met

Step 3.6: Update Coverage Badge in README

Use coverage-readme-workflow to update README with latest coverage:

Run tests with coverage
Extract coverage percentage
Update coverage badge in README.md
Ensure badge color reflects coverage level

This ensures PR includes updated coverage documentation.

Coverage Update Command:

# Run coverage workflow (delegated to coverage-readme-workflow)
opencode --agent coverage-readme-workflow "update coverage badge"

Behavior:

If coverage badge exists: Update with new percentage
If coverage badge doesn't exist: Add new badge and section
Badge color reflects coverage level (>=80% green, 60-79% yellow, 40-59% orange, <40% red)

Step 4: Identify Tracking System

Read PLAN.md for JIRA ticket references:

# Check for JIRA ticket
PLAN_JIRA=$(grep -oE "[A-Z]+-[0-9]+" PLAN.md | head -1)

Step 5: Create Pull Request via PR Workflow

Use pr-creation-workflow framework with Next.js-specific configuration:

Quality checks: npm run lint, npm run build, and npm run test
Test validation is MANDATORY - PR cannot be created if tests fail
Target branch: User-specified or detected
Tracking: JIRA ticket or git issue
Platform: GitHub PR (not GitLab)
Use git-semantic-commits for PR title formatting: Follow Conventional Commits specification
- Examples: feat: add user authentication, fix(ui): resolve layout issue, docs: update API docs
- Include ticket reference: feat: add login feature [IBIS-456] or fix(IBIS-456): resolve session timeout
- Use scope: feat(api): add authentication, fix(ui): resolve layout issue
- Breaking changes: feat!: breaking API change or feat(api)!: breaking change to authentication
PR body should include test results summary
Apply semantic versioning label automatically:
- feat! → major label (breaking change)
- feat → minor label (new feature)
- fix → patch label (bug fix)

Step 5.5: Apply Semantic Versioning Label

After PR creation, apply the appropriate version label:

# Get PR number
PR_NUMBER=$(gh pr list --head "$(git branch --show-current)" --json number --jq '.[0].number')

# Detect and apply label based on PR title
PR_TITLE=$(gh pr view "$PR_NUMBER" --json title --jq '.title')

if [[ "$PR_TITLE" =~ ^[^:]+\! ]]; then
  gh pr edit "$PR_NUMBER" --add-label "major"
elif [[ "$PR_TITLE" =~ ^feat ]]; then
  gh pr edit "$PR_NUMBER" --add-label "minor"
elif [[ "$PR_TITLE" =~ ^fix ]]; then
  gh pr edit "$PR_NUMBER" --add-label "patch"
else
  gh pr edit "$PR_NUMBER" --add-label "patch"
fi

Step 6: Handle JIRA Integration via Git Issue Updater

Use git-issue-updater framework for:

JIRA resource detection (cloud ID, projects)
Adding comments with PR details (user, date, time, commit hash, files changed)
Uploading images (if applicable)
Consistent progress tracking across all JIRA tickets

Step 7: Merge Confirmation

After PR creation, ask user to confirm merge target before proceeding.

Example PLAN.md Integration

When your PLAN.md contains:

# Plan: Add New Feature

## Overview
Implements a new feature for...

## JIRA Reference
IBIS-456: https://company.atlassian.net/browse/IBIS-456

## Implementation
...

This skill will:

Detect JIRA ticket IBIS-456
Run linting and build
Create PR with Conventional Commits format (e.g., feat: add user component [IBIS-456])
Add comment to JIRA ticket IBIS-456 using git-issue-updater
Prompt for merge target

Common Issues

Linting Errors

Issue: Many linting errors at once
Solution: Run npm run lint -- --fix first, then manually fix remaining errors

Build Failures

Type Errors: Check TypeScript types and interfaces
Import Errors: Verify all imports are correct and paths exist
Missing Dependencies: Run npm install to ensure all dependencies are installed
Environment Variables: Check .env.local or environment configuration

JIRA Integration

Permission Denied: Ensure your account has JIRA access and comment permissions
Cloud ID Not Found: Use atlassian_getAccessibleAtlassianResources to locate it
Ticket Not Found: Verify the ticket key exists and is accessible

Git Issues

Branch Diverged: Rebase with git rebase <target-branch> before PR creation
Wrong Target Branch: Verify you're creating the PR against the correct branch (not always dev)
Unstaged Changes: Ensure all changes are committed before PR
No gh CLI: Install GitHub CLI: https://cli.github.com/

Best Practices

Always run linting, building, and testing before creating any PR
Never create a PR with failing tests - this is a blocking requirement
Keep PRs focused and small (ideally < 400 lines changed)
Use git-semantic-commits for PR title formatting following Conventional Commits specification
Write clear, descriptive PR titles: feat: add user component [IBIS-456] or fix(IBIS-456): resolve session timeout
Include scope when relevant: feat(api): add authentication, fix(ui): resolve layout issue
Use breaking change indicator: feat!: breaking API change or feat(api)!: breaking change to authentication
Include quality check status in every PR (linting ✓, build ✓, test ✓)
Use git-issue-updater for JIRA ticket updates with consistent format (user, date, time, PR details)
Add JIRA comments immediately after PR creation for traceability
Never skip the build or test steps - they catch production-breaking issues
Commit linting, build, and test fixes separately for clarity
Use semantic branch names (e.g., feature/IBIS-456-add-component)
Review your own changes before submitting PR

Troubleshooting Checklist

Before creating PR:

npm run lint passes with no errors
npm run build completes successfully
npm run test passes with no failures (BLOCKING)
All tests pass (unit, integration, e2e)
No skipped tests (unless documented)
Coverage badge updated in README.md
All changes are committed and staged
Target branch is identified (main, develop, staging, etc. - not necessarily dev)
Branch is up to date with target branch
PLAN.md is updated if implementation changed
JIRA ticket or git issue reference is identified
PR body includes all necessary documentation

Semantic Versioning Labels

Add version bump labels to indicate release impact:

Label	Color	Description	Version Bump	Examples
`major`	#d73a4a (red)	Breaking changes	X.0.0	API removal, breaking refactor
`minor`	#fbca04 (yellow)	New features	0.X.0	New API, new component
`patch`	#0e8a16 (green)	Bug fixes	0.0.X	Bug fix, typo correction

Label Mapping from Commit Type:

feat! or feat(scope)! → major (breaking change)
feat → minor (new feature)
fix → patch (bug fix)
refactor → patch (code improvement)
docs → patch (documentation)

Usage in Next.js PRs:

# Add version label to PR
gh pr edit <PR_NUMBER> --add-label "minor"

# During PR creation with Next.js feature
gh pr create --title "feat: add user dashboard" --add-label "minor"