// Generate a PR title and description, then commit, create/update the PR on approval
Ask the agent whether it finished everything or has more to do — a lightweight completeness gate for the end of any task
Audit personal skills for redundancy, verbosity, weak triggers, and overlap. Runs a Claude→Codex review loop, presents per-item approval checkboxes, then applies approved edits and updates README and agent metadata. Use when asked to "review my skills", "audit my skills", "revisit my skills", or "clean up my skills". Accepts an optional skill name to scope the review to a single skill.
Set up or extend golden/snapshot tests for a project. Covers fixture design, Makefile targets, snapshot storage, diff workflow, and update protocol.
Resolve merge conflicts systematically with context-aware 3-tier classification and escalation protocol
Reshape code for readability, naming, structure, TODOs, and reduced surface area across any language
Create or improve Makefiles with minimal complexity. Templates available: base, python-uv, python-fastapi, postgres, nodejs, go, chrome-extension, flutter, electron, static-site.
| name | cmd-pr-description |
| description | Generate a PR title and description, then commit, create/update the PR on approval |
| disable-model-invocation | false |
Generate a concise PR description by analyzing the diff against a base branch.
Output the result in a markdown file named PR_DESCRIPTION.md.
Copy to clipboard: cat PR_DESCRIPTION.md | pbcopy
Default (no scope specified): diff the current branch against the repo's base branch.
Detect the base branch in order — stop at the first success:
gh repo view --json defaultBranchRef -q '.defaultBranchRef.name' 2>/dev/nullgit remote show origin 2>/dev/null | grep "HEAD branch" | cut -d: -f2 | xargsgit symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'Do not assume main or master. If all methods fail, ask the user.
Once resolved, run:
git diff <base>...HEAD -- ":(exclude)*.lock" ":(exclude)package-lock.json" ":(exclude)pnpm-lock.yaml" ":(exclude)package.json"
If the user specifies a scope, use the corresponding command instead:
| Scope | Command | What it covers |
|---|---|---|
unstaged | git diff HEAD -- <excludes> | All uncommitted changes (staged + unstaged) |
last commit / last 1 commit | git diff HEAD~1...HEAD -- <excludes> | Changes in the most recent commit |
last N commits | git diff HEAD~N...HEAD -- <excludes> | Changes in the last N commits |
entire repo | git ls-files | grep -vE "\.(lock|snap)$|package-lock\.json|pnpm-lock\.yaml" | All tracked source files — generate a codebase overview description instead of a diff-based PR description |
For all diff commands, apply: -- ":(exclude)*.lock" ":(exclude)package-lock.json" ":(exclude)pnpm-lock.yaml" ":(exclude)package.json"
If the user passed a branch name as an argument (e.g. /cmd-pr-description feature-branch), use that as BASE_BRANCH. Skip auto-detection entirely.
For entire repo scope: skip diff analysis; use git ls-files and the repo's README/entry points to generate a codebase overview description. Jump directly to Step 3 with that as your source material.
Otherwise, use the detection methods in Determine Scope above to set BASE_BRANCH.
Validation: Verify BASE_BRANCH exists before proceeding:
git rev-parse --verify "$BASE_BRANCH" 2>/dev/null || git rev-parse --verify "origin/$BASE_BRANCH" 2>/dev/null
If the branch does not exist locally or on the remote, stop and ask the user to confirm the branch name.
git diff $BASE_BRANCH...HEAD --stat -- ":(exclude)*.lock" ":(exclude)package-lock.json" ":(exclude)pnpm-lock.yaml" ":(exclude)package.json"
git log $BASE_BRANCH..HEAD --oneline
Generate both a PR title (see Title Format) and the full description body (see Output Format).
Write the description to PR_DESCRIPTION.md and display both the title and description to the user.
Use AskUserQuestion to present the generated title and description. Prefix the prompt with an emoji (e.g., ⏳, 🤔, or 📝) and use square-bracketed numeric option labels so the user can reply with [1], [2], or [3]:
⏳ Please review and choose one:
- [1] Approve as-is
- [2] Request changes (provide feedback, re-generate)
- [3] Reject (stop here)
Do NOT proceed to step 5 until the user explicitly approves.
Once the user approves, execute the following steps in order:
Step 5a — Commit unstaged changes (if any):
git add -A && git commit -m "<generated title>"
If there are no unstaged/staged changes, skip this step.
Step 5b — Push the branch:
git push -u origin HEAD
Step 5c — Create or update the PR:
Check if a PR already exists for the current branch:
gh pr view --json number 2>/dev/null
If a PR exists, update it:
gh pr edit --title "<generated title>" --body "$(cat PR_DESCRIPTION.md)"
If no PR exists, create one. Always pass --base so the PR targets the correct branch (especially important when the base is not the repo default):
gh pr create --base "$BASE_BRANCH" --title "<generated title>" --body "$(cat PR_DESCRIPTION.md)"
PR titles must follow this format:
[KEYWORD] Summary
Rules:
KEYWORD is an uppercase word that best categorizes the PR — not a fixed list. Common examples: FEAT, FEATURE, FIX, BUG, REFACTOR, TECHDEBT, DOCS, TEST, CHORE, PERF, PERFORMANCE, CI, BUILD, STYLE, CLI, CONFIG, MIGRATION, SECURITY, API, UI, INFRASummary is a concise imperative phrase (e.g., "Add session-based auth", "Fix null pointer in user lookup")Examples:
[FEAT] Add session-based authentication[FIX] Resolve race condition in queue worker[REFACTOR] Simplify middleware chain[DOCS] Update API reference for v2 endpoints_tl;dr Single sentence, 120 characters max, summarizing the most important outcome of this PR._
## Summary
- **Subject/topic**: < 100 character explanation
- ...
- ...
## Feature Diff
| S | Component | Before | After |
| ---- | ---------------------------------- | ------------------------------------------ | ---------------------------------------- |
| 🟢/🔴/… | 1-3 words describing the component | 1 sentence describing how it worked before | 1 sentence describing how it works after |
| … | ... | ... | ... |
> 🔴 Critical fix · 🟡 Improvement · 🟢 New feature · ⚪ Neutral · ⚙️ Infra/tooling · ⚠️ Breaking
## Details
<details>
<summary>Technical Details</summary>
### Subsection Title
- **Subject/topic**: < 100 character explanation
- ...
### Another Subsection
- **Subject/topic**: < 100 character explanation
- ...
</details>
Use GitHub admonitions at the very top of the description (before the tl;dr) when the PR has important context that reviewers need upfront. Do NOT use admonitions by default — only when one of the situations below applies.
Syntax:
> [!NOTE]
> Useful information that users should know, even when skimming content.
> [!TIP]
> Helpful advice for doing things better or more easily.
> [!IMPORTANT]
> Key information users need to know to achieve their goal.
> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.
> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
When to use each type:
| Type | When to use |
|---|---|
NOTE | PR is a follow-up/review of another PR, replaces a previous approach, or has non-obvious scope context |
TIP | PR unlocks a workflow or has a recommended migration/adoption path reviewers should know |
IMPORTANT | PR requires a specific merge order, has deployment prerequisites, or needs coordinated rollout |
WARNING | PR includes a breaking change, requires a migration, or has a tight deadline |
CAUTION | PR touches sensitive systems (auth, billing, data deletion) or has irreversible side effects |
Rules:
N/A if newRemoved if deletedsessions table, /auth/login, TOKEN_TTL)> 🔴 Critical fix · 🟡 Improvement · 🟢 New feature · ⚪ Neutral · ⚙️ Infra/tooling · ⚠️ Breaking| Emoji | Label | When to use |
|---|---|---|
| 🔴 | Critical fix | Bug fix for broken/incorrect behavior |
| 🟡 | Improvement | Enhancement to existing behavior |
| 🟢 | New feature | Net-new capability |
| ⚪ | Neutral | Config, docs, chore, cleanup |
| ⚙️ | Infra/tooling | CI, build, dev tooling changes |
| ⚠️ | Breaking | Breaking change or deprecation |
<details> tagsfile.py, get_user(), /api/v1/users)file.py), file paths (src/auth/), commands (npm run build), config keys (TOKEN_TTL), env vars (NODE_ENV), endpoints (/api/v1/users), function names (getUser()), table/column names (sessions.token)_tl;dr Users can now log in with email/password and stay authenticated across browser sessions._
## Summary
- **Session-based login**: Users authenticate with email/password and maintain sessions across browser restarts
- **Faster auth checks**: Session lookups use an indexed `token` column instead of scanning the full `users` table
- **Remember-me support**: Users can opt into 30-day sessions instead of the default 24-hour expiry
## Feature Diff
| S | Component | Before | After |
| ---- | ---------------- | -------------------------- | ----------------------------------------------- |
| 🟢 | Auth method | API key only | Email/password + session cookie |
| 🟢 | Session duration | `N/A` | 24 hours (default), 30 days (remember-me) |
| 🟢 | `sessions` table | `N/A` | New table with `user_id`, `token`, `expires_at` |
| 🟡 | Token lookup | Full table scan on `users` | Indexed lookup on `sessions.token` |
| 🟢 | `/auth/login` | `N/A` | New endpoint |
| 🟢 | `/auth/logout` | `N/A` | New endpoint |
> 🔴 Critical fix · 🟡 Improvement · 🟢 New feature · ⚪ Neutral · ⚙️ Infra/tooling · ⚠️ Breaking
## Details
<details>
<summary>Technical Details</summary>
### Authentication Service
- **New login service**: Handles JWT issuance, session creation, and cookie management
- Add `login_service.py` with session create/validate/revoke methods
- Integrate `/auth/login` and `/auth/logout` endpoints in `routes/auth.py`
- Support `remember_me` flag to toggle 24h vs 30d expiry
### Database Schema
- **New sessions table**: Stores active sessions with automatic expiry
- Add `sessions` table with `user_id`, `token`, `expires_at` columns
- Add B-tree index on `token` for O(1) lookups
- Add index on `expires_at` for cleanup job performance
</details>