raulrgmx/oci-deal-accelerator
1
0
Fork 0
forked from diegoecab/oci-deal-accelerator
Code Pull Requests 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

20
README.md
View File

@@ -452,6 +452,26 @@ For temporary overrides (e.g., focusing on a specific customer), create `AGENTS.
Full setup details: [`codex/README.md`](codex/README.md)
#### Keeping the Claude and Codex skills in sync
The root `SKILL.md` (read by Claude Code) and `.agents/skills/oci-deal-accelerator/SKILL.md` (read by Codex) MUST stay byte-aligned modulo an auto-generated banner. If they drift, the two agents give the user different instructions.
Three layers of defense, run from least to most enforcement:
1. **Local pre-commit hook (recommended once per clone):**
```bash
make install-hooks
```
Sets `core.hooksPath = .githooks`. From then on, any commit that touches `SKILL.md` auto-runs `scripts/sync-skill.py` and stages the regenerated `.agents/` copy in the same commit. No manual step required.
2. **Manual sync (anytime):**
```bash
make sync-skill # write the .agents/ copy from SKILL.md
make lint # check (also runs sync --check)
```
3. **CI gate (`.gitea/workflows/skill-sync.yaml`):** every push/PR runs `python scripts/sync-skill.py --check` and fails the build if the two files have drifted. Catches anyone who skipped the hook.
## Roadmap
### ECAL Completeness (see `docs/ecal-gaps-backlog.md` for full list)