CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

setup

Use when installing or refreshing sound taste rules in a project — an explicit "sound setup", starting work in a repo with no .claude/sound/, or a taste-not-defined nudge. Also use to re-run after a stack change (new framework, new package in a monorepo).

Quality

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

sound:setup

Scaffold a project's taste rules from the sound corpus: probe the stack, select ONLY rules whose subject the repo's code actually shows — evidence-cited per rule, never a tag-wide dump — confirm with the user, then install each confirmed rule's corpus prose verbatim. Each rule lands as a plain reference file in .claude/sound/<topic>/ — the tree sound:prime points at. Written files belong to the user; re-runs reconcile (see Re-runs).

Corpus: ../../corpus/ relative to this SKILL.md — the candidate universe, laid out as <topic>/<rule>.md: the directory is the rule's topic, the file is the pure rule body — no frontmatter, no metadata. Sibling ../../corpus-optin/ (same layout) holds opt-in rules, excluded from candidacy unless the user names one at invocation (Phase 2). If corpus/ is missing or unreadable, STOP and say so — never install a partial set silently.

Phase 1 — Probe

Decide which kind-tags apply (react, db, distributed) — verified STACK FACTS that anchor Phase 2's per-rule judgment and are presented at Confirm, not a filter that earns any rule an install.

Usage decides; manifest presence only says where to look. Verify every hint at its USE sites in source before proposing a tag — deps can be dead weight, hoisted, or tooling-only. Negatives need the same rigor: a client's config/wrapper file never clears a dep; search its use sites (.publish(, .send(, .create(…) before ruling a tag out. Read every package.json (root + workspaces) and workspace markers (pnpm-workspace.yaml, turbo.json) → hypotheses → verify each in source. Note TS / pure-JS / neither: it sets the TS-only veto (Phase 2) and the no-JS/TS abort (Failure modes).

TagFires on (verified usage)Does NOT fire on
react.tsx/.jsx files, JSX or react imports in real sourcereact in deps with zero usage; react-shaped tooling (ink absent too)
dba db client or ORM imported in source, whichever one; redis-as-store; EMBEDDED dbs with owned DDL/schema (sqlite, node:sqlite, level — in-process still counts); owned schema/migration filesconsuming someone else's hosted API without owning storage
distributedany SIDE-EFFECTFUL remote boundary: payments, email/SMS, queue/broker publish, webhook handlers, bot messaging SDKs, multiple owned services reconciling state. FRAMEWORK-WRAPPED senders count: an auth provider configured with an SMTP transport, e.g. next-auth EmailProvider, IS email-sending usage even with no direct nodemailer import. Publisher-side evidence alone is SUFFICIENT — the consumer usually lives outside the repoREAD-ONLY consumption of remote APIs (fetch-and-render); analytics beacons; redis as a plain same-process cache (get/set/del only)

Phase 2 — Select (per rule, evidence-cited)

Candidates = the ENTIRE corpus/. There is no tag pre-filter — each rule's own subject-surface gate below is the selection; the Phase 1 facts are the evidence it judges against.

Opt-in gate (deterministic). The candidate universe is corpus/ ONLY. A corpus-optin/ rule enters candidacy solely when the user names it at invocation — then read it from corpus-optin/. Directory membership is the gate; a default run never proposes an opt-in rule.

A candidate installs iff the repo contains the SUBJECT-SURFACE the rule governs — code where the rule's Detect: question is askable — cited as ONE FILE path (never a directory, never a glob). The rule's Not-when: can veto. No citation, no install. An actual violation is NOT required (rules are prevention) and its absence never vetoes. Existing COMPLIANCE is evidence FOR install: a repo already doing the mandated shape has the surface.

