@zalom/plastic 1.14.0 → 2.0.0-alpha.1

package/skills/skill-creating/references/agents.md

@@ -1,168 +0,0 @@
-# Authoring an Agent (subagent)
-
-How to write a subagent / Agent role file: scope, tools, description, the reviewer pattern,
-collector discipline, and the skill-vs-agent decision. Rules cite section D of the
-best-practices standard (D1 through D6).
-
-## Contents
-
-- [When a skill suffices vs escalate to an agent](#when-a-skill-suffices-vs-escalate-to-an-agent)
-- [The agent definition fields](#the-agent-definition-fields)
-- [One focused task per agent](#one-focused-task-per-agent)
-- [Tight tool set](#tight-tool-set)
-- [Description: embedded when-to-use examples](#description-embedded-when-to-use-examples)
-- [Collectors, not implementers](#collectors-not-implementers)
-- [Reviewer / devil's-advocate agents](#reviewer--devils-advocate-agents)
-- [Composing skills and agents](#composing-skills-and-agents)
-- [Self-checks](#self-checks)
-
-For load levels, the three-bucket model, and description-as-trigger rules, open
-`progressive-disclosure.md` and `skills.md`. Do not re-derive them here (C7).
-
-## When a skill suffices vs escalate to an agent
-
-Decide before authoring an agent at all. A full agent carries its own context window and tool
-grant, so it is too heavyweight for quick work [D5].
-
-| Situation | Build | Why |
-| --- | --- | --- |
-| Light read-only check, single-file validation, scaffold one file | Skill | A skill loads on trigger and runs in the current context, no spin-up cost [D5] |
-| Deep multi-file audit, parallel investigation, isolated noisy work | Agent | The isolated context keeps search and log noise off the main thread [D2][D5] |
-| Same task repeated with deterministic steps | Script (see `scripts.md`) | Executed, not loaded; token-free and variance-free |
-
-Default to a skill. Escalate to an agent only when the work needs an isolated context budget or
-its own restricted tool grant.
-
-## The agent definition fields
-
-An agent file is frontmatter plus a system-prompt body. Set each field for one reason.
-
-| Field | When it matters | Set it to |
-| --- | --- | --- |
-| `name` | Always. The orchestrator and `SendMessage` address the agent by it | Lowercase-hyphen, one capability (`spec-reviewer`, `dependency-auditor`) |
-| `description` | Always. The orchestrator delegates purely on this text [D3] | Trigger conditions plus embedded when-to-use example pairs (see below) |
-| `tools` | Always. Omitting it grants every tool, which over-arms the agent [D1] | Only the tools the one task needs |
-| `model` | When the task is cheap (Haiku) or hard (Opus) | The cheapest tier that holds quality |
-| `proactive` marker | When the agent should auto-fire without an explicit ask [D3] | Include "use proactively" inside the description |
-
-Keep the body in imperative voice. State the agent's single job, its numbered process, and its
-output contract. Push reference detail into files the agent reads on demand, same as a skill body.
-
-## One focused task per agent
-
-Give each agent exactly one task. Focused scope plus a tight tool set is what makes delegation
-decidable and cheap [D1].
-
-1. Name the single responsibility in one phrase. If the name needs "and", split into two agents.
-2. Start with one agent. Add a specialist only when it materially improves isolation or tool
-   scoping [D1]. More agents widen the discovery surface and the orchestrator's choice space.
-3. Write the body around that one task. An agent that "reviews and also fixes and also reports" has
-   three jobs and no clear output contract.
-
-## Tight tool set
-
-Grant only the tools the one task requires [D1].
-
-| Agent kind | Typical tools | Excluded |
-| --- | --- | --- |
-| Reviewer / auditor | Read, Grep, Glob | Edit, Write, Bash (read-only by design) [D4] |
-| Collector / researcher | Read, Grep, Glob, WebFetch | Edit, Write (returns a summary, does not change code) [D2] |
-| Implementer | Read, Edit, Write, Bash | Only the surface its task touches |
-
-A reviewer with Edit can rewrite the code it judges. A collector with Write can leak its noisy
-context back into the tree. The tool list is the guardrail; keep it narrow.
-
-## Description: embedded when-to-use examples
-
-The orchestrator never reads the body at delegation time. It routes on the description alone, so
-the description must teach the boundary by example [D3].
-
-Write the description with:
-
-1. A trigger clause in third person ("Use when reviewing a spec before the plan stage").
-2. One or more `<example>` pairs showing a matching prompt, the assistant's choice to delegate, and
-   a one-line `<commentary>` on why. Example pairs teach the boundary a keyword list cannot [D3].
-3. "use proactively" when the agent should auto-fire without the user naming it [D3].
-
-Concrete shape:
-
-```
-description: >
-  Use when a spec is complete and needs an adversarial review before planning.
-  Use proactively after the spec-specialist writes spec.md.
-  <example>
-    Context: spec.md just landed for the active intent.
-    user: "Is this spec ready to plan?"
-    assistant: "I'll use the spec-reviewer agent to challenge the spec before planning."
-    <commentary>Adversarial review runs at the Why-to-How boundary.</commentary>
-  </example>
-```
-
-A description that summarizes the agent's workflow instead of its trigger makes the orchestrator
-act on the summary and skip the body. State when to fire, not how the agent works.
-
-## Collectors, not implementers
-
-Use a subagent as an information collector that returns a short summary, not as an implementer [D2].
-
-| Do | Avoid |
-| --- | --- |
-| Return a tight summary: findings, file paths, a verdict | Stuffing raw search output or full file dumps back into the main thread |
-| Write a plan or summary markdown file as shared memory; have the main thread read it [D2] | Passing large results inline, which defeats the isolation |
-| Keep search, log, and crawl noise inside the agent's own context [D2] | Re-emitting that noise to the orchestrator |
-
-The reason a subagent has an isolated context is to absorb noise. The filesystem (a plan or summary
-file) is the shared memory between agents; the agent's return value is the headline, not the
-transcript [D2].
-
-## Reviewer / devil's-advocate agents
-
-A reviewer agent needs four things, or it produces unscoped, unverifiable results [D4].
-
-1. Read-only tools: Read, Grep, Glob, and nothing that edits [D4]. A reviewer that can edit stops
-   being a reviewer.
-2. A numbered review process in the body, so every run covers the same checks in the same order.
-3. Explicit anti-scope: a "do not use for" clause that names what the agent must not do (implement
-   fixes, refactor, approve its own changes) [D4].
-4. A fixed, severity-bucketed output format, so findings are comparable across runs [D4].
-
-Fixed output contract:
-
-```
-## Critical
-- <finding> (file:line) -> <why it blocks>
-
-## Major
-- <finding> (file:line) -> <impact>
-
-## Minor
-- <finding> (file:line) -> <suggestion>
-
-## Verdict
-PASS | BLOCK, with one-line reason.
-```
-
-The severity buckets and the verdict are mandatory. Empty buckets stay in, marked "none", so a
-reader can tell the agent checked.
-
-## Composing skills and agents
-
-Two mechanisms load content into an agent's context. Choose by what budget the isolated agent
-should carry [D6].
-
-| Mechanism | Effect | Use when |
-| --- | --- | --- |
-| Subagent `skills:` | Preloads the full skill content into the agent at spawn [D6] | The agent must always have that skill's rules in hand |
-| Skill `context: fork` | Runs the skill body as a task prompt inside a chosen agent type [D6] | A skill should execute as an isolated agent, not inline |
-
-Pick deliberately. `skills:` spends the agent's budget up front for guaranteed availability;
-`context: fork` hands the body to a fresh agent so the work runs isolated [D6].
-
-## Self-checks
-
-- Could this be a skill instead? If the work is light or single-file, build a skill [D5].
-- Does the agent have exactly one job, named without "and"? [D1]
-- Is the tool list the minimum the job needs, and read-only for a reviewer? [D1][D4]
-- Does the description carry at least one `<example>` pair and "use proactively" if it auto-fires? [D3]
-- Does the agent return a summary and use a file as shared memory, not dump its context? [D2]
-- Does a reviewer have a numbered process, an anti-scope clause, and a severity-bucketed output? [D4]

package/skills/skill-creating/references/defaults-first.md

@@ -1,23 +0,0 @@
-# Defaults First
-
-This chapter holds the Plastic-first, delegate-by-exception rule for naming an external skill as a default.
-
-### Defaults-First
-
-Plastic stands on its own. Skills and agents use Plastic's own defaults; an
-external skill (for example `superpowers:*`) is opt-in, never load-bearing.
-
-- **Default to Plastic, delegate by exception.** Name the Plastic-native path as
-  the default. Delegate to an external skill only when (a) it is available in the
-  harness, or (b) the user explicitly asks for it. A user without that plugin must
-  still get the core behavior.
-- **Phrase external skills as enhancements.** Write "use Plastic's native X by
-  default; if `superpowers:<skill>` is available, or the user prefers it, delegate
-  to it" never "delegate to `superpowers:<skill>`" as the only path.
-- **Optional dependencies detect then degrade.** `qmd` is the reference shape:
-  `scripts/lib/qmd_sync.rb` detects the binary first and every verb no-ops cleanly
-  when it is absent (see `scripts/qmd-sync`). Optional CLIs and MCP servers follow
-  the same detect-then-skip pattern, so a missing tool never crashes a session.
-- **Legitimate hard dependencies are exempt.** Ruby, Node, git, and POSIX tools are
-  the cost of running Plastic, not silent coupling. The principle targets accidental
-  dependence on external skills doing work Plastic should do itself.

package/skills/skill-creating/references/evals.md

@@ -1,41 +0,0 @@
-# Evals (author-time gate)
-
-This is the gate, not the method. It states the eval decisions an author makes while building a
-skill, then hands the full procedure to one place. Do not duplicate that procedure here.
-
-## Build evals before docs
-
-Build at least three evals before writing extensive documentation. A skill without an eval is an
-assertion, not a capability, so the eval forces the skill to close a real observed gap instead of an
-imagined one. [F1]
-
-Build RED-GREEN-REFACTOR. Run the scenario without the skill and record the verbatim failure (RED),
-write the minimal instructions that fix exactly that failure (GREEN), then close the loopholes the
-failure exposed (REFACTOR). Only instructions that move a failing eval earn their tokens. [F2]
-
-## What each eval must cover
-
-- Description triggering. Pair should-trigger queries with near-miss negatives: prompts that share
-  keywords with the skill but need a different skill entirely. Near-miss negatives catch
-  over-triggering, the most common description failure. State the trigger set here; do not size the
-  query count or split here. [F3]
-- Output quality. Write assertions only after observing real output. Make them specific, verifiable,
-  and countable, with no benefit of the doubt and no brittle exact-phrase matching. Assertions
-  written before observation encode hopes, not behavior, so include at least one output-quality case
-  graded this way. [F4]
-- Discipline under pressure. For a skill whose job is restraint, stack pressures (time, sunk cost,
-  authority, exhaustion) with forced options and run the case via a subagent. Reciting the rule is
-  not complying with it. [F5]
-
-## Grading and reliability decisions
-
-Grade with the cheapest sufficient tier, and track capability (pass@k) separately from reliability
-(pass^k) with k at least three. The evaluating-skills skill owns the grader taxonomy, judge
-calibration, clean-context execution, and cross-model testing. [F6, F7, F8]
-
-## Run them with the methodology skill
-
-Use the evaluating-skills skill to author and run the evals. It owns the full method: eval scope
-selection, the query-count and train/validation protocol, the grader taxonomy and judge calibration,
-the iteration loop, and graduation of stable capability evals into regression. It is the source of
-truth for those steps; this file states the author-time gate and stops there. [F6, F7, F8]

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

@@ -1,251 +0,0 @@
-# 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: `hooks/edit-gates` -> `scripts/hook-edit-gates`
-(PreToolUse, the merged dispatcher that runs code-gate, lock-gate, savepoint-pre, links-gate,
-and create-gate in one process; each gate's own logic lives in `scripts/lib/edit_gates.rb`
-and is also reachable through the standalone `scripts/hook-code-gate` CLI wrapper),
-`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/skill-creating/references/progressive-disclosure.md

@@ -1,176 +0,0 @@
-# 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-skill-evaluating.` | Good. Names the skill, leaves loading to the agent. |
-| `@skills/skill-evaluating/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]