Merge pull request #65 from olehsvyrydov/ci/validate-gates

Run the gates that were being run by hand

Author: olehsvyrydov

.github/workflows/validate.yml

@@ -0,0 +1,69 @@
+name: Validate
+
+# The skills in this repository are markdown: nothing compiles and no test suite
+# runs, so a defect stays invisible until someone reads the exact line. Until
+# now every gate was run by hand, which means they were run when someone
+# remembered. These are the same checks, on every change.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  gates:
+    name: Framework gates
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install PyYAML
+        run: pip install --quiet pyyaml
+
+      # Frontmatter, manifests, counts, links, credential shapes, retired
+      # mechanisms, and the vendor-neutrality boundary. Each gate exists
+      # because the thing it checks actually broke once.
+      - name: Framework gates
+        run: python3 scripts/validate-framework.py
+
+  plugin-validate:
+    name: claude plugin validate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      # Pinned on purpose. An unpinned validator means a green pull request can
+      # turn red tomorrow with no change in this repository, and a behaviour
+      # change in the checker arrives silently. Bump it deliberately.
+      - name: Install Claude Code
+        env:
+          CLAUDE_CODE_VERSION: 2.1.221
+        run: npm install --global --no-fund --no-audit "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}"
+
+      # Runs without credentials — it reads the plugin off disk. This is the
+      # check that first caught a skill whose frontmatter did not parse, which
+      # had been loading with empty metadata and could never auto-trigger.
+      - name: Validate the plugin
+        run: claude plugin validate ./claude
+
+  installer:
+    name: install.sh still works
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # install.sh is the path for Cursor, Kiro and VS Code and stays supported
+      # through the plugin transition, so it must keep running.
+      - name: Dry-run every editor
+        run: ./install.sh --dry-run --editors=all --scope=project --yes

CHANGELOG.md

@@ -4,6 +4,10 @@ This file records all notable changes to the project. Versioning roughly follows
 
 ## [Unreleased]
 
+### Added
+- **CI.** The skills here are markdown: nothing compiles and no test suite runs, so a defect stays invisible until someone reads the exact line. Every gate was previously run by hand, which means it was run when someone remembered — and the record of what shipped was reconciled against the tree only after it had drifted nine behind. Three jobs now run on every pull request: `scripts/validate-framework.py`, `claude plugin validate` (which needs no credentials), and `install.sh --dry-run --editors=all`.
+- **`scripts/validate-framework.py`** — seven gates, each covering something that has actually broken in this repository: a `SKILL.md` whose frontmatter does not parse and therefore loads with empty metadata and can never auto-trigger; malformed plugin JSON, or a `version` key reappearing where it is omitted on purpose; a documented count that no longer matches the tree; a relative link pointing at nothing; a credential-shaped file being tracked in a public repository; a reference to a mechanism that was removed; and a backend product named inside a skill rather than in its adapter reference. Every gate was verified to fail on its own defect and pass when clean, because a gate that cannot fail is decoration.
+
 ## [5.2.0] — 2026-08-03
 
 Distribution moves from copying files to a versioned plugin, and three skills that documented

CONTRIBUTING.md

@@ -65,6 +65,31 @@ Key ideas:
 ```
 Then invoke the agent/command in your editor and confirm it behaves as intended.
 
+### Run the gates before you push
+
+CI runs these on every pull request; running them locally is faster than a round trip.
+
+```bash
+pip install pyyaml                        # once
+python3 scripts/validate-framework.py     # the framework gates
+claude plugin validate ./claude           # the plugin manifest + component check
+./install.sh --dry-run --editors=all --scope=project --yes
+```
+
+`validate-framework.py` checks seven things, each of which has actually broken here at least once:
+
+| Gate | Catches |
+|------|---------|
+| G1 frontmatter | A `SKILL.md` whose YAML does not parse. It then loads with **empty metadata** — no description, so it can never auto-trigger, while looking correct in the file |
+| G2 manifests | Malformed plugin JSON, and a `version` key reappearing in `plugin.json` (omitted on purpose so the commit SHA is the version) |
+| G3 counts | A documented skill/command/template count that no longer matches the tree |
+| G4 links | A relative `.md` link pointing at nothing. Fenced blocks are skipped, since template examples are illustrative |
+| G5 credentials | A credential-shaped file being tracked in a public repository |
+| G6 retired | A reference to a mechanism that was removed — a promise the repo no longer keeps |
+| G7 vendor-neutrality | A backend product named inside a skill instead of in its adapter reference |
+
+If a gate is wrong, change the gate deliberately and say why in the commit — do not work around it.
+
 ## Pull requests & commits
 
 - Branch from `main`: `feat/<short-desc>` or `fix/<short-desc>`.