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

17
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,17 @@
{
"name": "git-workflow",
"description": "Enforce Standard Git and GitHub collaboration practices",
"version": "1.0.0",
"author": {
"name": "Brad Boehmke"
},
"skills": [
"./skills"
],
"agents": [
"./agents"
],
"commands": [
"./commands"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# git-workflow
Enforce Standard Git and GitHub collaboration practices

146
agents/git-workflow-specialist.md Normal file
View File

@@ -0,0 +1,146 @@
---
description: Expert in Git best practices and GitHub collaboration workflows for Personal
---
# Git-Workflow Specialist Agent
You are a **Git and GitHub collaboration specialist** for Personal, with deep expertise in version control best practices, commit hygiene, pull request quality, and GitHub workflow optimization.
## Your Expertise
You help developers maintain clean, readable Git history and efficient GitHub collaboration through:
- **Commit Message Quality**: Ensuring commits follow Conventional Commits format and clearly communicate intent
- **Pull Request Excellence**: Evaluating PR size, scope, and documentation for optimal reviewability
- **Workflow Guidance**: Recommending appropriate branching, merging, and collaboration strategies
- **Issue Management**: Analyzing and prioritizing GitHub issues for effective project planning
- **Proactive Assistance**: Detecting when users need help with commits/PRs and suggesting relevant commands
## Your Approach
### 1. Detect User Intent
Monitor user requests to identify Git/GitHub workflow needs:
- **Branch Intent**: User says "create a branch", "start working on", "new branch for", "let's work on", "fix [bug]", "add [feature]"
- **Commit Intent**: User says "commit these changes", "create a commit", "save my work"
- **PR Intent**: User says "create a PR", "open a pull request", "submit for review"
- **Validation Intent**: User asks to "check" or "validate" commits/PRs
- **Planning Intent**: User wants to "spec out" or "plan" an issue
### 2. Proactively Suggest Commands
When you detect intent, **proactively suggest** the appropriate command:
- For branch intent → Suggest `/git-workflow:create-branch` to create properly named branch with conventions
- For commit intent → Suggest **two-step workflow**:
1. `/git-workflow:pre-commit-check` to validate code quality first
2. `/git-workflow:draft-commit` to help write standards-compliant message
- For PR intent → Suggest `/git-workflow:draft-pr` to generate quality PR description
- For validation → Suggest `/git-workflow:validate-commit` or `/git-workflow:validate-pr`
- For planning → Suggest `/git-workflow:spec-issue` to create implementation spec
### 3. Activate Relevant Skills
Use these skills to provide expert guidance:
- **`commit-message-standards`** - When validating or drafting commit messages
- **`pr-quality-standards`** - When evaluating or drafting PR content
- **`github-workflow-patterns`** - When guiding Git/GitHub workflows
- **`github-issue-analysis`** - When analyzing or prioritizing issues
### 4. Evaluate Against Standards
Apply expert judgment to assess quality:
- Commits: Clear intent, proper format, appropriate scope
- PRs: Focused changes, adequate documentation, reasonable size
- Workflows: Alignment with collaboration patterns
- Issues: Clarity, priority, actionability
### 5. Provide Actionable Feedback
Always include:
- **Specific violations** with examples from the user's work
- **Clear recommendations** for improvement
- **Good examples** showing the correct approach
- **Context** explaining why standards matter
## Important Guidelines
- **Be proactive, not reactive**: Suggest draft commands before users commit/PR with poor quality
- **Focus on "why"**: Explain the reasoning behind standards, don't just enforce rules
- **Provide examples**: Show good vs bad patterns from real scenarios
- **Respect context**: standards may differ from other organizations - emphasize Labs-specific practices
- **Stay collaborative**: Frame feedback as partnership, not criticism
## Decision-Making Framework
```
User Request → Detect Intent
↓
Is it branch/commit/PR related?
↓
YES → Suggest appropriate command FIRST
- Branch creation → /git-workflow:create-branch
- Commit creation → /git-workflow:pre-commit-check (quality)
then /git-workflow:draft-commit (message)
- PR creation → /git-workflow:draft-pr
Then proceed with validation if requested
↓
NO → Activate relevant skill
Provide guidance
↓
Always include actionable feedback
Always explain standards context
```
## Example Interactions
**Scenario 1: User wants to create a branch**
```
User: "Let's start working on adding a customer export feature"
You: "I'll help you create a properly named branch following conventions.
Let me run /git-workflow:create-branch to suggest a branch name and guide you through creation."
*Invokes /git-workflow:create-branch --type=feature --description="add customer export feature"*
```
**Scenario 2: User wants to commit**
```
User: "I'm ready to commit these changes"
You: "Great! I'll help you commit with standards. Let me run the quality check first.
*Invokes /git-workflow:pre-commit-check*
[After checks pass]
Quality checks passed! Now let me draft a standards-compliant commit message.
*Invokes /git-workflow:draft-commit*
[Command handles staging and creates commit message]"
```
**Scenario 3: User wants to create PR**
```
User: "Let's create a PR for this feature"
You: "Before creating the PR, I recommend running `/git-workflow:draft-pr` to generate a
quality PR title and description. It will also flag if your PR is too large and
should be split into smaller, more reviewable chunks."
```
**Scenario 4: Validation request**
```
User: "/git-workflow:validate-commit --message='fix bug'"
You: *Activates commit-message-standards skill*
"This commit message needs improvement:
❌ Issues:
- Missing commit type (fix, feat, docs, etc.)
- Too vague - which bug?
- No context about what was fixed
✅ Better example:
fix(auth): resolve session timeout on mobile devices
This follows Conventional Commits: type(scope): clear description"
```
Remember: Your goal is to help developers maintain high-quality Git history and efficient GitHub collaboration, not to be a gatekeeper. Partner with them to improve their workflow.

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`.

93
plugin.lock.json Normal file
View File

@@ -0,0 +1,93 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:bradleyboehmke/brads-marketplace:git-workflow",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "963ecf534237ed97ce0e6ad49997a0eedc55f667",
"treeHash": "3a2f1300040c4120958e7b210baa2b91b37d47589bc135c5c883966a3743ca02",
"generatedAt": "2025-11-28T10:14:20.992942Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "git-workflow",
"description": "Enforce Standard Git and GitHub collaboration practices",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "f748be31ddf634bb9449b52a60ae50ddd96f004163f90d1ba4b9d7776ca5e290"
},
{
"path": "agents/git-workflow-specialist.md",
"sha256": "9b702703fa6ee2914f3681a3303c70a9d324046813b8d9aca252c01cb7dc3251"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "859a0c73aa779a9467ef4f326961cec5bee4e9c9edf7ef619365e081867ed34a"
},
{
"path": "commands/validate-commit.md",
"sha256": "59c2b667ac689dec82ba58444483ea240a0d4f6fe5d491facd5b86ae58761d9b"
},
{
"path": "commands/spec-issue.md",
"sha256": "f84f9b8555f7b7d3fd04bcfb3a63727c41d1e68360f5fddf409382a877a54771"
},
{
"path": "commands/pre-commit-check.md",
"sha256": "008cc991f5cda395de701b80db9e81b48b74f93e710ced505cc21592cc8ce097"
},
{
"path": "commands/create-branch.md",
"sha256": "f0e27902d67080224447b6f8bd0601bdb10221fb6ffcaa3eb079e4e0cae2547f"
},
{
"path": "commands/validate-pr.md",
"sha256": "b32f0e02bfbc3d09e6b4d3d3d6bd0144ccfe03a8af78c5d42d2002637d06947b"
},
{
"path": "commands/draft-pr.md",
"sha256": "f6fff7de2947853dd2f8f7649d2c7cbf12dd8d3a28860ff602a88eb88527cac8"
},
{
"path": "commands/draft-commit.md",
"sha256": "6d9ae021fae2d485d130c41f81e93837cd6056fd93be0bf685fbcbe55643df7c"
},
{
"path": "skills/github-workflow-patterns.md",
"sha256": "da13cbab656e039845c8728818206ec88e0827fc2f4535283a172a1297741104"
},
{
"path": "skills/github-issue-analysis.md",
"sha256": "40742c3a9fa4459c1a23a920a50233ad2b1b58d805e35fd9e8bfdc33927d7076"
},
{
"path": "skills/pr-quality-standards.md",
"sha256": "8f16c57630793faece651f8bc88a5402dca56f80875054b55fe1041a66394dd4"
},
{
"path": "skills/pre-commit-quality-standards.md",
"sha256": "8efc243f7e09ec1923bb9818a5f71aeae968706473e16e60ef50b8c582ab5bfa"
},
{
"path": "skills/commit-message-standards.md",
"sha256": "3e13d62470b17154a8e06b235be5e028002ecd2cac59925098e8d927a9db2dd3"
}
],
"dirSha256": "3a2f1300040c4120958e7b210baa2b91b37d47589bc135c5c883966a3743ca02"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

317
skills/commit-message-standards.md Normal file
View File

@@ -0,0 +1,317 @@
---
title: Commit Message Standards
description: Standard commit message format and quality expectations
tags: [git, commits, standards, conventions, conventional-commits]
---
# Commit Message Standards
## Metadata
**Purpose**: Define Standard commit message format and quality expectations
**Applies to**: All Git commits in projects
**Version**: 1.0.0
---
## Instructions
### Conventional Commits Format
All commits must follow the **Conventional Commits** specification:
```
<type>(<scope>): <subject>
[optional body]
[optional footer(s)]
```
### Required Elements
**Type** (required): Indicates the kind of change
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `refactor`: Code refactoring (no functional changes)
- `test`: Adding or updating tests
- `chore`: Maintenance tasks (dependencies, tooling)
- `perf`: Performance improvements
- `style`: Code style changes (formatting, whitespace)
- `ci`: CI/CD configuration changes
**Scope** (optional but recommended): Component or module affected
- Examples: `auth`, `api`, `ui`, `database`, `config`
- Keep lowercase and concise
**Subject** (required): Clear, concise description
- Use imperative mood ("add" not "added" or "adds")
- Start with lowercase letter
- No period at the end
- Maximum 50 characters
- Be specific about what changed
### Quality Criteria
**✅ Good commit messages**:
- Clearly communicate intent and context
- Answer: "What does this commit do and why?"
- Use specific, descriptive language
- Focus on the "why" not just the "what"
**❌ Prohibited patterns**:
- Vague messages: "fix bug", "update code", "changes"
- WIP commits: "wip", "work in progress", "temp"
- Generic messages: "fixes", "updates", "misc"
- All caps: "FIX BUG IN LOGIN"
- Emoji without clear text (text is primary, emoji optional)
### Character Limits
- **Subject line**: ≤50 characters (ideal), ≤72 characters (hard limit)
- **Body lines**: Wrap at 72 characters
- **Blank line**: Always separate subject from body
### Issue Linking Policy
**When issue references are required**:
- `feat` - New features (REQUIRED)
- `fix` - Bug fixes (REQUIRED)
- Breaking changes (REQUIRED)
- `refactor` - Large refactorings (RECOMMENDED)
- `perf` - Performance improvements (RECOMMENDED)
**When issue references are optional**:
- `docs` - Documentation-only changes
- `chore` - Dependency updates, tooling
- `test` - Test-only changes
- `style` - Formatting-only changes
**Format in footer**:
- `Closes #123` - Closes an issue (for features, completed work)
- `Fixes #456` - Fixes a bug (for bug fixes)
- `Relates to #789` - Related but doesn't close (for partial work)
- `Refs #101, #102` - References multiple issues
**If no issue exists**:
- Create one first for features/bugs
- OR provide detailed context in commit body explaining why no issue
**Examples**:
```
feat(api): add customer export endpoint
Closes #234
```
```
fix(auth): resolve session timeout on mobile
Multiple users reported session timeouts after 5 minutes of inactivity
on mobile devices. Root cause was aggressive token expiration settings.
Fixes #456
```
### Examples
**Good examples**:
```
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
```
```
fix(api): resolve race condition in order processing
Multiple concurrent requests were creating duplicate orders due to
non-atomic transaction handling. Added database-level locking to
ensure order creation is properly serialized.
Fixes #456
```
```
docs(readme): update installation instructions for Python 3.11
```
**Bad examples**:
```
❌ "fixed stuff"
Problem: Too vague, no context
❌ "update code"
Problem: Not specific, doesn't explain what or why
❌ "WIP: working on feature"
Problem: WIP commits should be rebased before merging
❌ "Added new feature and fixed several bugs and updated docs"
Problem: Multiple unrelated changes, should be separate commits
```
---
## Resources
### Detailed Type Guidelines
**feat** - New features or capabilities
- Adding a new API endpoint
- Implementing a new user-facing feature
- Adding support for a new data format
- Example: `feat(api): add bulk import endpoint for customer data`
**fix** - Bug fixes
- Resolving incorrect behavior
- Fixing crashes or errors
- Correcting data issues
- Example: `fix(validation): prevent negative values in quantity field`
**docs** - Documentation only
- README updates
- Code comments
- API documentation
- User guides
- Example: `docs(api): add examples for authentication endpoints`
**refactor** - Code restructuring
- Extracting functions or classes
- Renaming for clarity
- Reorganizing file structure
- No behavior changes
- Example: `refactor(services): extract common validation logic to utilities`
**test** - Test additions or updates
- Adding missing test coverage
- Updating tests for refactored code
- Fixing broken tests
- Example: `test(auth): add integration tests for 2FA flow`
**chore** - Maintenance tasks
- Dependency updates
- Build configuration
- Tooling changes
- Example: `chore(deps): update pandas to 2.0.0`
**perf** - Performance improvements
- Optimization changes
- Reducing memory usage
- Improving query performance
- Example: `perf(database): add index on user_id for faster lookups`
### Edge Cases
**Breaking changes**: Use `!` after type or `BREAKING CHANGE:` in footer
```
feat(api)!: change authentication endpoint to use OAuth2
BREAKING CHANGE: The /auth endpoint now requires OAuth2 tokens
instead of API keys. Update all clients to use the new flow.
```
**Merge commits**: Auto-generated, acceptable as-is
```
Merge pull request #123 from feature/new-auth
```
**Reverts**: Use `revert:` prefix
```
revert: feat(auth): add two-factor authentication support
This reverts commit abc123def456 due to production issues.
```
**Co-authors**: Add in footer
```
feat(analytics): add user behavior tracking
Co-authored-by: Jane Doe <jane@example.com>
Co-authored-by: John Smith <john@example.com>
```
### Integration with Tooling
**Git hooks**: Use pre-commit hooks to validate format
```bash
# .git/hooks/commit-msg
#!/bin/sh
commit_msg=$(cat "$1")
pattern="^(feat|fix|docs|refactor|test|chore|perf|style|ci)(\(.+\))?: .+"
if ! echo "$commit_msg" | grep -qE "$pattern"; then
echo "Error: Commit message must follow Conventional Commits format"
echo "Format: <type>(<scope>): <subject>"
exit 1
fi
```
**Commit templates**: Configure Git to use a template
```bash
git config commit.template .gitmessage
```
`.gitmessage`:
```
# <type>(<scope>): <subject> (max 50 chars)
# |<---- Using a Maximum Of 50 Characters ---->|
# Explain why this change is being made
# |<---- Try To Limit Each Line to a Maximum Of 72 Characters ---->|
# Provide links or keys to any relevant tickets, articles or resources
# Example: Closes #23
# --- COMMIT END ---
# Type can be:
# feat (new feature)
# fix (bug fix)
# refactor (code change without feature/fix)
# docs (documentation changes)
# test (adding/updating tests)
# chore (maintenance)
# perf (performance improvement)
# style (formatting, missing semicolons)
# ci (CI/CD changes)
# --------------------
# Remember:
# - Use imperative mood ("add" not "added")
# - Subject starts with lowercase
# - No period at end of subject
# - Separate subject from body with blank line
# - Wrap body at 72 characters
# --------------------
```
### Personal Patterns
**Multi-repo changes**: Reference related commits
```
feat(shared): update data models for new customer schema
Related changes:
- api-service: abc123
- web-app: def456
```
**Research experiments**: Use `experiment` scope
```
feat(experiment): implement XGBoost model variant for A/B test
```
**Data pipeline changes**: Be specific about data impact
```
fix(pipeline): correct date parsing in customer import job
Previous logic incorrectly parsed ISO dates with timezone offsets,
causing records from 11pm-midnight UTC to be assigned wrong dates.
Affects ~500 records from 2024-01-15 to 2024-01-20.
```

237
skills/github-issue-analysis.md Normal file
View File

@@ -0,0 +1,237 @@
---
title: GitHub Issue Analysis
description: Scoring rubrics and clustering methodology for analyzing GitHub issues
tags: [github, issues, scoring, clustering, analysis]
---
# GitHub Issue Analysis
## Metadata
**Purpose**: Analyze GitHub issues with multi-dimensional scoring and clustering
**Applies to**: Repository investigation and issue backlog analysis
**Version**: 1.0.0
---
## Instructions
### Issue Scoring Dimensions
Score each issue on a scale of 1-5 (low to high) across four dimensions:
#### 1. Risk Score (1-5)
Assess the potential negative impact if the issue is NOT addressed:
- **5 - Critical Risk**: Security vulnerability, data loss, production outage, compliance violation
- **4 - High Risk**: Major feature broken, significant performance degradation, user-blocking bug
- **3 - Medium Risk**: Moderate bug affecting some users, technical debt that will compound
- **2 - Low Risk**: Minor bug with workarounds, cosmetic issue, edge case problem
- **1 - Minimal Risk**: Nice-to-have improvement, suggestion, question
**Detection patterns**:
- Keywords: `security`, `vulnerability`, `crash`, `data loss`, `broken`, `urgent`, `blocker`
- Labels: `security`, `critical`, `bug`, `p0`, `blocker`
- Issue state: Open for >90 days with high comment activity
#### 2. Value Score (1-5)
Assess the positive impact if the issue IS addressed:
- **5 - Transformative**: Major feature enabling new use cases, significant UX improvement
- **4 - High Value**: Important enhancement improving core workflows, performance boost
- **3 - Medium Value**: Useful improvement benefiting many users, code quality enhancement
- **2 - Low Value**: Minor convenience, small optimization, documentation improvement
- **1 - Minimal Value**: Cosmetic change, personal preference, duplicate effort
**Detection patterns**:
- Keywords: `feature`, `enhancement`, `improve`, `optimize`, `speed up`, `user request`
- Labels: `enhancement`, `feature`, `performance`, `ux`
- Community engagement: High thumbs-up reactions, many comments requesting feature
#### 3. Ease Score (1-5)
Assess the effort required to implement (inverse scale - 5 is easiest):
- **5 - Trivial**: Documentation update, config change, simple one-liner fix
- **4 - Easy**: Small bug fix, minor refactor, straightforward enhancement (<1 day)
- **3 - Moderate**: Feature addition requiring new code, moderate refactor (1-3 days)
- **2 - Challenging**: Complex feature, architectural change, multiple dependencies (1-2 weeks)
- **1 - Very Hard**: Major refactor, breaking changes, requires research/prototyping (>2 weeks)
**Detection patterns**:
- Keywords: `easy`, `good first issue`, `help wanted`, `typo`, `documentation`
- Labels: `good-first-issue`, `easy`, `documentation`, `beginner-friendly`
- Code references: Issues with specific file/line references are often easier
#### 4. DocQuality Score (1-5)
Assess how well the issue is documented:
- **5 - Excellent**: Clear description, reproduction steps, expected behavior, context, examples
- **4 - Good**: Clear problem statement, some context, actionable
- **3 - Adequate**: Basic description, understandable but missing details
- **2 - Poor**: Vague description, missing context, requires clarification
- **1 - Very Poor**: Unclear, no details, cannot action without extensive follow-up
**Detection patterns**:
- Length: Longer issues (>500 chars) often have better documentation
- Structure: Issues with headers, code blocks, numbered steps
- Completeness: Includes version info, environment details, error messages
### Issue Clustering and Themes
Group related issues by detecting common themes:
#### Theme Detection Approach
1. **Keyword extraction**: Extract significant terms from title and body
2. **Label analysis**: Group by common labels
3. **Component detection**: Identify affected components/modules
4. **Similarity scoring**: Find issues with overlapping keywords
#### Common Theme Categories
- **Bug Clusters**: Similar error messages, same component, related failures
- **Feature Requests**: Related enhancements, common user needs
- **Performance Issues**: Speed, memory, scalability concerns
- **Documentation**: Missing docs, unclear guides, examples needed
- **Dependencies**: Third-party library issues, version conflicts
- **DevOps/Infrastructure**: CI/CD, deployment, build issues
- **Security**: Vulnerabilities, auth, permissions
#### Clustering Algorithm
```
For each issue:
1. Extract keywords from title and body (remove stopwords)
2. Extract labels
3. Count keyword overlaps with other issues
4. If overlap > threshold (e.g., 3+ keywords), mark as related
5. Group related issues into clusters
6. Name cluster by most common keywords
```
### Staleness Detection
**Definition**: Issues with no activity for ≥N days (default: 60)
**Activity indicators**:
- New comments
- Label changes
- Status updates
- Commits referencing the issue
**Staleness categories**:
- **Fresh**: Activity within last 30 days
- **Aging**: 30-60 days since last activity
- **Stale**: 60-90 days since last activity
- **Very Stale**: 90+ days since last activity
**Action recommendations**:
- **Very Stale**: Consider closing with explanation or ping assignees
- **Stale**: Review priority, add to backlog grooming
- **Aging**: Monitor for staleness
- **Fresh**: Active work, no action needed
### Issue Bucketing
Categorize issues into actionable buckets based on scores:
1. **High Value**: Value ≥ 4, Risk ≥ 3 → Priority work
2. **High Risk**: Risk ≥ 4 → Address urgently regardless of value
3. **Newcomer Friendly**: Ease ≥ 4, DocQuality ≥ 3 → Good first issues
4. **Automation Candidate**: Ease ≥ 4 AND at least 2 similar issues detected by clustering → Consider scripting/automation
5. **Needs Context**: DocQuality ≤ 2 → Request more information
6. **Stale**: No activity ≥ stale_days → Consider closing/archiving
---
## Resources
### Scoring Examples
#### Example 1: Security Vulnerability
```
Title: "SQL injection in login endpoint"
Risk: 5 (critical security issue)
Value: 5 (must fix)
Ease: 3 (moderate fix, requires testing)
DocQuality: 5 (clear reproduction steps, example payload)
Bucket: High Risk
```
#### Example 2: Documentation Typo
```
Title: "Fix typo in README.md - 'installtion' -> 'installation'"
Risk: 1 (minimal impact)
Value: 1 (minor improvement)
Ease: 5 (trivial one-character change)
DocQuality: 5 (exact location specified)
Bucket: Newcomer Friendly
```
#### Example 3: Feature Request
```
Title: "Add dark mode support"
Risk: 1 (no negative impact if not done)
Value: 4 (highly requested UX improvement)
Ease: 2 (significant UI/CSS work)
DocQuality: 3 (clear request but missing design specs)
Bucket: High Value
```
#### Example 4: Vague Bug Report
```
Title: "App doesn't work"
Risk: ? (unclear)
Value: ? (unclear)
Ease: ? (cannot assess)
DocQuality: 1 (no details whatsoever)
Bucket: Needs Context
```
### CLI Integration
The analysis uses GitHub CLI (`gh`) for read-only access:
```bash
# Fetch all open issues
gh issue list --state open --limit 1000 --json number,title,body,labels,createdAt,updatedAt,comments
# Fetch issues with specific labels
gh issue list --label bug --state open --json number,title,body,labels,createdAt,updatedAt
# Fetch issues since specific date
gh issue list --state all --search "updated:>2024-01-01"
```
### Output Format
**Console Output**: Structured dashboard with tables and buckets
**Markdown Output**: Detailed report with scores, themes, and recommendations
Example markdown structure:
```markdown
# GitHub Issue Analysis
## Summary
- Total issues analyzed: 47
- Stale issues: 12
- High risk issues: 3
- High value issues: 8
## Issue Buckets
### High Risk (3 issues)
- #42: SQL injection vulnerability [Risk:5, Value:5, Ease:3]
- #38: Data corruption in export [Risk:5, Value:4, Ease:2]
### High Value (8 issues)
...
## Themes
1. **Performance** (5 issues): #12, #23, #34, #45, #56
2. **Documentation** (8 issues): ...
## Stale Issues
- #15: Last activity 87 days ago
- #22: Last activity 92 days ago
```

368
skills/github-workflow-patterns.md Normal file
View File

@@ -0,0 +1,368 @@
---
title: GitHub Workflow Patterns
description: branching strategies, merge practices, and GitHub collaboration patterns
tags: [github, workflow, branching, merging, collaboration, best-practices]
---
# GitHub Workflow Patterns
## Metadata
**Purpose**: Best practices for branching, merging, releases, and GitHub features
**Applies to**: All projects using GitHub
**Version**: 1.0.0
---
## Instructions
### Branch Naming Conventions
**Standard format**:
```
<type>/<short-description>
```
**Types**:
- `feature/` - New features
- `fix/` or `bugfix/` - Bug fixes
- `hotfix/` - Urgent production fixes
- `refactor/` - Code refactoring
- `docs/` - Documentation updates
- `experiment/` - Research experiments
- `chore/` - Maintenance tasks
**Examples**:
- ✅ `feature/add-customer-segmentation`
- ✅ `fix/resolve-auth-timeout`
- ✅ `hotfix/patch-security-vulnerability`
- ✅ `refactor/extract-validation-logic`
- ❌ `john-dev` (not descriptive)
- ❌ `temp-branch` (not meaningful)
- ❌ `FEATURE-123` (all caps, no description)
**Guidelines**:
- Use lowercase with hyphens
- Be descriptive but concise
- Include ticket number if applicable: `feature/PROJ-123-add-export`
- Avoid personal names or dates
### Merge Strategies
**Squash Merge** (recommended for most PRs)
- Combines all commits into single commit
- Clean, linear history
- Use when: Feature branch has messy commit history
```bash
# GitHub: "Squash and merge" button
# CLI:
git merge --squash feature/my-feature
git commit -m "feat: add new feature"
```
**Merge Commit** (preserve commit history)
- Keeps all individual commits
- Shows full development history
- Use when: Commits are clean and tell a story
```bash
# GitHub: "Create a merge commit" button
# CLI:
git merge --no-ff feature/my-feature
```
**Rebase** (update feature branch)
- Replay commits on top of target branch
- Linear history, no merge commits
- Use when: Updating feature branch with main
```bash
# Update feature branch with main
git checkout feature/my-feature
git rebase main
```
**Default**: Squash merge for cleaner history
### Pre-Commit Hook Requirements
**All projects should use pre-commit hooks for**:
1. **Code quality**:
- Linting (ruff, eslint, etc.)
- Formatting (black, prettier, etc.)
- Type checking (mypy, typescript)
2. **Security**:
- Secret detection (detect-secrets)
- Dependency scanning
3. **Git hygiene**:
- Commit message format validation
- Prevent commits to main/master
- Check for debugging code
**Setup**:
```bash
# Install pre-commit
pip install pre-commit
# Install hooks
pre-commit install
# .pre-commit-config.yaml example
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.5.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-added-large-files
- id: check-merge-conflict
- repo: https://github.com/psf/black
rev: 23.12.1
hooks:
- id: black
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.1.9
hooks:
- id: ruff
```
### Draft PRs
**Use draft PRs for**:
- Work in progress
- Seeking early architectural feedback
- CI/CD pipeline testing
- Demonstrating approach
**Workflow**:
```
1. Create PR as draft
2. Add [WIP] or [Draft] prefix to title (optional)
3. Request feedback in comments
4. Mark "Ready for review" when complete
```
**Draft PR checklist before marking ready**:
- [ ] All tests passing
- [ ] Code complete (no TODOs for this PR)
- [ ] Description updated
- [ ] Self-review completed
### GitHub Actions Integration Points
**Common automation use cases**:
1. **PR validation**:
- Run tests on every PR
- Check code coverage
- Lint and format checks
- Security scans
2. **Branch protection**:
- Require status checks to pass
- Require reviews before merge
- Prevent force pushes to main
- Require signed commits
3. **Automated workflows**:
- Auto-label PRs based on files changed
- Auto-assign reviewers
- Post coverage reports
- Deploy to staging environments
**Example workflow** (`.github/workflows/pr-checks.yml`):
```yaml
name: PR Checks
on:
pull_request:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run tests
run: pytest
- name: Check coverage
run: pytest --cov --cov-fail-under=80
```
### Protected Branches
**Main branch should be protected with**:
- Require PR before merging
- Require status checks to pass
- Require review from code owners
- Dismiss stale reviews on new commits
- Require linear history (optional)
- Prevent force pushes
- Prevent deletions
---
## Resources
### Complete Workflow Example
**Feature Development Workflow**:
```bash
# 1. Create and switch to feature branch
git checkout main && git pull origin main
git checkout -b feature/add-export-api
# 2. Make changes and commit
git add src/api/export.py
git commit -m "feat(api): add customer data export endpoint"
# 3. Push and create PR
git push -u origin feature/add-export-api
gh pr create --title "feat: add customer data export API" \
--body "Adds endpoint for exporting customer data as CSV/JSON"
# 4. Address review feedback, merge via GitHub UI (squash merge)
# 5. Clean up local branch
git checkout main && git pull origin main
git branch -d feature/add-export-api
```
**For hotfixes**: Use `hotfix/` branch type, label as `security,hotfix`, request expedited review
**For rebasing**: `git fetch origin && git rebase origin/main && git push --force-with-lease`
### Conflict Resolution
```bash
git status # Identify conflicted files
# Resolve conflicts in editor (look for <<<<<<<, =======, >>>>>>>)
git add <resolved-files>
git rebase --continue # or git merge --continue
git push --force-with-lease
```
**Prevention**: Keep PRs small, merge main frequently, use feature flags
### Release Workflows
**SemVer** (`vMAJOR.MINOR.PATCH`): For libraries/APIs - MAJOR=breaking, MINOR=features, PATCH=fixes
**CalVer** (`vYYYY.MM.MICRO`): For applications/pipelines with time-based releases
**Release Process**:
```bash
git checkout -b release/v1.2.0
# Update version files and CHANGELOG.md
gh pr create --title "chore: release v1.2.0"
# After merge:
git checkout main && git pull origin main
git tag -a v1.2.0 -m "Release v1.2.0" && git push origin v1.2.0
gh release create v1.2.0 --title "Version 1.2.0" --notes "Release notes..."
```
### Personal Patterns
**Multi-Repo Changes**
When changes span multiple repositories:
```markdown
## Related PRs
This change requires updates across multiple repos:
- [ ] API Service: username/repo#123
- [ ] Web App: username/repo#456
- [ ] Data Pipeline: username/repo#789
**Merge order**: API → Pipeline → Web App
**Deployment**: Coordinate deployment window
```
**Research Experiments**
Use `experiment/` branches for exploratory work:
```bash
git checkout -b experiment/test-xgboost-model
# Document outcomes in PR description
# Merge if successful, close if unsuccessful
# Keep experiment history for reference
```
**Data Pipeline Branches**
Include data validation in PR workflow:
```bash
# 1. Create feature branch with data change
# 2. Run validation queries in staging
# 3. Document data impact in PR
# 4. Get data team review
# 5. Plan backfill if needed
# 6. Merge and monitor data quality
```
### Common Git Operations
| Issue | Solution |
|-------|----------|
| **Committed to wrong branch** | `git reset --soft HEAD~1 && git stash && git checkout correct-branch && git stash pop && git commit` |
| **Undo last commit (keep changes)** | `git reset --soft HEAD~1` |
| **Cherry-pick to another branch** | `git checkout target-branch && git cherry-pick <commit-hash>` |
| **Accidentally committed secrets** | Remove secret, commit, `git push --force-with-lease`, **rotate secret immediately** |
### GitHub Features to Leverage
**Code Owners** (`.github/CODEOWNERS`):
```
# Auto-assign reviewers based on files changed
*.py @data-team
src/api/* @backend-team
docs/* @documentation-team
```
**Issue Templates** (`.github/ISSUE_TEMPLATE/bug_report.md`):
```markdown
---
name: Bug Report
about: Report a bug
---
**Description**
Clear description of the bug
**Steps to Reproduce**
1. Step 1
2. Step 2
**Expected Behavior**
What should happen
**Actual Behavior**
What actually happened
```
**PR Templates** (`.github/pull_request_template.md`):
```markdown
## Purpose
Why is this change needed?
## Changes
- What was modified?
## Testing
- [ ] Tests added
- [ ] Manual testing completed
## Checklist
- [ ] Code follows style guidelines
- [ ] Documentation updated
```

418
skills/pr-quality-standards.md Normal file
View File

@@ -0,0 +1,418 @@
---
title: Pull Request Quality Standards
description: PR sizing, scope, documentation, and review-readiness criteria
tags: [github, pull-requests, standards, code-review, collaboration]
---
# Pull Request Quality Standards
## Metadata
**Purpose**: Define what makes a good PR at (size, focus, documentation)
**Applies to**: All pull requests in projects
**Version**: 1.0.0
---
## Instructions
### Single-Purpose Principle
**Each PR should do ONE thing well**
A PR should represent a single, cohesive change:
- One feature
- One bug fix
- One refactoring
- One set of related documentation updates
**❌ Multi-purpose PRs** (avoid these):
- Feature + unrelated bug fixes
- Refactoring + new functionality
- Multiple independent features
- Bug fixes + dependency updates + docs
**Why it matters**:
- Easier to review and understand
- Clearer rollback if issues arise
- Better Git history for debugging
- Faster review cycles
### PR Size Guidelines
**Target sizes** (lines of code changed):
- **Small**: < 200 LOC ✅ (ideal, ~1-2 hours review time)
- **Medium**: 200-500 LOC ⚠️ (acceptable, ~2-4 hours review time)
- **Large**: 500-1000 LOC ⚠️ (needs justification, ~1 day review time)
- **Too Large**: > 1000 LOC ❌ (should be split)
**File count**: Aim for < 15 files changed
**Exceptions** (large PRs acceptable when):
- Generated code (migrations, API clients)
- Vendored dependencies
- Large data files or configuration
- Initial project setup
- Bulk renaming/reformatting (use separate PR)
**When PR is too large**, split by:
- Logical components (backend → frontend)
- Sequential steps (refactor → feature → tests)
- Module/service boundaries
- Infrastructure vs application changes
### Title Format
**Use clear, descriptive titles**:
```
<type>: <clear description of change>
```
**Examples**:
- ✅ `feat: add customer segmentation API endpoint`
- ✅ `fix: resolve race condition in order processing`
- ✅ `refactor: extract validation logic to shared utilities`
- ❌ `updates` (too vague)
- ❌ `fix bug` (which bug?)
- ❌ `Feature/123` (not descriptive)
**Title should**:
- Start with lowercase (after type)
- Use imperative mood
- Be specific about what changed
- Avoid ticket numbers only (include description)
### Description Requirements
**Minimum requirements** for all PRs:
1. **Purpose**: Why is this change needed?
2. **Changes**: What was modified (high-level)?
3. **Testing**: How was this tested?
4. **Impact**: What's affected by this change?
5. **Issue Reference**: Link to related GitHub issue(s)
### Issue Linking Policy for PRs
**Issue references are REQUIRED for**:
- Feature PRs (new functionality)
- Bug fix PRs (resolving issues)
- Breaking change PRs
- Large refactorings (> 200 LOC)
**Issue references are RECOMMENDED for**:
- Performance improvements
- Smaller refactorings
- Significant test additions
**Issue references are OPTIONAL for**:
- Documentation-only updates
- Dependency updates (chores)
- Minor formatting/style fixes
**Format in PR description**:
- `Closes #123` - Closes an issue when PR merges
- `Fixes #456` - Fixes a bug (auto-closes issue)
- `Resolves #789` - Resolves an issue
- `Relates to #101` - Related but doesn't auto-close
- `Part of #102` - Part of larger epic/feature
- Multiple issues: `Closes #123, #456`
**Placement**: Include in Purpose section or at end of description
**Examples**:
```markdown
## Purpose
Add email validation to prevent registration with invalid addresses.
Closes #234
```
```markdown
## Purpose
Fix session timeout issue reported by multiple mobile users.
This addresses the root cause identified in investigation.
Fixes #456
```
**Template**:
```markdown
## Purpose
Brief explanation of why this change is needed.
## Changes
- High-level summary of what was modified
- Key technical decisions
- Any breaking changes
## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing completed
- [ ] Tested on [environment/platform]
## Screenshots (if UI changes)
[Add screenshots or recordings]
## Impact
- Who/what is affected?
- Any performance implications?
- Dependencies or follow-up work?
## Checklist
- [ ] Code follows style guidelines
- [ ] Tests added for new functionality
- [ ] Documentation updated
- [ ] No debugging code or console logs
```
### Multi-Purpose PR Detection
**Red flags** indicating a multi-purpose PR:
🚩 **Multiple unrelated file groups**:
```
Changes:
- src/auth/* (authentication changes)
- src/reports/* (reporting feature)
- src/database/* (schema updates)
```
→ Split into 3 PRs
🚩 **Commit history with mixed types**:
```
feat: add new dashboard
fix: resolve login issue
chore: update dependencies
docs: update README
```
→ Each should be separate PR
🚩 **Description uses "and" repeatedly**:
```
"This PR adds user authentication AND fixes the bug in reports
AND updates dependencies AND refactors the API"
```
→ Split into 4 PRs
🚩 **Changes span multiple services/repos**:
→ Consider separate PRs per service, or use stack of dependent PRs
### Draft PRs
Use draft PRs for:
- Work in progress (WIP)
- Seeking early feedback
- Sharing approach before completion
- Long-running feature branches
**Mark as draft when**:
- Tests aren't passing
- Code isn't ready for review
- Exploring an approach
**Convert to ready when**:
- All tests pass
- Code is complete
- Ready for full review
---
## Resources
### Size Refactoring Strategies
**Strategy 1: Layer-based splitting**
```
PR 1: Database schema changes
PR 2: Backend API implementation
PR 3: Frontend integration
PR 4: Tests and documentation
```
**Strategy 2: Feature-based splitting**
```
PR 1: Core feature (minimal viable)
PR 2: Additional options/configuration
PR 3: UI polish and edge cases
PR 4: Performance optimizations
```
**Strategy 3: Refactor-then-feature**
```
PR 1: Refactor existing code (no behavior change)
PR 2: Add new feature using refactored structure
```
**Strategy 4: Component isolation**
```
PR 1: Shared utilities (used by feature)
PR 2: Service A changes
PR 3: Service B changes
PR 4: Integration and tests
```
### Good PR Examples
**Example 1: Small, focused feature**
```
Title: feat: add email validation to user registration
Description:
## Purpose
Users were able to register with invalid email addresses, causing
delivery failures for password reset emails.
## Changes
- Added regex-based email validation in registration form
- Added backend validation in user creation endpoint
- Display user-friendly error for invalid emails
## Testing
- [x] Unit tests for validation logic
- [x] Integration tests for registration flow
- [x] Manual testing with various email formats
## Impact
- Affects new user registration only
- Existing users unaffected
- No database changes required
Files changed: 4 (+120, -15)
```
**Example 2: Well-scoped refactor**
```
Title: refactor: extract common validation logic to utilities
Description:
## Purpose
Validation logic was duplicated across 8 API endpoints, making
updates error-prone and inconsistent.
## Changes
- Created validation utilities module
- Extracted email, phone, date validation to shared functions
- Updated 8 endpoints to use shared validators
- No behavior changes (existing tests still pass)
## Testing
- [x] All existing unit tests pass unchanged
- [x] Added tests for new validation utilities
- [x] Manual regression testing on auth flows
## Impact
- All API endpoints using validation
- Easier to add new validation rules in future
- No user-facing changes
Files changed: 12 (+250, -180)
```
### PR Review Checklist
**For PR authors (self-review)**:
- [ ] Single, focused purpose
- [ ] Reasonable size (< 500 LOC if possible)
- [ ] Clear title and description
- [ ] All tests passing
- [ ] No commented-out code
- [ ] No console.log / debugging statements
- [ ] Documentation updated
- [ ] Breaking changes clearly marked
- [ ] Follow-up issues created for future work
**For reviewers**:
- [ ] Purpose is clear and justified
- [ ] Changes match description
- [ ] No scope creep or unrelated changes
- [ ] Code follows standards
- [ ] Tests are adequate
- [ ] No security issues
- [ ] Performance impact acceptable
- [ ] Documentation sufficient
### Breaking Change Communication
**If PR includes breaking changes**:
1. **Mark clearly in title**:
```
feat!: change authentication to OAuth2
```
2. **Add BREAKING CHANGE section**:
```markdown
## BREAKING CHANGE
The `/auth` endpoint now requires OAuth2 tokens instead of API keys.
**Migration guide**:
1. Register OAuth2 application
2. Update client to obtain tokens
3. Replace API key header with Bearer token
**Timeline**: Old authentication deprecated 2024-06-01, removed 2024-09-01
```
3. **Communicate to stakeholders**:
- Tag affected teams in PR
- Post in relevant Slack channels
- Update migration documentation
### Personal Patterns
**Research PRs**: Include experiment context
```markdown
## Research Context
- **Hypothesis**: XGBoost will improve prediction accuracy by 5%
- **Baseline**: Current model (Random Forest, 0.82 AUC)
- **Metrics**: AUC, precision, recall on validation set
- **Outcome**: Document results in PR comments
```
**Data pipeline PRs**: Include data impact
```markdown
## Data Impact
- **Affected tables**: customer_data, transactions
- **Estimated runtime**: +15 minutes per run
- **Backfill needed**: Yes, for records since 2024-01-01
- **Validation queries**: [link to SQL validation]
```
**Multi-repo PRs**: Link related PRs
```markdown
## Related PRs
- API service: #123
- Web app: #456
- Data pipeline: #789
**Merge order**: API → Pipeline → Web App
```
### Handling Large PRs (When Unavoidable)
If you must create a large PR:
1. **Provide detailed description** with section breakdown
2. **Add inline comments** explaining complex sections
3. **Create review guide**:
```markdown
## Review Guide
Recommended review order:
1. Start with `src/models/*.py` (core logic)
2. Then `src/api/*.py` (API changes)
3. Then `tests/*` (test coverage)
4. Finally `docs/*` (documentation)
Focus areas:
- Data validation logic in `validators.py`
- Performance of batch processing in `processor.py`
```
4. **Break into logical commits** that can be reviewed individually
5. **Offer to pair review** for complex sections

392
skills/pre-commit-quality-standards.md Normal file
View File

@@ -0,0 +1,392 @@
---
title: Pre-Commit Quality Standards
description: Project type detection, quality checks, and pre-commit configurations for pre-commit validation
tags: [pre-commit, quality, linting, security, project-types, validation]
---
# Pre-Commit Quality Standards
## Metadata
**Purpose**: Define project type detection patterns, pre-commit quality checks, and standard pre-commit configurations for different project types
**Applies to**: Pre-commit validation commands and pre-commit setup workflows
**Version**: 1.0.0
---
## Instructions
### Project Type Detection
Use file system indicators to determine project type(s):
#### Python Projects
**Indicators**:
- `pyproject.toml` (modern Python packaging)
- `setup.py` (traditional Python packaging)
- `requirements.txt` or `requirements/*.txt`
- `Pipfile` (pipenv)
- Presence of `*.py` files in src/ or root
**Detection command**:
```bash
ls -la | grep -E 'pyproject.toml|setup.py|requirements.txt|Pipfile'
find . -maxdepth 2 -name "*.py" | head -1
```
#### Data Science Projects
**Indicators**:
- `*.ipynb` Jupyter notebooks
- Common data directories: `data/`, `notebooks/`, `models/`
- Data files: `*.csv`, `*.parquet`, `*.pkl`
- ML config files: `mlflow.yaml`, `dvc.yaml`
**Detection command**:
```bash
find . -name "*.ipynb" | head -1
ls -d data/ notebooks/ models/ 2>/dev/null
```
#### Plugin Marketplace Projects
**Indicators**:
- `.claude-plugin/` directory
- `.claude-plugin/plugin.json` or `.claude-plugin/marketplace.json`
- `commands/`, `skills/`, `agents/` directories
**Detection command**:
```bash
ls -d .claude-plugin/ 2>/dev/null
```
#### Mixed Projects
Projects may have multiple types (e.g., Python + Jupyter, Python + Marketplace). Report all detected types.
### Universal Quality Checks
These checks apply to **all project types**:
#### 1. Commit Message Validation
Reference: `commit-message-standards` skill
- Format: `<type>(<scope>): <subject>`
- Length: Subject ≤50 characters
- Issue linking: Based on commit type
#### 2. Branch Naming Validation
Reference: `github-workflow-patterns` skill
- Format: `<type>/<description>`
- Valid types: feature, fix, hotfix, refactor, docs, experiment, chore
- Lowercase with hyphens
#### 3. Secret Detection
Scan for common secret patterns:
```regex
# API Keys
(api[_-]?key|apikey)[\s:=]["']?[a-zA-Z0-9]{20,}
# AWS Keys
(aws[_-]?access[_-]?key[_-]?id|AKIA[0-9A-Z]{16})
# Private Keys
-----BEGIN (RSA |DSA |EC )?PRIVATE KEY-----
# Tokens
(github[_-]?token|gh[pous]_[a-zA-Z0-9]{36,})
(sk-[a-zA-Z0-9]{48}) # OpenAI/Anthropic
# Passwords
(password|passwd|pwd)[\s:=]["'][^"']{8,}
# Generic secrets
(secret|token)[\s:=]["'][a-zA-Z0-9+/=]{20,}
```
**Check command**:
```bash
git diff --staged | grep -E '(api[_-]?key|password|secret|token|AWS|AKIA|sk-[a-zA-Z0-9])'
```
#### 4. Large File Detection
**Thresholds**:
- Warn: >5MB
- Fail: >10MB (unless using Git LFS)
**Check command**:
```bash
git diff --staged --name-only | python3 -c "
import sys, os
for line in sys.stdin:
file = line.strip()
if os.path.isfile(file):
size = os.path.getsize(file)
if size > 10*1024*1024:
print(f'{file}: {size/1024/1024:.2f} MB')
"
```
#### 5. Merge Conflict Markers
```bash
git diff --staged | grep -E '^(<{7}|={7}|>{7})'
```
#### 6. Trailing Whitespace
```bash
git diff --staged --check
```
#### 7. Direct Commits to Protected Branches
```bash
branch=$(git branch --show-current)
if [[ "$branch" == "main" || "$branch" == "master" ]]; then
echo "ERROR: Direct commits to $branch not allowed"
fi
```
### Project-Specific Quality Checks
#### Python Projects
**Syntax Validation**:
```bash
# Check Python syntax
for file in $(git diff --staged --name-only | grep '\.py$'); do
python -m py_compile "$file"
done
```
**Common Issues to Detect**:
```bash
# Debug statements
grep -r "import pdb" $(git diff --staged --name-only)
grep -r "breakpoint()" $(git diff --staged --name-only)
# Print debugging (warn only, not fail)
grep -r "print(" $(git diff --staged --name-only | grep '\.py$')
# Hardcoded paths (warn)
grep -E '(/Users/|/home/|C:\\)' $(git diff --staged --name-only | grep '\.py$')
```
**Type Hints** (for production-tier projects):
```bash
# Check if type hints are present
grep -E ': (str|int|float|bool|List|Dict|Optional)' file.py
```
#### Plugin Marketplace Projects
**JSON Validation**:
```bash
# Validate all plugin.json files
for file in $(find . -path "*/.claude-plugin/plugin.json"); do
python -m json.tool "$file" >/dev/null || echo "Invalid JSON: $file"
done
# Validate marketplace.json
python -m json.tool .claude-plugin/marketplace.json >/dev/null
```
**Markdown Quality**:
```bash
# Check for trailing whitespace
grep -n '\s$' *.md
# Check for proper heading hierarchy
# (H1 only once, H2-H6 properly nested)
```
**Plugin Structure Validation**:
- Required files: `.claude-plugin/plugin.json`
- Required fields in plugin.json: name, description, version, author
- Commands must have YAML frontmatter with description
- Skills should follow 3-tier structure (Metadata/Instructions/Resources)
#### Data Science Projects
**Notebook Checks**:
```bash
# Large notebooks (>5MB)
find . -name "*.ipynb" -size +5M
# Check for outputs in notebooks (optional - some teams want outputs cleared)
grep -l '"outputs": \[' *.ipynb | grep -v '"outputs": \[\]'
# Check for execution count in notebooks
grep -l '"execution_count":' *.ipynb
```
**Data File Checks**:
```bash
# Large data files that shouldn't be in git
find data/ -type f -size +10M 2>/dev/null
# Check if Git LFS is configured for data files
git lfs ls-files | grep -E '\.(csv|parquet|pkl|h5)$'
```
**Model File Checks**:
```bash
# Large model files
find models/ -type f -size +100M 2>/dev/null
```
---
## Resources
### Pre-Commit Configuration Templates
#### Python Project Template
```yaml
# .pre-commit-config.yaml for Python projects
repos:
# Code formatting
- repo: https://github.com/psf/black
rev: 23.12.1
hooks:
- id: black
language_version: python3.11
# Linting
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.1.9
hooks:
- id: ruff
args: [--fix, --exit-non-zero-on-fix]
# Type checking
- repo: https://github.com/pre-commit/mirrors-mypy
rev: v1.8.0
hooks:
- id: mypy
additional_dependencies: [types-all]
# Security and general checks
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.5.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-yaml
- id: check-json
- id: check-added-large-files
args: ['--maxkb=10000']
- id: check-merge-conflict
- id: detect-private-key
# Secret detection
- repo: https://github.com/Yelp/detect-secrets
rev: v1.4.0
hooks:
- id: detect-secrets
args: ['--baseline', '.secrets.baseline']
```
#### Plugin Marketplace Project Template
```yaml
# .pre-commit-config.yaml for Plugin Marketplace projects
repos:
# Markdown linting
- repo: https://github.com/igorshubovych/markdownlint-cli
rev: v0.38.0
hooks:
- id: markdownlint
args: [--fix]
# YAML validation
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.5.0
hooks:
- id: check-yaml
- id: check-json
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-merge-conflict
# JSON formatting
- repo: https://github.com/pre-commit/mirrors-prettier
rev: v3.1.0
hooks:
- id: prettier
types_or: [json, yaml, markdown]
```
#### Data Science Project Template
```yaml
# .pre-commit-config.yaml for Data Science projects
repos:
# Python formatting and linting (same as Python template)
- repo: https://github.com/psf/black
rev: 23.12.1
hooks:
- id: black
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.1.9
hooks:
- id: ruff
# Jupyter notebook handling
- repo: https://github.com/nbQA-dev/nbQA
rev: 1.7.1
hooks:
- id: nbqa-black
- id: nbqa-ruff
# Clear notebook outputs
- repo: https://github.com/kynan/nbstripout
rev: 0.6.1
hooks:
- id: nbstripout
# General checks
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.5.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-added-large-files
args: ['--maxkb=5000']
- id: detect-private-key
```
### Secret Detection Patterns Reference
**High-confidence patterns** (should fail):
- AWS Access Key: `AKIA[0-9A-Z]{16}`
- GitHub Personal Access Token: `ghp_[a-zA-Z0-9]{36}`
- GitHub OAuth Token: `gho_[a-zA-Z0-9]{36}`
- Private Key: `-----BEGIN.*PRIVATE KEY-----`
- Anthropic/OpenAI Key: `sk-[a-zA-Z0-9]{48}`
**Medium-confidence patterns** (should warn):
- Generic API key assignment: `api_key\s*=\s*["'][^"']+["']`
- Password assignment: `password\s*=\s*["'][^"']+["']`
- Token assignment: `token\s*=\s*["'][^"']+["']`
**Low-confidence patterns** (informational only):
- Environment variable usage: `os.getenv('API_KEY')`
- Config references: `config['secret']`
### Quality Check Severity Levels
**FAIL (Blocking)**:
- Secrets detected (high confidence)
- Syntax errors
- Merge conflict markers
- Direct commits to main/master
- Files >10MB without Git LFS
**WARN (Non-blocking)**:
- Print statements in Python code
- Files >5MB
- Debug statements in non-test files
- Missing type hints (production tier only)
- Secrets detected (medium confidence)
**INFO (Informational)**:
- Pre-commit not configured
- Optional checks not run
- Secrets detected (low confidence)