Commit a7f7d1387db5

@@ -1,451 +1,203 @@
 # CreatePR Workflow
 
-Create a GitHub pull request with proper formatting, labels, and metadata.
+Create a GitHub pull request with validations, auto-push, and template support.
 
 ## When to Use
 
 - "create pr"
 - "open pull request"
 - "new pr"
-- "create pull request"
+- "submit changes"
 
-## Quick Commands
+## Recommended Tool: gh-pr create
+
+Use the `gh-pr create` command for a streamlined experience with built-in validations.
+
+```bash
+# Basic usage - validates branch, pushes, then creates PR
+gh-pr create
+
+# With title and body
+gh-pr create -t "feat: Add authentication" -b "Implements JWT auth"
+
+# Create from main branch with a new branch name
+gh-pr create --branch feat/my-feature
+
+# With template and draft mode
+gh-pr create --template feature.md --draft
+
+# Require signed commits
+gh-pr create --require-signed
+
+# Skip pushing (if already pushed)
+gh-pr create --no-push
+
+# Force push (for amended commits)
+gh-pr create --force
+```
+
+### gh-pr create Features
+
+| Flag | Description |
+|------|-------------|
+| `--branch` | Create new branch before PR (useful from main) |
+| `--allow-main` | Override main/master branch check |
+| `--no-push` | Skip pushing to remote |
+| `--require-signed` | Verify commits are GPG signed |
+| `--force`, `-f` | Force push with lease |
+| `--template` | Use specific PR template |
+| `--draft`, `-d` | Create as draft PR |
+| `--reviewer`, `-r` | Request reviewers |
+| `--assignee`, `-a` | Assign users |
+| `--label`, `-l` | Add labels |
+| `--web`, `-w` | Open in browser |
+
+### Built-in Validations
+
+The tool automatically:
+1. **Validates branch**: Prevents creating PRs from main/master
+2. **Checks uncommitted changes**: Ensures clean working directory
+3. **Pushes to remote**: Auto-pushes before creating PR
+4. **Detects remote**: Uses personal fork remote if available
+5. **Loads templates**: Discovers and uses PR templates
+
+## Alternative: Direct gh CLI
+
+For basic usage without validations:
 
 ```bash
 # Interactive PR creation
 gh pr create
 
-# With title and body
-gh pr create --title "feat: Add user authentication" --body "Description here"
-
-# From template
-gh pr create --template feature.md
-
-# Set base branch
-gh pr create --base main
-
-# Add reviewers, assignees, labels
-gh pr create --reviewer @user1,@user2 --assignee @me --label enhancement
-
-# Create as draft
-gh pr create --draft
-
 # Fill from commit messages
 gh pr create --fill
+
+# With all options
+gh pr create \
+  --title "feat: Add feature" \
+  --body "Description" \
+  --reviewer @user1 \
+  --assignee @me \
+  --label enhancement \
+  --draft
 ```
 
-## Workflow Steps
+## Workflow Steps (Manual)
 
-### 1. Verify Current State
+### 1. Pre-flight Checks
 
 ```bash
-# Check current branch
-git branch --show-current
+# Verify not on main/master
+branch=$(git branch --show-current)
+[[ "$branch" == "main" || "$branch" == "master" ]] && echo "Error: on protected branch"
 
-# Ensure changes are committed
-git status
+# Check for uncommitted changes
+git status --porcelain
 
 # Check if PR already exists
 gh pr status
 ```
 
-### 2. Check for PR Template
-
-**Look for templates in common locations:**
+### 2. Create Branch (if needed)
 
 ```bash
-# Check for pull request templates
-TEMPLATE=""
-
-# Check common locations
-if [ -f .github/pull_request_template.md ]; then
-  TEMPLATE=".github/pull_request_template.md"
-elif [ -f .github/PULL_REQUEST_TEMPLATE.md ]; then
-  TEMPLATE=".github/PULL_REQUEST_TEMPLATE.md"
-elif [ -f docs/pull_request_template.md ]; then
-  TEMPLATE="docs/pull_request_template.md"
-elif [ -f PULL_REQUEST_TEMPLATE.md ]; then
-  TEMPLATE="PULL_REQUEST_TEMPLATE.md"
-elif [ -d .github/PULL_REQUEST_TEMPLATE ]; then
-  # Multiple templates, list them
-  ls .github/PULL_REQUEST_TEMPLATE/
-fi
-
-if [ -n "$TEMPLATE" ]; then
-  echo "Found PR template: $TEMPLATE"
-  cat "$TEMPLATE"
-fi
+# From main, create feature branch
+git checkout -b feat/my-feature
 ```
 
