chore(release): prepare 1.4.0

.github/workflows/close-linked-issues.yml

@@ -30,7 +30,7 @@ jobs:
       pull-requests: read
     steps:
       - name: Close linked issues
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |

.github/workflows/lint.yml

@@ -0,0 +1,15 @@
+name: Lint SKILL.md
+
+on:
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Run lint
+        run: ./scripts/lint.sh

CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.0] - 2026-03-28
+
+### Added
+
+- GitHub Actions workflow to run lint on every PR (#79)
+- Lint status badge in README (#92)
+- Workflow comparison section in README: Gitflow vs GitHub Flow vs Trunk-Based (#80)
+- Integration guide with commitlint, husky, and branch name CI validation (#91)
+- 5 additional troubleshooting scenarios: wrong base branch, merge conflicts, deleted branch, committed secrets, wrong merge target (#81)
+- ONBOARDING.md worked example and FAQ section (#82)
+- ONBOARDING.md link in README navigation bar (#87)
+
+### Changed
+
+- Upgrade GitHub Actions to Node.js 24: checkout v4→v5, github-script v7→v8 (#80)
+- Update CLAUDE.md Architecture section to include scripts/ and workflows (#89)
+- Update CLAUDE.md Testing section with lint and install script references (#89)
+
 ## [1.3.0] - 2026-03-27
 
 ### Added
@@ -107,6 +125,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - CONTRIBUTING.md contribution guidelines
 - GitHub issue and PR templates
 
+[1.4.0]: https://github.com/qubernetic-org/git-workflow-agent-skill/compare/v1.3.0...v1.4.0
 [1.3.0]: https://github.com/qubernetic-org/git-workflow-agent-skill/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/qubernetic-org/git-workflow-agent-skill/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/qubernetic-org/git-workflow-agent-skill/compare/v1.0.4...v1.1.0

CLAUDE.md

@@ -15,7 +15,8 @@ This repo follows the same Gitflow workflow described in SKILL.md. Apply the ski
 ## Architecture
 
 - **SKILL.md** — The entire skill definition. Self-contained installable artifact. Contains YAML frontmatter (`name`, `description`, `version`, `metadata`) followed by the complete workflow specification: branch model, commit format, issue-driven flow, semantic versioning, release process, and forbidden operations.
-- **`.github/`** — PR template and issue templates (bug report, feature request).
+- **`scripts/`** — Tooling: `lint.sh` (structural validation of SKILL.md), `install_linux.sh`, `install_macos.sh`, `install_windows.ps1` (platform-specific install/uninstall via symlink).
+- **`.github/`** — PR template, issue templates (bug report, feature request), and GitHub Actions workflows (`lint.yml`, `close-linked-issues.yml`).
 
 ## Key Invariants
 
@@ -33,12 +34,11 @@ When modifying SKILL.md, preserve these non-negotiable rules:
 
 - SKILL.md must remain **self-contained** — it is the installable artifact
 - The `description` field in frontmatter controls when Claude Code triggers the skill — keep trigger keywords updated if scope changes
-- Keep version in sync between frontmatter `version`, `metadata.version`, and CHANGELOG.md
+- Keep version in sync between frontmatter `version`, `metadata.version`, README.md badge, and CHANGELOG.md — run `./scripts/lint.sh` to verify
 
 ## Testing Changes
 
-No automated tests. Manual verification:
-
-1. Copy updated `SKILL.md` to `~/.claude/skills/git-workflow/SKILL.md`
-2. Start a new Claude Code session
-3. Ask Claude to perform git operations and verify it follows the workflow
+1. Run the linter: `./scripts/lint.sh`
+2. Install the updated skill: `./scripts/install_linux.sh` (or platform equivalent)
+3. Start a new Claude Code session
+4. Ask Claude to perform git operations and verify it follows the workflow

ONBOARDING.md

@@ -25,9 +25,10 @@ When installed, Claude Code reads SKILL.md and enforces its rules during git ope
 ## How to Install and Test Locally
 
 ```bash
-# 1. Copy the skill to Claude Code's skill directory
-mkdir -p ~/.claude/skills/git-workflow
-cp SKILL.md ~/.claude/skills/git-workflow/SKILL.md
+# 1. Install using the platform-specific script (creates a symlink)
+./scripts/install_linux.sh     # Linux
+./scripts/install_macos.sh     # macOS
+.\scripts\install_windows.ps1  # Windows (PowerShell)
 
 # 2. Start a new Claude Code session
 claude
@@ -39,6 +40,8 @@ claude
 #    Verify Claude follows the workflow rules.
 ```
 
+> **Tip:** The install script creates a symlink, so the skill auto-syncs when you pull new changes. No need to re-copy after updates.
+
 ## How the Skill Works
 
 1. **Frontmatter** — The YAML block at the top of SKILL.md contains `name`, `description`, and `version`. The `description` field controls when Claude Code activates the skill (keyword matching).
@@ -79,3 +82,53 @@ Run `./scripts/lint.sh` to verify consistency.
 - **Version bumps happen on release branches only** — don't bump versions in feature/fix branches.
 - **Always pull before branching** — `git pull origin develop` before `git checkout -b` to avoid stale forks.
 - **No AI co-author signatures** — never add `Co-Authored-By` lines to commits in this repo.
+
+## Worked Example: Contributing a Bug Fix
+
+Here's a complete walkthrough of fixing a typo in SKILL.md:
+
+```bash
+# 1. Open an issue on GitHub: "fix: typo in Troubleshooting section"
+#    Note the issue number (e.g., #99)
+
+# 2. Create your branch
+git checkout develop
+git pull origin develop
+git checkout -b fix/99-troubleshooting-typo
+
+# 3. Make the fix in SKILL.md, then commit
+git add SKILL.md
+git commit -m "fix: correct typo in Troubleshooting section"
+
+# 4. Run the linter
+./scripts/lint.sh
+
+# 5. Push and open a PR
+git push -u origin fix/99-troubleshooting-typo
+gh pr create --base develop \
+  --title "fix: correct typo in Troubleshooting section (#99)" \
+  --body "Closes #99"
+
+# 6. After review and merge, clean up
+git checkout develop
+git pull origin develop
+git fetch --prune
+git branch -d fix/99-troubleshooting-typo
+```
+
+## FAQ
+
+**Can I use this skill with other AI assistants?**
+The skill is written for Claude Code specifically. The YAML frontmatter and activation keywords are Claude Code conventions. Other assistants would need their own format, but the workflow rules themselves are universal.
+
+**What if my project doesn't use Gitflow?**
+This skill enforces Gitflow. If your project uses GitHub Flow or trunk-based development, this skill isn't the right fit. See the [README comparison table](README.md#why-this-workflow) for guidance on when Gitflow makes sense.
+
+**Do I need all the files or just SKILL.md?**
+Users only need `SKILL.md` — it's the complete, self-contained skill. All other files (README, CONTRIBUTING, etc.) are for contributors to this repo.
+
+**How do I test if my SKILL.md change works?**
+Install the updated skill, start a fresh Claude Code session, and ask Claude to perform the git operation your change affects. There are no automated tests — verification is manual.
+
+**Why are there no automated tests?**
+The skill is a natural-language specification interpreted by an LLM. Traditional unit tests can't verify that Claude follows the rules correctly. The lint script validates structure, but behavioral testing requires a live Claude Code session.

README.md

@@ -2,7 +2,8 @@
 
 # Git Workflow — Claude Code Skill
 
-[![Version](https://img.shields.io/badge/version-1.3.0-blue.svg)](CHANGELOG.md)
+[![Lint](https://github.com/qubernetic-org/git-workflow-agent-skill/actions/workflows/lint.yml/badge.svg)](https://github.com/qubernetic-org/git-workflow-agent-skill/actions/workflows/lint.yml)
+[![Version](https://img.shields.io/badge/version-1.4.0-blue.svg)](CHANGELOG.md)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-skill-7c3aed.svg)](https://claude.ai/code)
 [![Conventional Commits](https://img.shields.io/badge/commits-conventional-fe5196.svg?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org)
@@ -11,7 +12,7 @@
 
 A Claude Code skill that enforces a disciplined Gitflow-based development workflow with conventional commits, semantic versioning, and issue-driven branching.
 
-[Installation](#installation) · [Usage](#usage) · [What It Enforces](#what-it-enforces) · [Contributing](CONTRIBUTING.md)
+[Installation](#installation) · [Usage](#usage) · [What It Enforces](#what-it-enforces) · [Contributing](CONTRIBUTING.md) · [Onboarding](ONBOARDING.md)
 
 </div>
 
@@ -180,9 +181,85 @@ feat!: drop support for Node 16
 
 See [SKILL.md](SKILL.md) for the full specification including commit types, breaking change conventions, versioning rules, release processes, and the complete forbidden operations list.
 
+## Why This Workflow?
+
+| Aspect | This Skill (Gitflow) | GitHub Flow | Trunk-Based |
+|--------|---------------------|-------------|-------------|
+| **Branches** | `main` + `develop` + typed branches | `main` + feature branches | `main` only |
+| **Releases** | Explicit release branches with version bump | Deploy from main on merge | Continuous deploy from main |
+| **Commit style** | Conventional Commits (enforced) | Free-form | Free-form |
+| **Merge strategy** | `--no-ff` merge commits (preserves topology) | Squash merge (flat history) | Squash or rebase |
+| **Traceability** | Issue → branch → PR → changelog | PR-based | Commit-based |
+| **Best for** | Versioned releases, libraries, skills, APIs | SaaS with continuous deploy | Small teams, rapid iteration |
+
+### When to use Gitflow
+
+- You ship **discrete versions** (v1.0, v1.1, v2.0) rather than continuous deploys
+- You need a **clear audit trail** from issue to release
+- Multiple features develop **in parallel** with different release timelines
+- You want **hotfix capability** without disrupting in-progress work
+
+### When NOT to use Gitflow
+
+- You deploy to production on every merge (GitHub Flow is simpler)
+- You have a single developer with no parallel work streams
+- Your project doesn't use semantic versioning
+
+## Integration with Git Hooks and CI Tools
+
+The skill enforces workflow rules through Claude Code, but you can add mechanical enforcement for your team with these tools:
+
+### Commit Message Validation (commitlint)
+
+```bash
+npm install --save-dev @commitlint/{cli,config-conventional}
+```
+
+```js
+// commitlint.config.js
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'type-enum': [2, 'always', [
+      'feat', 'fix', 'docs', 'chore', 'refactor',
+      'test', 'style', 'perf', 'ci', 'build', 'revert'
+    ]],
+    'subject-case': [2, 'always', 'lower-case'],
+    'subject-full-stop': [2, 'never', '.'],
+    'header-max-length': [2, 'always', 72],
+  },
+};
+```
+
+### Git Hooks (husky)
+
+```bash
+npm install --save-dev husky
+npx husky init
+echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg
+```
+
+### Branch Name Validation (CI)
+
+Add to your GitHub Actions workflow:
+
+```yaml
+- name: Validate branch name
+  if: github.event_name == 'pull_request'
+  run: |
+    BRANCH="${{ github.head_ref }}"
+    PATTERN="^(feature|fix|docs|hotfix|release)/[a-z0-9-]+$"
+    if [[ ! "$BRANCH" =~ $PATTERN ]]; then
+      echo "::error::Branch '$BRANCH' doesn't match pattern: $PATTERN"
+      exit 1
+    fi
+```
+
+> **Note:** These tools complement the skill — they catch mechanical errors (typos in commit types, wrong branch names) while Claude Code handles the higher-level workflow logic (correct base branch, issue traceability, release process).
+
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and [ONBOARDING.md](ONBOARDING.md) for a new contributor guide.
 
 ## License
 

SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: git-workflow
 description: "Enforce a strict Gitflow-based workflow with conventional commits, semantic versioning, and issue-driven branching. Use when the user asks to commit, create a branch, open a PR, tag a release, or perform any git operation. Also applies when mentions 'commit', 'branch', 'merge', 'release', 'hotfix', 'gitflow', 'conventional commit', 'semantic versioning', or 'semver'."
-version: 1.3.0
+version: 1.4.0
 license: MIT
 metadata:
   author: Qubernetic
-  version: 1.3.0
+  version: 1.4.0
 ---
 
 # Git Workflow Skill
@@ -225,7 +225,7 @@ jobs:
       pull-requests: read
     steps:
       - name: Close linked issues
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
@@ -603,3 +603,68 @@ git cherry-pick <commit-hash>
 ```
 
 > **Warning:** Cherry-picking duplicates commits. Prefer merging or back-merging when possible. Use cherry-pick only for isolated, urgent fixes.
+
+### "I created a branch from main instead of develop"
+
+```bash
+# If no commits yet — just recreate from the correct base
+git checkout develop
+git pull origin develop
+git checkout -b feature/<issue>-<slug>
+
+# If you already have commits — rebase them onto develop
+git rebase --onto develop main feature/<issue>-<slug>
+```
+
+### "My PR has merge conflicts"
+
+```bash
+# Merge the target branch into your feature branch
+git checkout feature/<issue>-<slug>
+git merge develop
+
+# Resolve conflicts in your editor, then:
+git add <resolved-files>
+git commit   # accept the merge commit message
+
+# Push the resolution
+git push origin feature/<issue>-<slug>
+```
+
+> **Note:** Never rebase a branch that's already pushed or has an open PR. Use merge to incorporate upstream changes.
+
+### "I accidentally deleted a branch before it was merged"
+
+```bash
+# Find the branch tip in reflog
+git reflog show --all | grep <branch-name>
+
+# Recreate the branch from the last known commit
+git checkout -b <branch-name> <commit-hash>
+git push -u origin <branch-name>
+```
+
+### "I committed secrets or credentials"
+
+```bash
+# Remove the file from history (requires git-filter-repo)
+git filter-repo --path <secret-file> --invert-paths
+
+# Force-push all affected branches (coordinate with team first)
+git push --force-with-lease origin <branch>
+```
+
+> **Critical:** After removing from git history, you must also:
+> 1. **Rotate the exposed credentials immediately** — assume they are compromised
+> 2. **Check GitHub's push protection** — enable secret scanning if not already active
+> 3. Force-push is normally forbidden, but this is a security exception
+
+### "I merged the wrong branch into develop or main"
+
+```bash
+# Revert the merge commit (use -m 1 to keep the mainline parent)
+git revert -m 1 <merge-commit-hash>
+git push origin <branch>
+```
+
+> **Note:** Reverting a merge makes Git think those changes were already applied. If you need to re-merge the branch later, you must first revert the revert.