Skip to main content
skill CX Codex

verify · sethgammon — Claude Code and Codex skill: live hook pipeline test

verify — a skill to self-test the Citadel hook pipeline during a live session. Exercises real tool calls (Write, Edit, Bash, Read), verifies that hooks fire, telemetry accumulates, and no errors occur.

MIT ★ 937 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local
Open on GitHub

What verify does

Available for Claude Code and Codex. The skill runs a sequence of operations: writes a temporary file, edits it, runs a Bash command, reads the file back, and cleans it up. Each step triggers different hooks—PreToolUse (file protection, governance) and PostToolUse (logging). After the test, it compares the baseline telemetry state against the final state: checks whether counters in hook-timing.jsonl, audit.jsonl grew and error log stays empty. Output is either "HOOK HEALTH: PASS" or "HOOK HEALTH: FAIL" with a per-hook breakdown.

Use it after updating hooks or when tool behavior feels unstable. If the .planning/telemetry/ directory does not exist, the skill fails immediately with instructions to initialize the project.

What it helps with

  • verify that all hooks in the pipeline fire without errors
  • diagnose why tools behave inconsistently or slowly
  • confirm telemetry is accumulating and logging correctly
  • validate Citadel setup after initial installation

Example prompts for the agent

  • Check hook health: /verify
  • Run pipeline self-test: verify hooks
  • Verify hooks are working: verify or hook health

How to install verify

1Plugin marketplace

/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local

This installs the whole citadel plugin with all its skills

2Skills CLI (Vercel)

npx skills add SethGammon/Citadel --skill verify -a claude-code

3Manually: put the files in place

~/.claude/skills/verify/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/verify/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about verify

How do I install verify in Claude Code?

Run these commands in order: /plugin marketplace add SethGammon/Citadel, then /plugin install citadel@citadel-local, then npx skills add SethGammon/Citadel --skill verify -a claude-code and open ~/.claude/skills/verify/SKILL.md.

How do I install verify in Codex?

Run npx skills add SethGammon/Citadel --skill verify -a codex and open .agents/skills/verify/SKILL.md.

What does HOOK HEALTH: FAIL mean and how do I fix it?

One or more hooks did not fire as expected. Check the detailed output to see which hook failed. Run node scripts/verify-hooks.js for deeper diagnostics or confirm that .planning/telemetry/ exists and is writable.

Source text

SKILL.md · MIT
---
name: verify
license: MIT
description: >-
  Self-test the Citadel hook pipeline from within a live session. Exercises
  real tool calls (Write, Edit, Bash, Read) and checks that hooks fired,
  telemetry accumulated, and no errors occurred. Reports HOOK HEALTH: PASS
  or HOOK HEALTH: FAIL with a per-hook breakdown.
user-invocable: true
auto-trigger: false
trigger_keywords:
  - verify
  - verify hooks
  - hook health
  - self-test
  - check hooks
  - harness health
last-updated: 2026-03-27
---

# /verify — Hook Pipeline Self-Test

Use this when:
- Hooks were recently updated and you want a live sanity check
- Something feels wrong (tools seem too slow, quality-gate not firing)
- After installing Citadel in a new project

## Protocol

### Step 1: Baseline

Read the current telemetry state:
```
.planning/telemetry/hook-timing.jsonl  → count lines (baseline_timing)
.planning/telemetry/audit.jsonl        → count lines (baseline_audit)
.planning/telemetry/hook-errors.log    → size in bytes (baseline_errors)
```

If telemetry directory doesn't exist, note it (init-project may not have run).

### Step 2: Exercise hooks

Run these tool calls in sequence. Each exercises a different hook:

1. **Write** a temp file at `.planning/verify-temp.ts`:
   ```typescript
   // citadel verify probe
   export const verifyProbe = true;
   ```
   → Exercises: PreToolUse (protect-files, governance), PostToolUse (post-edit)

2. **Edit** the same file — change `true` to `false`:
   → Exercises: PreToolUse (protect-files, governance), PostToolUse (post-edit)

3. **Bash** a harmless read command: `echo "verify-probe"`
   → Exercises: PreToolUse (governance)

4. **Read** the temp file back
   → Exercises: PreToolUse (protect-files — should allow, it's not .env)

5. **Delete** the temp file: `rm .planning/verify-temp.ts` or equivalent
   → Cleanup

### Step 3: Check side effects

After all tool calls complete, read telemetry again:

| Check | Expected | Result |
|---|---|---|
| hook-timing.jsonl grew | +2 or more lines (Write + Edit post-hooks) | PASS/FAIL |
| audit.jsonl grew | +3 or more lines (Write + Edit + Bash pre-hooks) | PASS/FAIL |
| hook-errors.log unchanged | same size as baseline | PASS/FAIL |

### Step 4: Report

Output a results block:

```
=== HOOK HEALTH CHECK ===

hook-timing.jsonl:  +N lines  [PASS / FAIL]
audit.jsonl:        +N lines  [PASS / FAIL]
hook-errors.log:    no errors [PASS / FAIL — N new errors]

HOOK HEALTH: PASS
```

Or if any check fails:

```
HOOK HEALTH: FAIL

Failing checks:
- hook-timing.jsonl did not grow: PostToolUse hooks may not be firing
  → Verify hooks are installed: node scripts/verify-hooks.js
  → Check settings.json: cat .claude/settings.json | grep PostToolUse

- audit.jsonl did not grow: governance hook may not be firing
  → Check: node hooks_src/governance.js <<< '{}'
```

## Edge Cases

**No .planning/telemetry/ directory**: Init-project may not have run.
Output: "HOOK HEALTH: FAIL — .planning/telemetry/ not found. Run: node hooks_src/init-project.js"

**Hooks installed but telemetry still zero**: The project may have a harness.json
that disables telemetry. Check `features.telemetry` in `.claude/harness.json`, Citadel's shared config path for all runtimes including Codex.

**First-time run (no baseline)**: If the files don't exist before the test,
they should be created during the test. Treat "file created" as equivalent to "grew".

## What This Does NOT Test

- Hook correctness on edge cases (use verify-hooks.js for that)
- Full PreToolUse → tool → PostToolUse sequence isolation (use integration-test.js)
- Skill output quality (use skill-bench.js --execute)

## Quality Gates

- All 3 telemetry checks must pass: timing grew, audit grew, no new errors
- Temp file must be cleaned up regardless of pass/fail outcome
- Report must include exact counts (+N lines), not just PASS/FAIL
- If .planning/telemetry/ does not exist, FAIL immediately — do not fabricate counts

## Contextual Gates

**Disclosure:** Creates and deletes `.planning/verify-temp.ts` during the test. No other files modified.
**Reversibility:** green — temp file deleted on completion; no persistent changes.
**Trust gates:** Any — no restrictions.

## Exit Protocol

```
---HANDOFF---
- Hook pipeline: PASS / FAIL
- hook-timing.jsonl: +N lines
- audit.jsonl: +N lines
- hook-errors.log: N new errors (0 expected)
- Reversibility: green — no persistent changes; verify-temp.ts cleaned up
- Next: if FAIL, run node scripts/verify-hooks.js for deeper diagnostics
---
```

© SethGammon · MIT · SethGammon/Citadel

Similar skills

All skills for Agent setup: memory, context, orchestration →

verify by other authors comes first.

verify react verify validates code changes against React repository requirements before committing. Runs Prettier, linter, Flow type checks, and tests. CX Codex +1 1,200installs verify Yeachan-Heo verify turns "it should work" into evidence you can read: which check ran, what passed, and what stayed unverified. CX Codex +1 721installs verify official anthropics verify — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode that tests harness changes end-to-end without Docker. CX Codex +1 257installs verify codewithmukesh verify — a skill for Claude Code, Codex, Cursor, and other agents that runs a seven-phase verification pipeline on .NET projects: build, analyzers, antipattern detection, tests, security, formatting, and diff review. CX Codex +1 4,000installs verify plastic-labs The verify Claude Code skill tests Honcho changes against a running local app. It exercises the HTTP API, deriver queue, and SQL query plans. CX Codex +1 172installs openspec-verify-change openspec openspec-verify-change is a Claude Code skill that checks code against OpenSpec specs, tasks, and design before archiving a change. CX Codex +1 4,000installs verify-this cursor The verify-this skill tests a specific claim against fresh local evidence: it captures before and after measurements, compares artifacts, and returns one verdict. CX Codex +1 2,600installs audit-verify-explain-grade-5 MengTo audit-verify-explain-grade-5 — a skill for Claude Code, Codex, Cursor, GitHub Copilot, and Gemini CLI that checks every claim against real evidence and delivers the result in plain language. CX Codex +1 1,700installs gsd-verify-work open-gsd gsd-verify-work is a Claude Code skill that runs conversational user acceptance testing for completed features. Validates changes test by test and outputs a markdown report. CX Codex +1 594installs verify-and-stop JuliusBrussee verify-and-stop proves existing work meets acceptance criteria without expanding scope. Useful for validation tasks and last-mile checks. CX Codex +1 129,000installs convex-verify convex convex-verify is a Claude Code skill that tests Convex features with multiple user identities. It runs when asked to verify a specific query, mutation, or action. CX Codex +1 43,800installs

From the same set55

The whole set →
arch-reviewer arch-reviewer inspects project files for layer boundary violations, circular dependencies, and dead imports without modifying code. CX Codex ★ 937repo stars knowledge-extractor The knowledge-extractor subagent saves reusable patterns, pitfalls, and decisions from finished work for a project wiki. Run it after completing a substantial piece of work. CX Codex ★ 937repo stars session-handoff session-handoff turns the current session into a structured HANDOFF block so the next session can pick up work without re-auditing the project. CX Codex +1 ★ 937repo stars unharness unharness is a Claude Code skill that plans Citadel removal from a project and keeps a portable archive. It runs on requests to remove Citadel or clean up the harness. CX Codex +1 ★ 937repo stars grill grill turns a vague plan into a sharp technical spec through one-question-at-a-time interview, each with a default answer you edit. CX Codex +1 ★ 937repo stars autopilot autopilot processes queued tickets from .planning/intake/ through automated research, implementation, and verification. CX Codex +1 ★ 937repo stars doc-gen doc-gen generates function comments, directory READMEs, and API references while following the project’s existing conventions. Use it when docs should explain code behavior rather than repeat signatures. CX Codex +1 ★ 937repo stars policy-enforcer policy-enforcer is a Claude Code subagent that checks proposed actions against Citadel’s rules and returns an allow-or-block verdict. Archon and Fleet spawn it before actions with low reversibility. CX Codex ★ 937repo stars

Project sponsors

Companies that keep this analytics open