SuperAPI AI Directory

git-precommit

General & other

View repository

Updated 10-16 09:44

About this skill

Pre-Git commit workflow (orchestrator)

Description

Coordinate multiple Skills to complete all preparation work before Git commit. This project simultaneously uses pre-commit framework to automatically run code quality checks, and AI orchestrator to handle documentation synchronization.

🔄 Self-Evolution Cycle

This project's quality gate is a self-evolving closed-loop system:

┌─────────────────────────────────────────────────────────────┐
│                自演化循環 (Self-Evolution Cycle)          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ① Instructions (copilot-instructions.md)                   │
│       │ 定義規範、引導 AI 使用 Skills                       │
│       ▼                                                      │
│  ② Skills (SKILL.md 檔案)                                   │
│       │ 確保建構完整、創建新 Hook                          │
│       ▼                                                      │
│  ③ Hooks (.pre-commit-config.yaml + scripts/hooks/)         │
│       │ 自動執行檢查、自動修正                            │
│       ▼                                                      │
│  ④ Validate (check_evolution_cycle.py)                       │
│       │ 驗證 ①②③ 的一致性                                  │
│       ▼                                                      │
│  ⑤ Feedback → 更新 Instructions & Skills                     │
│       │ 處理驗證失敗、補齊文檔、更新套件版本                │
│       └────→ 回到 ①(循環完成)                            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Cycle trigger timing

Event Trigger action
Add Hook Skill creation hook → evolution-cycle verifies whether documentation and instruction are synchronized
Modify Instruction evolution-cycle verifies whether skill/hook are still consistent
pre-commit autoupdate Package version update → auto-evolution
Verification failure Report inconsistencies; commit is only allowed after forced fixes

Architecture: Dual-layer protection + self-evolution

┌─────────────────────────────────────────────────────────────┐
│                   Git Commit 防護架構                        │
├──────────────────────┬──────────────────────────────────────┤
│  Layer 1: 自動化     │  Layer 2: AI 編排器                   │
│  (pre-commit hooks)  │  (agent orchestrator)                │
├──────────────────────┼──────────────────────────────────────┤
│  ✅ ruff + ruff-format│  ✅ Memory Bank 同步                  │
│  ✅ bandit security  │  ✅ CHANGELOG 更新                    │
│  ✅ vulture deadcode │  ✅ ROADMAP 更新                      │
│  ✅ deptry deps      │  ✅ README 更新                       │
│  ✅ file-hygiene     │  ✅ 架構文檔檢查                      │
│  ✅ commit-size-guard│  ✅ Commit 訊息建議                   │
│  ✅ file-hygiene     │                                      │
│  ✅ commit-size-guard│                                      │
│  ✅ async-test-checker│                                      │
│  ✅ tool-count-sync  │                                      │
│  ✅ skills-frontmatter│                                     │
│  ✅ evolution-cycle  │                                      │
│  ✅ future-annotations│                                      │
│  ✅ no-print-in-src  │                                      │
│  ✅ ddd-layer-imports│                                      │
│  ✅ no-type-ignore-bare│                                    │
│  ✅ docstring-tools  │                                      │
│  ✅ no-env-inner-layers│                                    │
│  ✅ source-counts-guard│                                    │
│  ✅ todo-scanner     │                                      │
│  ✅ instruction-drift│                                      │
│  ✅ yaml/toml/json   │                                      │
│  ✅ no large files   │                                      │
│  ✅ no debug stmts   │                                      │
│  ✅ no private keys  │                                      │
│  ✅ BOM / symlinks   │                                      │
│  ✅ case conflicts   │                                      │
│  ✅ Windows names    │                                      │
│  ✅ mixed line ending│                                      │
│  ✅ no-commit-to-branch│                                    │
│  ✅ name-tests-test  │                                      │
│ ── Pre-push ──────── │                                      │
│  ✅ mypy (pre-push)  │                                      │
│  ✅ semgrep (pre-push)│                                     │
│  ✅ pytest (pre-push) │                                     │
├──────────────────────┼──────────────────────────────────────┤
│  🔧 自動修復:       │  🔧 自動修復:                        │
│  trailing whitespace │  tool-count-sync (auto-stage)        │
│  end-of-file newline │                                      │
│  ruff --fix          │                                      │
│  ruff format         │                                      │
│  future-annotations  │                                      │
└──────────────────────┴──────────────────────────────────────┘

Developer setup (one-time)

uv sync                                         # 安裝所有依賴 (含 pre-commit)
uv run pre-commit install                       # 安裝 pre-commit hook
uv run pre-commit install --hook-type pre-push  # 安裝 pre-push hook (跑測試)

Hook auto-evolution (Auto-Evolution)

Package version update

uv run pre-commit autoupdate                   # 更新所有 hook 版本 (ruff, pre-commit-hooks 等)
uv run pre-commit run --all-files              # 驗證更新後所有 hook 正常

Cycle consistency verification

uv run python scripts/hooks/check_evolution_cycle.py  # 手動執行一致性檢查

This script verifies:

  • All hook IDs are documented in instruction and skill
  • The script files referenced by all hooks exist
  • The hook table in CONTRIBUTING.md is consistent with .pre-commit-config.yaml
  • addopts in pyproject.toml enforces multi-core
  • Skill documentation references the correct hook infrastructure

Complete process for adding a Hook

