Submit Pull Request Workflow

[!CAUTION] Scope boundary: This skill pushes code, creates pull requests, monitors CI, and commits CI fixes (with user approval). It does NOT implement new features or run formal code reviews. When the PR is created and CI passes, stop — the workflow is complete.

[!WARNING] Checkpoint protocol. When this workflow reaches a

### CHECKPOINT

, you must actively prompt the user for a decision — do not simply present information and continue. Use your agent's interactive prompting mechanism (e.g.,

AskUserQuestion

in Claude Code) to require an explicit response before proceeding. This prevents queued or in-flight messages from being misinterpreted as approval. If your agent lacks interactive prompting, output the checkpoint content and stop all work until the user explicitly responds.

Step 1: Pre-Submission Checks

1. Confirm we are on a feature branch (not

   main

   ). If on

   main

   , stop and ask the user to create a feature branch first.
2. Sync with main:
   bash

   git fetch origin
   git rebase origin/main

   If there are conflicts, stop and help the user resolve them before proceeding.
3. Run your project's quality checks:

   # Adapt to your project's toolchain
   type-check      # TypeScript tsc, mypy, etc.
   lint            # ESLint, Ruff, golangci-lint, etc.
   format:check    # Prettier, Black, gofmt, etc.
   test            # Vitest, Jest, pytest, etc.
   build           # If a build step exists

   If formatting checks fail, auto-fix by running the formatter on the reported files and stage the changes.
4. Perform a final security scan on changed files:
   • Are there hardcoded secrets, API keys, or credentials in the diff?
   • Are all user inputs validated and sanitized?
   • Are authentication and authorization checks present on new endpoints?
   • Are error responses safe? (no internal details leaked)
   • Are dependencies free of known CVEs?

   Claude Code optimization: If the

   /security-scanning:security-sast

   skill is available, use it for enhanced automated scanning. Otherwise, follow the manual checklist above.

Step 2: Analyze Changes

1. Run

   git log origin/main..HEAD --oneline

   to see all commits on this branch
2. Run

   git diff origin/main...HEAD --stat

   to see the file change summary
3. Run

   git diff origin/main...HEAD

   to read the actual changes

• Type of change: feature, fix, docs, refactor, test, chore (from commit prefixes)
• Scope: frontend, backend, full-stack, infrastructure
• Includes database migrations? (check for migration files or schema changes)
• Includes infrastructure changes? (containers, CI/CD, environment files)
• Includes security-sensitive changes? (auth, authorization, API security, secrets)
• Related issues: Extract from commit messages (Closes #NNN, Fixes #NNN)

Step 3: Deployment Council Review (Conditional)

councils/deployment-council.md

• Database migrations are included
• Container or infrastructure files changed
• Environment variables were added or modified
• Authentication or authorization code changed
• CI/CD pipeline files modified

agents/

Platform Engineer (Lead)

• Application builds and packages successfully for deployment?
• Environment variables configured?
• Health check endpoints working?
• Resource limits set (CPU, memory)?
• Logging and monitoring configured?
• Rollback strategy defined?

Security Engineer

• Secrets managed securely (not in code)?
• HTTPS/TLS configured?
• API authentication working?
• CORS configured correctly?
• Security headers configured (e.g., Content-Security-Policy, X-Frame-Options, HSTS)?
• No high-severity vulnerabilities?

QA Lead

• E2E tests passing?
• Critical user flows validated?
• Performance testing completed?
• No known P0/P1 bugs?
• Regression tests passing?
• Smoke tests defined for post-deployment?

Deployment Decision

• Status: Approved / Not Ready / Blocked
• Deployment Strategy: Rolling / Blue-Green / Canary
• Rollback Plan: How to rollback if issues arise

CHECKPOINT (only if Deployment Council was activated): Present the deployment readiness assessment to the user. Wait for confirmation before proceeding.

Step 4: Generate PR Description

.github/PULL_REQUEST_TEMPLATE.md

Title

• Format:

  <type>(<scope>): <short description>

  matching conventional commits
• Keep under 70 characters
• Use the primary commit type and scope

Body

Closes #NNN

• Check items that are actually done (tests pass, lint passes, etc.)
• Leave unchecked items that still need attention

Changelog Entry

• Determine the category: Added / Changed / Fixed / Removed
• Write a one-line description from the user's perspective
• Reference the PR number

CHECKPOINT: Present the PR title and full body to the user. Allow them to review and request edits before submission.

Step 5: Push and Create PR

1. Push the branch to the remote:
   bash

   git push origin <branch-name> -u

2. Create the PR. Using the GitHub CLI as an example:
   bash

   gh pr create --title "<title>" --body "<body>" --base main

   Adapt to your project's version control platform if not using GitHub.
3. If the PR template includes labels, add appropriate labels.

Step 6: Monitor CI Pipeline

1. Check for the latest CI run on the branch.
2. Monitor the run until it finishes. Using GitHub CLI as an example:
   bash

   gh run list --branch <branch-name> --limit 1 --json databaseId,status
   gh run watch <run-id> --exit-status

3. If CI fails, fetch the failed job logs and diagnose:
   • Formatting failures: Auto-fix with the formatter, commit, push, and re-watch. No checkpoint needed.
   • All other failures: CHECKPOINT — present the diagnosis and proposed fix to the user. Wait for approval before committing. After approval, fix, commit, push, and re-watch.
4. If CI passes: proceed to Step 7.

Step 7: Post-PR Summary

• PR URL (clickable link)
• Summary of what was submitted
• CI status (all checks passing)
• Changelog entry (if generated)
• Reminder about branch lifecycle: delete branch after merge

[!TIP] Workflow complete. The PR is submitted and CI is green. After the PR is merged and the branch is deleted, the feature lifecycle is done.

Pipeline:

/plan-feature

→

/build-feature

or

/build-api

→

/review-code

→

/submit-pr

(you are here)

If the user wants to start the next feature, suggest: "Run

/plan-feature

to begin planning the next feature."