notque/vexjoy-agent / skills/process/pr-workflow
pr-workflow
FlaggedPull request lifecycle: commit, codex review, sync, review, fix, status, cleanup, and PR mining. Use when user wants to commit changes, get a second-opinion code review from Codex, push changes, create a PR, check PR status, fix review comments, clean up branches after merge, or mine tribal knowledge from PR reviews. Use for "commit my changes", "codex review", "push my changes", "create a PR", "pr status", "fix PR comments", "clean up branches", "mine PRs", or "address feedback".
references/branch-name.md
View on GitHub# Branch Naming
Generate and validate Git branch names from conventional commit messages or plain descriptions. This reference only handles naming -- it does not create, delete, or manage branches.
## Instructions
### Step 1: Parse Input
Determine the commit type and subject from whatever the user provides.
**If a conventional commit message** (e.g., `feat: add user auth`):
- Extract type, optional scope, and subject
- Pattern: `<type>[optional scope]: <description>`
**If a plain description** (e.g., `add user authentication`):
- Infer type from keywords
- Keywords: add/implement/create -> feat, fix/resolve/correct -> fix, document/readme -> docs, refactor/restructure -> refactor, test/spec -> test, remove/delete/update -> chore
- Default to `feat` when no keywords match
Strip banned characters (emojis, special chars) from the input. If the input is too vague to determine a type (e.g., "stuff", "things"), prompt the user for a more descriptive input starting with an action verb.
**Gate**: Commit type identified and subject extracted. If not, prompt for clarification before continuing.
### Step 2: Generate Branch Name
**Map type to prefix** using the standard table (or `.branch-naming.json` overrides if present in the repo root):
| Type | Prefix |
|------|--------|
| feat | feature/ |
| fix | fix/ |
| docs | docs/ |
| refactor | refactor/ |
| test | test/ |
| chore | chore/ |
| style | style/ |
| perf | perf/ |
| build | build/ |
| ci | ci/ |
| revert | revert/ |
Every branch name must have a prefix from this list -- unprefixed names like `add-user-authentication` break CI/CD automation and make filtering impossible.
**Sanitize the subject to kebab-case** using the 7-step pipeline:
1. Lowercase
2. Strip leading/trailing whitespace
3. Replace spaces with hyphens
4. Replace underscores with hyphens (underscores violate kebab-case convention and create inconsistency with conventional commits)
5. Remove special characters (keep only a-z, 0-9, hyphens)
6. Collapse multiple consecutive hyphens
7. Remove leading/trailing hyphens
Only a-z, 0-9, and hyphens are allowed in the subject. The forward slash appears only once, separating prefix from subject.
**Apply the 50-character length limit** (prefix + subject combined). If exceeded:
1. Remove filler words (the, a, with, and, for, etc.)
2. Apply common abbreviations (authentication -> auth, configuration -> config)
3. Truncate at word boundaries -- never cut mid-word
Long names signal scope creep; move detail to the commit message body rather than cramming it into the branch name.
**Combine prefix + sanitized subject**:
Example: `feat: add user authentication` -> `feature/add-user-authentication`
**Gate**: Generated name has a valid prefix, uses kebab-case, stays within the length limit, and contains only allowed characters.
### Step 3: Validate
Run all checks against the generated (or user-provided) name:
**Format validation**:
- Has a valid prefix from the allowed list
- Subject is kebab-case (no uppercase, no underscores)
- Only allowed characters (a-z, 0-9, hyphens, one forward slash)
- No leading/trailing hyphens in subject
- No consecutive hyphens
- Name is specific enough to convey purpose (`feature/updates` or `fix/stuff` are too vague)
**Length check**: Total length is 50 characters or fewer.
**Duplicate detection**:
```bash
# Check local
git branch --list "<branch-name>"
# Check remote
git ls-remote --heads origin "<branch-name>"
```
If a duplicate is found, generate alternatives:
1. Append `-v2`, `-v3` for versioning
2. Append date `-YYYYMMDD` for uniqueness
3. Ask user for a custom suffix
**Repository convention compliance**: Check `.branch-naming.json` if present for custom prefix restrictions.
**Gate**: All validation checks pass. If any fail, regenerate with adjustments or present alternatives.
### Step 4: Confirm
Present the validated name and wait for user approval before proceeding:
```
Generated Branch Name: feature/add-user-authentication
Type: feat (feature)
Length: 31 characters
Format: Valid
Duplicates: None found
Use this branch name? [Y/n]
```
Handle the response:
- **Yes**: Output the final name with a `git checkout -b` command
- **No**: Return to Step 1 with new input
- **Customize**: User provides a custom name; run it through Step 3 validation
Skip confirmation only in automated/scripted workflows where the caller has explicitly opted into auto-accept.
**Gate**: User approved name. Workflow complete.
### Examples
**From a conventional commit**:
Input: `feat: add user authentication`
1. Parse: type=feat, subject="add user authentication"
2. Map feat -> feature/, sanitize -> "add-user-authentication"
3. Validate format, length (31 chars), no duplicates
4. Present and confirm
Result: `feature/add-user-authentication`
**From a plain description with truncation**:
Input: `add comprehensive user authentication system with OAuth2 and JWT`
1. Infer type=feat from "add" keyword
2. Sanitize, remove fillers, abbreviate auth -> 32 chars
3. Validate all checks pass
4. Present and confirm
Result: `feature/add-user-auth-oauth2-jwt`
**Validating an existing branch name**:
Input: `feature/User_Authentication`
1. Detect uppercase letters and underscores
2. Report issues with corrections
Result: Suggest `feature/user-authentication`
---
## Error Handling
### Error: "Cannot Infer Commit Type"
Cause: Description too vague (e.g., "stuff", "things") to determine type
Solution:
1. Prompt user to start with action verb (add, fix, update, remove)
2. Suggest using `--type` flag to specify explicitly
3. Provide examples of descriptive input
### Error: "Name Exceeds Length Limit"
Cause: Description too long even after truncation
Solution:
1. Remove filler words and apply abbreviations
2. Suggest shorter focused description
3. Move detail to commit message body instead of branch name
### Error: "Duplicate Branch Detected"
Cause: Branch name already exists locally or remotely
Solution:
1. Suggest alternatives with -v2 or date suffix
2. Offer to check out existing branch instead
3. Prompt for custom differentiating suffix
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |