Skills & Hooks, In Tandem Across the Full Lifecycle
Where each skill fires, which hooks run underneath, and how /resume and /ship close the loop between sessions. Updated 2026-04-21.
The Pipeline
The Ambient Layer — Hooks
Five hooks in ~/.claude/settings.json run deterministically, regardless of which phase you’re in. CLAUDE.md is advisory; hooks are guaranteed. If a rule must fire every time, it belongs in a hook.
UserPromptSubmit
skill-forced-eval-hook.sh
Fires on every prompt. Evaluates relevant skills and forces activation of tdd-first + verification-before-completion when code is being produced.
PreToolUse · Bash · ★ new
pgrep -f 'vitest --watch' && WARN
Before any Bash tool call, warns (stderr, non-blocking) if a vitest --watch is still running. Prevents the 22-minute git add hang.
PostToolUse · Write / Edit
britfix/run-hook.sh
After every file edit. Normalises British English spellings and other house-style tweaks.
Stop · ★ new entry
pkill -f 'vitest --watch' → beep → session-end.js
Session end. Kills any leaked vitest --watch, beeps, then runs the session bookkeeping script.
Notification · compact
pre-compact.js
Before auto-compaction. Saves session state so context loss after compaction is recoverable.
Always-Active Skills (enforced by the UserPromptSubmit hook)
/tdd-first/verification-before-completion
— these fire on every code-producing prompt without needing to be requested. The hook injects mandatory activation instructions so they can’t be silently skipped.
1
Discover — should this exist?
You have an idea or an opportunity. Before any code, validate it’s worth building.
Skills activated
/validate-problem/ce:ideate/find-first-10
/validate-problem — pressure-test whether the problem is real before building. Painkiller vs vitamin. /ce:ideate — generate and critically evaluate grounded improvement ideas for the current project. /find-first-10 — concrete plan for the first 10 manual customers. If you can’t find them, the feature isn’t worth building.
Output
Either a validated problem worth building, or a clear reason to stop. Both are wins.
2
Triage & Brainstorm — what to build
Explore requirements and trade-offs. If you’re adopting someone else’s recommendations (e.g. a /insights report), run the Adoption Discipline triage first.
When asked to adopt any recommendation set — /insights, audits, third-party suggestions — Claude must produce an explicit accept / reject / defer triage against current state before writing any plan. The reject column must exist. Paired with a CLAUDE.md growth brake: any proposal adding >20 lines requires a paired proposal for what to remove.
Skills activated
Adoption Discipline (CLAUDE.md)/ce:brainstorm
Adoption Discipline — triage-first for any recommendation set. Prevents blindly adopting rules that duplicate existing coverage. /ce:brainstorm — collaborative dialogue to shape requirements when scope is still fuzzy. Produces a requirements doc in docs/brainstorms/.
3
Plan — how to build it
Requirements are clear. Break work into ordered units, tag each with Claude-or-Codex routing, capture decisions.
Skills activated
/ce:plan-beta/deepen-plan-beta/document-review
/ce:plan-beta — transforms requirements into ordered implementation units with dependencies, acceptance criteria, and an Execution target: tag (Claude vs Codex) per unit. /deepen-plan-beta — challenge before running. Stress-tests weak sections via parallel research agents. Expensive — only when the plan has meaningful confidence gaps. /document-review — structured refinement of a plan document before execution.
Routing every unit (Claude vs Codex)
Every plan unit carries an explicit Execution target: tag. Default is codex-delegate (cheaper, for mechanical work). Use claude only when judgement, ambiguity, or design is the bottleneck. Plans without routing tags are incomplete.
Output
A plan at docs/plans/YYYY-MM-DD-NNN-*-beta-plan.md, plus initial entries in docs/decisions/decisions.md.
4
Build — code, test, debug
Plan exists, routing decided. Execute unit by unit. TDD is non-negotiable via the hook.
Hook-enforced: /tdd-first always active
Every code-producing prompt triggers /tdd-first activation. Tests must be written and confirmed failing before implementation code exists. The PreToolUse Bash hook will also warn if a vitest --watch is still running when you try to shell out.
/ce:work-beta — executes the plan unit-by-unit, respecting the routing tags. Writes to docs/handoff/handoff.md after each unit. /testing-practices — how to structure tests for the stack at hand. /systematic-debugging — root-cause-first methodology when a test fails unexpectedly or a bug surfaces. /security-review — fires contextually when you touch auth, secrets, or user input.
5
Verify — evidence before any claim
Tests pass locally. Now prove the running system works — browser + backend + review pass.
Hook-enforced: /verification-before-completion always active
No completion claims without fresh verification evidence. “Should work” is not evidence. Run the command, read the output, then claim the result.
/code-review / /code-quality — adversarial read before opening the PR. /security-review — OWASP-level audit when the change touches auth, secrets, payments, or user input. /e2e-feature-test — full matrix via agent-browser: UI drive, DB state, API response, report. /ce:review — heavyweight multi-agent review. Expensive — challenge via Adoption Discipline before launching.
6
Ship — merge with evidence
All green locally, reviews passed. Run the verified ship procedure — never claim “merged” without proof.
Skills activated
/ship ★ new/git-conventions/fix-pr/feature-video
/ship — single procedure: sequential test run → lint → commit (via git-conventions) → push → gh pr create → wait for merge → verify via gh pr view --json state,mergedAt. Composes with verification-before-completion for the final step. Terminates the “claimed merged but wasn’t” failure mode. /git-conventions — owns commit-message formatting. /ship delegates to it. /fix-pr — after a reviewer leaves comments. Fetches unresolved threads and addresses them. /feature-video — record a walkthrough and attach to the PR description.
7
Resume & Learn — close the loop
Session ends; or the token window flips. Next session picks up cleanly — no speculative continuation.
Plan Execution Continuity (MANDATORY rule)
Every project maintains docs/decisions/decisions.md (tactical log) and docs/handoff/handoff.md (newest-first running log). A fresh Claude or Codex session reads the top entry and picks up mid-flight.
Skills activated
/resume ★ new/learn/skill-publisher/ce:compound
/resume — at the start of a “continue” session, reads the most recent plan + top of handoff.md + git log + open PRs. Summarises in three bullets. Asks the user which thread to pull. Never starts work speculatively. /learn — analyse the session for reusable patterns worth saving as a new skill or ADR. /skill-publisher — mirror any new skill or walkthrough to this portal. Mandatory post-step after skill creation. /ce:compound — document a freshly-solved problem so your team benefits next time.
→ Loop back: the /resume summary usually sends you back to Plan (new work) or Build (next unit on an existing plan). That’s the loop that keeps multi-session work coherent.
Quick Reference — Situation to Skill
When
Skill(s)
Mandatory?
Vague idea, no validated demand
/validate-problem · /ce:ideate
No
Requirements still fuzzy
/ce:brainstorm
No
Adopting someone else’s rules (insights, audits)
Adoption Discipline triage
YES (CLAUDE.md)
Clear requirements, need a plan
/ce:plan-beta
No
Plan has weak or risky sections
/deepen-plan-beta
No (costly — challenge first)
Writing code with logic
/tdd-first
YES (hook)
Executing a plan unit-by-unit
/ce:work-beta
No
Root-cause debugging
/systematic-debugging
No
Touching auth, secrets, user input
/security-review
Triggered by context
Full feature test (UI + backend)
/e2e-feature-test
Recommended
Before saying “done”
/verification-before-completion
YES (hook)
Ready to push + PR + verify merge
/ship ★
Recommended
Responding to PR review comments
/fix-pr
No
Starting a session with “continue”
/resume ★
Recommended
Session produced a reusable pattern
/learn → /skill-publisher
Mandatory for new skills
Enforcement Architecture
Advisory (CLAUDE.md + memory) vs Deterministic (Hooks)
CLAUDE.md & auto-memory — rules Claude reads and should follow. Can be forgotten under load or in long sessions. Honour system. Hooks — shell commands the harness runs. Always fire. Can’t be forgotten. If a behaviour must happen every time, it belongs in a hook.
The two new hooks added 2026-04-21 (PreToolUse Bash warning + Stoppkill) are the pattern for turning a CLAUDE.md rule into guaranteed behaviour.
When to promote a rule from CLAUDE.md to a hook or skill
Hook — rule must fire every time, no exceptions, regardless of context. Example: vitest-watcher cleanup. Skill — rule only matters in specific contexts; triggers keep it out of the always-loaded prose. Example: /ship, /resume, /verification-before-completion. CLAUDE.md prose — rule applies broadly and needs to be readable context for any task. Example: the Adoption Discipline and Routing rules.
The CLAUDE.md growth brake (>20 lines requires a paired removal or skill migration) keeps the advisory layer from bloating.