When a hook needs to be added, the entire cycle must be completed:

  1. Create hook script → scripts/hooks/<name>.py
  2. Register in .pre-commit-config.yaml → add hook definition
  3. Update copilot-instructions.md → Pre-commit Hooks section
  4. Update this SKILL.md → architecture diagram Layer 1 list
  5. Update CONTRIBUTING.md → hooks table
  6. Run verification → uv run python scripts/hooks/check_evolution_cycle.py
  7. Confirm passing → evolution-cycle hook automatically checks at the next commit

⚠️ If only steps 1-2 are done without 3-5, the evolution-cycle hook will report an error at commit time.

💡 It is recommended to run once a month autoupdate, to automatically obtain the latest ruff rules, security checks, etc.

Trigger conditions

  • "Prepare commit" "about to submit" "git commit"

Legal basis

  • Constitution: CONSTITUTION.md Chapter 3
  • Sub-law: .github/bylaws/git-workflow.md

AI orchestrator execution flow

When the AI agent is asked to "prepare commit", execute the following additional steps:

┌─────────────────────────────────────────────────┐
│          AI Pre-Commit Orchestrator             │
├─────────────────────────────────────────────────┤
│  Step 1: memory-sync     [必要] Memory Bank 同步 │
│  Step 2: pre-commit-run  [必要] 執行所有 hooks   │
│  Step 3: readme-update   [可選] README 更新      │
│  Step 4: changelog-update[可選] CHANGELOG 更新   │
│  Step 5: roadmap-update  [可選] ROADMAP 更新     │
│  Step 6: arch-check      [條件] 架構文檔檢查     │
│  Step 7: commit-prepare  [最終] 準備提交         │
└─────────────────────────────────────────────────┘

Step 2 will run uv run pre-commit run --all-files, covering all automated checks such as ruff, file hygiene, and tool docs sync. mypy and semgrep have been moved to the pre-push stage to prevent OOM.

Required step: MCP tool count synchronization

Automatically handled by pre-commit hook tool-count-sync . It can also be run manually:

uv run python scripts/count_mcp_tools.py --update-docs

This script will automatically update:

  • README.md - tool count
  • README.zh-TW.md - tool count
  • .github/copilot-instructions.md - Tool count + complete list
  • src/.../TOOLS_INDEX.md - Complete tool index

Parameter

Parameter Description Default
--skip-readme Skip README update false
--skip-changelog Skip CHANGELOG update false
--skip-roadmap Skip ROADMAP update false
--skip-hooks Skip pre-commit hooks false
--dry-run Preview only, no modifications false
--quick Run only necessary steps (memory-sync + hooks) false

Usage examples

「準備 commit」           # 完整流程
「快速 commit」           # 等同 --quick
「commit --skip-readme」  # 跳過 README

Skip specific Hook

SKIP=mypy git commit -m "quick fix"         # 跳過 mypy (較慢)
git commit --no-verify -m "emergency"       # 跳過所有 hooks (慎用!)

Output format

🚀 Git Pre-Commit 工作流

[1/7] Memory Bank 同步 ✅
  └─ progress.md: 更新 2 項
  └─ activeContext.md: 已更新

[2/7] Pre-commit Hooks ✅
  └─ ruff lint: passed (auto-fixed 3 issues)
  └─ ruff format: passed
  └─ mypy: passed
  └─ file hygiene: passed
  └─ tool docs sync: passed (2 files updated)

[3/7] README 更新 ✅
  └─ 新增功能說明

[4/7] CHANGELOG 更新 ✅
  └─ 添加 v0.2.0 條目

[5/7] ROADMAP 更新 ⏭️ (無變更)

[6/7] 架構文檔 ⏭️ (無結構性變更)

[7/7] Commit 準備 ✅
  └─ 建議訊息:feat: 新增用戶認證模組

📋 Staged files:
  - src/auth/...
  - docs/...

準備好了!確認提交?

Hook configuration files

File Purpose
.pre-commit-config.yaml pre-commit hooks definition
pyproject.toml [tool.ruff] ruff lint + format rules
pyproject.toml [tool.mypy] mypy type check rules
pyproject.toml [tool.pytest] addopts Force multi-core testing
pyproject.toml [tool.bandit] bandit security scan rules
pyproject.toml [tool.deptry] deptry dependency hygiene rules
vulture_whitelist.py vulture dead code scan whitelist
scripts/hooks/check_file_hygiene.py File hygiene check
scripts/hooks/check_tool_sync.py MCP tool documentation sync
scripts/hooks/check_skills_frontmatter.py .claude/skills YAML frontmatter validation
scripts/hooks/check_evolution_cycle.py Self-evolution loop consistency validation
scripts/hooks/check_commit_size.py Commit file count limit (≤30)
scripts/hooks/check_future_annotations.py future annotations enforcement
scripts/hooks/check_no_print.py Prohibit print() in src/
scripts/hooks/check_ddd_layers.py DDD layer dependency check
scripts/hooks/check_type_ignore.py Prohibit bare type: ignore
scripts/hooks/check_docstring_tools.py MCP tool docstring check
scripts/hooks/check_env_config.py Prohibit os.environ in inner layers
scripts/hooks/check_source_counts.py Ensure per-source API return count is displayed
scripts/hooks/check_todo_scanner.py TODO/FIXME scan
scripts/hooks/check_instruction_drift.py Tool docstring change detection
scripts/check_async_tests.py async/sync test consistency

Unicode Mojibake Hook

  • unicode-mojibake uses scripts/hooks/check_unicode_mojibake.py to block newly staged corrupted emoji/UTF-8 artifacts while allowing valid emoji.