CRASH — Commands, Rules, Agents, Skills, Hooks¶

CRASH is gald3r's answer to a specific failure mode: instructions written in a markdown file that an LLM agent might read, and might follow. CRASH components are designed so that as much of the behavior as possible actually executes, rather than depending on an agent choosing to comply. This page walks through all five component types with real examples pulled from this repo's own component source (not invented samples).

Component	What it is	Executes, or read as context?
Commands	Named, invocable actions (`/g-<name>` in an IDE, `gald3r <verb>` at the CLI)	Dispatches to a skill or CLI verb
Rules	Always-apply behavioral constraints, loaded every session	Read as context (enforcement varies by IDE)
Agents	Specialized personas scoped to a narrower job	Read as context when the persona is invoked
Skills	On-demand instruction packages loaded when a command or judgment calls for them	Read as context, on demand
Hooks	Lifecycle scripts (session-start, pre-tool-call, agent-complete, ...)	Real executing code — the one CRASH type that is not "just markdown"

Commands: `/g-wpac-notify` (real file)¶

Commands are thin dispatchers — a short markdown file describing usage, that hands off to a skill for the actual instructions. This repo's own src/gald3r_core/platform/pipeline/neutral_source/commands/g-wpac-notify.md:

---
description: Send a lightweight [INFO] notification to one or more project INBOXes -- no task created, no approval needed.
subsystem_memberships: [WORKSPACE_COORDINATION]
execution_tier: guarded_prompt
---
# /g-wpac-notify

Send a freeform FYI notification across project boundaries.

## Usage

/g-wpac-notify --parent "subject"
/g-wpac-notify --all-siblings "subject"

## Skill

Read and follow: `g-skl-wpac-notify`

Inside an IDE integration this is invoked as /g-wpac-notify (Claude Code) or @g-wpac-notify (Cursor). At the CLI it corresponds to gald3r workspace outbox send plus the file-fallback transport the skill documents — see coordination.md.

Rules: always-apply, every session¶

Rules live under .claude/rules/g-rl-*.md (per-IDE folder; Cursor and others have their own equivalent path) and load at the start of every session, unconditionally. They're how a project encodes a standing constraint an agent should never have to be reminded of twice — for example g-rl-43 (this repo's own rule) mandates gald3r search over raw grep for anything that might touch a gitignored tree like .gald3r_sys/, because a plain grep/ripgrep search silently skips gitignored directories and produces a false "doesn't exist" result. The rule exists specifically because that false negative happened in practice.

Agents: scoped personas¶

An agent definition narrows a session to one job — g-agnt-qa-engineer only reasons about bugs and quality, g-agnt-verifier only verifies work it did NOT itself implement (a structural check, not just a suggestion — see g-go-review's fresh-reviewer requirement in autopilot.md). Invoke one directly with @g-agnt-<name> inside a supporting IDE.

Skills: the on-demand instruction layer¶

Skills are the largest CRASH surface by file count — see the Skills reference for the current total — one directory per skill, each with a SKILL.md. A skill loads when its owning command runs, or when an agent's own judgment decides it's relevant (the frontmatter description field is what a judgment call matches against). Skills are also where the HELP CONTRACT convention lives — every skill's preamble specifies that a bare -h/--help/help argument short-circuits to a usage card instead of running the real operation, so help output never accidentally mutates state.

Hooks: the one component type that is real code¶

Hooks are plain executable Python scripts wired into an IDE's lifecycle events — session-start, pre-tool-call, agent-complete. Unlike the other four CRASH types, a hook is not "context an LLM might follow"; it is code the harness actually runs, which is the concrete difference CRASH is built around. g-hk-session-start.py (this repo's real session-start hook, trimmed docstring):

"""Session-initialization hook (fires when a new composer conversation is
created). Ensures platform dirs are populated via the engine's
`gald3r platform install` CLI verb ... reads and auto-heals
.gald3r/.identity (user_id fallback ..., project_id UUID regeneration),
then assembles the additional_context banner: first-time-setup notice,
previous-session reflection reminder, vault context ..., TASKS.md archive
gate, HEARTBEAT no_agent watchdog output ..., an open bugs count ...,
a next-runnable-task banner ..., cross-project WPAC inbox summary, and
GUARDRAILS.md. Emits a compact JSON response {"continue": true,
"additional_context": ...} and always exits 0.
"""

That function runs on every session start in a wired-up project — no agent decision required for the platform-dirs check, the identity self-heal, or the banner assembly to happen. This is the pattern the rest of CRASH is built to approximate as closely as each layer allows.

See it running in your own session¶

Every real gald3r <verb> invocation runs CRASH dispatch for itself, as part of the CLI's own command lifecycle: it records its own command-type activation, and fires every .claude/rules/ (or .cursor/rules/) file's always-apply sections through the same dispatch engine gald3r crash-stats reads from. That means the FIRST real verb you run against a project already leaves a trace — you don't need a prior IDE session to see non-zero output:

gald3r crash-stats

# CRASH Activation Stats

_Generated 2026-08-16 10:43:53 -- 47 activation(s) across 394 known component(s)._

**By type:** Commands: 2 | Rules: 45 | Agents: 0 | Skills: 0 | Hooks: 0
**By route:** Engine: 2 | Fallback: 45

## Most Active (top 10)

| Component | Type | Count | Last Activated |
|---|---|---|---|
| crash-stats | command | 1 | 2026-08-16T14:43:53Z |
| platform install | command | 1 | 2026-08-16T14:43:50Z |
| rule:g-rl-01-documentation-before-creating-md-file:54a56016 | rule | 1 | 2026-08-16T14:43:53Z |

(Real output — captured from a fresh project immediately after setup and platform install claude. Every .claude/rules/g-rl-*.md file's ## sections carrying MUST/STOP enforcement language mechanically compile into individually-tracked, always-firing rule entries. The By route line distinguishes activations the dispatch engine itself recorded from ones reconstructed by a fallback path — both count, but the split tells you how much of what you're seeing came from live instrumentation versus a best-effort reconstruction. In an active IDE session, this fills in further with real per-component call counts across Agents/Skills/Hooks too, letting you see which components actually fire, not just which are installed.)

Where next¶

Generated CRASH catalog (every command/rule/agent/skill/hook — purpose, invocation, arguments, when-to-use, example; never hand-edited): Commands, Rules, Agents, Skills, Hooks. See also the narrative pages — Commands, Skills, Agents — and Verbs for the compiled CLI verb surface, which is complementary to the command layer above, not a duplicate of it.
task-bug-workflow.md — commands in practice
concepts.md — the shorter, one-paragraph-per-idea version of this page
Root GALD3R.md — the full internal CRASH contract, for people building ON gald3r_core rather than using the finished CLI