From 6d954fefee5cdefd92320bec046b093a96d63e9e Mon Sep 17 00:00:00 2001 From: Reza Rezvani Date: Wed, 12 Nov 2025 13:06:50 +0100 Subject: [PATCH] feat(commands): add GitHub workflow integration slash commands Phase 4: Claude Code Slash Commands Created 4 GitHub Integration Commands: 1. /github-init - CI/CD system initialization - Runs bootstrap workflow - Creates dev branch - Configures branch protection - Sets default branch to dev - Complete setup verification 2. /commit-smart - Smart commits with quality gates - Pre-commit validation (Python, Bash, secrets) - Conventional Commits format generation - Interactive commit message builder - Quality checks before committing 3. /create-pr - Pull request creation - Branch validation - Target branch detection (dev/main) - PR title generation (Conventional Commits) - PR template population - Workflow trigger explanation 4. /release - GitHub release creation - Version validation (semantic versioning) - CHANGELOG.md integration - Automated release notes - Post-release actions guide All commands provide: - Step-by-step guidance - Copy-paste ready commands - Validation checks - Error handling - Links to documentation Integration with workflows: - Commands trigger bootstrap, pr-into-dev, dev-to-main, release workflows - Enforces quality gates and conventions - Aligns with branching strategy Next: Test workflows with sample feature PR --- .claude/commands/github/commit-smart.md | 123 +++++++++++++ .claude/commands/github/create-pr.md | 184 ++++++++++++++++++++ .claude/commands/github/github-init.md | 95 ++++++++++ .claude/commands/github/release.md | 221 ++++++++++++++++++++++++ 4 files changed, 623 insertions(+) create mode 100644 .claude/commands/github/commit-smart.md create mode 100644 .claude/commands/github/create-pr.md create mode 100644 .claude/commands/github/github-init.md create mode 100644 .claude/commands/github/release.md diff --git a/.claude/commands/github/commit-smart.md b/.claude/commands/github/commit-smart.md new file mode 100644 index 0000000..236dee4 --- /dev/null +++ b/.claude/commands/github/commit-smart.md @@ -0,0 +1,123 @@ +--- +title: /commit-smart +description: Create smart commit with quality checks and conventional format +--- + +# Smart Commit with Quality Gates + +You are helping the user create a well-formatted commit with pre-commit validation. + +## Workflow + +1. **Check Staged Changes** + ```bash + git status + git diff --cached --stat + ``` + - Show what files are staged + - If nothing staged, ask user what to add + +2. **Pre-Commit Quality Checks** + + Run local quality gates before committing: + + **Python syntax** (if .py files changed): + ```bash + flake8 skill/ --count --select=E9,F63,F7,F82 --show-source + ``` + + **Bash syntax** (if .sh files changed): + ```bash + bash -n install.sh + bash -n hooks/pre-commit.sh + ``` + + **Secret scan**: + ```bash + git diff --cached | grep -iE "(api_key|api_secret|password|token|AWS_ACCESS)" || echo "No secrets detected" + ``` + +3. **Generate Conventional Commit Message** + + Ask user about the change: + - Type: feat, fix, docs, style, refactor, perf, test, build, ci, chore + - Scope: installer, skill, command, agent, docs, ci, workflows + - Description: what changed (imperative mood) + - Why: reason for change (optional body) + - Issue: related issue number + + **Format:** + ``` + (): + + [optional body explaining why] + + [optional footer: Closes #123] + ``` + +4. **Validate Message Format** + - Check format matches Conventional Commits + - Ensure subject is imperative mood ("add" not "added") + - Verify no period at end + - Check length < 50 characters for subject + +5. **Create Commit** + ```bash + git commit -m "" + ``` + +6. **Post-Commit Actions** + - Show commit hash + - Show commit in log + - Ask if user wants to push + +## Examples + +**Feature commit:** +```bash +git commit -m "feat(installer): add Windows PowerShell support + +Adds install.ps1 script with equivalent functionality to +install.sh for Windows users. + +Closes #42" +``` + +**Fix commit:** +```bash +git commit -m "fix(skill): correct Python syntax validation + +Fix flake8 configuration to properly detect syntax errors. +Previous config was too permissive. + +Fixes #156" +``` + +**Docs commit:** +```bash +git commit -m "docs: update GitHub workflows documentation + +Add troubleshooting section and configuration examples." +``` + +## Quality Gates + +Before committing, ensure: +- ✅ No syntax errors +- ✅ No hardcoded secrets +- ✅ Conventional Commits format +- ✅ Related issue linked (for feat/fix) +- ✅ Files staged are relevant to commit message + +## Interactive Flow + +1. Show staged changes +2. Run quality checks +3. Ask for commit details (type, scope, description) +4. Generate commit message +5. Show preview +6. Confirm with user +7. Execute commit +8. Display result + +Use clear prompts and provide the exact commands for the user to run. diff --git a/.claude/commands/github/create-pr.md b/.claude/commands/github/create-pr.md new file mode 100644 index 0000000..e67ec59 --- /dev/null +++ b/.claude/commands/github/create-pr.md @@ -0,0 +1,184 @@ +--- +title: /create-pr +description: Create pull request with proper validation +--- + +# Create Pull Request + +You are helping the user create a pull request that follows ClaudeForge conventions. + +## Workflow + +1. **Detect Current Branch** + ```bash + CURRENT_BRANCH=$(git branch --show-current) + echo "Current branch: $CURRENT_BRANCH" + ``` + +2. **Determine Target Branch** + - If current branch starts with `feature/`, `fix/`, `hotfix/`, `test/`, `refactor/`, `docs/`: + - Target: `dev` + - If current branch is `dev`: + - Target: `main` (release PR) + - Otherwise: Ask user + +3. **Validate Branch Name** + - Check if branch follows convention + - If not, suggest renaming: + ```bash + git branch -m feature/new-name + ``` + +4. **Check for Uncommitted Changes** + ```bash + git status --short + ``` + - If changes exist, suggest committing first + +5. **Push Branch** (if needed) + ```bash + git push -u origin $CURRENT_BRANCH + ``` + +6. **Generate PR Title** + - Based on commits since target branch + - Must follow Conventional Commits format + - Examples: + - `feat(installer): add Windows PowerShell support` + - `fix(skill): correct template selection logic` + - `docs: update installation guide` + +7. **Generate PR Description** + + Use PR template format: + ```markdown + ## Description + [Describe changes] + + ## Type of Change + - [x] [Selected type] + + ## Related Issues + Closes #[issue number] + + ## Changes Made + - Change 1 + - Change 2 + + ## Testing Performed + - [x] Tested installation + - [x] Tested slash command + ... + ``` + +8. **Create PR** + ```bash + gh pr create \ + --base [target branch] \ + --title "[PR title]" \ + --body "[PR description]" + ``` + + Or for draft: + ```bash + gh pr create --draft \ + --base [target branch] \ + --title "[PR title]" \ + --body "[PR description]" + ``` + +9. **Post-Creation** + - Show PR URL + - Explain what workflows will run: + - For PR to dev: `pr-into-dev.yml` + - For PR to main: `dev-to-main.yml` + - Link to workflow documentation + +## Validation Checklist + +Before creating PR, verify: +- ✅ Branch name follows convention +- ✅ PR title follows Conventional Commits +- ✅ At least one issue referenced +- ✅ All changes committed and pushed +- ✅ Target branch is correct + +## Examples + +**Feature PR to dev:** +```bash +gh pr create \ + --base dev \ + --title "feat(skill): add Rust template support" \ + --body "## Description + +Adds Rust project template with Cargo.toml detection and +appropriate CLAUDE.md generation. + +## Type of Change +- [x] New feature + +## Related Issues +Closes #42 + +## Changes Made +- Add Rust template in skill/examples/ +- Update template_selector.py with Rust detection +- Add Rust-specific validation rules + +## Testing Performed +- [x] Tested on sample Rust project +- [x] Validated template output +- [x] Python syntax checks pass" +``` + +**Release PR (dev to main):** +```bash +gh pr create \ + --base main \ + --title "release: v1.1.0" \ + --body "## Description + +Release version 1.1.0 with new features and bug fixes. + +## Changes in This Release +- feat(skill): Rust template support +- feat(installer): Windows improvements +- fix(skill): Template selection bugs +- docs: Updated installation guide + +## Related Issues +Closes #42, #45, #48 + +## CHANGELOG +See CHANGELOG.md for full details. + +## Testing +- [x] All quality gates pass +- [x] Tested installation on macOS, Linux, Windows +- [x] Tested all new features" +``` + +## Workflow Triggers + +**PR to dev:** +- Validates branch name (must be feature/*, fix/*, etc.) +- Validates PR title (Conventional Commits) +- Checks for linked issues +- Runs quality gates (Python, Markdown, Bash, secrets) + +**PR to main:** +- Validates source branch (must be dev, release/*, or dependabot/*) +- Checks CHANGELOG.md updated +- Validates production build +- Runs full quality gates + +## Success Output + +Show user: +1. PR URL +2. Workflow status link +3. Next steps (wait for CI, request review) +4. Link to relevant docs (GITHUB_WORKFLOWS.md, BRANCHING_STRATEGY.md) + +Provide clear guidance and actual commands user can run. diff --git a/.claude/commands/github/github-init.md b/.claude/commands/github/github-init.md new file mode 100644 index 0000000..b620592 --- /dev/null +++ b/.claude/commands/github/github-init.md @@ -0,0 +1,95 @@ +--- +title: /github-init +description: Initialize ClaudeForge CI/CD system +--- + +# GitHub CI/CD Initialization + +You are helping the user initialize the ClaudeForge CI/CD system. + +## Workflow + +1. **Check Current State** + - Verify `.github/workflows/` directory exists + - Check if bootstrap workflow has been run (look for labels/milestones) + - Check if dev branch exists + - Check branch protection status + +2. **Run Bootstrap Workflow** + - If not yet run, guide user to run bootstrap workflow: + - Go to Actions → Bootstrap Repository → Run workflow + - Enable all options (create labels, milestones, validate settings) + - Explain what will be created (23 labels, 3 milestones) + +3. **Create Dev Branch** (if not exists) + ```bash + git checkout -b dev + git push -u origin dev + ``` + +4. **Configure Branch Protection** + + Guide user step-by-step: + + **For main branch:** + - Go to Settings → Branches → Add rule + - Pattern: `main` + - Enable: + - Require PR before merging + - Require status checks: `quality-gates`, `production-build`, `validate-release-pr` + - Require linear history + - Block force pushes + - Restrict deletions + + **For dev branch:** + - Pattern: `dev` + - Enable: + - Require PR before merging + - Require status checks: `quality-gates`, `validate-pr` + - Require linear history + - Block force pushes + - Restrict deletions + +5. **Set Default Branch** + - Settings → General → Default branch → Change to `dev` + - This ensures new PRs target dev by default + +6. **Verification** + - Show current branch protection rules + - Verify workflows are present + - Confirm setup is complete + +7. **Next Steps** + - Point to docs/GITHUB_WORKFLOWS.md for workflow reference + - Point to docs/BRANCHING_STRATEGY.md for branch flow + - Suggest creating first feature branch to test + +## Commands to provide + +```bash +# Check current setup +gh repo view --json name,defaultBranchRef,hasIssuesEnabled + +# List workflows +ls -la .github/workflows/ + +# Check labels +gh label list + +# Check milestones +gh api repos/:owner/:repo/milestones + +# Check branch protection +gh api repos/:owner/:repo/branches/main/protection 2>/dev/null || echo "Not protected" +gh api repos/:owner/:repo/branches/dev/protection 2>/dev/null || echo "Not protected" +``` + +## Success Criteria + +✅ Bootstrap workflow run successfully +✅ Dev branch created and pushed +✅ Branch protection configured for main and dev +✅ Default branch set to dev +✅ User understands next steps + +Provide clear, step-by-step guidance with actual commands the user can copy-paste. diff --git a/.claude/commands/github/release.md b/.claude/commands/github/release.md new file mode 100644 index 0000000..dd77d42 --- /dev/null +++ b/.claude/commands/github/release.md @@ -0,0 +1,221 @@ +--- +title: /release +description: Create GitHub release with automated notes +--- + +# Create GitHub Release + +You are helping the user create a GitHub release for ClaudeForge. + +## Prerequisites Check + +1. **Verify on main branch** + ```bash + git branch --show-current + ``` + - Should be `main` + - If not, `git checkout main && git pull` + +2. **Check for uncommitted changes** + ```bash + git status + ``` + - Should be clean + +3. **Verify CHANGELOG.md updated** + ```bash + grep -A 10 "## \[" CHANGELOG.md | head -15 + ``` + - Should have entry for new version + +## Workflow + +1. **Determine Version** + - Ask user for version number + - Validate semantic versioning format (X.Y.Z) + - Examples: 1.1.0, 1.0.1, 2.0.0-beta.1 + +2. **Check Tag Doesn't Exist** + ```bash + git tag -l "v1.1.0" + ``` + - Should return nothing + - If tag exists, ask user to choose different version + +3. **Verify CHANGELOG.md** + - Check if version is documented + - Extract release notes for this version + - Show preview to user + +4. **Run Release Workflow** + + **Option 1: Via GitHub CLI** + ```bash + gh workflow run release.yml \ + -f version=1.1.0 \ + -f prerelease=false \ + -f draft=false + ``` + + **Option 2: Via GitHub UI** + - Go to Actions → Create Release + - Click "Run workflow" + - Enter version: 1.1.0 + - Select options (prerelease, draft) + - Click "Run workflow" + +5. **Monitor Workflow** + ```bash + gh run list --workflow=release.yml --limit 1 + gh run watch + ``` + +6. **Verify Release Created** + ```bash + gh release list + gh release view v1.1.0 + ``` + +## Release Types + +**Stable Release:** +- Version: X.Y.Z (e.g., 1.1.0) +- Prerelease: false +- Draft: false +- Published immediately + +**Pre-Release:** +- Version: X.Y.Z-beta.N (e.g., 1.2.0-beta.1) +- Prerelease: true +- Draft: false +- Marked as pre-release on GitHub + +**Draft Release:** +- Version: X.Y.Z +- Draft: true +- Not published until manually approved + +## Release Notes Generation + +The release workflow automatically: +1. Extracts notes from CHANGELOG.md +2. Adds installation instructions +3. Lists commits since last release +4. Includes full changelog link + +**Example output:** +```markdown +Release v1.1.0 + +[Content from CHANGELOG.md] + +--- + +## 📦 Installation + +### One-Line Install +```bash +curl -fsSL https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.sh | bash +``` + +## 📝 Commits +- feat(skill): add Rust template (a1b2c3d) +- fix(installer): Windows path fix (e4f5g6h) + +**Full Changelog**: https://github.com/alirezarezvani/ClaudeForge/blob/main/CHANGELOG.md +``` + +## Post-Release Actions + +After release is created: + +1. **Verify on GitHub** + - Go to Releases page + - Check release notes are correct + - Test one-line installation command + +2. **Update References** (if needed) + - install.sh version reference + - install.ps1 version reference + - README.md version badge + +3. **Announce Release** + - Create Discussion post + - Share on social media + - Update documentation site + +4. **Sync Dev Branch** (recommended) + ```bash + git checkout dev + git merge main + git push origin dev + ``` + +## Example: Creating v1.1.0 Release + +```bash +# 1. Ensure on main and up to date +git checkout main +git pull origin main + +# 2. Verify CHANGELOG.md +cat CHANGELOG.md | grep -A 20 "\[1.1.0\]" + +# 3. Run release workflow +gh workflow run release.yml \ + -f version=1.1.0 \ + -f prerelease=false \ + -f draft=false + +# 4. Monitor workflow +gh run watch + +# 5. Verify release +gh release view v1.1.0 + +# 6. Test installation +curl -fsSL https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/v1.1.0/install.sh | bash + +# 7. Sync dev +git checkout dev +git merge main +git push origin dev +``` + +## Troubleshooting + +**"Tag already exists":** +- Check existing tags: `git tag -l` +- Either delete old tag or use different version + +**"Version not in CHANGELOG":** +- Edit CHANGELOG.md +- Add section for new version +- Commit and push to main + +**"Workflow failed":** +- Check workflow logs: `gh run view` +- Common issues: + - Invalid version format + - Tag conflicts + - Missing CHANGELOG entry + +## Validation + +Before creating release, ensure: +- ✅ On main branch, clean working tree +- ✅ CHANGELOG.md has entry for version +- ✅ All tests passing on main +- ✅ PR from dev to main was merged +- ✅ Version number follows semantic versioning +- ✅ Tag v doesn't already exist + +## Success Criteria + +✅ GitHub release created with auto-generated notes +✅ Git tag created (v1.1.0) +✅ Release appears on Releases page +✅ Installation command works +✅ Dev branch synced with main + +Guide user through the process with clear steps and commands they can copy-paste.