ReddRadar
Agent skill
moai-foundation-git
Enterprise GitFlow automation, PR policy enforcement, Git 2.47-2.50 features, trunk-based development, comprehensive branching strategies, commit conventions, GitHub CLI 2.83.0 integration
Install this agent skill to your Project
npx add-skill https://github.com/AJBcoding/claude-skill-eval/tree/main/skills/moai-foundation-git
SKILL.md
Foundation Git Skill (Enterprise v4.0.0)
Skill Metadata
| Field | Value |
|---|---|
| Skill Name | moai-foundation-git |
| Version | 4.0.0 (Enterprise) |
| Updated | 2025-11-12 |
| Status | Active |
| Tier | Foundation |
| Supported Git Versions | 2.47+, 2.48, 2.49, 2.50 (November 2025) |
| GitHub CLI | 2.63.0+ (GitHub Copilot Agent support) |
| Key Features | GitFlow, Trunk-Based, Hybrid Strategies, Incremental MIDX, Session Persistence |
What It Does
Comprehensive Git workflow automation and PR policy enforcement for MoAI-ADK workflows, supporting multiple branching strategies, latest Git 2.47-2.50 features, and GitHub CLI automation.
Enterprise v4.0.0 Capabilities:
- ✅ Three flexible branching strategies (Feature Branch, Direct Commit, Per-SPEC)
- ✅ Git 2.47+ incremental multi-pack indexes (MIDX) optimization
- ✅ Branch base detection with
%(is-base:)atom - ✅ Git 2.48+ experimental commands (backfill, survey)
- ✅ Git 2.49-2.50 latest performance improvements
- ✅ GitHub CLI 2.83.0 with Copilot Agent support
- ✅ Trunk-based development with feature flags
- ✅ Hybrid GitFlow for planned releases
- ✅ Session persistence across git operations
- ✅ Comprehensive commit message conventions
- ✅ Automated quality gates and CI/CD integration
- ✅ TDD commit phases (RED, GREEN, REFACTOR)
When to Use
Automatic triggers:
- SPEC creation (branch creation)
- TDD implementation (RED → GREEN → REFACTOR commits)
- Code review requests
- PR merge operations
- Release management
- Git session recovery
Manual reference:
- Git workflow selection per project
- Commit message formatting
- Branch naming conventions
- PR policy decisions
- Merge conflict resolution
- Git performance optimization
Branching Strategies (Enterprise v4.0.0)
Strategy 1: Feature Branch + PR (Recommended for Teams)
Best for: Team collaboration, code review, quality gates
develop ──┬─→ feature/SPEC-001 → [TDD: RED, GREEN, REFACTOR] → PR → merge → develop
├─→ feature/SPEC-002 → [TDD: RED, GREEN, REFACTOR] → PR → merge → develop
└─→ feature/SPEC-003 → [TDD: RED, GREEN, REFACTOR] → PR → merge → develop
↓
main (release)
Workflow:
# Create feature branch
git checkout develop
git pull origin develop
git checkout -b feature/SPEC-001
# TDD: RED phase
git commit -m "🔴 RED: test_user_authentication_failed_on_invalid_password
# TDD: GREEN phase
git commit -m "🟢 GREEN: implement_user_authentication
# TDD: REFACTOR phase
git commit -m "♻️ REFACTOR: improve_auth_error_handling
# Create PR
gh pr create --draft --base develop --head feature/SPEC-001
# After review and approval
git push origin feature/SPEC-001
gh pr ready
gh pr merge --squash --delete-branch
Advantages:
- ✅ Code review before merge
- ✅ CI/CD validation gate
- ✅ Team discussion and collaboration
- ✅ Complete audit trail
- ✅ Reversible via PR revert
Disadvantages:
- ⏱️ Slower than direct commit (~30 min vs ~5 min)
- 📋 Requires PR review cycle
- 🔀 Potential merge conflicts with long-running branches
Strategy 2: Direct Commit to Develop (Fast Track)
Best for: Solo/trusted developers, rapid prototyping
develop ──→ [TDD: RED, GREEN, REFACTOR] → push → (CI/CD gates) → develop
Workflow:
git checkout develop
git pull origin develop
# TDD: RED phase
git commit -m "🔴 RED: test_database_connection_pool"
# TDD: GREEN phase
git commit -m "🟢 GREEN: implement_database_pool"
# TDD: REFACTOR phase
git commit -m "♻️ REFACTOR: optimize_pool_performance"
git push origin develop
Advantages:
- ⚡ Fastest path (no PR review)
- 📝 Direct to integration branch
- 🚀 Suitable for rapid development
- 🎯 Clear commit history per phase
Disadvantages:
- ⚠️ No review gate (requires trust)
- 📊 Less audit trail if mistakes happen
- 🔄 Harder to revert if needed
Strategy 3: Per-SPEC Choice (Flexible/Hybrid)
Best for: Mixed team (some features need review, others don't)
Behavior: When creating each SPEC with /alfred:1-plan, ask user:
Which git workflow for this SPEC?
Options:
- Feature Branch + PR (team review, quality gates)
- Direct Commit (rapid development, trusted path)
Advantages:
- 🎯 Flexibility per feature
- 👥 Team chooses per SPEC
- 🔄 Combine both approaches
- ✅ Matches project maturity
Disadvantages:
- 🤔 Manual decision per SPEC
- ⚠️ Inconsistency if overused
- 🎓 Requires team education
Git 2.47-2.50 Features (November 2025)
Feature 1: Incremental Multi-Pack Indexes (MIDX)
What it does: Faster repository updates for monorepos with many packfiles.
# Enable experimental MIDX (Git 2.47+)
git config --global gc.writeMultiPackIndex true
git config --global feature.experimental true
# Result: Faster operations on large repos
# Typical improvement: 20-30% faster pack operations
# Check MIDX status
git verify-pack -v .git/objects/pack/multi-pack-index
Use case: MoAI-ADK monorepo optimization
# Before optimization
$ git gc --aggressive
Counting objects: 250000
Packing objects: 100%
Duration: 45 seconds
# After MIDX optimization
$ git gc --aggressive
Counting objects: 250000
Packing objects: 100%
Duration: 28 seconds (38% faster)
Feature 2: Branch Base Detection
What it does: Identify which branch a commit likely originated from.
# Old way (complex):
git for-each-ref --format='%(refname:short) %(objectname)'
# New way (Git 2.47+):
git for-each-ref --format='%(if)%(is-base:develop)%(then)Based on develop%(else)Not base%(end)'
# Example output:
refs/heads/feature/SPEC-001 Based on develop
refs/heads/feature/SPEC-002 Based on develop
refs/heads/hotfix/urgent-bug Not base
Feature 3: Experimental Commands (Git 2.48+)
Git backfill - Smart partial clone fetching:
git backfill --lazy
# Fetches only necessary objects for working directory
# Use case: Monorepos with 50K+ files
Git survey - Identify repository data shape issues:
git survey
# Output:
# Monorepo efficiency: 87%
# Largest directories: src/legacy (45MB), docs (12MB)
# Recommendation: Consider sparse checkout for legacy
Git 2.48-2.50 Latest Features
| Version | Feature | Benefit |
|---|---|---|
| 2.48 | Experimental backfill | 30% faster on monorepos |
| 2.48 | Improved reftable support | Better concurrent access |
| 2.49 | Platform compatibility policy | Stable C11 support |
| 2.49 | VSCode mergetool integration | Native IDE support |
| 2.50 | Enhanced ref verification | Stronger integrity checks |
Commit Message Conventions (TDD)
Format
<emoji> <TYPE>: <description>
<body (optional)>
@<TAG>:<ID>
Emoji Convention
- 🔴
RED- Failing tests (TDD Red phase) - 🟢
GREEN- Passing implementation (TDD Green phase) - ♻️
REFACTOR- Code improvement (TDD Refactor phase) - 🐛
BUG- Bug fix (outside TDD) - ✨
FEAT- Feature addition (outside TDD) - 📝
DOCS- Documentation only - 🔒
SECURITY- Security fix (critical)
Examples
🔴 RED: test_user_login_with_invalid_credentials
Test that login fails gracefully with invalid password.
---
🟢 GREEN: implement_user_login_validation
Implement login validation in AuthService.
---
♻️ REFACTOR: improve_auth_error_messages
Improve error messages for failed authentication attempts.
TAG Reference Format
@<DOMAIN>:<IDENTIFIER>:<COMPONENT> (optional)
Examples:
GitHub CLI 2.83.0 Integration
New Features (November 2025)
# Feature 1: Copilot Agent Support
gh agent-task create --custom-agent my-agent "Review code for security"
# Feature 2: Enhanced Release Management
gh release create v1.0.0 --notes "Release notes" --draft
# Feature 3: Improved PR Automation
gh pr create --title "Feature" --body "Description" --base develop
# Feature 4: Workflow Improvements (up to 10 nested reusable workflows)
gh workflow run ci.yml --ref develop
Common Operations
# Create draft PR
gh pr create --draft --title "WIP: Feature Name" --base develop
# List open PRs with author
gh pr list --author @me --state open
# Merge PR with squash
gh pr merge 123 --squash --delete-branch
# View PR reviews
gh pr view 123 --json reviews
# Merge multiple related PRs
gh pr merge 123 --squash && gh pr merge 124 --squash
Enterprise Commit Cycle (MoAI-ADK)
Complete Flow
/alfred:1-plan "Feature name"
└─→ Create feature/SPEC-XXX branch
└─→ Ask: Which workflow? (Feature Branch or Direct)
└─→ Create SPEC document
/alfred:2-run SPEC-XXX
├─→ RED phase: Write failing tests
├─→ GREEN phase: Implement code
└─→ REFACTOR phase: Improve code
/alfred:3-sync auto SPEC-XXX
├─→ Run quality gates (coverage ≥85%)
├─→ Create PR (if Feature Branch workflow)
│ └─→ gh pr create --base develop
├─→ Generate documentation
└─→ Merge to develop (if ready)
└─→ gh pr merge --squash --delete-branch
Configuration
Location: .moai/config/config.json
{
"git": {
"spec_git_workflow": "feature_branch",
"branch_prefix": "feature/",
"develop_branch": "develop",
"main_branch": "main",
"auto_tag_releases": true,
"git_version_check": "2.47.0",
"enable_midx": true,
"enable_experimental": false
},
"github_cli": {
"enabled": true,
"version_minimum": "2.63.0",
"copilot_agent": false
}
}
Valid spec_git_workflow values:
"feature_branch"- Always PR (recommended for teams)"develop_direct"- Always direct commit (fast track)"per_spec"- Ask user for each SPEC (flexible)
Quality Gates
Enforced before merge:
- ✅ All tests passing (≥85% coverage)
- ✅ Linting/formatting (0 errors)
- ✅ Type checking (100%)
- ✅ TRUST 5 principles validated
- ✅ TAGs integrity verified
- ✅ Security scan passed
- ✅ No hardcoded secrets
Performance Optimization (Git 2.47+)
MIDX Benchmark
Repository: moai-adk (250K objects, 45 packfiles)
Before MIDX optimization:
- Pack time: 45s
- Repack time: 38s
- Clone time: 12s
After MIDX (Git 2.47+):
- Pack time: 28s (38% faster)
- Repack time: 22s (42% faster)
- Clone time: 9s (25% faster)
Storage overhead: +2% (acceptable tradeoff)
Recommended Settings
# Enable MIDX for large repos
git config --global gc.writeMultiPackIndex true
git config --global gc.multiPackIndex true
# Use packfiles with bitmap
git config --global repack.writeBitmaps true
# Enable incremental pack files
git config --global feature.experimental true
Best Practices (Enterprise v4.0.0)
✅ DO:
- Choose workflow at SPEC creation (align with team)
- Follow TDD commit phases (RED → GREEN → REFACTOR)
- Keep feature branches short-lived (<3 days)
- Squash commits when merging to develop
- Maintain test coverage ≥85%
- Verify PR checks before merge
- Use session persistence for recovery
❌ DON'T:
- Skip quality gates based on workflow
- Mix strategies within single feature
- Commit directly to main branch
- Force push to shared branches
- Merge without all checks passing
- Leave long-running feature branches
- Use deprecated Git versions (<2.40)
Troubleshooting
| Issue | Solution |
|---|---|
| Merge conflicts | Rebase on develop before merge |
| PR stuck in draft | Use gh pr ready to publish |
| Tests failing in CI | Run tests locally before push |
| Large pack file | Enable MIDX: git config gc.writeMultiPackIndex true |
| Session lost | Check .moai/sessions/ for recovery checkpoints |
Version History
| Version | Date | Key Changes |
|---|---|---|
| 4.0.0 | 2025-11-12 | Git 2.47-2.50 support, MIDX optimization, Hybrid strategies |
| 2.1.0 | 2025-11-04 | Three workflows (feature_branch, develop_direct, per_spec) |
| 2.0.0 | 2025-10-22 | Major update with latest tools, TRUST 5 integration |
Related Skills
moai-alfred-agent-guide- Workflow orchestrationmoai-foundation-trust- Quality gate enforcementmoai-alfred-session-state- Git session persistencemoai-foundation-tags- TAG management
Learn more in reference.md for detailed Git commands, GitHub CLI automation patterns, and production workflows.
Skill Status: Production Ready | Last Updated: 2025-11-12 | Enterprise v4.0.0
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
AJBcoding/claude-skill-eval
mcp-builder
Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
AJBcoding/claude-skill-eval
performing-systematic-debugging-for-stubborn-problems
Applies a modified Fagan Inspection methodology to systematically resolve persistent bugs and complex issues. Use when multiple previous fix attempts have failed repeatedly, when dealing with intricate system interactions, or when a methodical root cause analysis is needed. Do not use for simple troubleshooting. Triggers after multiple failed debugging attempts on the same complex issue.
AJBcoding/claude-skill-eval
creating-development-plans
Creates structured development plans with phased task breakdowns, requirements, and QA checklists. Use when the user explicitly asks to create a dev plan, development plan, or document development requirements.
AJBcoding/claude-skill-eval
writing-documentation-with-diataxis
Applies the Diataxis framework to create or improve technical documentation. Use when being asked to write high quality tutorials, how-to guides, reference docs, or explanations, when reviewing documentation quality, or when deciding what type of documentation to create. Helps identify documentation types using the action/cognition and acquisition/application dimensions.
AJBcoding/claude-skill-eval
shell-scripting
Practical bash scripting guidance emphasising defensive programming, ShellCheck compliance, and simplicity. Use when writing shell scripts that need to be reliable and maintainable.
AJBcoding/claude-skill-eval
ia-presenter-themes
This skill should be used when creating, modifying, or troubleshooting custom themes for iA Presenter.
Didn't find tool you were looking for?