sorratheorc/git-management

Git Management Skill

Unified git management skill that orchestrates the full feature-branch lifecycle for AI agents and human operators.

Purpose

Provide a deterministic, safe, and auditable set of git operations covering the complete feature-branch lifecycle:

1. Branch creation — generate canonical branch names and create/check out branches.
2. Commit — stage changes and create conventional, Worklog-linked commit messages.
3. Push — push to remote with safety checks (no force-push, no direct-to-main).
4. PR creation — create GitHub Pull Requests from feature branches.
5. Merge — guarded merge with CI status verification.
6. Cleanup — post-merge branch pruning via existing cleanup infrastructure.
7. Workflow orchestration — single entry point for the full lifecycle.

When To Use

• An agent needs to create a feature branch from a work item.
• An agent needs to commit changes with proper formatting and work-item references.
• An agent needs to push to a remote branch with safety validation.
• An agent or operator needs to create a PR, merge it, and clean up.
• An agent or operator needs a single command to drive the full lifecycle.

Prerequisites

• git CLI installed and configured
• Node.js 18+ (for JavaScript scripts)
• gh CLI (for PR/merge operations — optional for push-only workflows)
• wl CLI (Worklog — for work-item context)

How Agents Invoke This Skill

/skill:git-management <action>

Where <action> is one of:

| Action | Description | |--------|-------------| | create-branch <work-item-id> <short-desc> | Create and check out a canonical feature branch | | commit --message <msg> --work-item <id> [--all] [--dry-run] | Stage and commit with conventional format | | push [--remote <name>] [--into-dev] [--dry-run] | Push current branch with safety checks | | create-pr [--base <branch>] [--title <title>] | Create a GitHub PR from the current branch | | merge-pr <pr-number> [--delete-source] | Merge an approved PR with CI checks | | cleanup [--dry-run] [--days <n>] | Post-merge branch pruning | | workflow <work-item-id> <short-desc> [--dry-run] [--phase <name>] | Full lifecycle orchestration | | help | Print this documentation |

Safety Constraints

Force-push prohibition

• No script in this skill performs force-push or history-rewrite operations.
• Any request for --force or equivalent is rejected with a non-zero exit status.

Protected branch protection

• Direct pushes to main, master, or HEAD are always rejected.
• Branch deletion of protected branches is always skipped.
• Use isBranchBlocked() from skill/ship/scripts/git-helpers.js for validation.

Branch naming

• All agent-created branches MUST follow wl-<work-item-id>-<short-desc>.
• Use makeBranchName() from skill/ship/scripts/git-helpers.js for generation.
• Use validateBranchName() for validation.

CI gate for merges

• merge-pr verifies CI/status checks before merging.
• Merges are skipped or fail if CI is pending or failing.

Script Contract

All scripts in skill/git-management/scripts/ follow these conventions:

Exit codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error (missing arguments, invalid state) | | 2 | Safety violation (protected branch, force-push request) | | 3 | Prerequisite not met (missing git, gh, wl, or dirty worktree) |

Output

• Human-readable: Progress messages, warnings, and errors go to stderr.
• Structured: When --json is passed, the primary result is JSON on stdout.
• JSON schema: All JSON output includes success (boolean), and on failure, error (string) and optionally code (exit code category).

Common flags

| Flag | Description | |------|-------------| | --dry-run | Validate and plan without mutating the repository | | --json | Output structured JSON instead of human-readable text | | --verbose | Include detailed debugging output | | --quiet | Suppress non-error output |

Prerequisite checks

Each script checks its prerequisites before performing operations:

• create-branch: requires git, valid work-item ID format
• commit: requires git, non-empty worktree changes (unless --all with no changes is allowed)
• push: requires git, valid branch name, remote configured
• create-pr: requires git, gh CLI, authenticated GitHub session
• merge-pr: requires git, gh CLI, valid PR number
• cleanup: requires git, access to cleanup infrastructure scripts
• workflow: requires all prerequisites for the phases it will execute

Delegation to Existing Infrastructure

This skill delegates to existing scripts where possible:

• Branch naming/policy: skill/ship/scripts/git-helpers.js (makeBranchName, validateBranchName, isBranchBlocked)
• Push validation: skill/ship/scripts/ship.js (validatePushTarget, validateForcePush, pushToDev, pushToBranch)
• Post-merge cleanup: skill/cleanup/scripts/ (Python cleanup scripts)

This skill does NOT duplicate the logic in these modules; it wraps and orchestrates them.

Scripts

| Script | Purpose | |--------|---------| | scripts/create-branch.mjs | Create and check out a canonical feature branch | | scripts/commit.mjs | Stage changes and commit with conventional format | | scripts/push.mjs | Push to remote with safety checks | | scripts/create-pr.mjs | Create a GitHub Pull Request | | scripts/merge-pr.mjs | Guarded merge with CI verification | | scripts/cleanup.mjs | Delegate to cleanup infrastructure | | scripts/workflow.mjs | Full lifecycle orchestration | | scripts/git-mgmt-helpers.mjs | Shared helpers for script I/O, argument parsing, and output formatting |

Integration with Agent Policies

• Patch agent (agent/patch.md): Respects the ask-first policy for push operations. The push script can be invoked in dry-run mode for review before execution.
• Ship agent (agent/ship.md): Provides scripted implementations of the branch/PR workflows described in the Ship agent documentation.