Git Workflow Manager

Purpose

Handles all git operations following git-flow + GitHub-flow hybrid model.

Branch Structure

main                           ← Production (tagged vX.Y.Z)
  ↑
release/vX.Y.Z                ← Release candidate
  ↑
develop                        ← Integration branch
  ↑
contrib/<gh-user>             ← Personal contribution branch
  ↑
feature/<timestamp>_<slug>    ← Isolated feature (worktree)
hotfix/vX.Y.Z-hotfix.N       ← Production hotfix (worktree)

Protected Branch Policy

CRITICAL: This skill manages git operations and MUST enforce branch protection rules.

Protected branches (NEVER delete, NEVER commit directly):

• main - Production branch (tagged releases only)
• develop - Integration branch (PR merges only)

All scripts in this skill comply with:

1. No direct commits to main (except tag operations)
2. No direct commits to develop (except backmerge_release.py - documented exception)
3. All merges via pull requests (user merges in GitHub/Azure DevOps UI)

Exception documented:

• backmerge_release.py commits to develop during Phase 5.5 back-merge
• This is safe: merges from release branch only, no code changes, maintains history

Script validation:

• All scripts in scripts/ directory are validated for compliance
• Test: tests/test_branch_protection.py verifies no unintended main/develop commits
• See WORKFLOW.md "Branch Protection Policy" for complete rules

Scripts

create_worktree.py

Creates feature/release/hotfix worktree with TODO file.

python .claude/skills/git-workflow-manager/scripts/create_worktree.py \
  <feature|release|hotfix> <slug> <base_branch>

Arguments:

• workflow_type: feature, release, or hotfix
• slug: Short descriptive name (e.g., 'json-validator')
• base_branch: Branch to create from (e.g., 'contrib/username')

Output:

• Creates worktree directory
• Creates new branch
• Generates TODO file in main repo

daily_rebase.py

Performs daily rebase of contrib branch onto develop.

python .claude/skills/git-workflow-manager/scripts/daily_rebase.py \
  <contrib_branch>

Steps:

1. Checkout contrib branch
2. Fetch origin
3. Rebase onto origin/develop
4. Force push with lease

semantic_version.py

Calculates semantic version based on component changes.

python .claude/skills/git-workflow-manager/scripts/semantic_version.py \
  <base_branch> <current_version>

Version bump logic:

• MAJOR: Breaking changes (API changes, removed features)
• MINOR: New features (new files, new functions)
• PATCH: Bug fixes, refactoring, docs

create_release.py

Creates release branch from develop with TODO file generation.

python .claude/skills/git-workflow-manager/scripts/create_release.py \
  <version> <base_branch>

Arguments:

• version: Semantic version (e.g., v1.1.0, v2.0.0)
• base_branch: Branch to release from (typically 'develop')

Steps:

1. Validates version format and inputs
2. Checks semantic version recommendation
3. Creates release branch (release/vX.Y.Z)
4. Generates TODO_release_*.md file
5. Pushes branch to origin

Output:

✓ Created release branch: release/v1.1.0
✓ Base: develop (commit abc123)
✓ TODO file: TODO_release_20251023T143000Z_v1-1-0.md
✓ Ready for final QA and documentation updates

tag_release.py

Creates annotated tag on main branch after release merge.

python .claude/skills/git-workflow-manager/scripts/tag_release.py \
  <version> <branch>

Arguments:

• version: Semantic version to tag (e.g., v1.1.0)
• branch: Branch to tag (typically 'main')

Steps:

1. Validates version format and inputs
2. Checks out and pulls latest from branch
3. Creates annotated tag with release message
4. Pushes tag to origin
5. Optionally creates GitHub release via gh CLI

Output:

✓ Checked out main branch
✓ Pulled latest changes (commit def456)
✓ Created annotated tag: v1.1.0
  Message: "Release v1.1.0: Production release with vocabulary modules"
✓ Pushed tag to origin
✓ GitHub release created: https://github.com/user/german/releases/tag/v1.1.0

backmerge_release.py

Merges release branch back to develop after main merge.

python .claude/skills/git-workflow-manager/scripts/backmerge_release.py \
  <version> <target_branch>

Arguments:

• version: Release version (e.g., v1.1.0)
• target_branch: Branch to merge into (typically 'develop')

Steps:

