name: git
description: Generic git operations for any GitHub repositories - commit, push, pull, PR creation with GitHub CLI integration
agent: engineer
version: 2.0
classification: public
last_updated: 2026-01-26
effort_default: QUICK
env_required: true

⛔ DUAL-PATH ROUTING - READ THIS FIRST

STOP. This skill requires the engineer agent for complex requests.

Identity check: If you are NOT the engineer agent AND your request is complex
(CI/CD setup, multi-repo workflows, infrastructure decisions) → DELEGATE NOW:

typescript Task(subagent_type="engineer", prompt="Execute git skill. Request: {user_request}")

DO NOT proceed if you lack engineer expertise for:
- CI/CD workflow design
- Multi-repository coordination
- Infrastructure decision-making
- Complex git workflows

Path 1 - Simple (Tier 1/Haiku): Basic operations
- "Commit these changes"
- "Push to remote"
- Routes directly, no delegation needed

Path 2 - Complex (Engineer): Infrastructure workflows
- "Set up CI/CD workflow"
- "Create PR with automated testing"
- Requires engineer delegation

Git Skill

Generic git operations for any GitHub repositories you control.

Works with any git repository configured via environment variables. No framework-specific requirements (except /framework-update which is optional).

Environment Setup

The Git Skill requires GitHub authentication and repository configuration. Use the interactive setup wizard to configure everything automatically.

Automated Setup (Recommended)

bun skills/git/scripts/setup.ts

The setup wizard will:
- ✅ Verify git is installed
- ✅ Install gh CLI (GitHub CLI) if needed
- ✅ Authenticate with GitHub (if not already)
- ✅ Generate GitHub personal access token
- ✅ Configure .env with required keys
- ✅ Validate repository paths
- ✅ Test connectivity

What You Need Before Running Setup:
1. Git installed - Check: git --version
2. GitHub account - Go to https://github.com/ if you don't have one
3. Repository access - You own or have push access to the repo

Prerequisites Checklist

• [ ] Git is installed (git --version works)
• [ ] You have a GitHub account
• [ ] You have push access to your repositories
• [ ] You know the local path to your repository(ies)

Setup Commands

# Full interactive setup
bun skills/git/scripts/setup.ts

# Just validate existing setup
bun skills/git/scripts/setup.ts validate

# Test GitHub and Git connectivity
bun skills/git/scripts/setup.ts test

Manual Configuration (Advanced)

If you prefer to configure manually:

1. Create GitHub personal access token
2. Go to https://github.com/settings/tokens/new
3. Create classic token (not fine-grained)
4. Scopes needed: repo (full control of repositories)