-**Common template locations:**
-- `.github/pull_request_template.md` (default)
-- `.github/PULL_REQUEST_TEMPLATE.md` (uppercase)
-- `.github/PULL_REQUEST_TEMPLATE/feature.md` (multiple templates)
+### 3. Push Branch
+
+```bash
+# Push with upstream tracking
+git push -u origin $(git branch --show-current)
+```
+
+### 4. Create PR
+
+```bash
+# Use template if available
+gh-pr create --template PULL_REQUEST_TEMPLATE.md
+
+# Or basic creation
+gh pr create --fill
+```
+
+## Template Discovery
+
+Templates are discovered from:
+- `.github/pull_request_template.md`
+- `.github/PULL_REQUEST_TEMPLATE.md`
+- `.github/PULL_REQUEST_TEMPLATE/` (directory with multiple templates)
 - `docs/pull_request_template.md`
-- `PULL_REQUEST_TEMPLATE.md` (root)
-
-### 3. Generate PR Content Following Template
-
-**If template exists, follow its structure:**
-
-Example template:
-```markdown
-## Description
-<!-- Describe your changes -->
-
-## Type of Change
-- [ ] Bug fix
-- [ ] New feature
-- [ ] Breaking change
-- [ ] Documentation update
-
-## Checklist
-- [ ] Tests added/updated
-- [ ] Documentation updated
-- [ ] All checks passing
-```
-
-**Fill in based on commits:**
+- `PULL_REQUEST_TEMPLATE.md`
 
