Type	Description
`feat`	New feature
`fix`	Bug fix
`perf`	Performance improvement
`test`	Adding/correcting tests
`docs`	Documentation only
`refactor`	Code change (no bug fix or feature)
`build`	Build system or dependencies
`ci`	CI configuration
`chore`	Routine tasks, maintenance

Scopes (optional but recommended)

backend — Backend/API (apps/backend or apps/api)
web — Frontend (apps/web)
types — Shared TypeScript types (packages/types)
api — Public API contract (serializers, endpoints)
infra — Deployment, Docker, Kamal, CI
docs — Documentation and strategy files

Summary Rules

Use imperative present tense: "Add" not "Added"
Capitalize first letter
No period at the end
Add ! before : for breaking changes (e.g. feat(api)!: ...)

Steps

Check current state:

git status
git diff --stat
git log origin/main..HEAD --oneline

Analyze changes to determine:
- Type: What kind of change is this?
- Scope: Which area is affected?
- Summary: What does the change do?
Push branch if needed:
```
git push -u origin HEAD
```
Create PR using gh CLI with title and body. If .github/pull_request_template.md exists, use it as the PR body instead of the default template:
```
gh pr create --title "<type>(<scope>): <summary>" --body "<body from template>"
```

Assign labels by parsing the PR title:

Extract <type> from the title
Extract <scope> if present in parentheses
Check for ! prefix indicating breaking change
Create labels if they don't exist
Apply labels using gh pr edit --add-labels

See references/labels.md for the complete implementation script.

gh pr create --title "<type>(<scope>): <summary>" --body "$(cat <<'EOF'
## What

<Describe the change concisely. What does this PR do and why?>

## Why

<What problem does this solve? Link to issue if applicable.>

<!-- Closes #123 / Fixes #123 / Resolves #123 -->

## Type of change

- [ ] Bug fix
- [ ] New feature
- [ ] Refactor
- [ ] Documentation
- [ ] Infrastructure / tooling

## Testing

<How was this tested? What cases were covered?>

## Checklist

- [ ] Tests pass (`<test command>`)
- [ ] No new dependencies introduced without justification
- [ ] Breaking changes are documented below (if any)

## Breaking changes

<!-- List any breaking API contracts, renamed fields, removed endpoints, or behaviour changes. Leave blank if none. -->
EOF
)"

Examples

New feature

feat(auth): Add OAuth2 login support

Bug fix

fix(api): Correct pagination offset calculation

Breaking API change

feat(api)!: Rename response field user_name to username

Infra / tooling

chore(infra): Update Docker base image to node:22-alpine

No scope (affects multiple areas)

chore: Upgrade dependencies and synchronise lockfile

Validation

The PR title must match this pattern:

^(feat|fix|perf|test|docs|refactor|build|ci|chore|revert)(\([a-zA-Z0-9 ]+\))?!?: [A-Z].+[^.]$

Key rules:

Type must be one of the allowed types
Scope is optional but must be in parentheses if present
! for breaking changes goes before the colon
Summary must start with a capital letter
Summary must not end with a period

Labels

After creating the PR, assign labels based on the type and scope extracted from the PR title.

Standard labels to apply:

Type label (from <type>(<scope>):): feat, fix, perf, test, docs, refactor, build, ci, chore
Scope label (if scope present): derived from the scope in the PR title
Special labels: breaking (if ! in title), dependencies (for dependency updates), security (for security fixes)

Create labels if they don't exist. See references/labels.md for complete color mapping and implementation script.

Iron Rule

The agentic coding assistant shall never merge to the main branch — create pull requests only. Never use gh pr merge, git merge, or any command that directly merges to main. Pull requests are for human review and merging.

create-pr

Create Pull Request

Collaborating skills

PR Title Format

Types (required)