@zalom/plastic 1.0.0-beta.2 → 1.0.0-beta.21

package/skills/creating-skills/references/hooks.md

@@ -0,0 +1,248 @@
+# Authoring a Lifecycle Hook
+
+A hook is a harness: deterministic code the Claude Code runtime fires at a lifecycle
+event. Author one when a probabilistic skill keeps dropping a behavior and that behavior
+must hold every time.
+
+For body voice, budgets, and reference rules, see `progressive-disclosure.md` and `skills.md`.
+For deciding script versus prose and writing the handler logic, read `scripts.md` when the
+handler grows past a few lines. This file covers only hook authoring.
+
+## Contents
+
+- When to reach for a hook (E1)
+- The event to matcher to handler model (E2)
+- Which event for which job (E2)
+- Path rules and executability (E3)
+- No-op by default, opt-in (E4)
+- Exit codes and output channels (E5)
+- Verify the harness engaged (E6)
+- Token levers: global hooks that shrink context (E7)
+- Propose-only self-improving loop (E8)
+- Authoring checklist
+
+## When to reach for a hook (E1)
+
+Reach for a hook only after a skill has lost the behavior. The documented order is: first
+strengthen the skill description and instructions so the model keeps preferring the skill;
+if it still drops the step, enforce it deterministically with a hook. [E1]
+
+Test: ask "does this behavior have to hold even when the model forgets the skill?" If yes
+(a gate before a destructive tool, a savepoint before compaction, a format pass after every
+edit), the runtime must enforce it, not the prompt. If no, leave it in the skill body and
+spend no hook tokens on it. [E1]
+
+A hook is code on the critical path of an event. It is not loaded into context, so it costs
+no tokens at trigger time, but a mistuned hook blocks real work. Make it earn the
+intervention. [E1]
+
+## The event to matcher to handler model (E2)
+
+Hooks are configured in three nested levels: event, then matcher group, then handler list.
+[E2]
+
+- Event: the lifecycle moment (for example PreToolUse, SessionStart, PreCompact).
+- Matcher: which instances of that event fire the handler. For tool events the matcher is a
+  tool-name pattern (`Bash`, `Edit|Write`, `mcp__memory__.*`). For SessionStart the matcher
+  is a source (`startup`, `resume`, `clear`, `compact`). For PreCompact it is `manual` or
+  `auto`.
+- Handler: what runs. Handler types include `command` (a script, JSON arrives on stdin),
+  `http`, `mcp_tool`, `prompt` (an LLM yes/no), and `agent`. Author `command` handlers as
+  scripts unless a non-script handler is clearly required. [E2]
+
+Each event exposes different inputs and a different blocking power, so the wrong event cannot
+do the job no matter how the handler is written. Select the event first, then the matcher,
+then the handler. [E2]
+
+## Which event for which job (E2)
+
+| Job | Event | Matcher example | Can block | Key inputs |
+| --- | --- | --- | --- | --- |
+| Gate or validate before a tool runs | PreToolUse | `Edit\|Write`, `Bash` | yes (exit 2 or `permissionDecision: deny`) | `tool_name`, `tool_input` |
+| Format, lint, or remind after a tool succeeds | PostToolUse | `Edit\|Write` | block before next model call only | `tool_name`, `tool_input`, `tool_output` |
+| Boot or inject context at session start | SessionStart | `startup`, `resume`, `clear`, `compact` | no | `source` |
+| Savepoint before compaction | PreCompact | `manual`, `auto` | no (savepoint; exits 0) | compaction trigger |
+| Erase or augment a prompt before processing | UserPromptSubmit | (none) | yes (exit 2) | `prompt`, `permission_mode` |
+
+Notes that change the choice of event: [E2]
+
+- PreToolUse fires before the tool runs and can stop it. Use it for gates and pre-act
+  validation (block an edit to project code before the plan exists, block a destructive
+  Bash command).
+- PostToolUse fires after the tool has already run. It cannot undo the tool. Use it to format
+  the result, lint it, or surface a reminder, and to block the next model call when the
+  output is unacceptable.
+- SessionStart cannot block. Use it to inject boot context, not to enforce anything. Its
+  stdout on exit 0 becomes conversation context (see exit codes).
+- PreCompact fires before the runtime compacts the conversation. Use it to write a savepoint
+  while the full context still exists.
+
+Plastic ships working instances of each: `scripts/hook-code-gate` (PreToolUse gate),
+`scripts/hook-session-start` (SessionStart boot and inject), `scripts/hook-savepoint-pre`
+(PreCompact savepoint). Read one before authoring a new hook of the same shape.
+
+## Path rules and executability (E3)
+
+Two failures here are silent: the hook never fires and nothing reports why. [E3]
+
+- Reference the handler script through the exported placeholders: `${CLAUDE_PLUGIN_ROOT}` for
+  a script shipped inside a plugin, `${CLAUDE_PROJECT_DIR}` for a script that lives in the
+  project. A relative path resolves against an unpredictable working directory; a hard-coded
+  absolute path works in development and breaks on another machine. [E3]
+- Make the script executable: `chmod +x` the handler file and commit that bit. A
+  non-executable `command` handler fails silently. [E3]
+- Give the script a shebang (`#!/usr/bin/env ruby` for Plastic hooks; any shell must run under
+  macOS /bin/bash 3.2). [E3]
+
+Other placeholders the runtime exports: `${CLAUDE_PLUGIN_DATA}`. [E3]
+
+## No-op by default, opt-in (E4)
+
+Make a hook a no-op by default and enable it only through explicit config. Exit 0 (allow,
+emit nothing) unless the user has opted in. A reminder or validation hook that fires for users
+who never enabled it blocks or noises work that was never asked for. [E4]
+
+Concrete shape of an opt-in, no-op-by-default handler:
+
+```ruby
+#!/usr/bin/env ruby
+# PostToolUse reminder. No-op unless explicitly enabled.
+require "json"
+config = ENV["CLAUDE_PROJECT_DIR"] ? File.join(ENV["CLAUDE_PROJECT_DIR"], ".myhook.yml") : nil
+exit 0 unless config && File.exist?(config)   # opt-in gate: silent allow when not enabled
+payload = JSON.parse($stdin.read) rescue {}
+# ... emit reminder only past this point ...
+exit 0
+```
+
+The early `exit 0` is the opt-in gate. Place the enable check before any side effect. [E4]
+Plastic gate hooks follow the same fail-open discipline: no bridge resolved means exit 0
+(allow), seen in `scripts/hook-code-gate`.
+
+## Exit codes and output channels (E5)
+
+The exit code, not the script's intent, decides what the runtime does with the output. [E5]
+
+| Exit code | Meaning | Where output goes |
+| --- | --- | --- |
+| 0 | success | stdout shown; for UserPromptSubmit and SessionStart, stdout becomes conversation context |
+| 2 | blocking error | stdout and JSON ignored; stderr fed back to Claude; blocks the action on events that support blocking |
+| other non-zero | non-blocking error | first stderr line in transcript, full text in debug log; action proceeds |
+
+Rules that follow from the table: [E5]
+
+- To inject context (SessionStart boot banner, UserPromptSubmit augmentation), exit 0 and
+  write the context to stdout. On those two events stdout is consumed as context, not just
+  displayed.
+- To block (a gate that refuses an edit, a validator that rejects a command), exit 2 and write
+  the reason to stderr. The agent reads stderr and can act on it. Plastic gates do exactly
+  this: `$stderr.puts "PLASTIC GATE - <reason>"; exit 2`.
+- For PreToolUse, prefer the structured decision over a bare exit. Emit
+  `hookSpecificOutput.permissionDecision` with value `allow`, `deny`, `ask`, or `defer`, plus
+  `permissionDecisionReason`. Do not use the deprecated top-level `decision` field. [E5]
+- Blocking with exit 2 works only on events that support it. PreToolUse is the clear gate
+  event; UserPromptSubmit, Stop, SubagentStop, and a few task events also support exit-2
+  blocking. SessionStart and SessionEnd cannot block; exit 2 there does not stop anything.
+  PreCompact runs a savepoint, not a gate (see the job table). [E5]
+
+PreToolUse JSON shape:
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Plan not yet written; edits to project code are gated."
+  }
+}
+```
+
+`hookSpecificOutput` requires `hookEventName`. [E5]
+
+## Verify the harness engaged (E6)
+
+A hook that is configured is not a hook that ran. Verify engagement before relying on a hook
+to hold a behavior. [E6]
+
+The known failure: in background sessions the session-id environment variable can be unset, so
+hooks that resolve their state through the session (Plastic gates and savepoints resolve a
+per-session bridge) silently no-op. The work proceeds ungated and nothing reports it. [E6]
+This claim is grounded mainly in Plastic's own operation rather than independent reports; treat
+it as Plastic-specific until confirmed elsewhere (LOW-EVIDENCE per E6).
+
+Verify by observation, not assumption: [E6]
+
+- Trigger the event and confirm the side effect (the gate blocked, the savepoint file appeared,
+  the boot context showed). Absence of an error is not proof the hook ran.
+- Check the session-id environment variable is set in the context where the hook must fire;
+  if it is unset, session-scoped hooks no-op.
+- For a gate, attempt the action the gate should block and confirm it is refused. A gate that
+  never refuses in testing is a gate that is not engaged.
+
+## Token levers: global hooks that shrink context (E7)
+
+Progressive disclosure trims what a skill loads. Two GLOBAL hooks trim what tool traffic
+costs at runtime, independent of any skill body. Both are token-reduction levers. Reach for
+them when prompts or tool output blow the context budget. [E7]
+
+- PostToolUse output preprocessing. Register a GLOBAL PostToolUse hook that trims noisy tool
+  output before it enters context: collapse repeated lines, cut a thousand-line log to its
+  head and tail, strip ANSI control codes, drop progress chatter. The model never sees the
+  noise, so it never pays tokens for it. Scope the hook with a matcher over the loud tools
+  (for example `Bash`), keep it lossless on signal (trim volume, never the line that carries
+  the answer), and make it no-op by default per E4. This is one GLOBAL hook, not a per-skill
+  or frontmatter hook. [E7]
+- Programmatic Tool Calling. When a tool runs in a loop and only the final result matters,
+  keep the intermediate results in code and return just the answer, instead of letting every
+  call land in context. Reach for it when a skill drives a tool in a loop and the per-call
+  output is throwaway. Pointer only: this is a Claude Code runtime feature, not a hook you
+  author here. [E7]
+
+The first lever trims output already produced; the second avoids producing the context at
+all. Pair either with sub-agent isolation (see `agents.md`) when a whole noisy sub-task can
+run off to the side and return only its conclusion. [E7]
+
+Both levers cut the CONTEXT axis (the input the model reads). The model's own OUTPUT tokens
+(what it writes) are a separate axis with no hook: cut them with terse instructions, tool
+responses that offer a concise mode, and sub-agent offloading that returns a short summary
+instead of the full trace. [E7]
+
+## Propose-only self-improving loop (E8)
+
+A skill can learn from its own real runs without ever editing itself unattended. Reach for
+this shape when a skill should improve from what actually happened in its runs. [E8]
+
+Wire a GLOBAL Stop or SubagentStop hook that, once an effort threshold is met, reads the
+just-finished transcript, drafts proposed edits to the skill, and stops. A human reviews the
+proposal, approves it, and the approved change lands in git. The hook never writes the skill
+directly. [E8]
+
+The guardrails that make this safe: [E8]
+
+- Propose only. The hook emits a diff or a suggestion, never an applied edit. Approval is a
+  human step, so a bad proposal costs a review, not a regression.
+- Effort-gated. Run the analysis only past a threshold (a long enough transcript, a real
+  failure observed), so cheap runs spend nothing.
+- Git-landed. The approved edit goes through the normal commit path, so every
+  self-improvement is reviewable and revertible.
+- Global, not scoped. This is one GLOBAL Stop or SubagentStop hook, not a per-skill
+  frontmatter hook.
+
+Pointer only. The real self-improving skill is the future `improving-skills` skill; this
+section records the safe shape so a skill author knows the loop exists and keeps it
+propose-only. [E8]
+
+## Authoring checklist
+
+- [ ] Behavior must hold deterministically; a stronger skill description was tried first (E1).
+- [ ] Event chosen for its inputs and blocking power; matcher scopes it; handler is a script
+      unless another handler type is required (E2).
+- [ ] Script referenced through `${CLAUDE_PLUGIN_ROOT}` or `${CLAUDE_PROJECT_DIR}`, has a
+      shebang, and is `chmod +x` (E3).
+- [ ] No-op by default; the opt-in check runs before any side effect; exits 0 when not enabled
+      (E4).
+- [ ] Exit codes deliberate: 0 to allow or inject context, 2 to block with the reason on
+      stderr; PreToolUse uses `hookSpecificOutput.permissionDecision`, not top-level `decision`
+      (E5).
+- [ ] Engagement verified by triggering the event and observing the side effect, including the
+      unset-session-id no-op case (E6).

package/skills/creating-skills/references/progressive-disclosure.md

@@ -0,0 +1,176 @@
+# Progressive Disclosure
+
+The canonical load-level model for Plastic skills, agents, and hooks. Every other
+reference and the SKILL.md body point here for this model and must not restate it (C7).
+Read it before authoring any skill body, before splitting content into `references/`,
+and before deciding where a file goes (scripts, references, or assets).
+
+## Contents
+
+- [The three load levels](#the-three-load-levels)
+- [When to split the body into references](#when-to-split-the-body-into-references)
+- [Bucket selection: scripts vs references vs assets](#bucket-selection-scripts-vs-references-vs-assets)
+- [Reference-link discipline (C4)](#reference-link-discipline-c4)
+- [One level deep, with a table of contents (C5, C6)](#one-level-deep-with-a-table-of-contents-c5-c6)
+- [Store each fact once (C7)](#store-each-fact-once-c7)
+- [Cross-reference other skills by name (C8)](#cross-reference-other-skills-by-name-c8)
+- [Ship only what does the job (C9)](#ship-only-what-does-the-job-c9)
+- [The thin-router pattern (C10)](#the-thin-router-pattern-c10)
+- [Quarantine worked examples (C11)](#quarantine-worked-examples-c11)
+
+## The three load levels
+
+Treat each level as a hard design target, not a guideline. The agent platform loads
+each level at a different moment, so a fact in the wrong level either burns context that
+is always present or never arrives when needed. [C1]
+
+| Level | What lives here | Budget | When it loads |
+|-------|-----------------|--------|---------------|
+| Metadata | `name` + `description` frontmatter | ~100 tokens | Always, for every skill in the catalog |
+| Body | `SKILL.md` after the frontmatter | under 5000 tokens / under 500 lines | On trigger (description matches the request) |
+| Resources | files in `references/`, `scripts/`, `assets/` | unbounded | On demand (the body points to them, or the agent runs them) |
+
+Consequences that drive every other rule in this file:
+
+1. Metadata is paid for on every request, so the description earns its ~100 tokens by
+   triggering correctly and nothing more. Authoring rules for the description live in
+   `skills.md`.
+2. Body tokens are paid for only when the skill fires, but then they are paid in full.
+   Keep the body to the non-skippable rules plus routing. Push how-to down to resources.
+3. Resource tokens are paid for only when the agent reaches the file. This is where
+   depth, variants, and worked examples belong.
+
+## When to split the body into references
+
+Split when the body approaches the budget or carries material the agent does not need on
+every run. Move out first, in this order: advanced cases, variant paths, long worked
+examples, deep domain background. Keep inline only the core workflow plus the selection
+guidance that tells the agent which path or reference to take. [C2]
+
+Move to `references/`:
+
+- Detailed procedures the agent needs only for one task shape.
+- Advanced or edge-case handling most runs never hit.
+- Variant flows (one file per variant) so the common path stays short.
+- Long examples and tables that document rather than instruct.
+
+Keep in the body:
+
+- The non-skippable rules (the ones an agent must not get wrong even if it never opens a
+  reference).
+- The routing table that maps a request shape to the right reference.
+- Selection guidance: how to choose between the references and paths on offer.
+
+## Bucket selection: scripts vs references vs assets
+
+Choose the bucket by how the file touches the context window, not by file type. [C3]
+
+| Bucket | Relationship to context | Use for |
+|--------|-------------------------|---------|
+| `scripts/` | Executed, not read. Output enters context, the source does not. | Deterministic logic the agent would otherwise re-derive each run: validators, generators, formatters. See `scripts.md`. |
+| `references/` | Read only when the body points the agent to it. | Depth, procedures, variants, examples that instruct. |
+| `assets/` | Copied into output, never read into context. | Templates, boilerplate, fixtures the agent emits or copies verbatim. |
+
+Decision rule: if the content is logic that runs, put it in `scripts/` and document the
+interface (`--help`, exit codes) rather than the implementation. If it is knowledge the
+agent reads to decide or act, put it in `references/`. If it is bytes the agent copies
+into its output without reading, put it in `assets/`.
+
+## Reference-link discipline (C4)
+
+Bind every reference link to an observable trigger: a condition the agent can check
+against the request or the run state. Never ship a bare "see references/ for more". A
+bare pointer makes loading a judgment call, so the agent either loads everything (burning
+the budget the split was meant to save) or loads nothing (and acts blind). [C4]
+
+| Form | Verdict |
+|------|---------|
+| `Read references/hooks.md when authoring a lifecycle hook.` | Good. Trigger is the task shape. |
+| `Read references/errors.md when the API returns a non-200 status.` | Good. Trigger is observable run state. |
+| `See references/ for more detail.` | Bad. No trigger; loading is a guess. |
+| `Refer to the references as needed.` | Bad. "As needed" is not a condition. |
+
+Write the trigger as the request shape the agent can match ("when authoring an agent",
+"when the user names a hook event") or a run-state signal it can read ("when the test
+suite reports a failure", "when the frontmatter validator exits non-zero").
+
+## One level deep, with a table of contents (C5, C6)
+
+Keep every reference exactly one level deep from `SKILL.md`: the body links to
+`references/x.md`, and `references/x.md` does not link onward to a further file the agent
+must chase. Nested references get head-previewed by the platform, so the agent acts on a
+partial read and misses content below the preview window. Flatten instead: if a reference
+grows a second level, split it into sibling files the body routes to directly. [C5]
+
+Add a table of contents to the top of any reference over 100 lines so the agent can jump
+to the relevant section instead of reading linearly. For very large files, put grep
+patterns in the body so the agent can locate a section without loading the whole file.
+[C6]
+
+## Store each fact once (C7)
+
+Keep each fact in exactly one place. Do not restate a rule across the body and a
+reference, across two references, or across two skills. Duplicated doctrine drifts: one
+copy gets updated, the other goes stale, and the agent cannot tell which is current. When
+two files need the same fact, one owns it and the other points to the owner.
+
+This file owns the load-level model. The body and the other references point here for it
+and do not repeat the table or the budgets. [C7]
+
+## Cross-reference other skills by name (C8)
+
+Name a required companion skill with a requirement marker, not a path. Use a line the
+agent reads as a dependency it loads on its own terms. [C8]
+
+| Form | Effect |
+|------|--------|
+| `REQUIRED BACKGROUND: superpowers:test-driven-development` | Good. Names the dependency; the agent loads it when relevant. |
+| `For eval depth, use plastic-evaluating-skills.` | Good. Names the skill, leaves loading to the agent. |
+| `@skills/evaluating-skills/SKILL.md` | Bad. `@`-path syntax force-loads the file immediately, defeating disclosure. |
+
+The `@`-path form pulls the target into context the moment the line is read, so it spends
+the budget the level split was built to protect. Name the skill and let the trigger
+decide when it loads.
+
+## Ship only what does the job (C9)
+
+Ship the SKILL.md, the references the body routes to, the scripts it runs, and the assets
+it copies. Nothing else. No README, CHANGELOG, or QUICK_REFERENCE inside a skill: the
+description is the skill's front door, and a second front door duplicates it (C7) and adds
+files the agent must skip past. No orphan files (a file no link points to and no script
+runs). If nothing reaches a file, delete it. [C9]
+
+## The thin-router pattern (C10)
+
+For a knowledge-heavy domain (one with many distinct request shapes, each needing
+different depth), make the body a thin router: a short header of non-skippable rules plus
+a table that maps a request shape to the one reference that handles it. The body inlines
+no how-to. It decides which reference to load and stops. [C10]
+
+Router body shape:
+
+```
+# skill-name
+
+<non-skippable rules: the few facts an agent must not get wrong>
+
+## Routing
+
+| When the task is... | Read |
+|---------------------|------|
+| authoring an Agent Skill | references/skills.md |
+| authoring a subagent     | references/agents.md |
+| authoring a lifecycle hook | references/hooks.md |
+```
+
+The router keeps the always-paid body cost flat as the domain grows: adding a new request
+shape adds one reference and one table row, not more body. Each reference stays focused on
+its one shape.
+
+## Quarantine worked examples (C11)
+
+Keep the maxim in context, keep the example out of it. State the rule in the body or the
+reference; move long worked examples to a file the agent loads only when it needs to see
+the rule applied. An example is illustration, not instruction: it is paid for on every run
+if it sits in the body, but it is needed only when the rule alone is not enough. Put the
+short rule where it triggers, and route to the example with a trigger condition (C4). [C11]

package/skills/creating-skills/references/scripts.md

@@ -0,0 +1,166 @@
+# Scripts: when deterministic code beats prose
+
+Decide whether a skill ships a script, and write scripts that hold their determinism.
+Read this when choosing script versus prose, or when writing a script that ships with a
+skill.
+
+For which bucket holds a given piece of content (scripts versus references versus
+assets), read `references/progressive-disclosure.md`. This file covers only the
+script-or-prose decision and script discipline.
+
+## Contents
+
+- [Ship a script or write prose](#ship-a-script-or-write-prose)
+- [The three-way test](#the-three-way-test)
+- [Make scripts solve, not punt](#make-scripts-solve-not-punt)
+- [Test by running](#test-by-running)
+- [Match freedom to fragility](#match-freedom-to-fragility)
+- [Wire validators into hooks](#wire-validators-into-hooks)
+- [Script hard requirements](#script-hard-requirements)
+- [Plastic conventions](#plastic-conventions)
+- [Worked example](#worked-example)
+- [Self-check](#self-check)
+
+## Ship a script or write prose
+
+Ship a script when either condition holds:
+
+1. The same code gets rewritten on every run.
+2. Deterministic reliability matters (one wrong character breaks the result).
+
+Otherwise write prose. A script is executed, not loaded, so its body stays out of
+context and costs no tokens at trigger time. The price is an indirection: the agent must
+find the script, learn its interface, and run it. Pay that price only when repetition or
+determinism earns it. [G1]
+
+## The three-way test
+
+When something repeats, route it by what repeats, not by gut feel. [G2]
+
+| What repeats | Bucket | Why |
+| --- | --- | --- |
+| Identical code | `scripts/` | Run it; do not regenerate it each time. |
+| Identical boilerplate output | `assets/` (template) | Copy the template into output; never read it into context. |
+| Re-discovered facts | `references/` | Read it once, on the trigger that needs it. |
+
+A symptom of the wrong choice: an agent pasting the same 30 lines of Ruby across three
+runs belongs in `scripts/`, not in prose; a fixed file header the agent retypes belongs
+in `assets/`; a constant the agent keeps looking up belongs in `references/`.
+
+## Make scripts solve, not punt
+
+A script that hands its failure back to the agent loses the determinism that justified
+shipping it. [G3]
+
+- Handle errors inside the script. Catch the failure, print a clear diagnostic to stderr,
+  and exit non-zero. Do not raise a raw stack trace and leave the agent to interpret it.
+- No voodoo constants. Every magic number, path, or threshold gets a name and a comment
+  stating where it came from. An unexplained `0.87` is a future break.
+- State the mode. Say explicitly whether the agent executes the script or reads it. A
+  validator is executed; a snippet meant to be copied is read. Ambiguity makes the agent
+  guess.
+
+## Test by running
+
+An untested script is a latent break. Run it against real input before shipping. [G4]
+
+- Exercise the success path and at least one failure path; confirm the exit code and the
+  stderr message.
+- Delete any example or scratch files the run generated that the skill does not ship.
+  Stray files are clutter and may load by accident.
+
+## Match freedom to fragility
+
+Match degrees of freedom to fragility. Put guardrails on the narrow bridge, not the open
+field. [G6]
+
+| Task shape | Form | Reason |
+| --- | --- | --- |
+| Open, judgment-heavy | Prose | The agent needs room to adapt; code would over-constrain. |
+| A preferred, repeatable pattern | Parameterized script (flags/env) | One correct shape, with controlled variation. |
+| Fragile or destructive sequence | Fixed "do not modify" script | One exact path; any edit risks data loss. |
+
+Mark a fragile script as "do not modify" in its `--help` and in the pointer that sends the
+agent to it. For side-effecting workflows, gate execution behind a validator (see below)
+rather than trusting the agent to check preconditions by hand.
+
+## Wire validators into hooks
+
+When a rule must hold every time, wire a deterministic validator into a hook rather than
+restating the rule in prose. [G5]
+
+- A `PreToolUse` validator can refuse an action before it runs; a packaging step can
+  refuse to ship a skill that fails validation.
+- Gate destructive steps behind validate-then-act: the validator passes, then the action
+  runs. A prose reminder ("remember to check X first") is probabilistic; a hook is not.
+
+For hook event selection, exit-code semantics, and path conventions, read
+`references/hooks.md`.
+
+## Script hard requirements
+
+Every script that ships with a skill meets these, because an agent runs it unattended:
+
+1. No interactive prompts. A blocking `gets` or `read -p` hangs the agent forever. Take
+   all input up front.
+2. Input via flags, environment variables, or stdin. Never mid-run questions.
+3. `--help` is the primary documentation. Describe purpose, every flag, input, output, and
+   exit codes there, so the agent learns the interface without reading the source.
+4. Structured output. Data on stdout, diagnostics and progress on stderr, so the caller
+   can capture one without the other.
+5. Idempotent operations. Running twice produces the same end state; re-running after a
+   partial failure is safe.
+6. Meaningful, documented exit codes. 0 for success, distinct non-zero codes for distinct
+   failures, each named in `--help`.
+
+## Plastic conventions
+
+- Scripts ship in Ruby. A worked example that shows a script shows Ruby.
+- Any shell script runs under macOS `/bin/bash` 3.2. No `bash` 4.x features (no
+  associative arrays, no `mapfile`, no `${var^^}`), and no heredocs inside `$(...)`.
+
+## Worked example
+
+A skill validates that an intent slug is well formed before any directory is created. The
+check runs on every intent and must be exact, so it ships as a script, not prose. [G1][G3]
+
+`scripts/validate_slug.rb`:
+
+```ruby
+#!/usr/bin/env ruby
+# Validate an intent slug. Execute this; do not inline its logic.
+# Usage: validate_slug.rb SLUG
+# Exit: 0 valid, 1 malformed, 2 wrong argument count.
+
+# Convention source: A5 of the best-practices standard (lowercase,
+# digits, single hyphens, no leading/trailing/consecutive hyphens).
+SLUG_PATTERN = /\A[a-z0-9]+(-[a-z0-9]+)*\z/
+
+if ARGV.length != 1
+  warn "usage: validate_slug.rb SLUG"
+  exit 2
+end
+
+slug = ARGV.fetch(0)
+if SLUG_PATTERN.match?(slug)
+  puts slug            # data on stdout
+  exit 0
+else
+  warn "malformed slug: #{slug.inspect}" # diagnostic on stderr
+  exit 1
+end
+```
+
+This script earns its place: identical code on every run, one exact rule, errors handled
+inside, the named constant cites its source, data on stdout and diagnostics on stderr,
+documented exit codes, and the header states it is executed. An open task ("name this
+intent well") would stay prose; this fixed check is a script.
+
+## Self-check
+
+- Does this code repeat or demand exactness? If not, it stays prose. [G1]
+- Did the right bucket win the three-way test? [G2]
+- Are errors handled inside, constants named, and the execute-or-read mode stated? [G3]
+- Did the script run green on a success path and a failure path, with scratch files
+  removed? [G4]
+- Does fragility match form, with destructive steps gated by a validator? [G5][G6]