@thedecipherist/claude-packs 0.0.0-stage → 1.1.0

package/packs/writing/skills/reply-stance/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: reply-stance
+description: Use when about to draft any reply to a comment, a review or a thread, or when asked whether to agree with what someone said.
+---
+
+# Stance before voice: is the position right?
+
+Voice is HOW it sounds; this is WHETHER the position is even right. Getting the voice right but conceding a false point is still a failed reply.
+
+<constraints>
+Always do:
+1. Replying to a comment on OUR post, or to OUR comment? The reply MUST be rooted in and consistent with what we already said. If the author's original text is NOT in context, STOP and ask for it before drafting. The commenter quoting or summarizing the user does NOT count; their recap is their framing. If you can "infer the gist", that is exactly the trap.
+2. Verify before agreeing, ALWAYS. Polite and reasonable-sounding is not verification. If you can't verify it, don't endorse it. Definitive is on-brand for the author, but only when the claim is actually true.
+3. If the core framing is false, LEAD with the correction.
+
+Never do:
+- Stroke egos, or agree with anything partly false, not even the agreeable-sounding part. The trap: someone polite and technically sharp, and the instinct is "you're right that... but". NO.
+- Use the disguised version: "X is real, sure, but..." / "fair point, but..." is the same concession wearing a correction's clothes. Watch for "sure", "fair", "real", "valid" right before a "but".
+</constraints>
+
+Worked example. A commenter politely said hooks "alone don't fully cover" the supply chain risk. WRONG draft: "You're right that the skill file can be the attack vector. The supply chain risk is real." RIGHT (the author's actual line): "There is no security in a skill. Period. Hooks are the only thing that can stop Claude from reading, writing or piping a curl command through shell to steal all your personal information." Lead with the correction.
+
+Check on the finished reply: consistent with what we already said, or did I ask for the author's original instead of guessing? Verified before agreeing with any part? No false premise conceded because they were polite?

package/packs/writing/skills/should-i-reply/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: should-i-reply
+description: Use when deciding whether a comment deserves a reply at all, or when surfacing comments for the author.
+---
+
+# Decide whether to reply at all
+
+The author does NOT reply just to be right. A reply must make a difference.
+
+<constraints>
+Always do:
+- Wrong + few upvotes: ignore. Going nowhere.
+- Wrong + highly upvoted + clear why: reply. The reply is for the silent many who upvoted the misinformation, not for the author.
+- Right but adds nothing, or low visibility: skip.
+- Merely smug, no spreading misinformation: skip; replying would be ego.
+- When surfacing comments for the author, filter OUT "technically wrong but changes nothing".
+- Whenever we do reply: tear down AND redirect. Give the correct approach.
+
+Never do:
+- Leave someone with just "no".
+</constraints>

package/packs/zod/hooks/schemas-only.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// schemas-only (PreToolUse, Write|Edit|MultiEdit|NotebookEdit|Bash): a Zod schema is written once, in the schemas folder
+// (STEP 3 item 4: "Zod v4 schemas only under schemas/"). Routes, handlers, adapters and the web app import the shape
+// from there (and infer its type with z.infer), so a request, a record and a form never drift apart.
+// Refused, by every write route (lib/writes.mjs): a write that ADDS a `z.object(` (or `z.strictObject(` / `z.looseObject(`)
+// to a JS or TS file outside the layout's "schemas" concept (default: any schemas/ folder). env.ts is the one other place a
+// shape lives (the environment's names and types); it is let through. Another project's files are not judged.
+//   node schemas-only.mjs --selftest
+import { basename, extname, join } from 'node:path';
+import { judgeEvent } from './lib/writes.mjs';
+import { matchesAny } from './lib/glob.mjs';
+import { conceptGlobs, readLayout } from './lib/layout.mjs';
+import { blankCode } from './lib/cpp-scan.mjs';
+import { claudeRoot } from './lib/project.mjs';
+import { runHook, scratchProject, verdicts, writeOf } from './lib/selftest.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const CODE = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.tsx', '.jsx']);
+const SCHEMA = /\bz\.(?:object|strictObject|looseObject)\s*\(/g;
+const count = (t) => (blankCode(t ?? '').match(SCHEMA) ?? []).length;
+
+export function verdict(rel, before, after, globs) {
+  if (!CODE.has(extname(rel)) || after === null || /^env\.[cm]?[jt]s$/.test(basename(rel))) return null;
+  if (matchesAny(rel, globs) || count(after) <= count(before)) return null;
+  return `BLOCKED by schemas-only: ${rel} gains a Zod schema (z.object) outside the schemas folder (${globs.join(', ')}).\n` +
+    'Write the schema once in the schemas folder (packages/core/src/schemas), export it, and import it here; take its type with z.infer.\n';
+}
+
+const main = (text) => judgeEvent(text, {
+  name: 'schemas-only',
+  write: (w, rel) => verdict(rel, w.before, w.after, conceptGlobs(readLayout(claudeRoot(w.path)), 'schemas') ?? ['**/schemas/**']),
+});
+
+function selftest() {
+  const hook = new URL(import.meta.url).pathname;
+  const layout = { folders: { schemas: { path: 'packages/core/src/schemas', purpose: 'schemas' } }, concepts: { schemas: ['schemas'] } };
+  const dir = scratchProject({ 'api/src/routes/old.ts': 'const Q = z.object({ id: z.string() });\n' }, layout);
+  const w = (rel, text) => runHook(hook, dir, writeOf(join(dir, rel), text));
+  const cases = [
+    ['a schema in the schemas folder', w('packages/core/src/schemas/user.ts', 'export const User = z.object({ id: z.string() });\n'), 0],
+    ['a schema in a route', w('api/src/routes/user.ts', 'const Body = z.object({ name: z.string() });\n'), 2],
+    ['a strictObject in a handler', w('api/src/handlers/user.ts', 'const B = z.strictObject({});\n'), 2],
+    ['a schema in the web app', w('channel/app/form.tsx', 'const F = z.object({});\n'), 2],
+    ['the route imports the schema', w('api/src/routes/user.ts', "import { User } from '@core/schemas/user';\n"), 0],
+    ['env.ts shapes the environment', w('api/src/env.ts', 'export const Env = z.object({ PORT: z.coerce.number() });\n'), 0],
+    ['a file that already had one keeps it', w('api/src/routes/old.ts', 'const Q = z.object({ id: z.string() });\nexport { Q };\n'), 0],
+    ['a comment that shows z.object is not a schema', w('api/src/routes/c.ts', '// never z.object( here\n'), 0],
+  ];
+  return verdicts('schemas-only', cases);
+}
+
+export const hook = main; // run-hooks.mjs calls it with the event's text (KWB-24)
+if (isMain(import.meta.url)) process.exit(process.argv.includes('--selftest') ? selftest() : await asHook('schemas-only', main));

package/packs/zod/pack.json

@@ -0,0 +1,44 @@
+{
+  "name": "zod",
+  "version": "1.0.0",
+  "description": "Zod 4 schemas written once, in one folder, and imported everywhere (schemas-only), with the environment shaped in one env.ts.",
+  "type": "stock",
+  "author": "claude-packs",
+  "license": "MIT",
+  "homepage": "https://github.com/TheDecipherist/claude-packs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TheDecipherist/claude-packs.git",
+    "directory": "packs/zod"
+  },
+  "keywords": [
+    "zod",
+    "schemas"
+  ],
+  "engines": {
+    "claude-packs": ">=0.26.0"
+  },
+  "concepts": {
+    "schemas": [
+      "**/schemas/**",
+      "**/*.schema.ts"
+    ],
+    "env": [
+      "**/env.ts"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/schemas-only.mjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/packs/zod/rules/env-shapes-only.md

@@ -0,0 +1,14 @@
+---
+# concepts: env
+---
+# env.ts holds the shape of the environment, never a value; .env is never committed
+
+<constraints>
+Always do:
+- Parse `process.env` once, at start, with a Zod schema in `env.ts`: each name, its type, whether it is required, a default only when it is not a secret. Fail at start when one is missing.
+- Keep the values in an ignored `.env`; commit `.env.example` with the names.
+
+Never do:
+- Write a secret or a real value into `env.ts`, or read `process.env` anywhere else.
+- Commit a `.env` (`secrets-guard` refuses it).
+</constraints>

package/packs/zod/rules/zod-4-schemas.md

@@ -0,0 +1,14 @@
+---
+# concepts: schemas
+---
+# Zod 4 schemas live only in the schemas folder, written once and imported everywhere
+
+<constraints>
+Always do:
+- Write every request, response, record and form shape as a Zod 4 schema in the schemas folder, exported, and take its type with `z.infer`.
+- Give the API's routes these schemas (a Zod type provider), and the web app the same ones for its forms.
+
+Never do:
+- Write `z.object` anywhere else (`schemas-only` refuses it), or a second shape of the same thing.
+- Use Zod 3 for new code.
+</constraints>

package/profiles/stellix.layout.json

@@ -0,0 +1,315 @@
+{
+  "_comment": "Stellix, tailored from docs/project.md (surveyed 2026-10-26, branch work/notes-hit, b41d77d). Complete: packs add no default folders. stage-guard is disabled: the house git-guard already refuses git add -A. 0.4.0: the SOUND and MIXER layers (lib/app/src/layer*, cards, controls) are UI, so the control and look rules load there; confirm against the re-survey. 0.6.0: the copy trees are folders of kind copy (protect-vendor guards them; copy-tree-guard.py is merged into it), and guards carries Stellix's values for the house guards. enable: the opt-in hooks Stellix runs (user-asks, idle-wake); guards.git.refuseTrunk: Stellix works on a branch per step.",
+  "complete": true,
+  "folders": {
+    "app": {
+      "path": "lib/app",
+      "purpose": "the standalone, processor, editor, player, demo and the one launch function (launch.cpp)"
+    },
+    "app_copy": {
+      "path": "lib/app/tabula",
+      "kind": "copy",
+      "purpose": "a COPY TREE (kind copy): Tabula 1's PIANO loader, bridge and prebuild tool, copied unchanged by tools/copy_tabula.py; read-only as every copy tree"
+    },
+    "snapshot": {
+      "path": "lib/snapshot",
+      "purpose": "the one shared snapshot header the painter reads (header-only)"
+    },
+    "world": {
+      "path": "lib/world",
+      "purpose": "the world: travellers, strikes, rebounds, PULL, walls, the snapshot ring, State and the seeded RandomSource"
+    },
+    "engines": {
+      "path": "lib/engines",
+      "purpose": "SlotSound and Tabula 1's voice, copied and proved (src/tabula is read-only)"
+    },
+    "engines_copy": {
+      "path": "lib/engines/src/tabula",
+      "kind": "copy",
+      "purpose": "a COPY TREE (kind copy): Tabula 1's voice, effects and dspblocks files, copied unchanged by tools/copy_tabula.py; read-only (L8), each file with its origin line"
+    },
+    "engines_own": {
+      "path": "lib/engines/src/own",
+      "kind": "own",
+      "purpose": "PROMOTED files (kind own): copied files that measured identical, moved out of the copy tree by tools/copy_promote.py with their .origin record; these may be changed"
+    },
+    "dsp": {
+      "path": "lib/effects",
+      "purpose": "effects and dynamics: delay, EQ, compressor, limiter (S11a-S11d)"
+    },
+    "painter": {
+      "path": "lib/painter",
+      "purpose": "everything drawn: scene, camera, card, GPU layer, shaders, the Painter facade"
+    },
+    "records": {
+      "path": "data",
+      "purpose": "data/records (fixed ids, moons) and data/bank (factory patches)"
+    },
+    "probes": {
+      "path": "probes",
+      "purpose": "probe executables, each with --selftest, and the shot program (pictures, benches)"
+    },
+    "plants": {
+      "path": "tools/plants",
+      "purpose": "planted-fault sources run by tools/plants.sh"
+    },
+    "docs": {
+      "path": "docs",
+      "purpose": "spec, delay spec, laws, licences, research, work order (plan and logs at the root: build.md, bugs.md, workflow-bugs.md)"
+    },
+    "tools": {
+      "path": "tools",
+      "purpose": "build.sh, step.py, gates/, hooks/, plants.sh and plants.d/, copy and compare tools"
+    }
+  },
+  "concepts": {
+    "cpp": [
+      "lib/**/*.cpp",
+      "lib/**/*.h",
+      "lib/**/*.mm",
+      "probes/**/*.cpp",
+      "probes/**/*.h",
+      "tools/plants/**/*.cpp"
+    ],
+    "audio": [
+      "lib/app/src/processor.h",
+      "lib/app/src/processor.cpp",
+      "lib/app/src/sound.h",
+      "lib/app/src/mixer.h",
+      "lib/engines/include/**",
+      "lib/engines/src/*.cpp",
+      "lib/effects/**"
+    ],
+    "dsp": [
+      "lib/effects/**",
+      "lib/engines/include/**",
+      "lib/engines/src/*.cpp"
+    ],
+    "params": [
+      "lib/app/src/controls.h",
+      "lib/app/src/params.h",
+      "lib/app/src/moonparams.h",
+      "lib/app/src/host_params.h",
+      "lib/app/src/processor.h",
+      "data/records/**",
+      "data/bank/**"
+    ],
+    "records": [
+      "data/records/**",
+      "data/bank/**",
+      "lib/world/include/stellix/world/state.h"
+    ],
+    "world": [
+      "lib/world/**",
+      "lib/snapshot/**",
+      "lib/app/src/launch.*",
+      "lib/app/src/demo.cpp"
+    ],
+    "painter": [
+      "lib/painter/**"
+    ],
+    "shaders": [
+      "lib/painter/src/card/*_glsl.h",
+      "lib/painter/src/card/ui2d_*.h",
+      "lib/painter/src/gl/glsl.h",
+      "**/*.wgsl"
+    ],
+    "ui": [
+      "lib/app/src/editor*.h",
+      "lib/app/src/live.*",
+      "lib/painter/src/view.*",
+      "lib/app/src/layer*",
+      "lib/app/src/*card*",
+      "lib/app/src/*control*"
+    ],
+    "app": [
+      "lib/app/**"
+    ],
+    "tests": [
+      "probes/**",
+      "lib/*/tests/**",
+      "tools/gates/**",
+      "tools/plants/**",
+      "tools/plants.d/**"
+    ],
+    "bench": [
+      "probes/shot/cpugate.cpp",
+      "probes/shot/simbench.cpp",
+      "probes/shot/shot.cpp",
+      "probes/machine/**"
+    ],
+    "build": [
+      "CMakeLists.txt",
+      "**/CMakeLists.txt",
+      "cmake/**"
+    ],
+    "claude": [
+      ".claude/skills/**",
+      "**/.claude/skills/**",
+      ".claude/agents/**",
+      ".claude/rules/**"
+    ],
+    "notes": [
+      "build.md",
+      "bugs.md",
+      "workflow-bugs.md",
+      "docs/**/*.md"
+    ],
+    "docs-folder": [
+      "docs"
+    ]
+  },
+  "files": {
+    "seeded_random": "lib/world/include/stellix/world/random_source.h",
+    "world_math": "lib/world/src/sim_fly.h",
+    "snapshot": "lib/world/src/sim.h",
+    "render_thread": "lib/app/src/editor.h"
+  },
+  "protected": [
+    "lib/engines/src/tabula/**",
+    "design/reference/**",
+    "build/evidence/**"
+  ],
+  "disable": [
+    "hooks/no-shipped-images.mjs",
+    "checks/one-seeded-random.json",
+    "hooks/stage-guard.mjs"
+  ],
+  "gates": {
+    "hover": "bash tools/gates/hover_gate.sh"
+  },
+  "commands": {
+    "build": "bash tools/build.sh build",
+    "test": "bash tools/build.sh test",
+    "test-one": "bash tools/build.sh test -R <name>",
+    "plants": "bash tools/plants.sh",
+    "run": "bash tools/build.sh run",
+    "step": "python3 tools/step.py status",
+    "cpu-gate": "bash tools/build.sh test -R stellix.cpu_gate",
+    "frame-bench": "stellix_shot --bench (built by `bash tools/build.sh build`)",
+    "picture-gates": "bash tools/build.sh test -R '_gate'"
+  },
+  "siblings": [
+    "../"
+  ],
+  "kinds": {
+    "audio-entry": {
+      "what": "processBlock and the processor, voices, sound and mixer",
+      "in": "lib/app/src/processor.* (audio files) or lib/engines",
+      "concepts": [
+        "audio",
+        "dsp",
+        "tests"
+      ],
+      "content": "\\b(processBlock|renderNextBlock|getNextAudioBlock)\\s*\\("
+    },
+    "world": {
+      "what": "travellers, strikes, rebounds, PULL, walls, the world step, the snapshot ring, seeded random",
+      "in": "world"
+    },
+    "snapshot": {
+      "what": "the one plain-data snapshot type the painter reads",
+      "in": "snapshot"
+    },
+    "engine": {
+      "what": "SlotSound and the copied Tabula voice (src/tabula is read-only)",
+      "in": "engines"
+    },
+    "dsp-block": {
+      "what": "effects and dynamics: delay, EQ, compressor, limiter",
+      "in": "dsp"
+    },
+    "gpu-code": {
+      "what": "anything that calls Dawn/WebGPU, the scene, camera, card, Painter facade",
+      "in": "painter",
+      "concepts": [
+        "painter",
+        "tests"
+      ],
+      "content": "\\b(wgpu::|wgpu[A-Z]\\w*\\s*\\(|WGPU[A-Z]\\w+)"
+    },
+    "shader": {
+      "what": "WGSL shaders",
+      "in": "painter",
+      "concepts": [
+        "painter"
+      ],
+      "files": [
+        "**/*.wgsl"
+      ]
+    },
+    "editor": {
+      "what": "the editor, live view and UI wiring",
+      "in": "app",
+      "concepts": [
+        "ui",
+        "painter",
+        "app",
+        "tests"
+      ],
+      "content": "\\bvoid\\s+(?:\\w+::)*paint\\s*\\(\\s*(?:juce::)?Graphics\\b"
+    },
+    "records": {
+      "what": "fixed-id records, moons, factory patches",
+      "in": "records"
+    },
+    "probe": {
+      "what": "a probe executable with --selftest, the shot program",
+      "in": "probes"
+    },
+    "plant": {
+      "what": "a planted-fault source for tools/plants.sh",
+      "in": "plants"
+    },
+    "docs": {
+      "what": "spec, laws, licences, research, work orders",
+      "in": "docs",
+      "concepts": [
+        "docs-folder"
+      ],
+      "files": [
+        "**/laws.md",
+        "**/*-spec.md"
+      ]
+    },
+    "tools": {
+      "what": "build.sh, step.py, gates, hooks, copy and compare tools",
+      "in": "tools"
+    }
+  },
+  "guards": {
+    "git": {
+      "safeRestore": "python3 tools/safe_restore.py <paths>",
+      "branchStart": "python3 tools/step.py start <STEP> \"task\" (work that is not a step: start --work <name> \"task\")",
+      "refuseTrunk": true,
+      "house": true
+    },
+    "copy": {
+      "tools": [
+        "tools/copy_tabula.py",
+        "tools/copy_reimport.py",
+        "tools/copy_promote.py"
+      ]
+    },
+    "time": {
+      "saveCommand": "add new files by path, then python3 tools/step.py save \"<note>\""
+    },
+    "browser": {
+      "pictureCommand": "the shot program (stellix_shot --render)"
+    },
+    "images": {
+      "guarded": [
+        "**"
+      ],
+      "allowed": [
+        "design/reference/**",
+        "build/pictures/**",
+        "out/**"
+      ]
+    }
+  },
+  "enable": [
+    "hooks/user-asks.mjs",
+    "hooks/idle-wake.mjs"
+  ]
+}