Gitdoctor

gitdoctor

One-command Git Flow for AI coding agents (Claude Code, Cursor, and anything that can follow a markdown playbook and run bash). Classic git-flow model: `main` + `develop`, `feature/*`, `release/x.y.z`, `hotfix/x.y.z`, SemVer tags on main.

**One command each:** start/finish feature, release and hotfix branches; scan the repo for anomalies (doctor); verify alignment (main↔develop, local↔origin, version file↔tag); SemVer tagging + CHANGELOG + GitHub Release; and branch-protection-aware PR/local merging.

What's inside

Piece	Role
SKILL.md	Agent playbook: command routing, gates, dry-run contract, safety rails
scripts/gitflow-doctor.sh	The only executable: ~40 read-only checks + finish probes, JSON out
references/*.md	Choreographies (finish release/hotfix/feature, init/start), fix recipes, config schema
adapters/cursor/	Cursor /gitdoctor command wrapper
tests/	Fixture-based suite: every check has a scratch-repo test; probes and read-only guarantees included

Design principles:

• Deterministic checks, agent-driven mutations. The doctor never writes (one sanctioned git fetch); the agent performs merges/tags/pushes gated on the doctor's JSON.
• Idempotent finish. Every finish is a probe walk — rerun after any crash or CI wait and it continues from the first missing step. No state files as source of truth.
• Squash-aware. Content-equivalence via git merge-tree catches squash-merged branches that ancestry checks miss; gh (when available) is the authoritative tier.
• Protection-aware. mergeMode: auto resolves PR vs local merge per target branch from GitHub branch protection.

Install

Requirements: git ≥ 2.38 recommended (≥ 2.30 works with degraded conflict prediction), bash (Git Bash on Windows), optional `gh` (authenticated) for PR mode + GitHub checks. No jq needed.

Claude Code (user-level skill)

./install.sh            # or .\install.ps1 on Window