1. Validates version and verifies tag exists
2. Checks out and pulls target branch
3. Attempts merge with --no-ff strategy
4. On success: pushes to remote
5. On conflicts: creates PR for manual resolution

Output (no conflicts):

✓ Checked out develop
✓ Pulled latest changes
✓ Merged release/v1.1.0 into develop (no conflicts)
✓ Pushed to origin/develop
✓ Back-merge complete

Output (with conflicts):

⚠ Merge conflicts detected
✓ Created PR: https://github.com/user/german/pull/46
  Title: "chore(release): back-merge v1.1.0 to develop"

Please resolve conflicts in GitHub UI and merge.

cleanup_release.py

Deletes release branch after successful release and back-merge.

python .claude/skills/git-workflow-manager/scripts/cleanup_release.py \
  <version>

Arguments:

• version: Release version (e.g., v1.1.0)

Safety Checks (all must pass):

1. Tag exists
2. Tag is on main branch
3. Release commits are in develop
4. Branch is fully merged

Steps:

1. Runs comprehensive safety checks
2. Deletes local release branch (git branch -d)
3. Deletes remote release branch
4. Archives TODO file

Output:

✓ Verified tag v1.1.0 exists
✓ Verified tag on main branch
✓ Verified back-merge to develop complete
✓ Deleted local branch: release/v1.1.0
✓ Deleted remote branch: origin/release/v1.1.0
✓ Archived: TODO_release_20251023T143000Z_v1-1-0.md
✓ Release workflow complete for v1.1.0

generate_work_items_from_pr.py

Generates work-items from unresolved PR conversations for tracking follow-up work.

python .claude/skills/git-workflow-manager/scripts/generate_work_items_from_pr.py \
  <pr_number>

Arguments:

• pr_number: Pull request number to analyze

Purpose:

• Extracts unresolved PR review conversations
• Creates separate work-items (GitHub issues or Azure DevOps tasks) for each conversation
• Enables PR approval while tracking feedback as separate feature work

When to use:

• After PR review, when conversations require follow-up work
• Before approving PR in web portal
• When feedback is substantive enough to warrant separate features

What it does:

1. Detects VCS provider (GitHub or Azure DevOps)
2. Fetches PR conversations/threads
3. Filters for unresolved conversations:
   • GitHub: reviewThreads.isResolved == false
   • Azure DevOps: threads.status == active|pending
4. For each unresolved conversation, creates work-item:
   • GitHub: gh issue create with label "pr-feedback"
   • Azure DevOps: az boards work-item create --type Task
5. Work-item slug pattern: pr-{pr_number}-issue-{sequence}
   • Example: pr-94-issue-1, pr-94-issue-2
6. Links work-item to original PR in title/body
7. Outputs work-item URLs for tracking

GitHub Integration:

• Uses GitHub GraphQL API for isResolved status
• Query: repository.pullRequest.reviewThreads
• Filters: isResolved: false, isOutdated: false
• Creates issues with:
  • Title: "PR #94 feedback: {first line of conversation}"
  • Body: Full conversation thread with file/line context
  • Labels: pr-feedback, pr-94
  • Metadata: Author, file path, line number, PR link

Azure DevOps Integration:

• Uses Azure CLI for thread enumeration
• Query: az repos pr show --id {pr} --query threads
• Filters: status == "active" || status == "pending"
• Creates work-items with:
  • Title: "PR #{pr} feedback: {thread subject}"
  • Description: Full thread content with file context
  • Type: Task
  • Tags: pr-feedback, pr-{pr_number}
  • Relations: Links to PR URL

Workflow Pattern:

# 1. Create PR from feature to contrib
gh pr create --base contrib/stharrold --head feature/20251108T112041Z_auth

# 2. Reviewers add comments in web portal

# 3. Generate work-items for unresolved conversations
python .claude/skills/git-workflow-manager/scripts/generate_work_items_from_pr.py 94

# Output:
# ✓ Found 3 unresolved conversations
# ✓ Created work-item: pr-94-issue-1 (https://github.com/user/repo/issues/123)
# ✓ Created work-item: pr-94-issue-2 (https://github.com/user/repo/issues/124)
# ✓ Created work-item: pr-94-issue-3 (https://github.com/user/repo/issues/125)

# 4. Approve PR in web portal (conversations remain as work-items)

# 5. For each work-item, create new feature worktree:
python .claude/skills/git-workflow-manager/scripts/create_worktree.py \
  feature pr-94-issue-1 contrib/stharrold

