Agent Skills
› modu-ai/moai-adk
› moai-ref-git-workflow
moai-ref-git-workflow
GitHub提供Git工作流、分支策略、提交规范及PR模板参考，辅助Agent执行标准化的版本控制操作。
Trigger Scenarios
需要遵循特定Git分支策略
生成符合规范的Commit Message
创建或审查Pull Request
Install
npx skills add modu-ai/moai-adk --skill moai-ref-git-workflow -g -y
SKILL.md
Frontmatter
{
"name": "moai-ref-git-workflow",
"metadata": {
"tags": "git, branch, commit, pr, workflow, reference",
"status": "active",
"updated": "2026-03-30",
"version": "1.0.0",
"category": "workflow"
},
"description": "Git workflow patterns, branch strategies, conventional commits, and PR templates reference for git operations. Agent-extending skill that amplifies manager-git expertise with production-grade git workflow patterns. NOT for: code implementation, testing, architecture design, documentation content.\n",
"when_to_use": "Use for git workflow reference: branch strategies, conventional commits, PR templates, merge and rebase flows, and commit\/branch\/release conventions. Amplifies manager-git expertise with production-grade git workflow patterns.\n",
"user-invocable": false,
"progressive_disclosure": {
"enabled": true,
"level1_tokens": 100,
"level2_tokens": 3000
}
}
Git Workflow Reference
Target Agent
manager-git - Applies these patterns directly to git operations, branch management, and PR creation.
Branch Strategy Patterns
GitHub Flow (Default for Most Projects)
main ─────────────────────────────────────────
└── feat/SPEC-XXX-description ──── PR ──→ merge
Rules:
mainis always deployable- Feature branches from
main - PR required for all merges
- Delete branch after merge
GitFlow (Complex Release Cycles)
main ──────────────────────────────────────────
└── develop ─────────────────────────────────
├── feature/SPEC-XXX ──── PR ──→ develop
└── release/v1.2.0 ────── PR ──→ main + develop
Trunk-Based (CI/CD Heavy)
main ──────────────────────────────────────────
└── short-lived branch (< 1 day) ──→ merge
Branch Naming Convention
| Pattern | Example | Use Case |
|---|---|---|
feat/SPEC-{ID}-{slug} |
feat/SPEC-AUTH-001-jwt-auth |
New feature |
fix/SPEC-{ID}-{slug} |
fix/SPEC-BUG-042-null-check |
Bug fix |
refactor/{slug} |
refactor/extract-auth-middleware |
Refactoring |
docs/{slug} |
docs/api-reference-update |
Documentation |
chore/{slug} |
chore/upgrade-dependencies |
Maintenance |
Conventional Commits Reference
| Type | When | Example |
|---|---|---|
feat |
New feature | feat(auth): add JWT refresh token flow |
fix |
Bug fix | fix(api): handle null user in profile endpoint |
refactor |
Code restructure | refactor(db): extract query builder |
test |
Test changes | test(auth): add login edge case tests |
docs |
Documentation | docs(api): update endpoint descriptions |
chore |
Maintenance | chore(deps): upgrade Go to 1.23 |
perf |
Performance | perf(query): add index for user lookup |
style |
Formatting | style: apply gofmt formatting |
ci |
CI/CD changes | ci: add GitHub Actions workflow |
revert |
Revert commit | revert: undo feat(auth) commit abc123 |
Commit Message Structure
<type>(<scope>): <description> # max 72 chars
[optional body] # what and why, not how
[optional footer] # Breaking changes, issue refs
BREAKING CHANGE: <description>
Refs: #123, SPEC-AUTH-001
Pull Request Template
## Summary
- [1-3 bullet points describing what this PR does]
## Changes
- [ ] File 1: description of change
- [ ] File 2: description of change
## Test Plan
- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing completed
## SPEC Reference
- SPEC-{ID}: {title}
## Checklist
- [ ] Tests pass (`go test ./...`)
- [ ] Linting pass (`golangci-lint run`)
- [ ] No secrets committed
- [ ] Documentation updated if needed
Merge Strategy Selection
| Strategy | When | Command |
|---|---|---|
| Squash merge | Feature branches (clean history) | gh pr merge --squash |
| Merge commit | Release branches (preserve history) | gh pr merge --merge |
| Rebase | Small, clean commits | gh pr merge --rebase |
The active method for sync-phase PR auto-merge is governed by the git_strategy.<mode>.merge_method config value (squash | merge | rebase; default squash), not hardcoded. The sync agent resolves it from the active mode profile and renders the matching gh pr merge --<merge_method> command.
Git Safety Rules
| Action | Risk | Rule |
|---|---|---|
git push --force |
Overwrites remote | NEVER on main/master, ask user first |
git reset --hard |
Loses local changes | Confirm with user first |
git checkout . |
Discards changes | Confirm with user first |
git branch -D |
Deletes branch | Only after merge confirmed |
--no-verify |
Skips hooks | NEVER unless user explicitly requests |
git rebase -i |
Interactive (not supported) | NEVER use (requires interactive input) |
Context Memory in Commits
Embed decision context in commit messages for future session continuity:
feat(auth): implement JWT refresh token rotation
Decision: Chose rotation over sliding window for security
Pattern: Middleware chain: RateLimit -> Auth -> Authz -> Handler
Gotcha: Token blacklist requires Redis, not just in-memory cache
Refs: SPEC-AUTH-001
Common Rationalizations
| Rationalization | Reality |
|---|---|
| "I will clean up the commit messages before merging" | Interactive rebase is error-prone under pressure. Write clean commits from the start. |
| "Force push is fine on my feature branch" | Collaborators or CI may have fetched the branch. Force push destroys their reference. Use --force-with-lease. |
| "This commit is too small to need a conventional format" | Changelog generators, bisect, and blame all depend on consistent commit formats. Every commit matters. |
| "I will push directly to main, it is a small fix" | Direct pushes bypass code review and CI. Even small fixes can break production. |
| "Merge commits are messy, I always squash" | Squash loses individual commit context. Merge commits preserve the development narrative for future debugging. |
Red Flags
- Commit message does not follow conventional format (type(scope): description)
- Force push to main or shared release branch
- PR merged without CI passing
- Branch name does not indicate feature, fix, or SPEC reference
- Merge conflict markers found in committed files
Verification
- All commit messages follow conventional format (show git log --oneline)
- Branch name follows convention (feature/, fix/, chore/ prefix)
- No force pushes to main or protected branches (check reflog or CI)
- PR has passing CI checks before merge
- No merge conflict markers in committed files (grep for <<<<<<<)
- SPEC-ID referenced in commit message or PR description when applicable
Version History
- 4100d87 Current 2026-08-20 09:09
