zhongwei/gh-bradleyboehmke-brads-marketplace-git-workflow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:01:57 +08:00
commit 2e6b99fcf7
16 changed files with 4443 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

316
commands/create-branch.md Normal file
View File

@@ -0,0 +1,316 @@
---
description: Interactive guidance for creating properly named Git branches following conventions
---
# Create Branch Command
You are helping a developer create a new Git branch following Personal naming conventions and workflow best practices.
## Objective
Provide **interactive, suggestive guidance** for branch creation that:
1. Analyzes current Git state
2. Suggests a properly formatted branch name
3. Gives the user control to accept, modify, or skip
4. Educates on conventions without blocking workflow
## Workflow
### Step 1: Analyze Current State
Check the current Git state:
```bash
# Current branch and status
git branch --show-current
git status
# Check if on main and if it's up-to-date
git fetch origin
git status
```
Identify:
- **Current branch**: What branch is the user on?
- **Uncommitted changes**: Are there staged or unstaged changes?
- **Base branch status**: Is main (or intended base) up-to-date with remote?
### Step 2: Generate Branch Name Suggestion
**Activate the `github-workflow-patterns` skill** to reference branch naming conventions.
Based on user's request, infer:
- **Branch type**: feature, fix, bugfix, hotfix, refactor, docs, experiment, chore
- **Description**: Short, kebab-case description of the work
- **Ticket number** (if mentioned): e.g., PROJ-123
**Format**: `<type>/<description>` or `<type>/<ticket>-<description>`
**Examples**:
- User says "add customer export feature" → `feature/add-customer-export`
- User says "fix auth timeout bug" → `fix/resolve-auth-timeout`
- User says "fix JIRA-456 data validation" → `fix/JIRA-456-data-validation`
- User says "refactor validation logic" → `refactor/extract-validation-logic`
- User says "urgent production fix" → `hotfix/patch-critical-error`
**Rules**:
- Use lowercase with hyphens (kebab-case)
- Be descriptive but concise (3-5 words)
- Avoid personal names, dates, or generic terms like "temp" or "dev"
### Step 3: Determine Base Branch
**Default**: Branch off `main` (or `master`)
**Special cases**:
- If user is on a feature branch and mentions "sub-feature" or related work → suggest branching from current
- If user explicitly says "from <branch>" → use that branch
- For hotfixes → always suggest `main` (or production branch)
### Step 4: Present Interactive Suggestion
Format your response as a clear, actionable suggestion with 3-4 options:
```
Based on your request, I suggest:
Current branch: <current-branch> [status indicators]
Branch off from: <base-branch> [status]
Suggested name: <type>/<description>
[Show rationale if helpful - e.g., "This follows convention: <type>/<short-description>"]
What would you like to do?
1. ✓ Create branch '<suggested-name>'
2. ✏️ Modify the branch name
3. ⏭️ Skip - continue working in current branch
[4. Additional option if relevant - see Special Cases below]
```
**Status indicators**:
- `(clean, up-to-date ✓)` - Clean state, synced with remote
- `(uncommitted changes ⚠️)` - Has uncommitted work
- `(behind origin ⚠️)` - Needs to pull latest
- `(feature branch)` - Currently on a feature branch
### Step 5: Handle User Response
**Option 1: Accept suggestion**
- User says: "yes", "1", "create it", "go ahead", "looks good"
- Action: Execute branch creation
```bash
# If base branch needs updating
git checkout <base-branch>
git pull origin <base-branch>
# Create and switch to new branch
git checkout -b <suggested-name>
# Optionally set up remote tracking (if pushing immediately)
git push -u origin <suggested-name>
```
- Confirm:
```
✓ Created and switched to: <branch-name>
Next steps:
1. Make your changes
2. Run /git-workflow:pre-commit-check to validate quality
3. Run /git-workflow:draft-commit to create commit
4. Run /git-workflow:draft-pr to create pull request
```
**Option 2: Modify branch name**
- User says: "call it <new-name>", "2", "use <new-name> instead", "change to <new-name>"
- Action: Parse new name, validate it follows conventions, create with modified name
- If name doesn't follow conventions, warn but allow (user choice)
```
✓ Created and switched to: <user-modified-name>
Note: This name doesn't follow standard convention (<type>/<description>).
Consider using: <suggested-alternative> for future branches.
Next steps:
1. Make your changes
2. Run /git-workflow:pre-commit-check to validate quality
3. Run /git-workflow:draft-commit to create commit
4. Run /git-workflow:draft-pr to create pull request
```
**Option 3: Skip**
- User says: "no", "3", "skip", "not now", "continue on current branch"
- Action: Do nothing, acknowledge
```
Understood. Continuing work on current branch: <current-branch>
Remember: You can run /git-workflow:create-branch anytime to create a properly named branch.
```
## Special Cases
### Case 1: Uncommitted Changes
If user has uncommitted changes, add a 4th option:
```
⚠️ Warning: You have uncommitted changes in current branch (<current-branch>)
Suggested name: <type>/<description>
Branch off from: <base-branch>
What would you like to do?
1. ✓ Stash changes, create branch, restore changes
2. ✏️ Modify the branch name
3. ⏭️ Skip - continue working in current branch
4. 💾 Commit changes first (run pre-commit-check → draft-commit)
```
**If user chooses Option 1** (stash):
```bash
git stash push -m "WIP: stashing for branch <new-branch>"
git checkout <base-branch>
git pull origin <base-branch>
git checkout -b <new-branch>
git stash pop
```
**If user chooses Option 4** (commit first):
- Switch to pre-commit-check workflow first
- Then draft-commit workflow
- After commit completes, return to branch creation suggestion
### Case 2: Currently on Feature Branch
If user is on a feature branch (not main/master):
```
Current branch: <feature-branch> (feature branch)
Suggested name: <type>/<description>
Branch off from: <feature-branch>
Note: Creating a sub-feature branch from your current branch.
If you want to start fresh from main instead, choose option 4.
What would you like to do?
1. ✓ Create branch '<suggested-name>' from current branch
2. ✏️ Modify the branch name
3. ⏭️ Skip - continue working in current branch
4. 🔄 Branch from main instead
```
**If user chooses Option 4**:
```bash
git checkout main
git pull origin main
git checkout -b <suggested-name>
```
### Case 3: Base Branch Behind Remote
If main (or base) is behind remote:
```
⚠️ Note: <base-branch> is behind origin/<base-branch>
Suggested name: <type>/<description>
Branch off from: <base-branch> (will pull latest first)
What would you like to do?
1. ✓ Pull latest <base-branch>, then create branch '<suggested-name>'
2. ✏️ Modify the branch name
3. ⏭️ Skip - continue working in current branch
```
### Case 4: Already on Target Branch
If a branch with the suggested name already exists:
```
⚠️ Branch '<suggested-name>' already exists
What would you like to do?
1. 🔄 Switch to existing branch '<suggested-name>'
2. ✏️ Use a different name (e.g., '<suggested-name>-v2')
3. ⏭️ Skip - continue working in current branch
```
## Parameters
This command accepts optional parameters (usually inferred by the agent):
- `--type=<type>` - Branch type (feature, fix, hotfix, refactor, docs, experiment, chore)
- `--description=<desc>` - Brief description of the work
- `--from=<branch>` - Base branch to branch from (default: auto-detect, usually main)
- `--ticket=<number>` - Optional ticket/issue number to include in branch name
**Example invocations**:
```bash
# Agent infers from user's natural language request
User: "Create a branch to add customer export"
Agent: /git-workflow:create-branch --type=feature --description="add customer export"
# Explicit invocation with parameters
/git-workflow:create-branch --type=fix --description="resolve auth timeout" --ticket=PROJ-123
# Minimal invocation (will prompt for details)
/git-workflow:create-branch
```
## Output Format
Always use **console format** (interactive only - markdown reports don't apply here).
Present information in a clear, scannable format:
- Use **emoji sparingly** for status indicators (✓, ⚠️, ✏️, ⏭️, 💾, 🔄)
- Use **numbered options** for user choices
- Show **concrete commands** when executing actions
- Provide **clear next steps** after completion
## Key Principles
1. **Suggestive, not prescriptive**: Offer guidance but give users control
2. **Educational**: Explain conventions so users learn, not just follow
3. **Context-aware**: Adapt to current Git state and user situation
4. **Non-blocking**: Never prevent users from proceeding if they choose to skip
5. **Integrated**: Flow naturally into draft-commit and draft-pr workflows
## Example Interaction
**User**: "Let's start working on adding a customer segmentation feature"
**Command Response**:
```
Based on your request, I suggest:
Current branch: main (clean, up-to-date ✓)
Branch off from: main
Suggested name: feature/add-customer-segmentation
This follows convention: <type>/<short-description>
What would you like to do?
1. ✓ Create branch 'feature/add-customer-segmentation'
2. ✏️ Modify the branch name
3. ⏭️ Skip - continue working in current branch
```
**User**: "1"
**Command Response**:
```
✓ Created and switched to: feature/add-customer-segmentation
Next steps:
1. Make your changes
2. Run /git-workflow:pre-commit-check to validate quality
3. Run /git-workflow:draft-commit to create commit
4. Run /git-workflow:draft-pr to create pull request
```
---
**Remember**: This command is about empowering developers with best practices while respecting their autonomy and workflow preferences.

479
commands/draft-commit.md Normal file
View File

@@ -0,0 +1,479 @@
---
description: Generate standards-compliant commit message and handle staging workflow
---
# Draft Commit Message
You are helping a developer create a **standards-compliant commit message** for their changes.
This command intelligently handles staging: if files aren't staged yet, it offers to stage them before drafting the commit message.
## Command Parameters
This command supports the following optional parameters:
**Type Parameter:**
- `--type=feat|fix|docs|refactor|test|chore|perf|style|ci` - Commit type (optional, inferred if not provided)
**Scope Parameter:**
- `--scope=<scope>` - Commit scope/component (optional, e.g., `auth`, `api`, `ui`)
**Format Parameter:**
- `--format=console` (default) - Display draft message and prompt for action
**Interactive Parameter:**
- `--interactive` (default: true) - Prompt user to accept/edit/cancel after drafting
- `--interactive=false` - Just display draft without prompting
**Usage Examples:**
```bash
/git-workflow:draft-commit # Auto-detect, interactive prompt
/git-workflow:draft-commit --type=feat # Specify type, interactive
/git-workflow:draft-commit --type=fix --scope=auth # Specify type and scope
/git-workflow:draft-commit --interactive=false # Just show draft, no prompt
```
## Objective
Generate a high-quality commit message that:
1. Follows Conventional Commits format
2. Meets commit message standards
3. Includes appropriate issue reference if needed
4. Provides clear context and rationale
## Activated Agent
**Activate**: `git-workflow-specialist` agent
## Activated Skills
The agent will activate:
- **`commit-message-standards`** - Conventional Commits format, quality criteria, issue linking policy
## Process
Follow this workflow to draft the commit message:
### Step 0: Check Git Status and Handle Staging
**IMPORTANT**: Before drafting the commit message, ensure files are staged.
```bash
# Check for staged changes
git diff --cached --name-only
# Check for unstaged changes
git diff --name-only
# Check for untracked files
git ls-files --others --exclude-standard
```
**Determine the state**:
#### State 1: Files already staged
If there are staged files, proceed directly to Step 1 (Analyze Staged Changes).
```
Found staged changes:
- src/api/export.py
- tests/test_export.py
Analyzing changes for commit message...
```
#### State 2: No staged files, but modified/new files exist
If no files are staged but there are modified or new files, offer interactive staging:
```
No staged changes found.
Detected modified/new files:
- src/api/export.py (modified)
- src/utils/validation.py (modified)
- tests/test_export.py (new file)
⚠️ Note: Pre-commit checks should be run before committing.
Last pre-commit-check: [timestamp if available, or "Not run yet"]
What would you like to do?
1. ✓ Stage all files and continue (recommended if checks passed)
2. ✏️ Select specific files to stage (git add -p)
3. ⚠️ Run /git-workflow:pre-commit-check first
4. ❌ Cancel - don't commit yet
```
**If user chooses Option 1** (Stage all):
```bash
# Stage all modified and new files
git add -A
# Confirm staging
✓ Staged 3 files
# Continue to Step 1 (Analyze Staged Changes)
```
**If user chooses Option 2** (Selective staging):
- Prompt user: "Which files would you like to stage?"
- User provides list or pattern
- Stage those specific files
- If they want to use `git add -p`: pause and let them do it manually, then re-run draft-commit
```bash
# User specifies: src/api/export.py, tests/test_export.py
git add src/api/export.py tests/test_export.py
✓ Staged 2 files:
- src/api/export.py
- tests/test_export.py
Excluded from staging:
- src/utils/validation.py
# Continue to Step 1
```
**If user chooses Option 3** (Run pre-commit-check first):
- Exit with message: "Run /git-workflow:pre-commit-check to validate quality first, then come back to draft-commit."
- This is the recommended workflow if checks haven't been run
**If user chooses Option 4** (Cancel):
- Exit with message: "No changes staged. Stage your changes when ready."
#### State 3: No changes at all
If no staged, unstaged, or untracked files:
```
❌ **No Changes to Commit**
Current state:
- Working directory clean
- No files staged for commit
- No modified or new files
Make some changes first, then run /git-workflow:draft-commit
```
Exit gracefully.
---
### Step 1: Analyze Staged Changes
After files are staged (either already staged or staged via Step 0):
```bash
# Get staged changes
git diff --staged
```
Examine:
- Which files are changed
- What functionality is affected
- Scope/component of changes
- Nature of the changes (new feature, bug fix, etc.)
### Step 2: Determine Commit Type
If `--type` not provided, infer from changes:
- **feat**: New functionality, new files with features
- **fix**: Bug fixes, error handling improvements
- **docs**: Documentation-only changes (README, comments)
- **refactor**: Code restructuring without behavior change
- **test**: Test additions or updates
- **chore**: Dependency updates, build config, tooling
- **perf**: Performance improvements
- **style**: Formatting, whitespace, code style
- **ci**: CI/CD configuration changes
### Step 3: Determine Scope
If `--scope` not provided, infer from files:
- Look at directory structure (e.g., `src/auth/*` → scope: `auth`)
- Look at module names (e.g., `api/users.py` → scope: `api` or `users`)
- If changes span multiple areas, choose the primary one or omit scope
Common scopes in general:
- `auth`, `api`, `ui`, `database`, `pipeline`, `models`, `tests`, `docs`, `config`
### Step 4: Activate Agent and Skill
```
Activate: git-workflow-specialist agent
Agent activates: commit-message-standards skill
```
### Step 5: Craft Commit Message
**Subject line** (≤50 characters):
```
<type>(<scope>): <clear, specific description>
```
Requirements:
- Use imperative mood ("add" not "added")
- Start with lowercase
- No period at end
- Be specific about what changed
**Body** (optional but recommended):
- Explain WHY the change was made
- Provide context or background
- Note any important technical decisions
- Wrap lines at 72 characters
**Footer** (for issue references):
- Check commit type against issue linking policy
- If feat or fix: Include issue reference (REQUIRED)
- If refactor/perf: Include issue reference (RECOMMENDED)
- If docs/chore/test: Issue reference optional
Format:
- `Closes #123` - For features that close an issue
- `Fixes #456` - For bug fixes
- `Relates to #789` - For related work
### Step 6: Check Against Standards
Validate the draft message:
- [ ] Follows Conventional Commits format
- [ ] Subject ≤50 characters
- [ ] Uses imperative mood
- [ ] Specific and clear (not vague like "fix bug")
- [ ] Includes issue reference if required by type
- [ ] Body provides context (if non-trivial change)
- [ ] No WIP or temp language
### Step 7: Present Draft Message
Display the complete draft message in a code block:
```
<type>(<scope>): <subject>
[Body explaining why and providing context]
[Footer with issue reference if applicable]
```
Then provide:
1. **Explanation** of why this message structure was chosen
2. **Issue linking note** if issue reference is required but missing
3. **Alternative suggestions** if applicable
## Output Format
Present the draft commit message like this:
```markdown
## Draft Commit Message
\```
feat(auth): add two-factor authentication support
Implements TOTP-based 2FA for user accounts to enhance security.
Users can enable 2FA in account settings and must verify with
authenticator app on subsequent logins.
Closes #123
\```
## Explanation
**Type**: `feat` - This adds new functionality (2FA feature)
**Scope**: `auth` - Changes are in authentication system
**Subject**: Clear and specific about what was added
**Body**: Explains the implementation approach and user impact
**Footer**: Includes `Closes #123` as required for feat commits
## Notes
✅ Follows Conventional Commits format
✅ Subject is 48 characters (under 50 limit)
✅ Uses imperative mood ("add")
✅ Includes required issue reference for feat type
✅ Body provides clear context
## Next Steps
**If `--interactive=true` (default)**, prompt the user:
\```markdown
Would you like to:
1. ✅ **Accept and commit** - Use this message and execute `git commit`
2. ✏️ **Edit message** - Modify the message before committing
3. ❌ **Cancel** - Don't commit, just show the draft
Enter your choice (1, 2, or 3):
\```
**Option 1: Accept and commit**
- Execute the commit with the drafted message
- Show confirmation: "✅ Committed successfully with message: [first line]"
**Option 2: Edit message**
- Display the message in an editable format
- User can modify subject, body, or footer
- After editing, prompt again: Accept edited version or Cancel
- Execute commit with edited message
**Option 3: Cancel**
- Display: "Draft message saved for reference but not committed."
- Provide copy command:
\```bash
git commit -m "$(cat <<'EOF'
feat(auth): add two-factor authentication support
Implements TOTP-based 2FA for user accounts to enhance security.
Users can enable 2FA in account settings and must verify with
authenticator app on subsequent logins.
Closes #123
EOF
)"
\```
**If `--interactive=false`**, just display the draft and copy command without prompting.
```
## Special Cases
**No Issue Exists**:
If feat/fix commit but no issue reference found in changes:
```markdown
⚠️ **Issue Reference Required**
This is a `feat` commit, which requires an issue reference per standards.
Options:
1. Create a GitHub issue first, then update commit message
2. Provide detailed context in commit body explaining why no issue
Example with detailed context:
\```
feat(api): add rate limiting to prevent abuse
Implements token bucket algorithm with 100 requests/minute limit.
Prevents API abuse and ensures fair usage across all clients.
No issue created as this is a quick security hardening measure
responding to recent spike in automated requests.
\```
```
**Multiple Changes in Staging**:
If staged changes mix multiple types (feat + fix):
```markdown
⚠️ **Multiple Change Types Detected**
Your staged changes include both new features AND bug fixes.
Recommendation: Split into separate commits for cleaner history.
Suggested approach:
1. Unstage all: `git reset`
2. Stage and commit feature changes first
3. Then stage and commit bug fixes separately
```
**Trivial Changes** (docs, formatting):
```markdown
## Draft Commit Message (Simple)
\```
docs(readme): update installation instructions for Python 3.11
\```
This is a simple documentation change, so no body or issue reference needed.
```
## Important Notes
- **Read staged changes first**: Always examine `git diff --staged` before drafting
- **Be specific**: Avoid vague subjects like "update code" or "fix bug"
- **Context matters**: Provide body for non-trivial changes
- **Issue linking**: Enforce policy from commit-message-standards skill
- **No assumptions**: If unclear, ask user for clarification
- **Quality over speed**: Take time to craft a good message
## Error Handling
| Error | Message | Resolution |
|-------|---------|------------|
| **No changes** | ❌ No staged/unstaged changes to commit | Make changes first, then run command |
| **Ambiguous type** | Commit type unclear from changes | Specify: `/git-workflow:draft-commit --type=feat` |
## Interactive Workflow (Default)
When `--interactive=true` (default), follow this flow:
1. **Draft message** (as described above)
2. **Present to user** with explanation and validation notes
3. **Prompt for action**:
```
Would you like to:
1. ✅ Accept and commit
2. ✏️ Edit message
3. ❌ Cancel
```
4. **Handle user choice**:
**Choice 1 - Accept and commit**:
```bash
# Execute commit
git commit -m "$(cat <<'EOF'
[drafted message]
EOF
)"
# Confirm
✅ Committed successfully: feat(auth): add two-factor authentication support
```
**Choice 2 - Edit message**:
```markdown
## Edit Commit Message
Current draft:
\```
feat(auth): add two-factor authentication support
Implements TOTP-based 2FA for user accounts to enhance security.
Users can enable 2FA in account settings and must verify with
authenticator app on subsequent logins.
Closes #123
\```
Please provide your edited version below:
[Wait for user input]
[After user provides edited version]
Updated message:
\```
[user's edited version]
\```
Would you like to:
1. ✅ Commit with edited message
2. ❌ Cancel
```
**Choice 3 - Cancel**:
```markdown
Draft message not committed. You can manually commit using:
\```bash
git commit -m "$(cat <<'EOF'
[drafted message]
EOF
)"
\```
```
---
**Remember**: Interactive mode (default) allows executing commits directly. Non-interactive mode just displays the draft.

306
commands/draft-pr.md Normal file
View File

@@ -0,0 +1,306 @@
---
description: Generate standards-compliant PR title and description from branch changes
---
# Draft PR Description
You are helping a developer create a **standards-compliant pull request** for their branch.
## Command Parameters
**Base Branch Parameter:**
- `--base=main` - Base branch for comparison (default: main)
**Interactive Parameter:**
- `--interactive` (default: true) - Prompt to create PR after drafting
- `--interactive=false` - Just show draft without creating PR
**Format Parameter:**
- `--format=console` (default) - Display draft and prompt for action
**Usage Examples:**
```bash
/git-workflow:draft-pr # Compare to main, interactive
/git-workflow:draft-pr --base=develop # Compare to develop branch
/git-workflow:draft-pr --interactive=false # Just show draft
```
## Objective
Generate a high-quality PR that:
1. Follows PR quality standards
2. Has clear, descriptive title
3. Includes complete description (Purpose, Changes, Testing, Impact)
4. References appropriate GitHub issue(s)
5. Flags if PR is too large
## Activated Agent
**Activate**: `git-workflow-specialist` agent
## Activated Skills
- **`pr-quality-standards`** - PR sizing, scope, documentation, issue linking
- **`github-workflow-patterns`** - Best practices for PRs
## Process
### Step 1: Analyze Branch Changes
```bash
# Get commits on this branch
git log main..HEAD
# Get diff summary
git diff main...HEAD --stat
# Get full diff for analysis
git diff main...HEAD
```
Examine:
- Number of commits
- Files changed and LOC
- Scope of changes (single feature vs multiple)
- Component/module affected
### Step 2: Determine PR Title
Format: `<type>: <clear description>`
Type based on changes:
- `feat`: New functionality
- `fix`: Bug fixes
- `refactor`: Code restructuring
- `docs`: Documentation updates
- `chore`: Maintenance, dependencies
Example: `feat: add customer export API endpoint`
### Step 3: Check PR Size
**Size thresholds:**
- Small: < 200 LOC ✅
- Medium: 200-500 LOC ⚠️
- Large: 500-1000 LOC ⚠️ (flag and suggest split)
- Too Large: > 1000 LOC ❌ (recommend splitting)
**File count:** Flag if > 15 files
### Step 4: Detect Multi-Purpose Issues
Red flags:
- Commits with different types (feat + fix + chore)
- Changes in unrelated components
- Multiple features in one PR
If detected: Recommend splitting into focused PRs
### Step 5: Draft Description
**Template:**
```markdown
## Purpose
[Why is this change needed? What problem does it solve?]
## Changes
- [High-level summary of modifications]
- [Key technical decisions]
- [Any breaking changes]
## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing completed
## Impact
- [Who/what is affected?]
- [Performance implications?]
- [Follow-up work needed?]
[Issue reference: Closes #123]
```
### Step 6: Check Issue Linking
Based on PR type:
- **feat, fix, breaking**: Issue reference REQUIRED
- **refactor (>200 LOC), perf**: Issue reference RECOMMENDED
- **docs, chore, small refactor**: Issue reference OPTIONAL
Format: `Closes #123`, `Fixes #456`, `Relates to #789`
### Step 7: Present Draft
Show:
1. PR title
2. Complete description
3. Size analysis
4. Multi-purpose warnings (if any)
5. Issue linking status
## Output Format
```markdown
## Draft Pull Request
**Title:**
\```
feat: add customer export API endpoint
\```
**Description:**
\```markdown
## Purpose
Enable customers to export their data in CSV or JSON format for compliance
and data portability requirements.
## Changes
- Added /api/customers/export endpoint with format parameter
- Implemented CSV and JSON serializers
- Added authentication and rate limiting
- Updated API documentation
## Testing
- [x] Unit tests for serializers and endpoint
- [x] Integration tests for auth and rate limiting
- [x] Manual testing with sample customer data
- [x] Tested both CSV and JSON formats
## Impact
- New API endpoint available to all authenticated users
- Rate limited to 10 requests/hour per user
- No changes to existing endpoints
Closes #234
\```
---
## Size Analysis
**Files changed:** 8 files (+245, -12)
**LOC changed:** 257 lines
**Size:** Medium ⚠️ (within acceptable range)
✅ PR is reasonably sized and focused
---
## Validation
✅ Single-purpose PR (one feature)
✅ Clear title and description
✅ Issue reference present (required for feat)
✅ Testing section complete
✅ Impact documented
---
## Next Steps
**If `--interactive=true` (default)**, prompt:
Would you like to:
1. ✅ **Create PR** - Open pull request with this content
2. ✏️ **Edit** - Modify title or description
3. ❌ **Cancel** - Just show draft
Enter your choice (1, 2, or 3):
```
## Interactive Options
**Option 1 - Create PR:**
```bash
gh pr create \
--title "feat: add customer export API endpoint" \
--body "$(cat <<'EOF'
[full description]
EOF
)"
✅ Pull request created: #456
View at: https://github.com/owner/repo/pull/456
```
**Option 2 - Edit:**
```markdown
## Edit PR Content
Current title:
feat: add customer export API endpoint
New title (press Enter to keep current):
[Wait for user input]
Current description:
[Show description]
New description (press Enter to keep current):
[Wait for user input]
[After edits] Would you like to:
1. Create PR with edited content
2. Cancel
```
**Option 3 - Cancel:**
```markdown
Draft PR saved for reference. You can create it manually:
\```bash
gh pr create --title "feat: add customer export API endpoint" --body "..."
\```
```
## Size Warnings
**If PR is too large (>1000 LOC):**
```markdown
⚠️ **PR Too Large**
This PR changes 1,245 lines across 23 files, which will be difficult to review.
**Recommendation:** Split into smaller PRs
**Suggested split strategy:**
1. PR 1: Database schema changes (backend foundation)
2. PR 2: API endpoint implementation
3. PR 3: Frontend integration
4. PR 4: Tests and documentation
Would you like help planning the split? (yes/no)
```
**If multi-purpose detected:**
```markdown
⚠️ **Multi-Purpose PR Detected**
This PR includes changes for multiple unrelated purposes:
- New feature: customer export
- Bug fix: authentication timeout
- Chore: dependency updates
**Recommendation:** Create separate PRs for each purpose
1. feat: add customer export endpoint
2. fix: resolve authentication timeout
3. chore: update dependencies
This will make review easier and history clearer.
Would you like me to help split this? (yes/no)
```
## Important Notes
- **Analyze commits**: Look at all commits on branch, not just latest
- **Check for focus**: Flag if changes span unrelated components
- **Size matters**: Warn if too large for effective review
- **Issue linking**: Enforce based on PR type
- **Breaking changes**: Detect and highlight prominently
---
**Remember**: This generates PR drafts. For validating existing PRs, use `/git-workflow:validate-pr`.

444
commands/pre-commit-check.md Normal file
View File

@@ -0,0 +1,444 @@
---
description: Run comprehensive pre-commit checks with project-aware validation
---
# Pre-Commit Check
You are running **pre-commit quality checks** before allowing a commit or push.
## Command Parameters
**Scope Parameter:**
- `--scope=commit` (default) - Check staged changes and commit message
- `--scope=push` - Check all commits on branch before push
**Auto-Fix Parameter:**
- `--auto-fix` (default: false) - Attempt to fix issues automatically
**Format Parameter:**
- `--format=console` (default) - Display results in console
- `--format=markdown` - Generate markdown report
**Output Parameter:**
- `--output=<path>` - Custom report path (only with --format=markdown)
**Usage Examples:**
```bash
/git-workflow:pre-commit-check # Check staged changes
/git-workflow:pre-commit-check --scope=push # Check before push
/git-workflow:pre-commit-check --auto-fix # Fix issues automatically
/git-workflow:pre-commit-check --format=markdown # Generate report
```
## Objective
Run comprehensive quality checks based on:
1. Project type detection (Python, Data Science, Plugin Marketplace)
2. Pre-commit framework status (installed or not)
3. Universal checks (always run)
4. Project-specific checks (context-aware)
## Activated Agent
**Activate**: `git-workflow-specialist` agent
## Activated Skills
- **`commit-message-standards`** - Validate commit format
- **`github-workflow-patterns`** - Branch naming, pre-commit best practices
- **`pre-commit-quality-standards`** - Project type detection, quality checks, pre-commit configs
## Check Process
### Step 0: Check Git Status and Handle Unstaged Changes
**IMPORTANT**: Before running any checks, detect what files need to be checked.
```bash
# Check for staged changes
git diff --cached --name-only
# Check for unstaged changes
git diff --name-only
# Check for untracked files
git ls-files --others --exclude-standard
```
**Determine the state**:
#### State 1: Files already staged
If there are staged files, proceed to check them:
```
Found staged changes:
- src/api/export.py
- tests/test_export.py
Running quality checks on 2 staged files...
```
Continue to Step 1 (Detect Project Type).
#### State 2: No staged files, but unstaged/untracked files exist
If no files are staged but there are modified or new files, offer interactive options:
```
No staged changes found.
Detected modified/new files:
- src/api/export.py (modified)
- src/utils/validation.py (modified)
- tests/test_export.py (new file)
What would you like to do?
1. ✓ Check all modified/new files (recommended)
2. ✏️ Stage specific files first, then check (git add -p)
3. ⏭️ Cancel - nothing to check
```
**If user chooses Option 1** (Check all files):
- Temporarily stage all modified/new files for checking purposes
- Run all quality checks
- After checks complete, **unstage** them if they weren't originally staged
- Report: "Files checked but not staged. Run /git-workflow:draft-commit to stage and commit."
**If user chooses Option 2** (Selective staging):
- Pause and instruct user to run `git add -p` or `git add <specific-files>`
- After staging, re-run pre-commit-check
- Continue to Step 1
**If user chooses Option 3** (Cancel):
- Exit with message: "No files to check. Make changes first."
#### State 3: No changes at all
If no staged, unstaged, or untracked files:
```
No changes detected.
Current state:
- Working directory clean
- No files staged for commit
Make some changes first, then run /git-workflow:pre-commit-check
```
Exit gracefully.
---
### Step 1: Detect Project Type
Use the **`pre-commit-quality-standards`** skill to detect project type(s).
Examine repository for indicators of:
- Python projects
- Data Science projects
- Plugin Marketplace projects
- Mixed projects (e.g., Python + Data Science)
### Step 2: Check Pre-Commit Status
```bash
# Check if pre-commit is configured
test -f .pre-commit-config.yaml && echo "configured" || echo "not configured"
# If configured, check if installed
pre-commit --version 2>/dev/null && echo "installed" || echo "not installed"
```
**Three scenarios**:
1. **Configured + Installed**: Run pre-commit hooks
2. **Configured but not installed**: Warn and suggest `pre-commit install`
3. **Not configured**: Run Claude-native checks + offer to generate config
### Step 3: Universal Checks (Always Run)
Run all universal checks from the **`pre-commit-quality-standards`** skill:
1. **Commit Message Validation** (if `--scope=commit`) - Use `commit-message-standards` skill
2. **Branch Naming Validation** - Use `github-workflow-patterns` skill
3. **Secret Detection** - Use patterns from `pre-commit-quality-standards`
4. **Large File Detection** - Thresholds defined in `pre-commit-quality-standards`
5. **Merge Conflict Markers** - Check for `<<<<<<<`, `=======`, `>>>>>>>`
6. **Trailing Whitespace** - Use `git diff --staged --check`
7. **Direct Commits to Protected Branches** - Fail if on main/master
### Step 4: Run Pre-Commit Hooks (If Configured)
If `.pre-commit-config.yaml` exists and pre-commit is installed:
```bash
# For commit scope - run on staged files only
pre-commit run
# For push scope - run on all files
pre-commit run --all-files
```
**Parse output**:
- Extract failed hooks
- Report specific file/line issues
- If `--auto-fix`: re-run with auto-fixing enabled
**If pre-commit configured but NOT installed**:
```markdown
⚠️ **Pre-commit configured but not installed**
Your project has `.pre-commit-config.yaml` but pre-commit is not installed.
To install:
\```bash
pip install pre-commit
pre-commit install
\```
Continuing with Claude-native checks...
```
### Step 5: Project-Specific Claude-Native Checks
If pre-commit is NOT configured, run project-specific checks from the **`pre-commit-quality-standards`** skill based on detected project type(s):
- **Python Projects**: Syntax validation, debug statements, print statements, hardcoded paths
- **Plugin Marketplace Projects**: JSON validation, markdown linting, plugin structure
- **Data Science Projects**: Notebook size, outputs in notebooks, large data files
See `pre-commit-quality-standards` skill for complete check definitions.
### Step 6: Generate Recommendations
If pre-commit is NOT configured, use the **`pre-commit-quality-standards`** skill to:
1. Select appropriate pre-commit config template based on detected project type
2. Offer to create `.pre-commit-config.yaml` file
3. Provide installation instructions
## Output Format
### When All Checks Pass
```markdown
## Pre-Commit Check Results
**Scope**: commit
**Project Type**: Python
**Pre-commit**: Configured ✅
---
**All Checks Passed** ✅
- ✅ Branch naming follows convention (feature/add-export)
- ✅ Not on protected branch
- ✅ No secrets detected
- ✅ No large files
- ✅ No merge conflict markers
- ✅ Pre-commit hooks passed (black, ruff, mypy)
**Checked Files**:
- src/api/export.py
- src/utils/validation.py
- tests/test_export.py
**Summary**: Quality checks passed! Files are ready to commit.
**Next Step**: Run /git-workflow:draft-commit to stage and commit these changes.
```
### When Checks Fail
```markdown
## Pre-Commit Check Results
**Scope**: commit
**Project Type**: Python
**Pre-commit**: Not configured ⚠️
---
**Status**: ❌ FAIL
**Blocking Issues**:
1. ❌ **Commit message invalid**
- Current: "fix bug"
- Problem: Too vague, missing scope
- Fix: Use format `fix(<scope>): specific description`
- Run: `/git-workflow:draft-commit` to generate proper message
2. ❌ **Potential secret detected**
- File: `src/config.py`
- Line 15: `api_key = "sk-1234567890abcdef"`
- Action: Remove hardcoded secret, use environment variable
3. ❌ **Debug statement found**
- File: `src/api/users.py`
- Line 42: `import pdb; pdb.set_trace()`
- Action: Remove debug statement
**Warnings**:
1. ⚠️ **Large file staged**
- File: `data/export.csv` (15.2 MB)
- Consider: Use Git LFS or exclude from repository
2. ⚠️ **Print statements found**
- File: `src/api/export.py`
- Lines: 23, 45, 67
- Consider: Use logging instead of print()
**Summary**: 3 errors, 2 warnings - Cannot commit
---
## Recommendations
**Install pre-commit hooks** for automated checking:
\```bash
pip install pre-commit
\```
Create `.pre-commit-config.yaml` using the template from **`pre-commit-quality-standards`** skill for your project type:
- Python projects: Use Python template (black, ruff, mypy, detect-secrets)
- Plugin Marketplace: Use Marketplace template (markdownlint, YAML/JSON validation)
- Data Science: Use Data Science template (nbQA, nbstripout, black, ruff)
Then run:
\```bash
pre-commit install
\```
Would you like me to create this file for you? (yes/no)
```
### When Pre-Commit Configured But Not Installed
```markdown
## Pre-Commit Check Results
**Scope**: commit
**Project Type**: Python
**Pre-commit**: Configured but not installed ⚠️
---
⚠️ **Pre-commit hooks are configured but not installed**
Your project has `.pre-commit-config.yaml` with these hooks:
- black (formatting)
- ruff (linting)
- mypy (type checking)
- detect-secrets
**To install**:
\```bash
pip install pre-commit
pre-commit install
\```
**Continuing with Claude-native checks...**
---
[Rest of check results...]
```
## Auto-Fix Workflow
When `--auto-fix` is enabled:
### Step 1: Attempt Automatic Fixes
**If pre-commit configured**:
```bash
# Many pre-commit hooks support auto-fixing
pre-commit run --all-files
```
Hooks like black, prettier, trailing-whitespace will fix issues automatically.
**If using Claude-native checks**:
- Fix trailing whitespace
- Remove debug statements (if user confirms)
- Format basic syntax issues
### Step 2: Report What Was Fixed
```markdown
## Auto-Fix Results
**Fixes Applied** ✅:
1. ✅ **Formatted code with black**
- Files: `src/api/users.py`, `src/api/export.py`
- Changes: Line length normalized, imports sorted
2. ✅ **Removed trailing whitespace**
- Files: 5 files affected
**Issues Requiring Manual Fix** ❌:
1. ❌ **Potential secret detected**
- File: `src/config.py`
- Cannot auto-fix: Requires manual review and environment variable setup
2. ❌ **Commit message invalid**
- Run: `/git-workflow:draft-commit` to generate proper message
**Next Steps**:
1. Review auto-applied fixes: `git diff`
2. Fix remaining issues manually
3. Re-run checks: `/git-workflow:pre-commit-check`
```
## Push-Scope Checks
When `--scope=push`:
### Additional Checks:
1. **Validate All Commits on Branch**:
```bash
# Get all commits on current branch
git log main..HEAD --format="%H %s"
# Validate each commit message
for commit in $(git log main..HEAD --format="%H"); do
git log -1 $commit --format="%s%n%n%b" | validate
done
```
2. **Check for Divergence**:
```bash
# Check if branch is behind main
git fetch origin
git rev-list HEAD..origin/main --count
```
⚠️ **Warn** if branch is behind main (suggest rebase/merge)
3. **Verify No Direct Commits to Main**:
Already covered in universal checks, but more critical for push.
4. **Check for Force Push Protection**:
```bash
# Check if this would be a force push
git push --dry-run --force 2>&1 | grep "rejected"
```
❌ **Fail** if force push to protected branch
## Important Notes
- **Non-blocking by default**: Checks report issues but don't prevent commits (user decides)
- **Can be integrated**: Results can drive actual git hooks via exit codes
- **Progressive enhancement**: Works without pre-commit, better with it
- **Project-aware**: Adapts checks to project type
- **Educational**: Explains WHY issues are problems and HOW to fix
**Exit codes** (for git hook integration):
- `0` - All checks passed
- `1` - Blocking issues found
- `2` - Warnings only (non-blocking)
---
**Remember**: This command is flexible - it works standalone, as a pre-commit hook, or as a quality gate before pushing.

377
commands/spec-issue.md Normal file
View File

@@ -0,0 +1,377 @@
---
description: Create detailed implementation specification from a GitHub issue through interactive planning
---
# Spec Issue Command
You are helping a developer create a **detailed implementation specification** from a GitHub issue.
## Command Parameters
**Issue Parameter:**
- `--issue=<number>` - GitHub issue number (optional - will prompt if not provided)
**Repository Parameter:**
- `--repo=<owner/repo>` - Repository (default: auto-detect from git remote)
**Usage Examples:**
```bash
/git-workflow:spec-issue # Interactive - prompts for issue
/git-workflow:spec-issue --issue=15 # Spec for issue #15
/git-workflow:spec-issue --issue=22 --repo=owner/repo # Specify repo
```
## Objective
Transform a high-level GitHub issue into a detailed, actionable implementation specification including:
- Overview and scope
- Architecture decisions and rationale
- Component design breakdown
- File structure
- Phased implementation checklist
- Technical considerations
- Next steps
## Activated Agent
**Activate**: `git-workflow-specialist` agent
## Activated Skills
- **`github-workflow-patterns`** - For GitHub best practices and workflows
- **`github-issue-analysis`** - For understanding issue structure and prioritization
## Process
### Step 0: Issue Selection
If `--issue` parameter is not provided, help user select an issue interactively.
#### Fetch Recent Issues
```bash
# List recent open issues
gh issue list --limit 20 --json number,title,labels,createdAt
```
#### Present Issue List
Display issues in a clear, scannable format:
```
Which issue would you like to create a spec for?
Recent open issues:
1. #22 - Define scripts for programmatic auditing checks [enhancement]
2. #21 - Compare performance using different models
3. #20 - Plugin creation through GH issue workflow
4. #17 - MCP Confluence Integration
5. #15 - Add Git-Workflow Plugin [enhancement, git, github]
6. #14 - Outline Python-Dev Plugin for personal use Marketplace [enhancement]
...
Enter issue number (or 'cancel' to exit):
```
**User provides number:**
- Validate the number exists in the list
- If valid, proceed to Step 1
- If invalid, show error and re-prompt
**User types 'cancel':**
- Exit gracefully: "Spec creation cancelled."
#### If --issue Provided
Skip the selection step and proceed directly to Step 1 with the provided issue number.
---
### Step 1: Fetch Issue Details
Once issue number is selected, fetch complete issue information:
```bash
# Fetch issue with all details
gh issue view <number> --json title,body,labels,comments,createdAt,updatedAt
```
**Parse and display:**
```
Fetching issue #<number>...
✓ Issue loaded
Title: <issue-title>
Labels: [label1, label2, ...]
Created: <date>
Description:
<issue-body>
Comments: <number> comments
[Optionally show recent comments if relevant to planning]
Ready to create specification for this issue.
```
**Validate issue exists:**
- If issue not found: "❌ Issue #<number> not found. Please check the issue number."
- Exit gracefully
### Step 2: Interactive Planning
Ask clarifying questions to understand the implementation approach. Adapt questions based on issue content and labels.
#### Question 1: Implementation Type
```
What type of implementation is this?
1. 🔌 New plugin
2. 📝 New command in existing plugin
3. ✨ Feature enhancement to existing component
4. 🔧 Refactoring/improvement
5. 📚 Documentation
Enter choice (1-5):
```
#### Question 2: Architecture Pattern (if applicable)
For plugins or complex features:
```
What architecture pattern should we use?
1. Workflow Orchestration + Agent + Skills (complex, interactive workflows)
2. Commands + Skills (moderate complexity, reusable patterns)
3. Commands only (simple, standalone functionality)
Enter choice (1-3):
```
#### Question 3: Core Capabilities
```
Describe the core capabilities needed (1-2 sentences):
[User input]
```
#### Question 4: Components Needed
Based on architecture choice, ask about specific components:
**For Agent + Skills + Commands:**
```
What components are needed?
- Agent name/role:
- Skills (comma-separated):
- Commands (comma-separated):
```
**For Commands + Skills:**
```
What components are needed?
- Commands (comma-separated):
- Skills (comma-separated, if any):
```
#### Question 5: Implementation Phases
```
How should implementation be phased?
1. Single phase (implement all at once)
2. Multiple phases (specify below)
[If multiple phases]
Describe phases (one per line):
Phase 1:
Phase 2:
...
```
#### Question 6: Technical Constraints
```
Any technical constraints or considerations? (optional)
- Token budgets?
- Performance requirements?
- Integration dependencies?
[User input or skip]
```
**Store all answers** to use in spec generation (Step 3).
### Step 3: Generate Specification
Using answers from Step 2 and the issue details, generate a comprehensive specification document.
#### Spec Structure
```markdown
# [Issue Title] - Implementation Specification
**Generated**: [date]
**Status**: Design Specification for Implementation
---
## Overview
**Purpose**: [From core capabilities answer]
**Use Cases**:
- [Extracted from issue or inferred]
**Scope**:
- **Included**: [What will be implemented]
- **Excluded**: [What is out of scope, if any]
---
## Architecture Decision
**Pattern**: [From Question 2 answer]
**Rationale**:
[Explain why this pattern was chosen based on requirements]
**Benefits**:
- [List key benefits of this approach]
---
## Component Design
[Based on architecture choice - include agents, skills, commands sections]
### Agent (if applicable)
- **Name**: [agent-name]
- **Role**: [description]
- **Responsibilities**: [what it does]
### Skills (if applicable)
For each skill:
- **Name**: [skill-name]
- **Purpose**: [what it provides]
- **Used By**: [which components use it]
### Commands
For each command:
- **Name**: [command-name]
- **Purpose**: [what it does]
- **Parameters**: [list parameters]
- **Workflow**: [high-level flow]
---
## File Structure
\```
[directory tree of files to create]
\```
---
## Implementation Checklist
[Generate phases from Question 5]
### Phase 1: [name]
- [ ] Task 1
- [ ] Task 2
### Phase 2: [name]
- [ ] Task 1
---
## Technical Considerations
[From Question 6 or inferred from issue]
---
## Next Steps
1. Review specification
2. [Additional steps based on context]
```
**Generate this spec** based on all gathered information.
### Step 4: Output Options
Present interactive output options:
```
✓ Specification generated successfully!
What would you like to do with this spec?
1. 📄 Write to markdown file
2. 💬 Post as comment to GitHub issue #<number>
3. 📺 Display in terminal only
4. ✅ Both - write to file AND post to issue
Enter your choice (1-4):
```
| Option | Actions | Commands |
|--------|---------|----------|
| **1. Write to File** | Prompt for path (default: `./specs/issue-<number>-spec.md`)<br>Create `specs/` directory<br>Write spec to file | `mkdir -p specs`<br>`cat > path <<'EOF' [spec] EOF` |
| **2. Post to Issue** | Post spec as comment to GitHub issue | `gh issue comment <number> --body "[spec]"` |
| **3. Display Only** | Print full spec to console<br>No file/issue creation | *(Display spec content)* |
| **4. Both** | Execute options 1 AND 2<br>Prompt for path, write file, post to issue | *(Combine 1 + 2)* |
**Confirmation messages** (after execution):
- Option 1: `✓ Spec written to [path]`
- Option 2: `✓ Spec posted to https://github.com/<owner>/<repo>/issues/<number>`
- Option 3: `Note: Spec displayed only (not saved)`
- Option 4: Both confirmations from 1 + 2
---
## Important Notes
- **Be thorough**: Generate comprehensive specs that answer implementation questions
- **Be specific**: Include concrete component names, file paths, and task breakdowns
- **Be helpful**: Provide context and rationale for decisions
- **Be flexible**: Adapt structure based on implementation type
- **Ask when unclear**: If issue is vague, ask clarifying questions
## Error Handling
**Issue not found:**
```
❌ Issue #<number> not found in this repository.
Check:
- Issue number is correct
- You have access to this repository
- Issue hasn't been deleted
Try: gh issue list
```
**gh command not available:**
```
❌ GitHub CLI (gh) is not installed or not authenticated.
Install: https://cli.github.com/
Authenticate: gh auth login
Cannot proceed without gh CLI.
```
**Invalid input:**
```
❌ Invalid choice. Please enter 1, 2, 3, or 4.
[Re-prompt]
```
---
**Remember**: This command transforms ideas into actionable plans. Be thorough, ask good questions, and generate clear specifications that make implementation straightforward.
---
**Remember**: This command is fully interactive and guides users through creating comprehensive specs without requiring them to know all parameters upfront.

233
commands/validate-commit.md Normal file
View File

@@ -0,0 +1,233 @@
---
description: Validate commit message quality against standards
---
# Validate Commit Message
You are validating a **commit message** against standards.
## Command Parameters
**Message Parameter:**
- `--message="commit message"` - Message to validate (default: read from git staging)
**Format Parameter:**
- `--format=console` (default) - Display validation results in console
- `--format=markdown` - Generate markdown validation report
**Output Parameter:**
- `--output=<path>` - Custom report path (only with --format=markdown)
**Usage Examples:**
```bash
/git-workflow:validate-commit # Validate staged commit
/git-workflow:validate-commit --message="fix bug in auth" # Validate specific message
/git-workflow:validate-commit --format=markdown # Generate report
```
## Objective
Validate commit message against:
1. Conventional Commits format
2. commit message standards
3. Issue linking policy
4. Quality criteria
## Activated Agent
**Activate**: `git-workflow-specialist` agent
## Activated Skills
- **`commit-message-standards`** - Format, quality, issue linking policy
## Validation Process
### Step 1: Get Commit Message
If `--message` provided: Use that
If not: Read from git prepare-commit-msg or last commit
### Step 2: Check Format
✅ **Pass criteria:**
- Matches: `<type>(<scope>): <subject>`
- Type is valid (feat, fix, docs, refactor, test, chore, perf, style, ci)
- Subject ≤50 characters
- Uses imperative mood
- Starts with lowercase
- No period at end
❌ **Fail if:**
- No type prefix
- Invalid type
- Subject too long
- Vague (e.g., "fix bug", "update code")
### Step 3: Check Issue Linking
Based on commit type:
- **feat, fix**: Issue reference REQUIRED
- **refactor, perf**: Issue reference RECOMMENDED
- **docs, chore, test, style**: Issue reference OPTIONAL
✅ **Pass**: Has `Closes #123`, `Fixes #456`, or `Relates to #789`
⚠️ **Warning**: Missing but recommended
❌ **Fail**: Missing and required
### Step 4: Check Quality
- Not WIP/temp language
- Specific (not vague)
- Clear intent
- Appropriate body for non-trivial changes
## Output Format
```markdown
## Validation Results
**Message:**
\```
fix bug in auth
\```
**Status:** ❌ FAIL
**Issues Found:**
1. ❌ **Missing commit type format**
- Current: "fix bug in auth"
- Required: `fix(<scope>): <subject>`
- Fix: Add type prefix and scope
2. ❌ **Subject too vague**
- "bug in auth" doesn't explain what was fixed
- Be specific: which bug? what behavior?
3. ❌ **Missing issue reference**
- fix commits require issue reference
- Add: `Fixes #<issue-number>`
**Correct Example:**
\```
fix(auth): resolve session timeout on mobile devices
Fixes #456
\```
**Summary:** 3 errors, 0 warnings
---
**Next Steps:**
Would you like me to:
1. 🤖 **Run `/git-workflow:draft-commit`** - Generate a proper message automatically
2. ✏️ **Help you fix this message** - Guide you through corrections
3. ❌ **Cancel** - Just show validation results
Enter your choice (1, 2, or 3):
```
## Pass Example
```markdown
## Validation Results
**Message:**
\```
feat(api): add customer export endpoint
Adds new /api/customers/export endpoint supporting CSV and JSON formats.
Closes #234
\```
**Status:** ✅ PASS
**Checks:**
- ✅ Conventional Commits format
- ✅ Valid type: feat
- ✅ Clear, specific subject (38 characters)
- ✅ Imperative mood
- ✅ Issue reference present (required for feat)
- ✅ Body provides context
**Summary:** All checks passed
✅ This message is ready to commit!
```
## Important Notes
- **Agent use**: Can be called by git-workflow-specialist when user provides a commit message
- **CI/CD ready**: Can run in pipelines to enforce standards
- **Pre-commit hook**: Can block bad commits
- **Learning tool**: Shows WHY a message is wrong
## Interactive Failure Handling
When validation **FAILS**, prompt user with next steps:
**Option 1 - Run draft-commit**:
```markdown
Running `/git-workflow:draft-commit` to generate a proper message...
[Executes draft-commit command]
```
**Option 2 - Help fix message**:
```markdown
Let's fix your message step by step:
**Current:** "fix bug in auth"
**Step 1: Add commit type**
Your message starts with "fix" which is good, but needs proper format.
\```
fix(<scope>): <subject>
\```
**Step 2: Add scope**
What component is affected? (e.g., auth, api, ui)
[Wait for user input: "auth"]
**Step 3: Make subject specific**
Current: "bug in auth"
What specific bug? What behavior was wrong?
[Wait for user input: "session timeout on mobile"]
**Step 4: Add issue reference**
fix commits require an issue reference. What issue does this fix?
[Wait for user input: "456"]
**Updated message:**
\```
fix(auth): resolve session timeout on mobile
Fixes #456
\```
Would you like to commit with this message? (yes/no)
```
**Option 3 - Cancel**:
```markdown
Validation results saved. No further action taken.
```
## When Validation Passes
If message passes all checks, simply confirm:
```markdown
✅ Message validated successfully - ready to commit!
```
No need to prompt for further action.
---
**Remember**:
- Validation failures → Offer to help fix or regenerate
- Validation passes → Confirm and done
- Can be used standalone or by git-workflow-specialist agent

297
commands/validate-pr.md Normal file
View File

@@ -0,0 +1,297 @@
---
description: Validate PR quality and readiness against standards
---
# Validate Pull Request
You are validating a **pull request** against quality standards.
## Command Parameters
**PR Parameter:**
- `--pr=<number>` - PR number to validate (default: auto-detect from current branch)
**Repository Parameter:**
- `--repo=<owner/repo>` - Repository (default: auto-detect)
**Check Parameters:**
- `--check-size` (default: true) - Flag oversized PRs
- `--check-scope` (default: true) - Detect multi-purpose PRs
**Format Parameter:**
- `--format=console` (default) - Display validation in console
- `--format=markdown` - Generate markdown report
**Output Parameter:**
- `--output=<path>` - Custom report path (only with --format=markdown)
**Usage Examples:**
```bash
/git-workflow:validate-pr # Auto-detect PR from branch
/git-workflow:validate-pr --pr=123 # Validate specific PR
/git-workflow:validate-pr --format=markdown # Generate report
```
## Objective
Validate PR against:
1. Title format and clarity
2. Description completeness
3. Size appropriateness
4. Single-purpose principle
5. Issue linking policy
6. Review readiness
## Activated Agent
**Activate**: `git-workflow-specialist` agent
## Activated Skills
- **`pr-quality-standards`** - Sizing, scope, documentation, issue linking
- **`github-workflow-patterns`** - PR best practices
## Validation Process
### Step 1: Fetch PR Details
```bash
gh pr view <number> --json title,body,files,additions,deletions,commits
```
### Step 2: Validate Title
✅ **Pass criteria:**
- Follows format: `<type>: <description>`
- Type is valid (feat, fix, refactor, docs, chore)
- Clear and specific (not vague)
- Descriptive (not just issue number)
❌ **Fail if:**
- No type prefix
- Vague (e.g., "updates", "changes")
- Only ticket number
### Step 3: Validate Description
✅ **Pass criteria:**
- Has Purpose section
- Has Changes summary
- Has Testing section
- Has Impact section
- Includes issue reference (if required by type)
❌ **Fail if:**
- Missing required sections
- No issue reference when required
- Empty or placeholder text
### Step 4: Check Size
**Thresholds:**
- Small: <200 LOC ✅
- Medium: 200-500 LOC ⚠️ (acceptable)
- Large: 500-1000 LOC ⚠️ (warning)
- Too Large: >1000 LOC ❌ (fail, recommend split)
**File count:** Warn if >15 files
### Step 5: Check Single-Purpose
Analyze commits and files for:
- Mixed commit types (feat + fix + chore)
- Unrelated file groups
- Multiple independent features
❌ **Fail if:** Multi-purpose detected
### Step 6: Check Issue Linking
Based on PR type:
- **feat, fix, breaking**: REQUIRED
- **refactor (>200 LOC), perf**: RECOMMENDED
- **docs, chore**: OPTIONAL
## Output Format
### Validation Failure
```markdown
## PR Validation Results
**PR:** #123 - "Updates to authentication"
**Status:** ❌ FAIL
---
**Issues Found:**
1. ❌ **Title not descriptive**
- Current: "Updates to authentication"
- Problem: Too vague, doesn't explain what was updated
- Fix: `feat: add two-factor authentication support`
2. ❌ **Missing issue reference**
- This appears to be a feature PR (feat)
- Issue reference is REQUIRED for feat PRs
- Add: `Closes #456` to description
3. ⚠️ **PR size warning**
- Files changed: 18 files
- LOC changed: 645 lines
- Size: Large (consider splitting for easier review)
4. ❌ **Incomplete description**
- Missing Testing section
- Missing Impact section
- Add these sections to meet standards
**Summary:** 3 errors, 1 warning
---
## Next Steps
Would you like me to:
1. 🤖 **Run `/git-workflow:draft-pr`** - Regenerate PR content from branch
2. ✏️ **Help you fix this PR** - Guide through corrections
3. ❌ **Cancel** - Just show validation results
Enter your choice (1, 2, or 3):
```
### Validation Success
```markdown
## PR Validation Results
**PR:** #234 - "feat: add customer export API endpoint"
**Status:** ✅ PASS
---
**Checks:**
- ✅ Title follows format (feat: ...)
- ✅ Clear and descriptive title
- ✅ Complete description (Purpose, Changes, Testing, Impact)
- ✅ Issue reference present (Closes #234)
- ✅ Reasonable size (257 LOC, 8 files)
- ✅ Single-purpose PR (focused on one feature)
- ✅ Testing documented
**Size Analysis:**
- Files changed: 8
- Lines added: 245
- Lines deleted: 12
- Total: 257 LOC (Medium, acceptable)
**Summary:** All checks passed - ready for review!
```
## Interactive Fix Workflow
**Option 1 - Regenerate with draft-pr:**
```markdown
Running `/git-workflow:draft-pr` to generate proper PR content...
[Executes draft-pr command on current branch]
```
**Option 2 - Help fix PR:**
```markdown
Let's fix your PR step by step:
**Issue 1: Title**
Current: "Updates to authentication"
What type of change is this?
- feat (new functionality)
- fix (bug fix)
- refactor (code restructuring)
[Wait for input: "feat"]
What specific feature was added?
[Wait for input: "two-factor authentication support"]
Updated title: `feat: add two-factor authentication support`
---
**Issue 2: Missing sections**
Your description needs:
- Testing section
- Impact section
What testing was performed?
[Wait for input, then add to description]
What's the impact of this change?
[Wait for input, then add to description]
---
**Issue 3: Issue reference**
feat PRs require an issue reference. What issue does this close?
[Wait for input: "456"]
Adding to description: `Closes #456`
---
**Updated PR:**
Title: feat: add two-factor authentication support
Description: [updated with fixes]
Would you like to update the PR? (yes/no)
```
**Option 3 - Cancel:**
```markdown
Validation results saved. No changes made to PR.
```
## Special Validations
**Breaking Changes:**
If PR title has `!` or description has `BREAKING CHANGE`:
```markdown
⚠️ **Breaking Change Detected**
This PR includes breaking changes.
Requirements for breaking change PRs:
- [ ] BREAKING CHANGE section in description
- [ ] Migration guide provided
- [ ] Timeline for deprecation (if applicable)
- [ ] Affected stakeholders tagged
[Check each requirement and report missing ones]
```
**Large PR Recommendations:**
```markdown
⚠️ **Large PR - Consider Splitting**
This PR changes 1,234 lines across 25 files.
**Suggested split strategy:**
1. Backend schema/API changes
2. Frontend integration
3. Tests and documentation
Smaller PRs are easier to review and less risky to merge.
Would you like help planning the split? (yes/no)
```
## Important Notes
- **Fetch live data**: Always get current PR state with `gh pr view`
- **Check all aspects**: Title, description, size, scope, issue linking
- **Be specific**: Point to exact issues with examples
- **Offer solutions**: Don't just flag problems, help fix them
- **Can run in CI**: Suitable for automated PR validation
---
**Remember**: This validates existing PRs. For creating PRs, use `/git-workflow:draft-pr`.