+List available templates:
 ```bash
-# Read template
-TEMPLATE_CONTENT=$(cat .github/pull_request_template.md)
-
-# Generate filled content
-cat > /tmp/pr_body.md <<EOF
-## Description
-$(git log main..HEAD --format=%B | head -5)
-
-## Type of Change
-- [x] New feature
-- [ ] Bug fix
-- [ ] Breaking change
-- [ ] Documentation update
-
-## Checklist
-- [x] Tests added/updated
-- [x] Documentation updated
-- [ ] All checks passing
-
-## Related Issues
-Closes #42
-EOF
-```
-
-**If no template, use default format:**
-
-```markdown
-## Summary
-Brief overview of changes
-
-## Changes
-- Change 1
-- Change 2
-- Change 3
-
-## Testing
-- [ ] Unit tests added/updated
-- [ ] Manual testing completed
-- [ ] All checks passing
-
-## Related Issues
-Closes #123
-Relates to #456
-```
-
-### 4. Extract Title and Body
-
-**Title format** (conventional commits):
-```
-<type>: <short description>
-
-Types: feat, fix, docs, chore, refactor, test, perf, ci
-```
-
-**Generate from commits:**
-```bash
-# Get commit messages since diverging from main
-git log main..HEAD --oneline
-
-# Generate title from first commit
-TITLE=$(git log main..HEAD --format=%s | head -1)
-
-# Or use conventional commit format
-TITLE="feat: Add user authentication"
-```
-
-### 5. Create PR with Template Content
-
-**Using template file directly:**
-```bash
-# gh pr create will automatically use template if it exists
-gh pr create --fill
-```
-
-**Using custom template:**
-```bash
-# Specify template
-gh pr create --template feature.md
-```
-
-**Manual creation with template content:**
-```bash
-# Read and fill template
-BODY=$(cat .github/pull_request_template.md)
-
-# Replace placeholders or fill sections
-BODY=$(echo "$BODY" | sed 's/<!-- Describe your changes -->/Implements JWT authentication/')
-
-gh pr create \
-  --title "feat: Add user authentication" \
-  --body "$BODY" \
-  --base main
-```
-
-### 6. Verify and Monitor
-
-```bash
-# View created PR
-gh pr view
-
-# Check status
-gh pr checks --watch
-
-# Get PR URL
-gh pr view --json url --jq '.url'
-```
-
-## Template Detection and Usage
-
-### Automatic Detection
-
-The `gh pr create` command automatically detects and uses templates:
-
-```bash
-# Will use template if found
-gh pr create
-
-# Will prompt for which template if multiple exist
-gh pr create
-```
-
-### Manual Template Selection
-
-```bash
-# List available templates
-ls .github/PULL_REQUEST_TEMPLATE/
-
-# Use specific template
-gh pr create --template bug_fix.md
-gh pr create --template feature.md
-gh pr create --template hotfix.md
-```
-
-### Parse and Fill Template
-
-For intelligent template filling:
-
-```bash
-#!/bin/bash
-# parse_template.sh
-
-TEMPLATE=".github/pull_request_template.md"
-
-if [ ! -f "$TEMPLATE" ]; then
-  echo "No template found"
-  exit 1
-fi
-
-# Read template
-CONTENT=$(cat "$TEMPLATE")
-
-# Extract sections and fill
-# Example: Fill "Type of Change" based on branch name
-BRANCH=$(git branch --show-current)
-
-if [[ $BRANCH == feat/* ]]; then
-  CONTENT=$(echo "$CONTENT" | sed 's/\[ \] New feature/[x] New feature/')
-elif [[ $BRANCH == fix/* ]]; then
-  CONTENT=$(echo "$CONTENT" | sed 's/\[ \] Bug fix/[x] Bug fix/')
-fi
-
-# Auto-check completed items
-# If tests exist, mark checkbox
-if git diff main..HEAD --name-only | grep -q "test"; then
-  CONTENT=$(echo "$CONTENT" | sed '0,/\[ \] Tests added/s/\[ \] Tests added/[x] Tests added/')
-fi
-
-echo "$CONTENT"
-```
-
-## Advanced Usage
-
-### Create Custom Template
-
-Create `.github/pull_request_template.md`:
-```markdown
-## Description
-<!-- Describe your changes -->
-
-## Type of Change
-- [ ] Bug fix (non-breaking change which fixes an issue)
-- [ ] New feature (non-breaking change which adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
-- [ ] Documentation update
-- [ ] Code refactoring
-- [ ] Performance improvement
-- [ ] Test addition/update
-
-## Motivation and Context
-<!-- Why is this change required? What problem does it solve? -->
-<!-- If it fixes an open issue, please link to the issue here -->
-
-## How Has This Been Tested?
-<!-- Describe the tests you ran to verify your changes -->
-- [ ] Unit tests
-- [ ] Integration tests
-- [ ] Manual testing
-
-## Screenshots (if appropriate)
-<!-- Add screenshots to help explain your changes -->
-
-## Checklist
-- [ ] My code follows the code style of this project
-- [ ] I have updated the documentation accordingly
-- [ ] I have added tests to cover my changes
-- [ ] All new and existing tests passed
-- [ ] My changes generate no new warnings
-- [ ] I have checked my code and corrected any misspellings
-
-## Related Issues
-<!-- Link related issues: Closes #123, Relates to #456 -->
-```
-
-### Multiple Templates
-
-Create directory `.github/PULL_REQUEST_TEMPLATE/`:
-
-```bash
-.github/PULL_REQUEST_TEMPLATE/
-├── bug_fix.md
-├── feature.md
-├── hotfix.md
-└── documentation.md
-```
-
-Use specific template:
-```bash
-gh pr create --template bug_fix.md
-```
-
-### Auto-Fill PR
-
-```bash
-# Fill title from first commit, body from rest
-gh pr create --fill
-
-# Fill with verbose output
-gh pr create --fill-verbose
-```
-
-### Draft PR
-
-For work in progress:
-```bash
-# Create as draft
-gh pr create --draft
-
-# Mark ready later
-gh pr ready <number>
+gh-pr list-templates
 ```
 
 ## Common Scenarios
 
-### Scenario 1: Quick PR (with template)
+### Quick PR from Feature Branch
 
 ```bash
-# gh automatically detects and uses template
-gh pr create --fill --web
+# Already on feature branch with commits
+gh-pr create -t "feat: Add user dashboard" --web
 ```
 
