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:
- Create hook script →
scripts/hooks/<name>.py - Register in .pre-commit-config.yaml → add hook definition
- Update copilot-instructions.md → Pre-commit Hooks section
- Update this SKILL.md → architecture diagram Layer 1 list
- Update CONTRIBUTING.md → hooks table
- Run verification →
uv run python scripts/hooks/check_evolution_cycle.py - 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 countREADME.zh-TW.md- tool count.github/copilot-instructions.md- Tool count + complete listsrc/.../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-mojibakeusesscripts/hooks/check_unicode_mojibake.pyto block newly staged corrupted emoji/UTF-8 artifacts while allowing valid emoji.