@ethlete/agent-rules 0.1.0-next.2 → 0.1.0-next.21

package/content/hooks/subagent-model-policy.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: make a subagent's model an explicit choice.
+
+A `Task` call that passes no `model` runs the subagent on the parent session's
+model. A session led by an expensive model therefore spends that model on every
+grep and every file read it delegates, which burns a usage limit in minutes for
+work a small model does just as well.
+
+So this hook gates the tool call rather than only advising:
+
+  * No `model` at all - denied, with the model table returned to the agent. The
+    agent then repeats the call with a model, so the cost of the mistake is one
+    tool call, not a whole subagent run.
+  * `model: fable` - the user is asked. Fable is the right pick for planning,
+    design, cross-cutting review and leading other subagents, and the wrong pick
+    for the twentieth mechanical lookup; only the user knows which this is.
+  * Any other model - allowed silently.
+
+Two cases are left alone, because the tool's `model` would change nothing:
+
+  * `subagent_type: fork`, which always inherits the parent model.
+  * An agent type whose own definition under `.claude/agents/` sets a model.
+
+Can be disabled per machine via a gitignored ethlete-agents.config.local.json at
+the repo root: {"disableHooks": true} or {"disableHooks": ["subagent-model-policy"]}.
+
+Fail-safe: any error exits 0 with no output - the hook must never block work
+because it could not read its own input.
+"""
+
+import json
+import os
+import sys
+
+HOOK_NAME = "subagent-model-policy"
+LOCAL_CONFIG_FILE = "ethlete-agents.config.local.json"
+
+# The tool that spawns a subagent, under both names it has carried.
+SUBAGENT_TOOLS = ("Task", "Agent")
+
+POLICY = """A subagent's model is a choice, not an inheritance. This call passes no `model`, so the subagent \
+would run on the model leading this session - which is how one expensive model ends up doing every small job. \
+Call the tool again with `model` set:
+
+- `haiku` - lookups and small, fully specified jobs: grep, find, read and summarize files or a CI log, run a command and report, a mechanical edit in named files.
+- `sonnet` - scoped work with a clear target: a fix in a named file, a spec, a docs page, a lint cleanup, \
+research that needs reasoning. Sonnet 5.5 is close to opus here and costs less.
+- `opus` - hard work: a bug with no known cause, a change across many files, a review of a diff, and any task \
+sonnet did not finish.
+- `fable` - judgment-heavy work: planning, design, cross-cutting review, leading other subagents. The most \
+expensive of the four, so choosing it asks the user first.
+
+Effort follows the prompt, not a parameter: scope the prompt to one question, name what "done" is, and say \
+"keep it brief" for a lookup. An agent type defined under `.claude/agents/` carries its own model and reasoning \
+effort, so a call that names one needs no `model` of its own."""
+
+FABLE_REASON = """This subagent would run on fable, the most expensive model. Approve it where the task is \
+judgment-heavy - planning, design, cross-cutting review, or leading other subagents. Deny it for implementation \
+(`model: "sonnet"` or `"opus"`) or for a lookup or a small, fully specified job (`model: "haiku"`), then repeat the call with that model."""
+
+
+def agent_name(argv):
+    """The --agent value, defaulting to claude — older registrations pass no flag."""
+    for index, arg in enumerate(argv):
+        if arg == "--agent" and index + 1 < len(argv):
+            return argv[index + 1]
+        if arg.startswith("--agent="):
+            return arg.split("=", 1)[1]
+    return "claude"
+
+
+def repo_root(data):
+    """Repo root: the env var the agent sets, else the script's own location, else the cwd.
+
+    The script always lives at <root>/.<agent>/hooks/ethlete/subagent-model-policy.py, so
+    walking four levels up works for any agent that has no project-dir variable of its own.
+    """
+    for variable in ("CLAUDE_PROJECT_DIR", "CODEX_PROJECT_DIR"):
+        value = os.environ.get(variable)
+        if value:
+            return value
+    here = os.path.abspath(__file__)
+    derived = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(here))))
+    if os.path.isfile(os.path.join(derived, LOCAL_CONFIG_FILE)):
+        return derived
+    cwd = data.get("cwd")
+    return cwd if isinstance(cwd, str) and cwd else derived
+
+
+def load_local_config(root):
+    """Parsed ethlete-agents.config.local.json at the repo root, or {} if missing/unreadable."""
+    if not root:
+        return {}
+    try:
+        with open(os.path.join(root, LOCAL_CONFIG_FILE), encoding="utf-8") as f:
+            config = json.load(f)
+    except (OSError, ValueError, AttributeError):
+        return {}
+    return config if isinstance(config, dict) else {}
+
+
+def disabled_locally(config):
+    """True when the local config disables this hook (or all hooks) on this machine."""
+    disabled = config.get("disableHooks")
+    return disabled is True or (isinstance(disabled, list) and HOOK_NAME in disabled)
+
+
+def definition_sets_model(root, subagent_type):
+    """True when a project or user agent definition of that name declares its own model."""
+    if not subagent_type:
+        return False
+    file_name = f"{subagent_type.split(':')[-1]}.md".lower()
+    candidates = []
+    for directory in (
+        os.path.join(root or ".", ".claude", "agents"),
+        os.path.join(os.path.expanduser("~"), ".claude", "agents"),
+    ):
+        try:
+            entries = os.listdir(directory)
+        except OSError:
+            continue
+        candidates += [os.path.join(directory, entry) for entry in entries if entry.lower() == file_name]
+    for path in candidates:
+        try:
+            with open(path, encoding="utf-8") as f:
+                head = f.read(4096)
+        except OSError:
+            continue
+        for line in head.split("\n"):
+            key, separator, value = line.partition(":")
+            if separator and key.strip() == "model" and value.strip():
+                return True
+    return False
+
+
+def decision_for(tool_input, root):
+    """The (decision, reason) this call needs, or None when it may run untouched."""
+    subagent_type = str(tool_input.get("subagent_type") or "").strip().lower()
+    model = str(tool_input.get("model") or "").strip().lower()
+
+    if "fable" in model:
+        return "ask", FABLE_REASON
+    if model:
+        return None
+    if subagent_type == "fork" or definition_sets_model(root, subagent_type):
+        return None
+    return "deny", POLICY
+
+
+def main():
+    if agent_name(sys.argv[1:]) != "claude":
+        return
+
+    data = json.load(sys.stdin)
+
+    if data.get("tool_name") not in SUBAGENT_TOOLS:
+        return
+
+    tool_input = data.get("tool_input")
+
+    if not isinstance(tool_input, dict):
+        return
+
+    root = repo_root(data)
+
+    if disabled_locally(load_local_config(root)):
+        return
+
+    outcome = decision_for(tool_input, root)
+
+    if not outcome:
+        return
+
+    decision, reason = outcome
+    print(
+        json.dumps(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": decision,
+                    "permissionDecisionReason": reason,
+                }
+            }
+        )
+    )
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        pass
+    sys.exit(0)

package/content/output-styles/ste-clarity.md

@@ -0,0 +1,131 @@
+---
+name: ste-clarity
+description: Write all prose in ASD-STE100 Simplified Technical English — approved words, simple verb forms, active voice, one idea per sentence.
+keep-coding-instructions: true
+---
+
+# ASD-STE100 output style
+
+Write every sentence you show the user in Simplified Technical English, as specified
+by ASD-STE100. Clarity comes first. Never sacrifice technical accuracy for brevity.
+
+## Scope
+
+Apply STE to your own prose: answers, explanations, plans, summaries, commit
+messages, and pull request text.
+
+Do not apply STE to:
+
+- Code, identifiers, file paths, and command names.
+- Quoted material: error messages, log lines, command output, and text from files.
+  Copy these exactly. Never rewrite a quote to make it simpler.
+- Text the user asks you to write in a different style.
+
+Markdown is still available. Use code blocks, and use `file.ts:42` references.
+
+## Words
+
+1. Use the most common, shortest word that has one clear meaning.
+2. Use one word for one meaning. Do not use synonyms for the same thing. If you
+   write "flag" for a variable, do not later call it a "switch" or an "option".
+3. Use one meaning for one word. Do not use "close" for both a state and an action
+   if this can confuse the reader.
+4. Technical names are permitted. Use the exact name from the code or the domain.
+5. Do not use slang, idioms, or figures of speech. "The build blew up" is wrong.
+   "The build failed" is correct.
+6. Do not use "etc." Complete the list, or write "for example" and give two items.
+7. Do not use a noun as a verb. Write "make a request", not "request it", when
+   "request" is a name in the code.
+
+Prefer the word on the right:
+
+| Not approved             | Use               |
+| ------------------------ | ----------------- |
+| utilize, employ          | use               |
+| initiate, commence       | start             |
+| terminate                | stop, end         |
+| perform, execute         | do, run           |
+| modify                   | change            |
+| indicate                 | show              |
+| ascertain, determine     | find, find out    |
+| assist, aid              | help              |
+| attempt                  | try               |
+| require                  | need              |
+| sufficient               | enough            |
+| additional               | more              |
+| numerous, multiple       | many              |
+| approximately            | about             |
+| currently, presently     | now               |
+| prior to                 | before            |
+| subsequent to, following | after             |
+| in order to              | to                |
+| due to the fact that     | because           |
+| via                      | with, by, through |
+| such as                  | for example       |
+| in the event that        | if                |
+| at this point in time    | now               |
+
+This table is a guide, not the full ASD-STE100 Dictionary. The Dictionary holds about
+900 approved words, each with one approved part of speech and one approved meaning.
+When you do not know if a word is approved, choose the shortest common word that has
+one clear meaning.
+
+## Verbs
+
+1. Use only these verb forms: the infinitive, the imperative, the simple present, the
+   simple past, the simple future, and the past participle as an adjective.
+2. Do not use complex tenses. Write "I changed the config", not "I have changed the
+   config".
+3. Do not use "-ing" forms, unless the form is part of a technical name, for example
+   "a logging module".
+4. Use the active voice. Write "the parser drops the field", not "the field is dropped
+   by the parser". Use the passive voice only when the actor is unknown or does not
+   matter.
+5. Do not leave out a verb to make a sentence shorter.
+
+## Noun phrases
+
+1. Do not build a cluster of more than three nouns. Break up "user account balance
+   sync failure" as "a failure in the sync of the user account balance".
+2. Add articles ("a", "the") where they help the reader.
+
+## Sentences
+
+1. Instructions: 20 words maximum.
+2. Descriptions: 25 words maximum.
+3. One idea per sentence. One instruction per sentence.
+4. A paragraph holds 6 sentences maximum, and covers one topic.
+5. Put a condition at the start of the sentence, before the instruction. Write "If the
+   sync fails, restart the server".
+6. Use connecting words such as "however", "therefore", and "then" to show the link
+   between sentences.
+7. Use a vertical list when the content has more than three parallel parts. Do not use
+   a list to give structure to a single idea.
+
+## Procedures
+
+1. Use the imperative for each step. Write "Open the file", not "You should open the
+   file" or "We can open the file".
+2. Number the steps in the order the user must do them.
+3. Give the result after the action, if the result is not obvious.
+
+## Warnings
+
+1. Put a warning or a caution before the step it applies to, never after.
+2. Start the warning with a clear command. Write "Do not run this on the production
+   database. The command deletes all rows."
+3. State the consequence in a separate, simple sentence.
+
+## Punctuation
+
+1. Do not use a slash to mean "and" or "or". Write "the date or the payee".
+2. Do not use parentheses for information the reader needs. Put it in its own sentence.
+3. Do not use a dash to join two thoughts. Use two sentences.
+4. Use a hyphen only to make a compound word clear.
+
+## When STE and accuracy conflict
+
+Accuracy wins. If a simple word would hide a real distinction, use the exact term and
+define it once in a short sentence. Never simplify a claim about what the code does.
+Keep the difference between what you verified and what you assume: write "I ran the
+tests and they passed" or "I did not run the tests", not a sentence that blurs the two.

package/content/rules/app-styling.md

@@ -0,0 +1,59 @@
+---
+name: app-styling
+description: App components are styled with Tailwind utilities in their templates; app CSS stays out of @layer components; the SDK needs a 10px rem root; hardcoded colours are never primary values.
+kind: rule
+scope: consumer
+requires: ['@ethlete/core']
+---
+
+## Styling
+
+Every component in this workspace (views, pages, shells, shared UI in `libs/`) is laid out
+and styled with **Tailwind utility classes in its template**, including the colour utilities
+the app's theme provides: the generated SDK theme utilities (`bg-et-surface-bg`,
+`border-et-surface-border`, `text-et-<theme>`) where the app generates them, or the palette its
+Tailwind config defines. Do not
+invent a BEM class system, and do not write a `.css` file for layout, spacing or
+typography a utility expresses. Every app component sets `encapsulation: ViewEncapsulation.None`,
+as the `require-view-encapsulation-none` lint rule requires. Its CSS is then global, so give the
+component a host class (`host: { class: 'app-player-card' }`) and scope every selector under it,
+the way SDK components scope theirs under their `et-` classes. Never write a bare element or
+unprefixed class selector in a component stylesheet.
+
+In an existing repo, apply this to the component you are editing, not to the rest of the app. A
+legacy component that relies on emulated encapsulation keeps it until its CSS is scoped under a
+host class: without that scope, `ViewEncapsulation.None` leaks its CSS into every view.
+
+Write CSS only for what utilities cannot express. With Tailwind 4, keep that CSS **unlayered**
+or in `@layer utilities` — never in `@layer components`, and that includes the global
+stylesheet. SDK component styles are injected into `@layer components` at runtime, after your
+stylesheet, so an app rule in the same layer ties on layer and loses on source order. With
+Tailwind 3, `@layer` is a Tailwind directive that emits unlayered CSS, so app CSS already beats
+the SDK's layered styles.
+
+To change an SDK component's look, set its `--et-*` tokens first (documented per
+component), then use a utility class or unlayered CSS on the element — see "Overriding
+component styles" in the docs site's components overview.
+
+The SDK sizes everything in `rem` on a **10px root**: the app's global stylesheet must set
+`html { font-size: 62.5%; }`. Without it every SDK control renders 1.6× too large. With it,
+`1rem` is `10px`, so the app's own `rem` values stay easy to read.
+
+The 10px root also shrinks every rem-based Tailwind scale to 62.5% of its nominal size (1.6×
+smaller): `p-4` is 10px instead of 16px, and `max-w-3xl` is 480px instead of 768px. Keep the
+spacing scale on its 4px step: with Tailwind 4, set `--spacing: 0.4rem` in the app's `@theme`,
+as the SDK's own Storybook does; with Tailwind 3, redefine `theme.spacing` in
+`tailwind.config`. In an app that already uses utilities without it, the change rescales every
+view: tell the user rather than make it. Redefine any other rem scale the app uses (text,
+container, radius) the same way, or use px where a size matters. Breakpoints are not affected:
+a media query's `rem` ignores the root font size.
+
+**Never use a hardcoded colour as the primary value.** Backgrounds, text, borders and
+interaction states resolve from the app's theme: the SDK surface and colour tokens
+(`--et-surface-*-solid`, `--et-theme-color-*`) and their generated utilities, or the palette
+the app's Tailwind config defines. Never write an arbitrary colour value such as
+`bg-[#1a1a1a]` in a template. A static fallback inside `var(--token, <fallback>)` is
+permitted, but not required.
+
+Theme **names** (`brand`, `danger`, `dark-elevated`, …) are registered by this app; the SDK
+ships none. Semantic colours resolve by theme `type` (e.g. `injectSemanticColorTheme('error')`).

package/content/rules/comments.md

@@ -1,31 +1,64 @@
 ---
 name: comments
-description: Write comments for the next reader of the file, not for the reviewer of your change.
+description: Comments are an allowlist of four cases. Everything else gets deleted before the change is done.
 kind: rule
 scope: both
 ---
 
-## Comments: write for the next reader of this file, not for the reviewer of your change
+## Comments: almost none, and never for the reviewer of your change
 
-A comment earns its place by telling someone **using or editing this code** something the
-code cannot. Explaining _why the change was made_ is not that — it belongs in the commit
-message, the changeset, or the docs.
+**Write no comment unless it fits one of the four cases below.** This is an allowlist, not a
+set of tips. Anything outside it gets **deleted** before you call the change done — not
+softened, not shortened. Code that needs prose to be understood needs a better name, a
+smaller function, or a type; fix that instead of narrating it.
 
-Do **not** leave behind:
+### The only comments allowed
 
-- **Rationale for a mechanical choice.** `Record<Size, X>` with literal keys, a `@__PURE__`
-  annotation, a factory instead of a literal, a helper moved to another file — the type,
-  the annotation and the import already say what happens.
-- **Migration narration.** "moved here from X", "used to be a tuple", "so Y no longer pulls Z".
-  Git knows. A reader six months from now does not care.
-- **The same explanation repeated per call site.** If a pattern needs explaining, explain it
-  once where the pattern is defined (the helper's JSDoc, the lint rule's message, the guide)
-  and let every use site stay silent.
-- **Restating the code.** `// increment the counter` above `counter++`.
+1. **An ordering or timing constraint** a reasonable edit would break. Say what breaks.
+2. **An invariant the types cannot express**, that a caller or a future edit could violate.
+3. **A workaround**, naming its concrete cause (browser bug, upstream issue, framework
+   limitation) and linking it where a link exists, so the next reader can tell when it may go.
+4. **Public API JSDoc** — what it does and how to call it, on something a lib actually
+   exports. One or two sentences. Not internals, not history, not why it is shaped that way.
+   In an application nothing is public API unless it lives in a shared lib other projects
+   import, so this case rarely applies to app code.
 
-Do keep: non-obvious behaviour and ordering constraints, a real invariant a future edit could
-break, a workaround with the reason it exists, and public API JSDoc (what it does and how to
-use it — not why it is shaped that way).
+Nothing else qualifies. Not "this is subtle", not "worth noting", not a heading over a group
+of members, not a summary of the function underneath it.
 
-When you catch yourself writing "because", check whether the sentence is aimed at the reviewer
-of your diff. If it is, cut it.
+### The test each one still has to pass
+
+Delete it unless **both** are true:
+
+- a competent reader who never sees your diff would be **surprised** without it, and
+- a future edit could **break something** that this sentence is the only warning about.
+
+Unsure counts as no. A missing comment costs a minute of reading; a stale one misleads for
+years.
+
+### Always delete
+
+- **Restating the code** — `// increment the counter` over `counter++`; a JSDoc on `size` that
+  says nothing beyond "the size of the button".
+- **Section headers and dividers** — `// --- Inputs ---`, `// Helpers`, `// Public API`.
+- **Rationale for a mechanical choice** — `Record<Size, X>` with literal keys, a `@__PURE__`
+  annotation, a factory instead of a literal, a helper moved into its own file. The type, the
+  annotation and the import already say what happens.
+- **Migration narration** — "moved here from X", "used to be a tuple", "so Y no longer pulls
+  Z", "renamed for clarity", "see ADR-0012". Git and the ADR index know; the next reader does
+  not care.
+- **The same explanation at every call site.** Explain a pattern once where it is defined (the
+  helper's JSDoc, the lint rule's message, the guide) and let every use site stay silent.
+- **Commented-out code.**
+- **`TODO`/`FIXME` without an issue link.** Fix it now or leave nothing.
+- **Hedging and meta** — "note that", "for clarity", "just in case", "this is cleaner", "we
+  could also…".
+
+### Before you call the change done
+
+Re-read every comment in your diff and cut the ones that are not one of the four. Then fix or
+delete any existing comment your change made wrong — one describing behaviour that no longer
+exists is worse than none.
+
+Two signals you have already over-commented: you wrote the word "because", or the diff adds
+more than a handful of comments. Both mean go back and cut.

package/content/rules/lint-and-format.md

@@ -1,6 +1,6 @@
 ---
 name: lint-and-format
-description: Run lint with --fix before fixing anything by hand, and format every edited file.
+description: Run lint with --fix before fixing anything by hand, and format every edited source file Prettier supports.
 kind: rule
 scope: both
 vars: [lintCommand, lintFixCommand, formatCommand]
@@ -12,14 +12,15 @@ Run lint with `--fix` — most styleguide rules in `@ethlete/eslint-plugin` ship
 so let them do the work before correcting anything by hand:
 
 ```bash
-{%lintFixCommand%}   # auto-fixes first (case, ordering, $ suffix, metadata, …)
+{%lintFixCommand%}   # auto-fixes first (case, ordering, metadata, …); rename to the $ suffix by hand
 {%lintCommand%}      # then re-run to see what needs a manual fix
 ```
 
-For the judgment calls lint cannot enforce — signals vs RxJS, templates, lifecycle and DI
-patterns — see {%skill:styleguide%}.
+For judgment calls lint cannot enforce, load the repository's focused guidance for the
+code you are changing.
 
-After editing any file, format it before wrapping up:
+Format every edited Prettier-supported source file before wrapping up. Do not send binary,
+generated, or unsupported files to this command:
 
 ```bash
 {%formatCommand%}

package/content/rules/nx-layout.md

@@ -0,0 +1,47 @@
+---
+name: nx-layout
+description: Nx workspace layout - thin apps, feature code in libs grouped by kind, path-mirroring aliases, scope tags.
+kind: rule
+scope: consumer
+requires: ['nx']
+---
+
+## Nx workspace layout
+
+Apps are thin shells. All feature code lives in libs, grouped by kind, not by Nx type:
+
+```text
+apps/<app>/src/app/        app.component.ts, app.config.ts, app.routes.ts only
+libs/
+  domain/<app>/<feature>/  views, components, services, <feature>.routes.ts
+  domain/<app>/shared/     code shared by one app's features (optional)
+  queries/                 query clients and creators, one folder per backend
+  types/                   API models and shared types
+  uikit/                   app-agnostic presentational components
+  theme/                   surface and colour themes
+  env/                     environment.ts, environment.production.ts
+  assets/                  fonts, icons, images
+```
+
+- `app.routes.ts` only lazy-loads domain libs:
+  `loadChildren: () => import('@acme/domain/admin/users').then((m) => m.USERS_ROUTES)`.
+  Each feature lib exports its own `<FEATURE>_ROUTES`.
+- A small app may use one lib per app (`libs/domain/<app>`) with a folder per feature.
+  Never put features, queries, shared UI or theme in the app project.
+- Do not add Nx `feature/ui/data-access/util` folders or `type:*` tags.
+- Every lib has `src/index.ts` and explicit `build` (`@nx/angular:ng-packagr-lite`), `lint`
+  and `test` targets in `project.json`. Keep `plugins: []` in `nx.json`.
+- Alias = path with slashes: `@acme/domain/admin/users`, `@acme/queries`, `@acme/types`,
+  `@acme/uikit`, `@acme/env`. Project name = path with dashes (`domain-admin-users`).
+  Component `prefix` = the repo abbreviation.
+- Tag every project with one `scope:*`: `scope:<app>` for an app and its domain libs,
+  `scope:core` for env and types, plus `scope:queries`, `scope:uikit`, `scope:theme`.
+  `@nx/enforce-module-boundaries` with `enforceBuildableLibDependency: true` lets
+  `scope:<app>` depend on itself and the shared scopes, never on another app.
+- A backend in the same workspace is an app in `apps/` with its libs in
+  `libs/domain/<name>-api`. Ban `@angular/*` in backend scopes and `@nestjs/*` in frontend
+  scopes with `bannedExternalImports`.
+- Environment config lives only in `libs/env`, never hardcoded in a query client.
+
+This is the layout for new workspaces and new code. Do not restructure an existing
+workspace that deviates from it unless the user asks.

package/content/rules/reactive-state.md

@@ -12,4 +12,4 @@ scope: both
 - **Bridge, don't copy.** Cross the boundary with `toSignal()` / `toObservable()`, never by
   `.subscribe()`-ing and assigning the value somewhere.
 
-Subscriptions, effects, and the traps in each direction: {%skill:rxjs-signals%}.
+For subscriptions and effects, load the repository's focused reactive-state guidance.

package/content/rules/styling.md

@@ -1,8 +1,8 @@
 ---
 name: styling
-description: Component CSS is plain CSS in @layer components, and every colour comes from a theme token.
+description: Component CSS is plain CSS in @layer components, and hardcoded colours are never primary values.
 kind: rule
-scope: both
+scope: sdk
 requires: ['@ethlete/core']
 ---
 
@@ -26,10 +26,12 @@ utility can win.
 rule, so source order decides. Leave interaction states (`:hover`, `:focus-visible`,
 `:active`) bare so they escalate and win.
 
-**Never hardcode a colour.** Backgrounds, text, borders and interaction states all resolve
-from the surface and colour theming tokens (`--et-surface-*-solid`, `--et-theme-color-*`) —
-see {%skill:theming%}.
+**Never use a hardcoded colour as the primary value.** Backgrounds, text, borders and
+interaction states resolve from the surface and colour theming tokens
+(`--et-surface-*-solid`, `--et-theme-color-*`). A static fallback inside
+`var(--token, <fallback>)` is permitted, but not required.
 
 Theme **names** (`brand`, `danger`, `dark-elevated`, …) are registered by the application;
-the SDK ships none. Never hardcode a theme-name union in a type, a doc or an example —
-semantic colours resolve by theme `type` (e.g. `injectErrorTheme()`).
+the SDK ships none. Never hardcode them as an SDK-defined union or reusable API contract.
+If an app-specific example names one, label it as belonging to that app. Semantic colours
+resolve by theme `type` (e.g. `injectSemanticColorTheme('error')`).

package/content/rules/subagent-models.md

@@ -0,0 +1,29 @@
+---
+name: subagent-models
+description: A subagent's model is an explicit choice on every call - haiku for lookups and small specified jobs, sonnet for scoped work, opus for hard work, fable for judgment.
+kind: rule
+scope: both
+---
+
+## Delegating: name the subagent's model
+
+A subagent spawned without a `model` runs on the model leading the session, so an expensive
+model ends up doing every small job it delegates. **Set `model` on every call**, matched to the
+task:
+
+| Model    | The work it fits                                                                                                                                                                  |
+| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `haiku`  | Lookups and small, fully specified jobs: grep, find, read and summarize files or a CI log, run a command and report, a mechanical edit in named files. Haiku 5.5 does these well. |
+| `sonnet` | Scoped work with a clear target: a fix in a named file, a spec, a docs page, a lint cleanup, research that needs reasoning. Sonnet 5.5 is close to opus here and costs less.      |
+| `opus`   | Hard work: a bug with no known cause, a change across many files, a review of a diff, and any task sonnet did not finish.                                                         |
+| `fable`  | Judgment-heavy work: planning, design, cross-cutting review, leading other subagents. The most expensive of the four, so ask the user before picking it.                          |
+
+Effort follows the prompt, not a parameter: scope the prompt to one question, name what "done"
+means, and say "keep it brief" for a lookup. Two calls need no `model` of their own - a named
+agent type carries the model and reasoning effort its own definition sets, and a fork always
+inherits the parent's model.
+
+A subagent does not have to be a Claude one. Delegate to a Codex agent where another model
+family would answer better - a second opinion, a review of your own diff, a bug hunt your own
+reading failed - and whenever the Claude usage limit is close, because a Codex run does not draw
+on it. Read {%skill:codex-subagent%} first.