# 6. Implement fix, create PR, merge
# 7. Repeat for remaining work-items

Key Features:

• Compatible with all issue trackers (GitHub Issues, Azure DevOps Work Items)
• Preserves conversation context (file, line, author, timestamps)
• Enables PR approval without blocking on follow-up work
• Creates traceable lineage: PR → work-items → feature branches → new PRs
• Supports both GitHub and Azure DevOps workflows

Decision Tree:

PR reviewed with comments
├─ Simple fixes (typos, formatting)
│  └─ Fix directly on feature branch, push update
└─ Substantive changes (new features, refactoring)
   └─ Generate work-items, approve PR, fix in separate features

Release Workflow

The release workflow implements Phase 5 from WORKFLOW.md, providing a complete automation of git-flow release process.

When to Use Release Workflow

Use release workflow when:

• Ready to create production release from develop
• All features for version are integrated and tested
• Quality gates pass on develop branch
• Following semantic versioning for the release

Use hotfix workflow when:

• Critical production bug needs immediate fix
• Cannot wait for regular release cycle
• Fix targets specific production version

Typical Release Sequence

# Step 1: Create release branch from develop
python .claude/skills/git-workflow-manager/scripts/create_release.py \
  v1.1.0 develop

# Step 2: Perform QA on release branch
# - Run quality gates
# - Update documentation
# - Update version in pyproject.toml

# Step 3: Create PR: release/v1.1.0 → main
gh pr create --base main --title "Release v1.1.0"

# Step 4: User merges PR in GitHub UI
# (Manual step - review and merge)

# Step 5: Tag release on main
python .claude/skills/git-workflow-manager/scripts/tag_release.py \
  v1.1.0 main

# Step 6: Back-merge to develop
python .claude/skills/git-workflow-manager/scripts/backmerge_release.py \
  v1.1.0 develop

# Step 7: Cleanup release branch
python .claude/skills/git-workflow-manager/scripts/cleanup_release.py \
  v1.1.0

# Step 8: Update contrib branch
python .claude/skills/git-workflow-manager/scripts/daily_rebase.py \
  contrib/<gh-user>

Integration with Phase 5

The release scripts implement the 8-step process documented in WORKFLOW.md Phase 5:

Step	Script	Description
5.1	create_release.py	Create release branch
5.2	Manual	QA and documentation updates
5.3	gh pr create	Create PR to main
5.4	Manual	User merges in GitHub UI
5.5	tag_release.py	Tag release on main
5.6	backmerge_release.py	Back-merge to develop
5.7	cleanup_release.py	Delete release branch
5.8	daily_rebase.py	Update contrib branch

Error Recovery

If a release workflow step fails:

1. create_release.py fails: Branch and TODO file are cleaned up automatically
2. tag_release.py fails: Local tag is cleaned up on push failure
3. backmerge_release.py conflicts: PR is created for manual resolution
4. cleanup_release.py safety checks fail: Branch is NOT deleted, manual cleanup required

All scripts include comprehensive error messages with recovery instructions.

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Types: feat, fix, docs, style, refactor, test, chore

Example:

feat(validator): add JSON schema validation endpoint

Implements REST API endpoint for validating JSON against schemas.
Uses jsonschema library for validation logic.

Implements: impl_003
Spec: specs/json-validator/spec.md
Tests: tests/test_validator.py
Coverage: 85%

Refs: TODO_feature_20251022T143022Z_json-validator.md

PR Creation

# Feature → contrib/<gh-user>
gh pr create \
  --base "contrib/<gh-user>" \
  --head "<feature-branch>" \
  --title "feat: <description>" \
  --body "See TODO_feature_*.md for details"

# After user merges in GitHub UI:
# Contrib → develop
gh pr create \
  --base "develop" \
  --head "contrib/<gh-user>" \
  --title "feat: <description>" \
  --body "Completed feature: <name>"

Integration with Other Skills

Other skills call these scripts:

import subprocess

# Create worktree
result = subprocess.run([
    'python',
    '.claude/skills/git-workflow-manager/scripts/create_worktree.py',
    'feature', 'my-feature', 'contrib/user'
], capture_output=True, text=True)

# Calculate version
result = subprocess.run([
    'python',
    '.claude/skills/git-workflow-manager/scripts/semantic_version.py',
    'develop', 'v1.0.0'
], capture_output=True, text=True)

new_version = result.stdout.strip()