A fired tag earns NOTHING by itself — each rule's OWN Detect question must be askable at the cited file. A repo that publishes to Redis does not thereby get every distributed rule: with no replicas, no supervised queue, no versioned concurrent writes, the fold/restart-policy/write-conflict rules are skipped, each with its reason.

  • Subject-bearing rule: command-vs-fact-when-reconciled-elsewhere installs iff the repo has async-reconciled state (a server ack, a queue, a webhook-confirmed flow) — cite the file. A repo that names no events does not get the event-naming rules.
  • Universal-subject rule (subject is "any code": naming, transformation shape, comments, function design): passes trivially — cite any substantive source file. Never manufacture deeper evidence.
  • A rule whose mandated shape requires TypeScript (casts, branded types, satisfies, compile-time exhaustiveness) never installs in a pure-JS repo.
  • Candidacy does NOT mean universal-subject: command/event-naming, intent-vs-fact splits, and ledger rules are candidates like everything else but subject-bearing — they need their surface (a named event vocabulary, state reconciled elsewhere, an append-only store).
  • Test-scoped rule: its subject is the CODE UNDER TEST, never test-file presence — a zero-test repo with testable logic still earns the general testing rules (cite the testable code). Test rules with a more specific shape (roundtrip laws need encode/decode pairs; property generators need domain invariants) still need THAT shape cited.
  • Every rejected candidate gets a one-line reason, surfaced at Confirm.

Method — DEEP by design; spend the tokens. Every candidate rule is judged against its own full text and the real repo, returning per-rule install + citation or skip + reason. Batching rules that look at the same code across subagents buys parallelism on a large repo; a narrow surface is better served inline — the output SET is what's judged, not the mechanism.

Phase 3 — Confirm (never skip; a request to install is the confirmation, so write, then present)

Present compactly: the extracted facts (each with file evidence), the proposed tag set, and the proposed rule set — each rule as name + citation + its one-line statement (never name-only; the user must see what each rule requires) — plus the rejected candidates grouped with their reasons, plus the hook wiring change for each rule with a gate (Phase 4). The statement is the rule's opening mandate: the file's first sentence, extended to the next only when the first merely scopes or defines without stating the mandate (e.g. derive-dont-sync, module-is-the-noun-functions-are-bare-verbs). Never _Avoid_, Detect:, or Not-when:. The user's answer is the verdict — a corrected set replaces yours without argument; redo the affected phases. When the invocation already asks to install, that request confirms the rules: write them (Phase 4) and present this for correction, the corrected set replacing what you wrote. Otherwise write only after explicit confirmation. A gate's hook wiring is asked first either way. The user confirms the SET here; the written files are theirs afterward.

Propose-only mode: if the invocation asks for a proposal only (evals, dry runs), read propose-only.md and follow it instead of confirming or writing.

Phase 4 — Write

Copy each confirmed rule's file verbatim — no additions — to .claude/sound/<topic>/<rule-name>.md, a plain reference file. <topic> is the rule's parent directory in the corpus. These live OUTSIDE .claude/rules/, so they never auto-load; the browsable .claude/sound/ tree IS the map sound:prime points at. No marker, manifest, or hash anywhere.

A rule with a <rule-name>.gate beside it in the corpus installs that file too, verbatim and executable, and is wired as a pre-commit hook through the hook manager the repo already uses — never a new one. <gate> below is .claude/sound/<topic>/<rule-name>.gate, from the repo root.

Repo showsWire
lefthook.ymlpre-commit: commands: <rule-name>: run: <gate>
.pre-commit-config.yamla repo: local hook: id: <rule-name>, entry: <gate>, language: script, pass_filenames: false
.husky/a <gate> line in .husky/pre-commit
core.hooksPath set to another foldera <gate> line in that folder's pre-commit; folder missing → say so, wire nothing
none of thesea <gate> line in .git/hooks/pre-commit, created executable if absent

An entry already naming <gate> stays as it is. A declined wiring leaves the gate installed but unrun — say so.

Re-runs

If .claude/sound/ already exists, read re-runs.md before writing anything — existing files are user-owned and are reconciled, never overwritten.

Failure modes to keep loud

  • Corpus unreachable / rule file unparseable → stop before writing anything.
  • User declines all tags → Phase 2 still runs over the full corpus; rules whose surface lives behind a declined tag are skipped with that reason. Say that's what happened.
  • Repo has no JS/TS at all → the corpus doesn't apply; say so and install nothing.
  • A selected rule with no citable evidence is a selection BUG — drop it and say so, never install on vibes.
Repository

saadshahd/moo.md

Path

sound/skills/setup/SKILL.md

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.