diegoecab/oci-deal-accelerator
1
1
Fork 2
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

SKILL.md sync: pre-commit hook + CI gate + make install-hooks

Browse Source 
Three-layer defense to keep root SKILL.md (Claude Code) and
.agents/skills/oci-deal-accelerator/SKILL.md (Codex) byte-aligned.
Without this, Claude Code and Codex can drift and give the user
contradictory instructions — exactly the failure mode that produced
the workload-driven-mode incident on 2026-04-25.

Layers (least → most enforcement):

1. Local pre-commit hook (.githooks/pre-commit, opt-in via
   ``make install-hooks`` which sets core.hooksPath). When SKILL.md
   is staged, auto-runs scripts/sync-skill.py and stages the
   regenerated .agents/ copy in the same commit. Idempotent.

2. ``make install-hooks`` target + a tip line in ``make venv``'s
   output so any new clone discovers the hook setup.

3. CI gate (.gitea/workflows/skill-sync.yaml) on every push/PR
   touching SKILL.md or the .agents/ copy. Runs
   ``scripts/sync-skill.py --check`` and fails the build on drift.
   Catches anyone who skipped the hook.

README documents the rationale and the three layers.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
root
2026-04-25 22:58:33 -03:00
parent d86adaf7cc
commit fba2d23d5d
5 changed files with 135 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
Makefile
View File

@@ -1,6 +1,6 @@
# OCI Deal Accelerator — Build Automation
.PHONY: help install test validate example diagram deck full clean lint codex-package update-icons freshness freshness-refresh sync-skill sku-discover pptx-icons-refresh archcenter-benchmark-20 diagram-lookup diagram-validate-spec archcenter-descriptions-refresh diagram-spec-audit archcenter-smoke
.PHONY: help install test validate example diagram deck full clean lint codex-package update-icons freshness freshness-refresh sync-skill sku-discover pptx-icons-refresh archcenter-benchmark-20 diagram-lookup diagram-validate-spec archcenter-descriptions-refresh diagram-spec-audit archcenter-smoke install-hooks
# Use venv if present, otherwise find best available python3
ifneq (,$(wildcard .venv/bin/python))
@@ -25,6 +25,15 @@ venv: ## Create virtual environment and install dependencies
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -r requirements.txt
@echo "Virtual environment ready. Run: source .venv/bin/activate"
@echo "Tip: run 'make install-hooks' once to enable the pre-commit"
@echo " hook that keeps SKILL.md in sync with the Codex copy."
install-hooks: ## Install repo-versioned git hooks (pre-commit auto-syncs SKILL.md)
@if [ ! -d .git ]; then echo "install-hooks: not a git repo"; exit 1; fi
git config core.hooksPath .githooks
@echo "install-hooks: core.hooksPath set to .githooks"
@echo " → pre-commit now auto-syncs .agents/skills/.../SKILL.md"
@echo " whenever SKILL.md is part of the staged change set."
install: ## Install Python dependencies (system-wide)
pip install -r requirements.txt