Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/lnardev/opencode-config-agent/llms.txt

Use this file to discover all available pages before exploring further.

The branch-pr skill codifies a strict issue-first pull request workflow. It activates whenever the agent is creating a pull request, preparing a branch for submission, or helping a contributor open a PR. Every rule it enforces exists to prevent incomplete or unreviewed work from being merged — GitHub Actions will block any PR that skips the requirements.

​
Trigger

This skill loads automatically when:
  • Creating or opening a pull request
  • Preparing a branch for review
  • Helping a contributor submit changes

​
Critical Rules

These four rules are non-negotiable. GitHub Actions enforces them automatically and will block any PR that violates them.
  1. Every PR MUST link an approved issue — no exceptions. The linked issue must carry the status:approved label before a PR can be opened.
  2. Every PR MUST have exactly one type:* label — adding zero or multiple type labels fails the PR validation check.
  3. Automated checks must pass before a merge is possible — all four CI jobs must be green.
  4. Blank PRs without issue linkage will be blocked by GitHub Actions — the Check Issue Reference job validates Closes/Fixes/Resolves #N in the PR body.

​
Workflow

1

Verify the issue is approved

Confirm the linked issue has the status:approved label. If it only has status:needs-review, stop — a maintainer must approve it first.
2

Create the branch

Branch off main using the type/description format. See Branch Naming for the full regex and type table.
3

Implement changes with conventional commits

Every commit must match the conventional commit format. See Commit Format for the regex, type list, and label mappings.
4

Run shellcheck on modified scripts

Before pushing, run shellcheck scripts/*.sh on any shell scripts touched by the change. CI will fail if shellcheck finds errors.
5

Open the PR using the template

Use .github/PULL_REQUEST_TEMPLATE.md. The body must include: linked issue (Closes #N), PR type checkbox, summary bullets, a changes table, a test plan, and the contributor checklist.
6

Add exactly one type:* label

Add the label that matches your primary commit type. See the PR Type table for checkbox-to-label mappings.
7

Wait for automated checks to pass

All four jobs must pass: Check Issue Reference, Check Issue Has status:approved, Check PR Has type:* Label, and Shellcheck.

​
Branch Naming

Branch names must match this regex exactly — any deviation fails the branch validation check: 
^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$
Format: type/description — all lowercase, no spaces, only a-z0-9._- in the description.
TypeBranch PatternExample
Featurefeat/<description>feat/user-login
Bug fixfix/<description>fix/zsh-glob-error
Chorechore/<description>chore/update-ci-actions
Docsdocs/<description>docs/installation-guide
Stylestyle/<description>style/format-scripts
Refactorrefactor/<description>refactor/extract-shared-logic
Performanceperf/<description>perf/reduce-startup-time
Testtest/<description>test/add-setup-coverage
Buildbuild/<description>build/update-shellcheck
CIci/<description>ci/add-branch-validation
Revertrevert/<description>revert/broken-setup-change

​
Commit Format

Commit messages must match this regex: 
^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]+\))?!?: .+
Format: type(scope): description or type: description
  • type — required, one of the conventional commit types
  • (scope) — optional, lowercase with a-z0-9._-
  • ! — optional, marks a breaking change
  • description — required, starts after :
The commit type determines which type:* label the PR should carry:
Commit TypePR Label
feattype:feature
fixtype:bug
docstype:docs
refactortype:refactor
chore, style, test, build, citype:chore
perftype:feature
reverttype:bug
feat! / fix!type:breaking-change

​
PR Body Format

The PR template requires six sections — all must be present:
1. Linked Issue (REQUIRED)
Closes #<issue-number>
Valid keywords: Closes #N, Fixes #N, Resolves #N (case-insensitive). The linked issue must have status:approved.2. PR Type (REQUIRED)
Check exactly one checkbox and add the matching label:
CheckboxLabel
Bug fixtype:bug
New featuretype:feature
Documentation onlytype:docs
Code refactoringtype:refactor
Maintenance/toolingtype:chore
Breaking changetype:breaking-change
3. Summary — 1–3 bullet points describing what the PR does.4. Changes Table
| File | Change |
|------|--------|
| `path/to/file` | What changed |
5. Test Plan
- [x] Scripts run without errors: `shellcheck scripts/*.sh`
- [x] Manually tested the affected functionality
- [x] Skills load correctly in target agent
6. Contributor Checklist — all boxes must be checked before requesting review.

​
Automated Checks

CheckJob NameWhat It Verifies
PR ValidationCheck Issue ReferenceBody contains Closes/Fixes/Resolves #N
PR ValidationCheck Issue Has status:approvedLinked issue has status:approved
PR ValidationCheck PR Has type:* LabelPR has exactly one type:* label
CIShellcheckShell scripts pass shellcheck

​
Full PR Workflow Example

# 1. Verify the issue is approved
gh issue view 42 --json labels --jq '.labels[].name'
# should include "status:approved"

# 2. Create branch from main
git checkout main
git pull origin main
git checkout -b feat/add-codex-support

# 3. Make changes with conventional commits
git add .
git commit -m "feat(scripts): add Codex support to setup.sh"

# 4. Run shellcheck before pushing
shellcheck scripts/*.sh

# 5. Push branch
git push -u origin feat/add-codex-support

# 6. Open PR using the template
gh pr create \
  --title "feat(scripts): add Codex support to setup.sh" \
  --body "Closes #42

## PR Type
- [x] New feature

## Summary
- Adds a --agent codex flag to setup.sh
- Links skills to ~/.codex/skills/ on setup

## Changes
| File | Change |
|------|--------|
| \`scripts/setup.sh\` | Added Codex agent detection and symlink logic |

## Test Plan
- [x] Scripts run without errors: \`shellcheck scripts/*.sh\`
- [x] Manually tested with --agent codex on macOS

## Checklist
- [x] Linked an approved issue
- [x] Added exactly one type:* label
- [x] Ran shellcheck on modified scripts
- [x] Conventional commit format
- [x] No Co-Authored-By trailers"

# 7. Add the type label
gh pr edit --add-label "type:feature"

# 8. Monitor CI
gh pr checks --watch

Build docs developers (and LLMs) love

Get started for freeTalk to us