claude-code-arcane 2.8.0 → 2.9.1

package/CHANGELOG.md

@@ -1,3 +1,30 @@
+## [2.9.1](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.9.0...v2.9.1) (2026-09-04)
+
+
+### Bug Fixes
+
+* **deps:** patch the two vulnerabilities that reach users ([ec0e25c](https://github.com/SebastianLuser/claude-code-arcane/commit/ec0e25cfd57ce15bf13896bee91ca22d6c3a58cf))
+
+# [2.9.0](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.8.0...v2.9.0) (2026-09-04)
+
+
+### Bug Fixes
+
+* **settings:** point this repo's status line at its own hooks/statusline.sh ([3b180da](https://github.com/SebastianLuser/claude-code-arcane/commit/3b180daed519095f246b1db3d0038698efa28b80))
+* **tests:** pin ARCANE_HOME so npm test cannot write to real installs ([a3836cc](https://github.com/SebastianLuser/claude-code-arcane/commit/a3836cce4820b5651a92df9ad38d00510a74ec38))
+* **update:** refresh statusline.sh and output-styles, and honor --force ([9ebdb20](https://github.com/SebastianLuser/claude-code-arcane/commit/9ebdb2070501837607d7998fe426cd6578c1cbcd))
+* **update:** sync unhashed files past the version gate and activate the style ([0a998be](https://github.com/SebastianLuser/claude-code-arcane/commit/0a998be8ab6cc8848862c83ed547377ab0dd3a8d))
+
+
+### Features
+
+* **core:** ship the arcane output style and a code-comments rule ([2a981bf](https://github.com/SebastianLuser/claude-code-arcane/commit/2a981bf847d8c41143da1353dd230f98ca7f7e11))
+
+
+### Performance Improvements
+
+* **statusline:** cut ~2s of process spawns from the status line ([108afe4](https://github.com/SebastianLuser/claude-code-arcane/commit/108afe409f3a51e54e22587317bbebeba04f3e07))
+
 # [2.8.0](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.7.1...v2.8.0) (2026-08-27)
 
 

package/README.md

@@ -1,6 +1,6 @@
 # Claude Code Arcane
 
-> **437 skills, 115 agents, 17 hooks and 30 rules for Claude Code — selective deploy by profile.**
+> **437 skills, 115 agents, 17 hooks and 31 rules for Claude Code — selective deploy by profile.**
 
 A configuration harness installable via `npx`. Pick a **profile** that matches your stack and only the relevant tools get installed into your project's `.claude/` directory.
 
@@ -439,7 +439,7 @@ claude-code-arcane/
 ├── profiles/                  # 38 profiles (YAML)
 ├── agents/                    # 17 dirs, 109 agents (Markdown)
 ├── hooks/                     # 17 lifecycle hooks (Bash)
-├── rules/                     # 30 rules (Markdown)
+├── rules/                     # 31 rules (Markdown)
 ├── templates/                 # Gamedev templates
 ├── docs/                      # Documentation
 └── skills-selftest/           # QA framework

package/agents/game/gameplay-programmer.md

@@ -87,7 +87,6 @@ If an ADR exists for this system:
 - State machines must have explicit transition tables
 - No direct references to UI code (use events/signals)
 - Frame-rate independent logic (delta time everywhere)
-- Document the design doc each feature implements in code comments
 
 ### What This Agent Must NOT Do
 

package/dist/cli.js

@@ -26,6 +26,7 @@ function parseProfile(filePath) {
     },
     agents: raw.agents ?? [],
     hooks: raw.hooks ?? [],
+    output_styles: raw.output_styles ?? [],
     permissions: {
       allow: perms.allow ?? [],
       deny: perms.deny ?? []
@@ -67,6 +68,7 @@ function mergeProfiles(profilesDir, profileNames) {
   const seenRulesGamedev = /* @__PURE__ */ new Set();
   const seenAgents = /* @__PURE__ */ new Set();
   const seenHooks = /* @__PURE__ */ new Set();
+  const seenOutputStyles = /* @__PURE__ */ new Set();
   const allPermAllow = [];
   const allPermDeny = [];
   const skills = [];
@@ -74,6 +76,7 @@ function mergeProfiles(profilesDir, profileNames) {
   const rulesGamedev = [];
   const agents = [];
   const hooks = [];
+  const outputStyles = [];
   for (const name of namesToLoad) {
     const filePath = path.join(profilesDir, `${name}.yaml`);
     if (!fs.existsSync(filePath)) {
@@ -112,6 +115,12 @@ function mergeProfiles(profilesDir, profileNames) {
         hooks.push(h);
       }
     }
+    for (const o of profile.output_styles) {
+      if (!seenOutputStyles.has(o)) {
+        seenOutputStyles.add(o);
+        outputStyles.push(o);
+      }
+    }
     allPermAllow.push(...profile.permissions.allow);
     allPermDeny.push(...profile.permissions.deny);
   }
@@ -121,6 +130,7 @@ function mergeProfiles(profilesDir, profileNames) {
     rules: { universal: rulesUniv, gamedev: rulesGamedev },
     agents,
     hooks,
+    output_styles: outputStyles,
     permissions: {
       allow: [...new Set(allPermAllow)],
       deny: [...new Set(allPermDeny)]
@@ -805,6 +815,7 @@ function computeSourceHashes(packageRoot, skills, rules, agents) {
   const hooksDir = path7.join(packageRoot, "hooks");
   if (fs6.existsSync(hooksDir)) {
     for (const entry of fs6.readdirSync(hooksDir, { withFileTypes: true })) {
+      if (entry.name === "statusline.sh") continue;
       if (!entry.isDirectory()) {
         hashes.hooks[entry.name] = hashFile(path7.join(hooksDir, entry.name));
       }
@@ -990,6 +1001,7 @@ var Installer = class {
     this.copyHooks();
     this.copySkills();
     this.copyRules();
+    this.copyOutputStyles();
     this.copyAgents();
     this.copyDocs();
     this.generateSettings();
@@ -1024,6 +1036,9 @@ var Installer = class {
     for (const d of ["skills", "rules", "agents", "docs"]) {
       ensureDir(path8.join(this.claudeDir, d));
     }
+    if (this.merged.output_styles.length > 0) {
+      ensureDir(path8.join(this.claudeDir, "output-styles"));
+    }
   }
   get hasStatusline() {
     return this.merged.loaded.includes("statusline");
@@ -1147,6 +1162,26 @@ var Installer = class {
       }
     }
   }
+  copyOutputStyles() {
+    if (this.merged.output_styles.length === 0) return;
+    this.log("\nOutput styles:");
+    for (const style of this.merged.output_styles) {
+      const src = path8.join(this.root, "output-styles", `${style}.md`);
+      if (!fs7.existsSync(src)) {
+        this.log(`  WARN: Output style '${style}.md' not found`);
+        continue;
+      }
+      if (this.dryRun) {
+        this.log(`  [dry-run] ${style}.md`);
+      } else {
+        fs7.copyFileSync(
+          src,
+          path8.join(this.claudeDir, "output-styles", `${style}.md`)
+        );
+        this.log(`  [ok] ${style}.md`);
+      }
+    }
+  }
   copyAgents() {
     if (this.merged.agents.length === 0) return;
     this.log("\nAgents:");
@@ -1204,6 +1239,10 @@ var Installer = class {
         command: "bash .claude/statusline.sh"
       };
     }
+    const activeStyle = this.merged.output_styles[0];
+    if (activeStyle) {
+      settings.outputStyle = activeStyle;
+    }
     if (this.dryRun) {
       this.log(
         `  [dry-run] settings.json (${this.merged.permissions.allow.length} allow, ${this.merged.permissions.deny.length} deny)`
@@ -1290,7 +1329,7 @@ function storeInCache(version, contentDir) {
     fs8.rmSync(versionDir, { recursive: true, force: true });
   }
   fs8.mkdirSync(versionDir, { recursive: true });
-  for (const dir of ["skills", "rules", "agents", "hooks", "profiles", "templates", "docs"]) {
+  for (const dir of ["skills", "rules", "agents", "hooks", "profiles", "templates", "docs", "output-styles"]) {
     const src = path9.join(contentDir, dir);
     if (fs8.existsSync(src)) {
       copyDirRecursive(src, path9.join(versionDir, dir));
@@ -1847,6 +1886,7 @@ async function addCommand(items = []) {
     rules: { universal: manifest.installed_rules, gamedev: [] },
     agents: manifest.installed_agents,
     hooks: [],
+    output_styles: [],
     permissions: { allow: [], deny: [] }
   };
   writeManifest(target, merged, manifest.profile_command, root);
@@ -2355,16 +2395,34 @@ async function updateTarget(target, opts) {
   const root = await contentSource.getContentRoot();
   const currentVersion = await contentSource.getVersion();
   const installedVersion = manifest.source_version ?? manifest.arcane_version;
+  const profileNamesForSync = manifest.profile_command.split("+").filter(Boolean);
+  const claudeDirForSync = path17.join(target, ".claude");
+  const earlySync = syncUnhashedFiles(
+    root,
+    claudeDirForSync,
+    mergeProfiles(path17.join(root, "profiles"), profileNamesForSync),
+    opts.dryRun ?? false
+  );
+  if (earlySync.length > 0 && !opts.quiet) {
+    const prefix = opts.dryRun ? "[dry-run] " : "";
+    console.log(`
+${prefix}${chalk7.cyan("Refreshed:")}`);
+    for (const label of earlySync) {
+      console.log(`  ~ ${label}`);
+    }
+  }
   if (installedVersion === currentVersion && !opts.force) {
     if (!opts.quiet) {
-      console.log(chalk7.green(`Already up to date (v${currentVersion}).`));
+      console.log(
+        earlySync.length > 0 ? chalk7.green(`Refreshed ${earlySync.length} file(s); otherwise up to date (v${currentVersion}).`) : chalk7.green(`Already up to date (v${currentVersion}).`)
+      );
     }
     return {
       target,
-      status: "up-to-date",
+      status: earlySync.length > 0 ? "updated" : "up-to-date",
       fromVersion: installedVersion,
       toVersion: currentVersion,
-      updated: 0,
+      updated: earlySync.length,
       skipped: 0,
       removed: 0
     };
@@ -2382,6 +2440,7 @@ Update available: ${chalk7.red(installedVersion)} -> ${chalk7.green(currentVersi
   const sourceHashes = computeSourceHashes(root, merged.skills, allRules, merged.agents);
   const claudeDir = path17.join(target, ".claude");
   const installedHashes = computeContentHashes(claudeDir);
+  const unhashed = earlySync;
   const items = computeUpdatePlan(
     manifest.content_hashes ?? null,
     installedHashes,
@@ -2390,10 +2449,11 @@ Update available: ${chalk7.red(installedVersion)} -> ${chalk7.green(currentVersi
   const updates = items.filter((i) => i.action === "update" || i.action === "add" || i.action === "conflict");
   const skipped = items.filter((i) => i.action === "skip-customized" || i.action === "skip-unchanged");
   const removed = items.filter((i) => i.action === "remove");
+  const forcible = opts.force ? items.filter((i) => i.action === "skip-customized") : [];
   if (!opts.quiet) {
     printUpdateSummary(items, opts.dryRun ?? false);
   }
-  if (updates.length === 0 && removed.length === 0) {
+  if (updates.length === 0 && removed.length === 0 && forcible.length === 0) {
     if (!opts.dryRun) {
       updateManifestFields(target, {
         arcane_version: currentVersion,
@@ -2408,7 +2468,10 @@ Update available: ${chalk7.red(installedVersion)} -> ${chalk7.green(currentVersi
       });
     }
     if (!opts.quiet) {
-      console.log(chalk7.green("\nNo changes to apply."));
+      console.log(
+        unhashed.length > 0 ? chalk7.green(`
+Refreshed ${unhashed.length} file(s); no other changes to apply.`) : chalk7.green("\nNo changes to apply.")
+      );
     }
     return {
       target,
@@ -2570,6 +2633,58 @@ function applyUpdates(items, root, claudeDir, merged, force) {
     }
   }
 }
+function syncUnhashedFiles(root, claudeDir, merged, dryRun) {
+  const targets = [];
+  const statuslineDst = path17.join(claudeDir, "statusline.sh");
+  if (merged.loaded.includes("statusline") || fs14.existsSync(statuslineDst)) {
+    targets.push({
+      src: path17.join(root, "hooks", "statusline.sh"),
+      dst: statuslineDst,
+      label: "statusline.sh"
+    });
+  }
+  for (const style of merged.output_styles) {
+    targets.push({
+      src: path17.join(root, "output-styles", `${style}.md`),
+      dst: path17.join(claudeDir, "output-styles", `${style}.md`),
+      label: `output-styles/${style}.md`
+    });
+  }
+  const changed = [];
+  for (const t of targets) {
+    if (!fs14.existsSync(t.src)) continue;
+    const src = fs14.readFileSync(t.src);
+    if (fs14.existsSync(t.dst) && src.equals(fs14.readFileSync(t.dst))) continue;
+    changed.push(t.label);
+    if (dryRun) continue;
+    if (fs14.existsSync(t.dst)) {
+      const bak = `${t.dst}.bak`;
+      if (fs14.existsSync(bak)) fs14.rmSync(bak, { force: true });
+      fs14.renameSync(t.dst, bak);
+    }
+    fs14.mkdirSync(path17.dirname(t.dst), { recursive: true });
+    fs14.copyFileSync(t.src, t.dst);
+  }
+  const activeStyle = merged.output_styles[0];
+  if (activeStyle) {
+    const settingsPath = path17.join(claudeDir, "settings.json");
+    if (fs14.existsSync(settingsPath)) {
+      try {
+        const settings = JSON.parse(fs14.readFileSync(settingsPath, "utf-8"));
+        if (settings.outputStyle !== activeStyle) {
+          changed.push(`settings.json (outputStyle: ${activeStyle})`);
+          if (!dryRun) {
+            settings.outputStyle = activeStyle;
+            fs14.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}
+`, "utf-8");
+          }
+        }
+      } catch {
+      }
+    }
+  }
+  return changed;
+}
 function applyItem(item, root, claudeDir) {
   const src = getSourcePath(item, root);
   const dst = getInstalledPath(item, claudeDir);

package/docs/USER-GUIDE.md

@@ -2,7 +2,7 @@
 
 ## What is Arcane?
 
-Arcane is a configuration harness for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It provides a curated library of **437 skills**, **115 agents**, **17 hooks**, and **30 rules** that you selectively deploy into any project. Instead of shipping everything to every project (wasting tokens and degrading performance), you pick a **profile** that matches your stack and only the relevant tools get installed.
+Arcane is a configuration harness for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It provides a curated library of **437 skills**, **115 agents**, **17 hooks**, and **31 rules** that you selectively deploy into any project. Instead of shipping everything to every project (wasting tokens and degrading performance), you pick a **profile** that matches your stack and only the relevant tools get installed.
 
 ## Table of Contents
 

package/hooks/statusline.sh

@@ -15,12 +15,17 @@ fi
 # Skills/agents Claude can actually invoke = global (~/.claude) + project (.claude),
 # deduped by name (project overrides global). Follow -L so .claude/skills junctions count.
 # Top-level only (mindepth/maxdepth 2) so bundled sub-skills don't inflate the total.
+#
+# Names are extracted with a single awk, never `xargs -n1 dirname|basename`: that spawned one
+# process per file (~160 here), which cost ~1.7s of the ~2.5s total on Windows and made the
+# status line miss its execution window under load — Claude Code drops the output on a
+# non-zero exit or an abort, so the bar vanished at random.
 SKILLS=$( { find -L "$HOME/.claude/skills" -mindepth 2 -maxdepth 2 -name "SKILL.md" 2>/dev/null;
             find -L .claude/skills          -mindepth 2 -maxdepth 2 -name "SKILL.md" 2>/dev/null; } \
-          | xargs -n1 dirname 2>/dev/null | xargs -n1 basename 2>/dev/null | sort -u | wc -l | tr -d ' ')
+          | awk -F/ 'NF>1{print $(NF-1)}' | sort -u | wc -l | tr -d ' ')
 AGENTS=$( { find -L "$HOME/.claude/agents" -name "*.md" 2>/dev/null;
             find -L .claude/agents         -name "*.md" 2>/dev/null; } \
-          | xargs -n1 basename 2>/dev/null | sort -u | wc -l | tr -d ' ')
+          | awk -F/ '{print $NF}' | sort -u | wc -l | tr -d ' ')
 
 PYCMD=$(command -v python 2>/dev/null || command -v python3 2>/dev/null || command -v py 2>/dev/null)
 
@@ -117,8 +122,16 @@ PREFIX="🔮 ${PROJECT}"
 
 PARTS="${PREFIX}"
 [ -n "$BRANCH" ] && PARTS="${PARTS} | 🌿 ${BRANCH}"
-PARTS="${PARTS} | 🛠️ ${SKILLS} skills"
-[ "$AGENTS" -gt 0 ] 2>/dev/null && PARTS="${PARTS} | 🤖 ${AGENTS} agents"
+PARTS="${PARTS} | 🛠️ ${SKILLS:-0} skills"
+case "$AGENTS" in
+  ''|*[!0-9]*) ;;
+  0) ;;
+  *) PARTS="${PARTS} | 🤖 ${AGENTS} agents" ;;
+esac
 [ -n "$EXTRA" ] && PARTS="${PARTS} | ${EXTRA}"
 
 echo "$PARTS"
+
+# Claude Code discards the status line on a non-zero exit, so never inherit one from the
+# last conditional above.
+exit 0

package/output-styles/arcane.md

@@ -0,0 +1,53 @@
+---
+name: arcane
+description: Respuestas compactas, tablas para comparar, lenguaje literal y estructura legible — pensado para lectura con TEA y dislexia.
+---
+
+# Arcane
+
+Respondé de forma compacta, literal y estructurada. Estas instrucciones son sobre **la
+forma** de la respuesta, no sobre el alcance del trabajo: no reducen lo que hay que hacer ni
+autorizan entregar menos.
+
+## Largo
+
+- **La respuesta primero.** Primera línea: qué pasó o qué contestás. El detalle va después,
+  para quien lo quiera.
+- **Sin preámbulo.** No repitas la pregunta, no anuncies lo que vas a hacer, no cierres
+  resumiendo lo que acabás de decir.
+- **Un tema por párrafo, tres líneas como máximo.** Si un párrafo crece, partilo o pasalo a
+  lista.
+- **Cortá cuando terminaste.** Nada de relleno, cierres corteses ni ofertas genéricas de
+  ayuda.
+- **No enumeres lo que descartaste.** Si evaluaste opciones y elegiste, decí la elegida y el
+  porqué en una línea.
+
+## Estructura
+
+- **Tabla siempre que compares.** Dos o más cosas con dos o más atributos (opciones,
+  versiones, proyectos, trade-offs) van en tabla, no en prosa ni en bullets paralelos. Una
+  columna por atributo, una fila por cosa.
+- **Listas para pasos y hallazgos.** Prosa solo para el razonamiento que une las cosas.
+- **Títulos cuando hay más de un tema.** Que se pueda saltar a la parte que importa sin
+  leer todo.
+- **`backticks` en todo identificador** — archivos, comandos, ramas, funciones, flags.
+- **Bold para lo importante**, no italics: es más fácil de decodificar. Nunca MAYÚSCULAS
+  para enfatizar, deforman la silueta de la palabra.
+
+## Lenguaje
+
+- **Literal.** Sin ironía, sarcasmo, modismos, metáforas ni preguntas retóricas. Si algo
+  está mal, decilo derecho.
+- **Un término por concepto, siempre el mismo.** No alternes sinónimos para la misma cosa:
+  si es `worktree`, es `worktree` en toda la respuesta.
+- **Oraciones cortas, una idea cada una.** Preferí punto sobre subordinada.
+- **Voz activa y sujeto explícito.** Decí quién hace qué.
+- **La incertidumbre se declara, no se insinúa.** "No sé si X" o "no lo verifiqué", en vez
+  de prosa condicional que deja al lector adivinando el nivel de confianza.
+- **Decí explícitamente qué esperás del otro.** Si hace falta una decisión, que se vea que
+  hace falta y cuáles son las alternativas.
+
+## Números y datos
+
+- **El dato antes que el adjetivo.** "62 commits atrás" en vez de "bastante atrasado".
+- **Unidad y fecha completas.** `2026-09-04`, no "ayer"; `312 KB`, no "poco".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-arcane",
-  "version": "2.8.0",
+  "version": "2.9.1",
   "description": "Skills, agents, hooks and rules for Claude Code — installable via npx claude-code-arcane",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
     "rules/",
     "templates/",
     "docs/",
+    "output-styles/",
     "CHANGELOG.md"
   ],
   "scripts": {

package/profiles/core.yaml

@@ -32,9 +32,13 @@ rules:
     - prototype-code
     - test-standards
     - implementation-workflow
+    - code-comments
   gamedev:
     []
 
+output_styles:
+  - arcane
+
 agents:
   - quality
 

package/rules/code-comments.md

@@ -0,0 +1,63 @@
+---
+paths:
+  - "**/*.cs"
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+  - "**/*.py"
+  - "**/*.go"
+  - "**/*.java"
+  - "**/*.kt"
+  - "**/*.swift"
+  - "**/*.rb"
+  - "**/*.rs"
+  - "**/*.php"
+  - "**/*.dart"
+  - "**/*.c"
+  - "**/*.cpp"
+  - "**/*.cc"
+  - "**/*.h"
+  - "**/*.hpp"
+  - "**/*.sh"
+  - "**/*.sql"
+  - "**/*.shader"
+  - "**/*.hlsl"
+  - "**/*.glsl"
+  - "**/*.gd"
+  - "**/*.lua"
+---
+
+# Code Comments Rule
+
+Comments are written in **English**, whatever language the conversation is in.
+
+## Never write
+
+- **Session narration.** No comment records what was decided, changed, tried or removed
+  while working. Not `// removed the old validation`, not `// now uses a dictionary instead
+  of a list`, not `// moved above the null check as discussed`, not `// changed from 30 to
+  50`. The commit message carries the story; the code carries the result.
+- **WHAT restated.** The code already says what it does. `// increment the counter` above
+  `counter++` is noise.
+- **Ticket, task or doc references.** No `// added for JIRA-123`, no `// part of sprint04`,
+  no `// implements the boss design doc`. Traceability lives in the commit and the PR, where
+  it stays accurate and searchable.
+- **Attribution or dates.** No `// author:`, no `// created 2026-09-04`. Git owns that and
+  never goes stale.
+- **Multi-paragraph docstrings on simple functions.**
+- **`// used by X`.** Tooling answers that better and this rots the first time X moves.
+
+## Write
+
+- **The WHY that the code cannot show.** A constant that looks arbitrary, an ordering that
+  matters, a deliberate break from the surrounding pattern.
+- **Workarounds**, with a link to the upstream bug.
+- **Non-obvious invariants or preconditions** a caller has to respect.
+- **Doc comments on public APIs** consumed from outside the module. Private ones need none.
+- **`TODO(@owner, YYYY-MM-DD): description`.** Never a bare `TODO`.
+
+## Shape
+
+One line, unless the reason honestly needs two. A comment that needs a paragraph to explain
+the code beneath it is a signal to fix the code instead.

package/rules/gamedev/audio-code.md

@@ -14,7 +14,6 @@ paths:
 - Voice budget is a hard limit: define max simultaneous voices per category and drop by priority, never let it grow unbounded
 - Audio must degrade silently — a missing bank or failed event NEVER throws into the gameplay frame
 - Keep the audio update off the render-critical path; audio work budget is 5-10% of frame time
-- Reference the audio bible section each event implements in code comments
 
 ## Examples
 

package/rules/gamedev/gameplay-code.md

@@ -11,7 +11,6 @@ paths:
 - Every gameplay system must implement a clear interface
 - State machines must have explicit transition tables with documented states
 - Write unit tests for all gameplay logic — separate logic from presentation
-- Document which design doc each feature implements in code comments
 - No static singletons for game state — use dependency injection
 
 ## Examples

package/rules/gamedev/shader-code.md

@@ -20,7 +20,6 @@ visual quality, performance, and cross-platform compatibility.
 - Group related parameters (Unity: `[Header]`, Unreal: Category)
 - Comment non-obvious calculations (especially math-heavy sections)
 - No magic numbers — use named constants or documented uniform values
-- Include authorship and purpose comment at the top of each shader file
 
 ## Performance Requirements
 - Document the target platform and complexity budget for each shader