-### Scenario 2: Custom Template Filling
+### PR from Main (Create New Branch)
 
 ```bash
-# Detect template
-TEMPLATE=".github/pull_request_template.md"
-
-# Fill template intelligently
-BODY=$(cat "$TEMPLATE")
-
-# Auto-check items based on changes
-if git diff main..HEAD --name-only | grep -q "_test\|spec"; then
-  BODY=$(echo "$BODY" | sed '0,/\[ \] Tests added/s/\[ \] Tests added/[x] Tests added/')
-fi
-
-if git diff main..HEAD --name-only | grep -q "README\|docs/"; then
-  BODY=$(echo "$BODY" | sed '0,/\[ \] Documentation updated/s/\[ \] Documentation updated/[x] Documentation updated/')
-fi
-
-gh pr create \
-  --title "feat: Add user authentication" \
-  --body "$BODY" \
-  --reviewer @team
+# On main with uncommitted changes
+git checkout -b fix/typo
+git add -A && git commit -m "fix: correct typo"
+gh-pr create
 ```
 
-### Scenario 3: Cross-Fork PR
+### Draft PR for Early Feedback
+
+```bash
+gh-pr create --draft -t "WIP: New feature"
+```
+
+### Cross-Fork PR
 
 ```bash
-# From your fork to upstream
 gh pr create \
   --repo upstream/repo \
   --base main \
   --head yourname:feature-branch
 ```
 
-## Custom Tool: Smart PR Creation
-
-For intelligent template filling and validation:
+### Require Signed Commits
 
 ```bash
-# In tools/ directory
-./CreatePR.ts --auto-fill --validate-checklist --detect-type
+# Will fail if any commits are unsigned
+gh-pr create --require-signed
 ```
 
-**Tool capabilities:**
-- Auto-detect PR template location
-- Intelligently fill template sections based on commits
-- Validate all checklist items are addressed
-- Auto-detect PR type from branch name or commits
-- Link related issues automatically
-- Suggest reviewers based on file changes
-- Validate PR against project guidelines
+## PR Title Format
+
+Follow conventional commits:
+```
+<type>: <description>
+
+Types: feat, fix, docs, chore, refactor, test, perf, ci
+```
+
+Examples:
+- `feat: Add user authentication`
+- `fix: Resolve memory leak in parser`
+- `docs: Update API documentation`
+- `refactor: Simplify error handling`
 
 ## Best Practices
 
-1. **Use repository template**: Always use the repo's PR template if it exists
-2. **Fill template completely**: Don't leave sections empty or with placeholders
-3. **Check all boxes**: Actually verify checklist items before marking
-4. **Descriptive titles**: Follow conventional commit format
-5. **Comprehensive description**: Explain WHY, not just WHAT
-6. **Link issues**: Use "Closes #123" to auto-close
-7. **Add reviewers**: Don't leave empty, assign relevant people
-8. **Use labels**: Categorize for better tracking
-9. **Include tests**: Mention test coverage in description
-10. **Check before creating**: Ensure commits are ready
-11. **Use draft for WIP**: Don't request review for incomplete work
-
-## Template Best Practices
-
-1. **Keep templates concise**: Don't overwhelm contributors
-2. **Use clear sections**: Organize with headers
-3. **Provide examples**: Show what good looks like
-4. **Make checklists actionable**: Specific, verifiable items
-5. **Link to contributing guide**: Reference detailed guidelines
-6. **Support multiple types**: Create separate templates for bugs/features
-7. **Include issue links**: Remind to link related issues
-
-## Resources
-
-- [gh pr create documentation](https://cli.github.com/manual/gh_pr_create)
-- [Pull request templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository)
-- [Pull request best practices](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests)
+1. **Use gh-pr create**: Built-in validations prevent common mistakes
+2. **Descriptive titles**: Follow conventional commit format
+3. **Fill templates**: Don't leave sections empty
+4. **Link issues**: Use "Closes #123" for auto-close
+5. **Add reviewers**: Request appropriate reviewers
+6. **Use draft for WIP**: Don't request review for incomplete work
+7. **Check before creating**: Ensure commits are ready
+8. **Sign commits**: Enable commit signing for trusted contributions