From 4a6b514b06cbeaf0dab3205c80011322549ab2c0 Mon Sep 17 00:00:00 2001 From: Reza Rezvani Date: Tue, 4 Nov 2025 22:16:53 +0100 Subject: [PATCH] feat(commands): add git workflow and quality gate slash commands MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Implemented complete slash command system adapted from claude-code-skills-factory for streamlined git workflow and quality assurance in claude-skills repository. ## New Slash Commands ### Git Workflow (3 commands) - **git/cm.md** (/git:cm): Stage and commit (no push) - **git/cp.md** (/git:cp): Stage, commit, and push with quality checks - **git/pr.md** (/git:pr): Create pull request from current branch ### Quality Gates (2 commands) - **review.md** (/review): Local quality checks (YAML lint, schema validation, Python syntax, markdown links) - **security-scan.md** (/security-scan): Security validation (Gitleaks, Safety audit) ### Documentation - **README.md**: Complete command reference with usage examples and workflows ## Key Features ✅ Step-by-step instructions for each command ✅ Safety checks (secrets detection, credential scanning) ✅ Conventional Commit format enforcement ✅ Integration with CI workflows (ci-quality-gate.yml) ✅ Quality gate enforcement before push ## Adaptations from Factory Project - Updated directory paths for claude-skills structure - Configured for repository-specific workflows - Simplified for skills library workflow - Removed factory-specific commands (build, validate-output, etc.) - Kept essential git and quality commands only ## Usage Commands available in Claude Code CLI: - /git:cm - Commit without pushing - /git:cp - Complete git workflow - /git:pr - Create pull request - /review - Run quality checks - /security-scan - Run security validation ## Integration Commands integrate with GitHub automation: - /git:cp triggers ci-quality-gate workflow - /git:pr triggers claude-code-review workflow - Merged PRs trigger pr-issue-auto-close workflow See .claude/commands/README.md for complete documentation. --- .claude/commands/README.md | 349 ++++++++++++++++++++++++++++++ .claude/commands/git/cm.md | 14 ++ .claude/commands/git/cp.md | 14 ++ .claude/commands/git/pr.md | 25 +++ .claude/commands/review.md | 33 +++ .claude/commands/security-scan.md | 22 ++ 6 files changed, 457 insertions(+) create mode 100644 .claude/commands/README.md create mode 100644 .claude/commands/git/cm.md create mode 100644 .claude/commands/git/cp.md create mode 100644 .claude/commands/git/pr.md create mode 100644 .claude/commands/review.md create mode 100644 .claude/commands/security-scan.md diff --git a/.claude/commands/README.md b/.claude/commands/README.md new file mode 100644 index 0000000..7ce74b9 --- /dev/null +++ b/.claude/commands/README.md @@ -0,0 +1,349 @@ +# Claude Skills Slash Commands + +**Git workflow and quality assurance commands for the claude-skills repository.** + +--- + +## 🎯 Essential Commands + +### Git Workflow + +``` +/git:cm → Stage and commit (no push) +/git:cp → Stage, commit, and push +/git:pr → Create pull request +``` + +### Quality Gates + +``` +/review → Run local quality checks +/security-scan → Run security validation +``` + +--- + +## 📋 Git Commands + +### /git:cm - Commit (No Push) + +**Purpose**: Stage changes and create a conventional commit without pushing + +**Usage**: +``` +/git:cm +``` + +**What it does**: +1. Shows `git status --short` +2. Reviews each file diff for secrets +3. Stages files intentionally +4. Generates conventional commit message +5. Creates commit (no push) + +**When to use**: When you want to commit locally before pushing + +--- + +### /git:cp - Commit and Push + +**Purpose**: Complete git workflow with quality checks + +**Usage**: +``` +/git:cp +``` + +**What it does**: +1. Runs `/review` for quality checks +2. Stages changes +3. Creates conventional commit +4. Pushes to origin +5. Triggers CI workflows + +**When to use**: When ready to publish changes + +--- + +### /git:pr - Create Pull Request + +**Purpose**: Create a PR from current branch + +**Usage**: +``` +/git:pr # PR to main +/git:pr dev # PR to dev branch +``` + +**What it does**: +1. Verifies quality checks passed +2. Creates PR using template +3. Adds appropriate labels +4. Shares PR link + +**When to use**: After pushing changes and ready for review + +--- + +## 🔒 Quality Commands + +### /review - Local Quality Gate + +**Purpose**: Run all quality checks before pushing + +**Usage**: +``` +/review +``` + +**What it checks**: +- ✅ YAML linting (workflows) +- ✅ GitHub workflow schema validation +- ✅ Python syntax (all skill directories) +- ✅ Markdown link validation +- ✅ Dependency security audit (optional) + +**When to use**: Before committing/pushing changes + +--- + +### /security-scan - Security Validation + +**Purpose**: Scan for security issues + +**Usage**: +``` +/security-scan +``` + +**What it checks**: +- 🔍 Gitleaks (committed secrets detection) +- 🔍 Safety (Python dependency vulnerabilities) + +**When to use**: Before pushing, especially with new dependencies + +--- + +## 🔄 Complete Workflow + +### Standard Feature Development + +``` +# 1. Make changes to skills +[Edit files in marketing-skill/, product-team/, etc.] + +# 2. Run quality checks +/review + +# 3. Run security scan +/security-scan + +# 4. Commit and push +/git:cp + +# 5. Create pull request +/git:pr + +# 6. Wait for: + - ✅ Claude Code Review comment + - ✅ CI Quality Gate passing + - ✅ Human approval + +# 7. Merge PR + - Issue auto-closes (if linked) + - Project board updates +``` + +--- + +## 💡 Quick Reference + +| Command | Stage | Commit | Push | Quality Check | Create PR | +|---------|-------|--------|------|---------------|-----------| +| **/git:cm** | ✅ | ✅ | ❌ | ❌ | ❌ | +| **/git:cp** | ✅ | ✅ | ✅ | ✅ | ❌ | +| **/git:pr** | ❌ | ❌ | ❌ | Verify | ✅ | +| **/review** | ❌ | ❌ | ❌ | ✅ | ❌ | +| **/security-scan** | ❌ | ❌ | ❌ | ✅ | ❌ | + +--- + +## 📊 Commit Message Format + +All commits follow **Conventional Commits**: + +``` +(): + +## Context +- Why this change was needed +- What problem it solves + +## Testing +- [ ] All Python scripts tested +- [ ] Skills validated with Claude +- [ ] /review passed +- [ ] /security-scan passed + +## Reviewers +- [ ] @username +``` + +**Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert` + +**Scopes**: `marketing-skill`, `product-team`, `c-level-advisor`, `engineering-team`, `ra-qm-team`, `workflows`, `docs`, `ci` + +**Examples**: +``` +feat(marketing-skill): add LinkedIn content framework +fix(product-team): correct RICE prioritization calculation +docs(README): update skill installation instructions +ci(workflows): add auto-close issues on PR merge +``` + +--- + +## 🎯 Use Cases + +### Quick Fix + +``` +# Fix typo in skill +[Edit file] +/review # Quick check +/git:cp # Commit + push +``` + +### New Skill Addition + +``` +# Create new skill +[Create skill directory and files] +/review # Validate structure +/security-scan # Check for issues +/git:cm # Commit locally +[Test skill activation] +/git:cp # Push when ready +/git:pr # Create PR for review +``` + +### Major Feature with Multiple Skills + +``` +# Work on branch +git checkout -b feature/enterprise-skills + +# Add multiple skills +[Create skill 1] +/git:cm + +[Create skill 2] +/git:cm + +[Create skill 3] +/git:cm + +# Final quality check +/review +/security-scan + +# Push and create PR +git push origin feature/enterprise-skills +/git:pr + +# Or use /git:cp if you want to push single commit +``` + +--- + +## 🚨 Emergency Bypass + +### Skip Reviews (Emergency Only) + +If you need to bypass checks: + +```bash +# Method 1: Use --no-verify flag +git push --no-verify + +# Method 2: PR title bypass +[EMERGENCY] Fix critical bug + +# Method 3: PR label +Add label: emergency, skip-review, or hotfix +``` + +**Note**: These bypass automated reviews but manual review is still recommended. + +--- + +## 📖 Integration with Automation + +These commands work seamlessly with the GitHub automation: + +**After running `/git:cp`**: +- Triggers CI Quality Gate workflow +- Shows results in GitHub Actions + +**After running `/git:pr`**: +- Triggers Claude Code Review +- Runs CI Quality Gate +- Updates project board status + +**After merging PR**: +- Auto-closes linked issues +- Updates project board to "Done" +- Posts completion comments + +--- + +## 🔗 Related Documentation + +- **Automation Setup**: `.github/AUTOMATION_SETUP.md` +- **PR Template**: `.github/pull_request_template.md` +- **Commit Template**: `.github/commit-template.txt` +- **Workflow Guide**: See factory project for detailed reference + +--- + +## 📍 Command Locations + +``` +.claude/commands/ +├── git/ +│ ├── cm.md # Commit (no push) +│ ├── cp.md # Commit and push +│ └── pr.md # Create PR +├── review.md # Quality checks +├── security-scan.md # Security validation +└── README.md # This file +``` + +--- + +## 💡 Tips + +**Before committing**: +- ✅ Run `/review` to catch issues early +- ✅ Run `/security-scan` if adding dependencies +- ✅ Test skills with Claude before pushing + +**When creating PRs**: +- ✅ Link related issues (`Fixes #123`) +- ✅ Fill out PR template completely +- ✅ Add appropriate labels +- ✅ Request specific reviewers + +**For quality**: +- ✅ Keep commits focused and atomic +- ✅ Write clear, descriptive commit messages +- ✅ Follow conventional commit format +- ✅ Update documentation with changes + +--- + +**Last Updated**: 2025-11-04 +**Version**: 1.0.0 +**Status**: ✅ Ready to use + +**Streamline your Git workflow with simple commands!** 🚀 diff --git a/.claude/commands/git/cm.md b/.claude/commands/git/cm.md new file mode 100644 index 0000000..6a91f54 --- /dev/null +++ b/.claude/commands/git/cm.md @@ -0,0 +1,14 @@ +--- +description: Stage working tree changes and create a Conventional Commit (no push). +--- + +1. Run `git status --short` to review pending changes. +2. For each file, open a diff (`git diff -- path/to/file`) and ensure no secrets or credentials are present. +3. Stage the files intentionally (`git add path/to/file`). Avoid `git add .` unless every change was reviewed. +4. Generate a Conventional Commit message (types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert). + - Commit subject ≤ 72 chars. + - Scope uses kebab-case (e.g., `feat(marketing-skill): ...`). + - Use `.github/commit-template.txt` for Context / Testing / Reviewers sections. +5. Run `git commit` and paste the generated message + context from the template. +6. Show the resulting commit (`git log -1 --stat`) and keep the commit hash handy. +7. **Do not push** in this command. Use `git/cp.md` when you're ready to publish. diff --git a/.claude/commands/git/cp.md b/.claude/commands/git/cp.md new file mode 100644 index 0000000..01da198 --- /dev/null +++ b/.claude/commands/git/cp.md @@ -0,0 +1,14 @@ +--- +description: Stage, commit, and push the current branch following git governance rules. +--- + +1. Run `/review` to ensure lint/tests/security checks pass locally. +2. Review and stage changes with `git add` (avoid staging generated or secret files). +3. Craft a Conventional Commit message (types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert). + - Use `.github/commit-template.txt` and include Context / Testing / Reviewers blocks. + - Never add AI attribution strings to commits. +4. Commit with `git commit` using the prepared message. If commitlint fails, fix the message and retry. +5. Push to origin: `git push origin $(git branch --show-current)`. +6. Trigger remote checks for visibility: + - `gh workflow run ci-quality-gate.yml --ref $(git branch --show-current)` +7. Wait for workflow to finish (`gh run watch --workflow ci-quality-gate.yml`) before opening a pull request. diff --git a/.claude/commands/git/pr.md b/.claude/commands/git/pr.md new file mode 100644 index 0000000..54b9632 --- /dev/null +++ b/.claude/commands/git/pr.md @@ -0,0 +1,25 @@ +--- +description: Create a pull request from the current branch. +argument-hint: [target-branch] +--- + +## Variables + +TARGET_BRANCH: $1 (defaults to `main`) +SOURCE_BRANCH: current branch (`git branch --show-current`) + +## Workflow + +1. Ensure `/review` and `/security-scan` have passed locally. +2. Confirm `ci-quality-gate` workflow succeeded for `SOURCE_BRANCH`. +3. Create the PR using GitHub CLI: + ```bash + gh pr create \ + --base "$TARGET_BRANCH" \ + --head "$SOURCE_BRANCH" \ + --title "" \ + --body-file .github/pull_request_template.md + ``` + If no template exists, provide a summary referencing Context, Testing, and Security results. +4. Add labels (`gh pr edit --add-label "status: in-review"`). +5. Share the PR link with reviewers and ensure at least one human approval is obtained. diff --git a/.claude/commands/review.md b/.claude/commands/review.md new file mode 100644 index 0000000..8087d16 --- /dev/null +++ b/.claude/commands/review.md @@ -0,0 +1,33 @@ +--- +description: Run the local review gate before pushing. +--- + +Perform a complete review pass: + +1. Save work in progress and ensure the working tree is clean except for intentional changes. +2. Install tooling (only first run): + ```bash + pip install --upgrade pip + pip install yamllint==1.35.1 check-jsonschema==0.28.4 safety==3.2.4 + npm install --global markdown-link-check@3.12.2 + ``` +3. Lint GitHub workflows: + ```bash + yamllint -d '{extends: default, rules: {line-length: {max: 160}}}' .github/workflows + check-jsonschema --schema github-workflow --base-dir . .github/workflows/*.yml + ``` +4. Python syntax check: + ```bash + python -m compileall marketing-skill product-team c-level-advisor engineering-team ra-qm-team + ``` +5. Markdown sanity check: + ```bash + markdown-link-check README.md + ``` +6. Optional dependency audit (if `requirements*.txt` present): + ```bash + for f in $(find . -name "requirements*.txt" 2>/dev/null); do + safety check --full-report --file "$f" + done + ``` +7. Summarize results in the commit template's Testing section. Fix any failures before continuing. diff --git a/.claude/commands/security-scan.md b/.claude/commands/security-scan.md new file mode 100644 index 0000000..8c19bf8 --- /dev/null +++ b/.claude/commands/security-scan.md @@ -0,0 +1,22 @@ +--- +description: Run the security scan gate before pushing. +--- + +1. Ensure dependencies are installed: + ```bash + pip install safety==3.2.4 + brew install gitleaks # or appropriate package manager + ``` +2. Scan for committed secrets: + ```bash + gitleaks detect --verbose --redact + ``` + - Resolve any findings before continuing. +3. Audit Python dependencies (if requirements files exist): + ```bash + for f in $(find . -name "requirements*.txt" 2>/dev/null); do + safety check --full-report --file "$f" + done + ``` +4. Record results in the commit template's Testing section. +5. After a clean pass, proceed with commit and push workflow.