5. Save token (you can't view it again)

6. Install gh CLI (optional but recommended)
   ```bash
   # macOS
   brew install gh

# Ubuntu/Debian
sudo apt update && sudo apt install gh

# Windows
choco install gh

# Or visit: https://cli.github.com/
```

1. Configure .env file
   ```bash
   # Copy example
   cp ~/.claude/.env.example ~/.claude/.env

# Edit and add:
GITHUB_TOKEN=[insert_key]
GIT_PUSH_REPO_PATH=/path/to/your/private/repo
GIT_PUSH_REMOTE=origin
GIT_PUSH_BRANCH=main

# For public repo sync (optional):
GIT_PUBLIC_REPO_PATH=/path/to/your/public/repo
```

1. Verify configuration
   ```bash
   # Check token is readable
   echo $GITHUB_TOKEN

# Check repos exist and are git repos
cd $GIT_PUSH_REPO_PATH && git remote -v
```

Quick Start

1. Run setup wizard:
   bash bun skills/git/scripts/setup.ts

2. Test your configuration:
   bash /git-push # Commit + push to private repo /git-public # Sync to public repo (triple verification) /git-pull # Pull latest from private repo /framework-update # Update IA Framework (optional, framework users only)

Configuration

All repositories are configured via environment variables (.env file).

Required for all operations:
- GITHUB_TOKEN - Your GitHub personal access token

For private repo operations (/git-push, /git-pull):
- GIT_PUSH_REPO_PATH - Path to your private repository
- GIT_PUSH_REMOTE - Remote name (default: origin)
- GIT_PUSH_BRANCH - Branch name (default: main)

For public repo operations (/git-public):
- GIT_PUBLIC_REPO_PATH - Path to your public repository
- GIT_PUBLIC_REMOTE - Remote name (default: origin)
- GIT_PUBLIC_BRANCH - Branch name (default: main)

For framework operations (/framework-update):
- GIT_FRAMEWORK_REPO_PATH - Path to your local IA Framework clone

Commands

How Each Command Works

/git-push (Private Repo)

1. Pre-flight safety checks (verify repo & branch)
2. Pre-sync cleanup (removes debug/, sessions/, cache)
3. Security scan (blocks if credentials detected)
4. Documentation audit (informational)
5. Session state update
6. Stage changes (git add -A)
7. Generate commit message
8. Commit changes
9. Push to remote
10. Confirm success

/git-public (Public Repo)

Same as /git-push, plus:
- Triple verification before push (mandatory)
- Collects only approved public files
- Removes orphans (cleanup)
- Blocks on security findings (no override)

/git-pull (Private Repo)

1. Pre-flight checks
2. Fetch from remote
3. Rebase on origin (non-destructive)
4. Verify merge conflicts
5. Update session state
6. Confirm success

/framework-update (IA Framework)

For users who cloned the IA Framework locally:
- Fetches latest from upstream (public ia-framework)
- Analyzes differences from your customizations
- Presents smart merge options
- Preserves your custom skills and settings
- Creates backups before updating

Directory Structure

skills/git/
├── SKILL.md                      # This file - complete documentation
├── README.md                     # Quick reference guide
├── STATUS.md                     # Skill status and release readiness
├── VERIFY.md                     # Verification checklist
├── scripts/
│   ├── setup.ts                  # 🆕 Interactive setup wizard
│   ├── push/
│   │   ├── index.ts              # Main push orchestrator
│   │   ├── cleanup.ts            # Pre-push cleanup
│   │   ├── security-scan.ts      # Credential detection
│   │   ├── audit-documentation.ts # Documentation verification
│   │   └── update-session.ts     # Session state update
│   ├── public/
│   │   ├── index.ts              # Main public sync orchestrator
│   │   ├── collect-public-files.ts # Smart file collection
│   │   ├── clean-orphans.ts      # Orphan file cleanup
│   │   └── security-scan.ts      # Credential detection
│   └── pull/
│       └── index.ts              # Main pull orchestrator
├── .env.example                  # Configuration template
├── commands/                     # Symlinked to /commands/
│   ├── git-push.md               # Commit + push to private repo
│   ├── git-public.md             # Sync to public repo
│   ├── git-pull.md               # Pull from private repo
│   └── framework-update.md       # Update IA Framework (optional)
├── workflows/
│   ├── private-push.md           # 10-step workflow for private repo
│   ├── public-push.md            # 10-step workflow for public repo
│   └── pull.md                   # 5-step workflow for pulling
├── docs/                         # Domain knowledge & reference materials
├── templates/                    # Output templates for results
└── .env.example                  # Configuration template

Safety & Security

Before Any Operation:
- Pre-flight checks verify correct repository
- Branch verification (warns if not on main)
- Remote URL validation

During Operations:
- Security scan blocks commits with credentials
- Pre-commit hooks enforce additional validation
- No force push (requires manual intervention)
- Cleanup removes sensitive directories before commit

For Public Sync:
- Triple verification (3 manual confirmations in interactive mode)
- Credential scanning (blocking, no override)
- File collection based on manifest or safe defaults
- Orphan cleanup (removes files that shouldn't be public)

File Collection for Public Repo

If .framework-manifest.yaml exists (framework users):
- Uses manifest as source of truth
- Includes framework sections
- Excludes instance/private sections
- Enforces security patterns

If no manifest (generic users):
- Uses default safe patterns:
- Includes: commands/, agents/, skills/, library/, docs/, README.md, LICENSE
- Excludes: sessions/, .env*, debug/, cache directories
- Customizable via GIT_PUBLIC_FILES_PATTERN env var

Version: 2.1
Last Updated: 2026-01-18
Classification: Public
Status: Fully Generic