@damiangilgonzalez/harness 1.3.7

package/skills/cold-outreach/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — cold-outreach
+
+These cases are read by the catalog's routing harness (or by hand). There is no bundled runner. `should_trigger` asserts that the SKILL.md description + body are specific enough that the listed prompt would load `cold-outreach`; `should_not_trigger` asserts a near-miss prompt routes to the named real sibling instead (each `route_to` id must exist in the catalog); and `capability` is a rubric — feed the scenario to an agent with this skill loaded and grade the generated sequence against every `must_include` bullet (each is pass/fail). To sanity-check a *generated* draft against the structural rules, run `../scripts/verify.sh path/to/draft.md` from this directory — it is read-only and flags missing opt-out, multiple CTAs, over-ceiling word count, and spam/AI-tell phrases.

package/skills/cold-outreach/evals/cases.yaml

@@ -0,0 +1,60 @@
+skill: cold-outreach
+
+# Prompts that MUST load `cold-outreach`. The skill owns the COPY of an
+# unsolicited 1:1 touch (cold email, LinkedIn note/DM) and the CADENCE around it
+# (step count, spacing, per-inbox volume, warm-up ramp, compliant footer). It
+# does NOT source the list (lead-gen), set up DNS/auth (email-deliverability),
+# run the CRM after a reply (sales-pipeline), or write the proposal (proposals).
+should_trigger:
+  - prompt: "Write me a cold email to a VP of Engineering pitching our CI/CD tool."
+    why: "Core job — a first-touch cold message to a no-prior-relationship recipient, under the word ceiling with one binary CTA."
+
+  - prompt: "My open rate is fine but I get basically zero replies — can you fix my follow-up sequence?"
+    why: "Non-obvious: the user names a symptom (opens, no replies) not the skill. The 58/42 reply split and the 4-7 step bump table exist for exactly this rescue."
+
+  - prompt: "How many cold emails can I send per inbox per day before I get blacklisted, and how do I warm up a new domain?"
+    why: "Cadence/volume is owned here — per-inbox 20-50/day and the new-domain ramp table. The user is asking about sending rhythm, not DNS auth."
+
+  - prompt: "Escríbeme una secuencia de 4 correos en frío para captar agencias de marketing."
+    why: "Spanish phrasing for a 4-step cold email sequence — same skill regardless of language; the sequence decision table and Spanish skeleton apply."
+
+  - prompt: "Draft a LinkedIn connection note plus a DM bump for these 5 prospects."
+    why: "Channel adaptation — LinkedIn note (≤300 chars, no pitch) + DM sequence is an explicit owned variant with its own char caps and weekly limits."
+
+  - prompt: "This email reads like a template — every prospect can tell it's mail-merged. Make it feel one-to-one."
+    why: "Rescuing copy that 'reads like a template' is an explicit trigger; the one-real-signal rule and the spintax/name-only-merge anti-pattern answer it directly."
+
+should_not_trigger:
+  - prompt: "Set up SPF, DKIM and DMARC on our sending domain so we stop landing in spam."
+    route_to: email-deliverability
+    why: "DNS/auth configuration is the deliverability plumbing; cold-outreach only applies the resulting rules to cadence, it never edits DNS records."
+
+  - prompt: "Find me 200 SaaS CTOs with verified work emails I can email."
+    why: "Sourcing/qualifying the prospect list is lead-gen; cold-outreach assumes a verified recipient already exists."
+    route_to: lead-gen
+
+  - prompt: "A prospect just replied 'yes, interested' — move them to the right stage and set my next follow-up tasks."
+    route_to: sales-pipeline
+    why: "The moment a reply lands the relationship leaves this skill; stages, tasks, and CRM hygiene are sales-pipeline."
+
+  - prompt: "They asked for a proposal — write the SOW and pricing for the engagement."
+    route_to: proposals
+    why: "A cold touch earns a conversation, not a contract; the proposal/SOW/pricing document is owned by proposals."
+
+  - prompt: "Write the launch announcement email to our existing opted-in newsletter list."
+    route_to: marketing
+    why: "Broadcast copy to an opted-in list is marketing, not an unsolicited 1:1 cold touch — different legal basis and different playbook."
+
+capability:
+  - scenario: "Write a full 4-step cold email sequence for a DevOps observability tool, sent to a Head of Platform at a 200-person fintech, including sending cadence and a compliant footer."
+    must_include:
+      - "First touch is under ~80 words."
+      - "Exactly one binary (yes/no) CTA in the first touch — no double ask."
+      - "A plain subject line under ~6 words, no clickbait or spam-trigger words."
+      - "One observed, plausible signal as the hook (not 'I came across your company')."
+      - "Four steps with explicit day offsets (e.g. Day 0 / +3 / +7 / +12)."
+      - "Each step adds one new angle (proof, different pain, breakup) — no 'just following up' filler."
+      - "A breakup step that offers a graceful out."
+      - "A compliant footer: a one-click opt-out line AND a physical postal-address placeholder."
+      - "Per-inbox volume guidance noted (20-50/day) and that warm-up precedes high volume."
+      - "Points DNS/auth setup to email-deliverability rather than configuring it inline."

package/skills/cold-outreach/references/compliance-footer.md

@@ -0,0 +1,50 @@
+# Compliance footer — wording, matrix, LIA checklist
+
+Every cold send needs a footer that (a) identifies you truthfully, (b) gives a working opt-out, and (c) satisfies the recipient's jurisdiction. Write for the **strictest plausible jurisdiction** the recipient could be in. All figures accessed 2026-06-02.
+
+## Jurisdiction matrix
+
+| | CAN-SPAM (US) | GDPR (EU B2B) | CASL (Canada) | Spam Act (Australia) |
+|---|---|---|---|---|
+| Legal basis for cold B2B | Truthful + opt-out (no prior consent) | Art. 6(1)(f) legitimate interest **+ documented LIA** | Implied consent (conspicuous publication / existing relationship) — strict | Inferred consent for conspicuously-published business addresses |
+| Postal address | **Required**, physical | Identify the controller; address recommended | **Required** | Sender identification required |
+| Opt-out window | Within **10 business days** | Without undue delay (**treat 24-48h**) | Honored **without delay**, ≤10 business days | Functional unsubscribe, honored ≤5 business days |
+| Penalty | Up to **$53,088 per email** (Jan 2025) | Up to **€20M or 4%** of global revenue | Up to **CA$10M** per violation | Civil penalties per breach |
+
+*(Sources: Instantly compliance guide / Puzzle Inbox; litemail.ai / complydog GDPR cold-email guides 2026; standard CASL / Australian Spam Act 2003 references.)*
+
+## EU country notes (enforcement varies)
+
+- **UK (ICO) / France (CNIL):** relatively permissive for genuine B2B legitimate-interest outreach.
+- **Germany:** strict — UWG often treated as requiring prior consent for B2B email; tread carefully.
+- **Poland:** frequently requires prior consent even B2B.
+- Default: if you cannot confirm the recipient's country, write to the strictest (assume consent-style) and keep the LIA on file.
+
+## Footer wording (drop-in)
+
+```text
+You're receiving this because {{the legitimate-interest reason — e.g. "you lead
+infra at a team we believe we can help"}}. Not relevant? Reply "stop" or use the
+one-click unsubscribe and you won't hear from us again.
+
+{{Company legal name}}
+{{Physical postal address — street, city, country}}
+Unsubscribe: {{one-click opt-out link}}
+```
+
+Notes:
+- The `Unsubscribe:` link must be backed by an RFC 8058 one-click header (`List-Unsubscribe` + `List-Unsubscribe-Post`) for bulk Gmail/Yahoo sending. **You specify it must exist and be one-click; wiring the header is `email-deliverability`'s job.**
+- "Reply stop" is a fallback, not a substitute for the link.
+- Keep the From/Reply-To accurate and the subject honest — a deceptive subject voids CAN-SPAM compliance on its own.
+
+## Legitimate Interest Assessment (LIA) checklist — EU sends
+
+Keep this documented *before* sending to EU recipients:
+
+1. **Purpose test** — is there a genuine business interest (offering a relevant solution to a relevant role)? Name it.
+2. **Necessity test** — is cold email a proportionate way to reach this interest, or is there a less intrusive route?
+3. **Balancing test** — does your interest override the recipient's privacy expectation? B2B role-based address + relevant offer usually passes; consumer address usually does not.
+4. **Data minimization** — you hold only what's needed (name, role, business email, the signal). No scraped personal/sensitive data.
+5. **Opt-out honored fast** — 24-48h, suppression list updated, never re-contacted.
+
+If any test fails, do not send — that is a targeting problem to take back to `lead-gen`, not a wording fix.

package/skills/cold-outreach/references/hook-derivation.md

@@ -0,0 +1,73 @@
+# Hook derivation — worked OBSERVE → INFER → BRIDGE → PROVE chains
+
+The four-line bridge (SKILL.md → "Deriving the hook") is the method. This file shows it executed across industries so you can pattern-match the *shape* of a good INFER line — the one step that separates a one-to-one email from a mail-merge wearing a name tag.
+
+Read these for the INFER line specifically. Notice that in every good example the inference is something the recipient privately knows but didn't expect a stranger to. That recognition — not flattery, not a value prop — is what earns the reply.
+
+## The test every chain must pass
+
+After drafting the INFER line, ask: **"Would this sentence be FALSE for a competitor in the same situation?"**
+- If it's true of everyone in the industry → it's a platitude. Go back, pick a sharper OBSERVE fact.
+- If it's true only because of *this* specific signal → it's a hook. Ship it.
+
+---
+
+## 1. DevOps / infra tooling
+
+- **OBSERVE:** 3 SRE roles open on their careers page for the full quarter.
+- **INFER:** unfilled for a quarter means the current rotation is thin and absorbing the pages — recruiting isn't keeping up with on-call load.
+- **BRIDGE:** we reduce page volume so a short-staffed rotation survives without the missing hires.
+- **PROVE:** ~40% fewer alerts for two infra teams your size, month one.
+- *Why it passes:* a competitor with a fully staffed team wouldn't feel this. The pain is specific to the unfilled-reqs signal.
+
+## 2. B2B SaaS selling to RevOps
+
+- **OBSERVE:** they just announced a Series B and a new VP of Sales on LinkedIn.
+- **INFER:** post-B2 + new sales leader means the number tripled and the existing pipeline reporting won't survive the new board's scrutiny.
+- **BRIDGE:** we make pipeline forecasts the new VP can defend in week one, not month three.
+- **PROVE:** [named comparable] cut forecast variance from 30% to under 10% in a quarter.
+- *Why it passes:* a flat company with a tenured VP doesn't have the "defend the number to a new board" pain. The funding + hire combination creates it.
+
+## 3. E-commerce / DTC brand
+
+- **OBSERVE:** their site runs a specific subscription app you can see in the page source / their checkout flow.
+- **INFER:** that stack has a known involuntary-churn leak at card-expiry — they're losing ~5-8% of subscribers monthly to failed payments, not to cancellations.
+- **BRIDGE:** we recover the failed-payment cohort before it churns.
+- **PROVE:** [comparable DTC brand] recovered 6% of MRR that was bleeding to dunning failures.
+- *Why it passes:* the inference is tied to a *detectable tech detail*, so it's true of them specifically, not "all DTC brands churn."
+
+## 4. Professional services (agency → mid-market CMO)
+
+- **OBSERVE:** they published a case study landing page but their blog hasn't shipped since Q3.
+- **INFER:** the content engine stalled — likely the one person who owned it left or got pulled onto launches, and the pipeline that content fed is now thinning silently.
+- **BRIDGE:** we keep the demand-gen content shipping without the headcount they just lost.
+- **PROVE:** kept [comparable]'s organic pipeline flat through a content-team gap.
+- *Why it passes:* the gap between "has case studies" and "blog stopped" is the specific, observable evidence of a stall — not a guess.
+
+## 5. Fintech / regulated
+
+- **OBSERVE:** a new compliance regulation with a known enforcement date hits their license type in 6 months.
+- **INFER:** their compliance team is now triaging which controls to retrofit first, and the audit-trail gap is usually the one that surfaces late and panics legal.
+- **BRIDGE:** we close the audit-trail gap so the deadline is a checkbox, not a fire drill.
+- **PROVE:** [comparable] passed the equivalent audit with zero findings on first pass.
+- *Why it passes:* the deadline is real and dated; the inference about *which* control bites last is the insider-grade detail that earns trust.
+
+## 6. When the only signal is weak (the honest fallback)
+
+Sometimes you genuinely cannot find a strong signal — the company is quiet, no hiring, no news. Do NOT fabricate. Two legitimate moves:
+
+- **Use a category-level trigger honestly framed as a hypothesis, not a fake observation.** "Most [role]s at [company size] in [industry] are hitting [specific pain] right now — if that's you, [ask]. If not, ignore me." This is weaker than a real signal (expect reply rates at the low end of the band) but it's honest and still binary.
+- **Kick it back to targeting.** If you keep landing on companies with no signal, the list is the problem, not the copy — that's a `lead-gen` ICP/timing gap. The fix is a better-segmented list with built-in triggers (recently funded, recently hiring, recently launched), not a cleverer sentence.
+
+Never close the gap with an invented "I loved your recent post" — a signal the recipient knows is false destroys the contact on the first line.
+
+## Anti-examples — INFER lines that FAIL the test
+
+| Generic INFER (platitude) | Why it fails | Sharper version |
+|---|---|---|
+| "...so you probably want to grow revenue" | True of every company alive | Tie growth to the specific signal (new funding round → "defend a 3x number") |
+| "...so you care about efficiency" | Vacuous; everyone claims this | Name the specific inefficiency the signal implies |
+| "...AI is transforming your industry" | A trend, not a fact about *them* | Drop it; find a fact you can screenshot |
+| "...I imagine scaling is a challenge" | Hedged guess, no observed basis | Only say it if a hiring/funding signal makes it observable |
+
+The pattern: a failing INFER line is true regardless of the OBSERVE fact. A working one is true *because* of it.

package/skills/cold-outreach/references/templates.md

@@ -0,0 +1,88 @@
+# Templates — first-touch + bump skeletons
+
+Fill **every** `{{slot}}` with a real value before sending. An unfilled slot is a defect. The slots:
+
+- `{{signal}}` — the one true, public, business-relevant trigger (a hiring post, a launch, a number from their site, a role change).
+- `{{outcome}}` — one concrete result you delivered for a comparable team (with a number when you have one).
+- `{{proof}}` — a named comparable, a mini case study, or a metric.
+- `{{ask}}` — the binary yes/no CTA.
+- `{{name}}` / `{{company}}` — recipient + their company.
+
+## Email — first touch (≤ ~80 words)
+
+```text
+Subject: {{signal}}   ← ≤6 plain words, no clickbait
+
+Hi {{name}} — {{signal, stated plainly}}. Usually that means {{the pain it
+implies}}.
+
+We {{outcome}} for {{a comparable team}}.
+
+{{ask}} — yes or no?
+
+— {{your name}}, {{your company}}
+{{compliant footer: see references/compliance-footer.md}}
+```
+
+## Email — 4-step bump (same thread, reply to your own send)
+
+```text
+STEP 1 — Day 0   (the first touch above)
+
+STEP 2 — Day +3   (angle: proof)
+Hi {{name}} — following the note below, here's the concrete version:
+{{proof}}. {{ask}} — yes or no?
+
+STEP 3 — Day +7   (angle: different pain, lower-friction ask)
+One more angle: teams like {{company}} also hit {{second pain}}. I wrote a
+2-page teardown on it — want me to send it? (no call required)
+
+STEP 4 — Day +12 (the breakup)
+Hi {{name}} — I'll stop here so I'm not cluttering your inbox. Should I
+close the file, or is {{the value}} worth 15 minutes later this quarter?
+```
+
+The breakup is the highest-converting follow-up after step 1 — never skip it. Extend to step 5-7 only if a genuinely new `{{signal}}` appears.
+
+## LinkedIn — connection note (≤ ~300 chars, NO pitch)
+
+```text
+Hi {{name}} — {{signal, e.g. "your post on cutting on-call toil"}} resonated.
+Working on the same problem for infra teams; would value connecting.
+```
+
+No ask, no product name in the note. Earn the connection on a real signal.
+
+## LinkedIn — DM bump (after they accept, ~3-4 sentences)
+
+```text
+DM 1 — Day 0 (after accept)
+Thanks for connecting, {{name}}. {{signal}} is exactly what we work on — we
+{{outcome}} for {{comparable team}}. Open to a quick look, or not the right
+time?
+
+DM 2 — Day +4
+No worries if the timing's off. If on-call noise is on your radar this
+quarter, happy to share the {{proof}} we used — say the word.
+
+DM 3 — Day +9 (breakup)
+I'll leave it here, {{name}}. If {{the value}} ever moves up your list, my
+door's open. Either way, glad to be connected.
+```
+
+## Spanish — secuencia de cold email (primer toque, ≤ ~80 palabras)
+
+```text
+Asunto: {{signal}}
+
+Hola {{name}} — {{signal}}. Normalmente eso implica {{el dolor}}.
+
+Logramos {{outcome}} para {{un equipo comparable}}.
+
+{{ask}} — ¿sí o no?
+
+— {{tu nombre}}, {{tu empresa}}
+{{pie de página conforme: ver references/compliance-footer.md}}
+```
+
+Keep the same rules in any language: one true signal, one binary ask, ≤ ~80 words, a compliant footer. The breakup step is mandatory in every sequence.

package/skills/cold-outreach/scripts/verify.sh

@@ -0,0 +1,170 @@
+#!/usr/bin/env bash
+#
+# verify.sh — structural guardrail for a drafted cold email / sequence.
+#
+# WHAT IT DOES (read-only; never edits or writes a file)
+#   Static, network-free checks over ONE draft file you point it at (a cold
+#   email or a multi-step sequence in plain text / markdown):
+#     1. First-touch length: the first message block's body is over ~80 words
+#        -> warn (soft; brevity is a strong preference, not a law).
+#     2. Single binary CTA: more than one question-mark line ("?") in the first
+#        touch -> warn (a cold first touch should ask exactly one binary thing).
+#     3. Opt-out present: no unsubscribe / opt-out / "reply stop" line anywhere
+#        -> FAIL (CAN-SPAM/GDPR hard requirement).
+#     4. Postal address present: no street-style postal-address placeholder
+#        (a line with a digit + a street/PO token, or an explicit
+#        {{address}} / [address] placeholder) -> FAIL (CAN-SPAM requirement).
+#     5. Banlist: spam-trigger + AI-tell phrases ("I hope this email finds you
+#        well", "just circling back", "just following up", "act now",
+#        "100% free", "free guide", "guarantee(d)", "limited time",
+#        "to whom it may concern", "I came across your") -> warn each hit.
+#     6. Unfilled template slots ({{...}}, [SLOT], ???) outside the address
+#        line -> warn (fill before sending).
+#
+#   Only #3 and #4 are hard failures. Everything else is a warning. A clean OR
+#   empty/missing-content file exits 0 — never a false failure.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh draft.md                 # warnings + hard checks
+#   ./verify.sh draft.md --ceiling 100   # raise the first-touch word ceiling
+#   ./verify.sh draft.md --strict        # treat warnings as failures (CI gate)
+#
+# EXIT CODES
+#   0  clean, warnings only (without --strict), or empty/missing-content file
+#   1  a hard failure (no opt-out, or no postal address) — or any warning under --strict
+#   2  bad usage (no file given, or file does not exist)
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays, no bc.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+warn_count=0; fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() { sed -n '2,42p' "$0" | sed 's/^# \{0,1\}//'; }
+
+FILE=""
+CEILING=80
+STRICT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help) usage; exit 0 ;;
+    --ceiling) CEILING="${2:-80}"; shift 2 ;;
+    --strict) STRICT=1; shift ;;
+    -*) printf '%sunknown option: %s%s\n' "$RED" "$1" "$NC" >&2; usage; exit 2 ;;
+    *) if [ -z "$FILE" ]; then FILE="$1"; fi; shift ;;
+  esac
+done
+
+if [ -z "$FILE" ]; then
+  printf '%sno draft file given%s\n' "$RED" "$NC" >&2; usage; exit 2
+fi
+if [ ! -f "$FILE" ]; then
+  printf '%sfile not found: %s%s\n' "$RED" "$FILE" "$NC" >&2; exit 2
+fi
+
+# Empty / whitespace-only file: nothing to check, do not false-fail.
+if [ ! -s "$FILE" ] || ! grep -q '[^[:space:]]' "$FILE" 2>/dev/null; then
+  ok "empty file — nothing to check"
+  exit 0
+fi
+
+printf 'cold-outreach verify — %s (ceiling=%s words)\n\n' "$FILE" "$CEILING"
+
+# --- isolate the first-touch block --------------------------------------------
+# Heuristic: the first touch ends at the first "STEP 2", "Day +", "Follow-up",
+# or a markdown heading after content. We grab everything up to that marker,
+# then strip subject/footer-ish lines for the word count.
+FIRST_BLOCK="$(awk '
+  NR==1 {seen=0}
+  /^[[:space:]]*(STEP[[:space:]]*2|Follow[- ]?up[[:space:]]*2|Day[[:space:]]*\+|DM[[:space:]]*2|##[[:space:]])/ && seen {exit}
+  /[^[:space:]]/ {seen=1}
+  {print}
+' "$FILE")"
+
+# Body words: drop subject lines, unsubscribe/footer lines, and address lines.
+FIRST_WORDS="$(printf '%s\n' "$FIRST_BLOCK" \
+  | grep -iv -e '^[[:space:]]*subject:' -e '^[[:space:]]*asunto:' \
+             -e 'unsubscribe' -e 'opt[- ]out' -e 'reply "stop"' -e 'reply stop' \
+  | tr -s '[:space:]' '\n' | grep -c '[^[:space:]]' || true)"
+
+if [ "${FIRST_WORDS:-0}" -gt "$CEILING" ]; then
+  warn "first touch is ~${FIRST_WORDS} words (over the ${CEILING}-word ceiling) — tighten it"
+else
+  ok "first-touch length ~${FIRST_WORDS} words (<= ${CEILING})"
+fi
+
+# --- single binary CTA in the first touch -------------------------------------
+CTA_LINES="$(printf '%s\n' "$FIRST_BLOCK" | grep -c '?' || true)"
+if [ "${CTA_LINES:-0}" -gt 1 ]; then
+  warn "first touch has ${CTA_LINES} question lines — a cold first touch should ask exactly one binary thing"
+elif [ "${CTA_LINES:-0}" -eq 0 ]; then
+  warn "first touch has no question-mark CTA — add one binary yes/no ask"
+else
+  ok "first touch has exactly one CTA line"
+fi
+
+# --- opt-out present (hard) ----------------------------------------------------
+if grep -Eiq 'unsubscribe|opt[- ]out|reply[[:space:]]+["'\'']?stop|darse de baja|cancelar la suscripci' "$FILE"; then
+  ok "opt-out / unsubscribe line present"
+else
+  fail "no opt-out / unsubscribe line found — CAN-SPAM/GDPR requires a working opt-out"
+fi
+
+# --- postal address present (hard) --------------------------------------------
+# Accept either an explicit placeholder or a line that looks like a street addr.
+if grep -Eiq '\{\{[[:space:]]*(postal[_ ]?)?address|\[[[:space:]]*(postal[_ ]?)?address' "$FILE" \
+   || grep -Eiq '[0-9]+[[:space:]].*(street|st\.|ave|avenue|road|rd\.|blvd|suite|ste\.|p\.?o\.? box|calle|carrer|via)' "$FILE"; then
+  ok "postal address (or placeholder) present"
+else
+  fail "no physical postal address found — CAN-SPAM requires one (a {{address}} placeholder counts)"
+fi
+
+# --- banlist: spam-trigger + AI-tell phrases ----------------------------------
+BAN='i hope this email finds you well|just circling back|just following up|circling back|act now|100% free|free guide|guarantee|limited time|to whom it may concern|i came across your|dear sir or madam'
+HITS="$(grep -Eio "$BAN" "$FILE" 2>/dev/null | sort -u || true)"
+if [ -n "$HITS" ]; then
+  while IFS= read -r h; do
+    [ -n "$h" ] && warn "banned phrase present: \"$h\" (spam-trigger / AI-tell — rewrite)"
+  done <<EOF
+$HITS
+EOF
+else
+  ok "no banned spam/AI-tell phrases"
+fi
+
+# --- unfilled template slots (ignore the address-placeholder convenience) -----
+SLOTS="$(grep -Eo '\{\{[^}]*\}\}|\?\?\?|\[[A-Z_]{3,}\]' "$FILE" 2>/dev/null \
+  | grep -Eiv '\{\{[[:space:]]*(postal[_ ]?)?address|\[[[:space:]]*(POSTAL[_ ]?)?ADDRESS' \
+  | sort -u || true)"
+if [ -n "$SLOTS" ]; then
+  SLOT_N="$(printf '%s\n' "$SLOTS" | grep -c '[^[:space:]]' || true)"
+  warn "${SLOT_N} unfilled template slot(s) remain (e.g. $(printf '%s' "$SLOTS" | head -1)) — fill before sending"
+else
+  ok "no unfilled template slots"
+fi
+
+# --- summary ------------------------------------------------------------------
+printf '\n'
+if [ "$fail_count" -gt 0 ]; then
+  printf '%s%d hard failure(s), %d warning(s)%s\n' "$RED" "$fail_count" "$warn_count" "$NC"
+  exit 1
+fi
+if [ "$warn_count" -gt 0 ]; then
+  if [ "$STRICT" -eq 1 ]; then
+    printf '%s%d warning(s) — failing under --strict%s\n' "$YELLOW" "$warn_count" "$NC"
+    exit 1
+  fi
+  printf '%s%d warning(s), 0 hard failures%s\n' "$YELLOW" "$warn_count" "$NC"
+  exit 0
+fi
+printf '%sall checks passed%s\n' "$GREEN" "$NC"
+exit 0

package/skills/community/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: community
+description: "Use when building or running a persistent two-way community space — Discord, Telegram, Circle: platform choice, structure, onboarding, native→bot→human moderation, rituals, growth loops, health metrics. NOT churn of paying product customers (that is `retention`), NOT broadcast email (that is `newsletter`), NOT one live event (that is `webinar`)."
+tags: [community, discord, telegram, moderation, growth, rituals]
+recommends: [retention, newsletter, social-publisher, brand-voice, whatsapp-telegram, webinar]
+profiles: []
+origin: risco
+---
+
+# community
+
+Run the community like a **product with a job**, not a vanity chat room. The space — a Discord server, a Telegram group+channel, a Circle — is the product. **Onboarding is activation, rituals are the feature, moderation is reliability, and one north-star metric tied to your purpose is the only number that matters.** A room with 5,000 silent members is a failed product, not a big one. Design the system around the conversation, not the conversation itself.
+
+## When NOT to use — route instead
+
+| The ask | Route to |
+|---|---|
+| Stop *paying customers of a product/SaaS* from churning (win-back, lifecycle, NPS) | `retention` |
+| Write the one-to-many broadcast email that nurtures the list | `../newsletter/SKILL.md` |
+| Schedule / cross-post public posts across X, LinkedIn, Instagram | `../social-publisher/SKILL.md` |
+| Run a single timed live event end-to-end (registration, speakers, replay) | `webinar` |
+| Build an automated support desk / ticket triage | `customer-support` |
+| Actually code or host the Discord/Telegram bot (gateway, slash handlers) | `whatsapp-telegram`, `automation-flows` |
+| Define the voice/name/tone the community speaks in | `../brand-voice/SKILL.md` |
+
+You own the **persistent, two-way space and its ongoing operating rhythm.** The boundary that bites most: `retention` keeps *buyers of a product* from churning; you keep *members of a shared space* active and contributing. They rhyme (cohorts, re-activation) but the subject differs — a SaaS seat vs a Discord membership.
+
+## Step 0 — Purpose & north-star gate
+
+**Do not design a single channel until you have (a) a one-line purpose and (b) one business metric tied to it.** Why: a community without a job becomes a dead chat — there is no signal to design toward, so you sprawl channels and beg for activity. This is the most common cause of graveyards.
+
+If either is missing, **STOP and ask one focused batch**, then proceed:
+
+> 1. In one sentence, what is this community *for* — and for whom?
+> 2. What single business outcome does it move? (support deflection, retention uplift, expansion revenue, qualified referrals — pick ONE)
+
+Bad → Good:
+
+```text
+Bad:  "Set up a Discord for our users." → 14 channels, no purpose, silent in 3 weeks.
+Good: Purpose = "where indie game-devs trade WIP feedback so free players become paying supporters."
+      North-star = monthly free→supporter conversions sourced from the server.
+```
+
+Everything below is derived from those two lines. If a channel, ritual, or metric does not serve the purpose or move the north-star, cut it.
+
+## Pick the platform — decision table
+
+| Platform | Best for | Real-time chat | Broadcast | Monetization | Moderation maturity | Cost |
+|---|---|---|---|---|---|---|
+| **Discord** | Active, real-time builder/gamer/dev communities | Strong | Weak (announcement channels only) | Indirect (roles/Patreon links) | High — native AutoMod + bot ecosystem | Free |
+| **Telegram** (group **+** channel hybrid) | Mobile-first, fast-growing, announce-heavy audiences | Good | Strong (channel = one-way broadcast) | Weak native | Medium — native ML anti-spam >200 members + bots | Free |
+| **Circle** | Paid memberships bundling courses/events | Weak | Good | Strong (built-in payments + tiered Spaces) | Medium | Professional ~$89–129/mo → Business ~$199–219 → Circle Plus ~$419+ + 0.5–2% Circle fee on top of Stripe's 2.9%+$0.30 |
+
+Decision rules (pick the *purpose*, not the logo):
+- **Need persistent real-time conversation and free?** → Discord. It is the deepest moderation toolset and the strongest two-way default.
+- **Audience lives on mobile and you broadcast a lot?** → Telegram, run the hybrid: a **channel** for announcements + a **linked group** for discussion. This is the 2026 standard; a bare group has no broadcast lane and a bare channel has no conversation.
+- **You are charging for membership and bundling courses/events?** → Circle. But see the anti-pattern: do not monetize before activation works.
+
+Per-platform setup depth (AutoMod filters, verification levels, anti-spam tiers, plan ladder) is in `references/platform-playbooks.md`.
+
+## Structure & onboarding = activation
+
+Keep the structure **minimal**. Why: empty channels signal a dead room; people pattern-match "nobody's here" and leave. Start with the fewest channels the purpose needs (often 4–6: welcome/rules, intros, one core topic, help, off-topic, announcements) and split a channel only when an existing one is *demonstrably overflowing*.
+
+The onboarding path is an activation funnel. Drive every new member to a **first meaningful action** through a short, gated path:
+
+1. **Role-on-join** — pick a role/interest, which personalizes which channels they see. Why: a tailored, smaller room feels alive; the firehose feels dead.
+2. **Rules/membership gate** — on Discord, Rules Screening / Membership Screening blocks talking and DMs until rules are acknowledged. Why: it stops drive-by spam *and* forces a first deliberate click.
+3. **Intro with a prompt** — not "introduce yourself" (blank-page freeze) but a 3-field prompt. Why: prompted intros get answered; open ones get skipped.
+4. **Point to where-to-ask** — one obvious channel for "I need help." Why: time-to-first-response is a core health metric and it starts here.
+
+Bad → Good intro channel:
+
+```text
+Bad:  #introductions — "Say hi and introduce yourself!"  → blank-page paralysis, 4% post.
+Good: #introductions — pinned prompt: "(1) what you're building, (2) what you're stuck on,
+       (3) one thing you can help others with." → reply with the right role-ping. Activation jumps.
+```
+
+## Moderation — the 3-layer stack
+
+Moderation is reliability. The canonical stack is **native → bot → human**, and you scale layers by size, never skip the native layer.
+
+1. **Native** — Discord AutoMod (one Commonly-Flagged-Words preset rule + up to 6 custom keyword rules, each filter holding up to 1,000 terms, plus a mention-spam cap configurable up to 50 unique mentions/message) and an explicit **verification level** (Medium = verified email + 5-min-on-server before talking). Telegram: native ML anti-spam kicks in for groups **>200 members** (with an "Aggressive" auto-delete mode); for **≤30 messages/hour, slow-mode alone** is the right zero-setup control; add a CAPTCHA-on-join gate (button/math/question, e.g. Shieldy) as the raid wall.
+2. **Bot** — a specialized moderation bot for raid detection, scam-link filtering, and audit logs.
+3. **Human** — named mods, an escalation path, and a written ban policy.
+
+Size-tiered config (Discord, per Discord's own size guidance):
+
+| Server size | Native | Bot layer | Human |
+|---|---|---|---|
+| < 1,000 | AutoMod + Medium verification | optional | 1–2 mods |
+| > 1,000 | AutoMod + custom keyword rules | add one specialized bot | rota of mods |
+| > 10,000 | + Commonly-Flagged filter on | robust multi-tool bots | mod team + on-call |
+| > 100,000 | full filters + raid mode | multiple specialized bots | tiered mod org |
+
+Incident + ban policy (write these down before you need them):
+- **Ban policy is a rubric, not a mood** — define warn → mute → kick → ban thresholds and what triggers each. Why: inconsistent bans destroy trust faster than the spam did.
+- **Raid runbook** — who flips lockdown (slow-mode + raise verification + pause invites), who triages, where it is logged.
+- **Scam-DM stance** — pin a "we will never DM you first" notice; AutoMod-flag known scam phrases.
+
+Filter specifics, verification levels, and bot picks by tier live in `references/platform-playbooks.md`.
+
+## Rituals — the operating rhythm
+
+**Predictable cadence beats sporadic heroics.** Why: members learn when to show up only if there is something to show up *for*; rhythm is the feature that pulls lurkers back. Install a small set of recurring beats and run them on time, every time.
+
+Sample weekly cadence:
+
+| Day | Ritual | Friction |
+|---|---|---|
+| Mon | "What are you working on this week?" thread | Low — one reply |
+| Wed | Office hours / AMA in a voice or thread slot | Medium — opt-in |
+| Fri | "Wins of the week" — share + react | Low — a reaction counts |
+
+Design for **low-friction participation**: polls, emoji reactions, and *opt-in* role pings. The over-pinging trap: blasting `@everyone` for non-urgent posts. Why it backfires — over-pinging trains members to mute the server, and a muted member is functionally gone. Use a dedicated opt-in "announcements" role and reserve `@everyone` for genuine all-hands moments.
+
+A ritual template library and the full cadence rationale are in `references/metrics-and-rituals.md`.
+
+## Growth — loops, not buys
+
+Build loops that compound, not headcount that decays:
+- **Referral loop** — make inviting a friend a one-tap, rewarded action tied to a role/perk.
+- **Intro loop** — every prompted intro is a hook other members reply to, pulling the newcomer into a thread on day one.
+- **Partner cross-post** — trade shout-outs with an adjacent community whose audience overlaps but does not compete.
+
+**90-9-1 is a range, not a ceiling.** The old "1% rule" (90% lurk, 9% occasional, 1% drive activity) is a *starting observation*, not a law — healthier communities skew far more active (real profiles like 55-30-15 and 17-57-26). Design to **move lurkers up a tier** (prompts, easy reactions, direct asks), do not accept 90% lurkers as fixed.
+
+```text
+Bad:  Buy 2,000 members from a growth service to "look big."  → DAU/MAU craters,
+       signal drowns in silence, real members read the room as dead and leave.
+Good: Run a referral ritual + prompted intros. 200 members who each reply
+       in week one beats 2,000 who never speak.
+```
+
+Bought or inactive members are **negative-value**: they dilute every signal, wreck DAU/MAU, and make the room *look* dead to the people you actually want.
+
+## Metrics & health
+
+Three clusters plus exactly one business metric. Steer on these, not on raw member count.
+
+| Metric | What it tells you | Target |
+|---|---|---|
+| DAU/MAU stickiness | How often members come back | Floor ≥ 20%; social/messaging band ~50–80% |
+| 30/60/90-day cohort retention | Whether onboarding actually activates | Track each cohort vs the last |
+| Returning-member ratio | Rhythm is working | Trending up |
+| Time-to-first-response (TTFR) | A newcomer's first experience | Minutes-to-low-hours, the lower the better |
+| Answered rate | Questions don't die unanswered | → 100% |
+| **One business metric** (purpose-tied) | The only number that justifies the work | Set in Step 0 |
+
+The one business metric is a menu — **pick exactly one** that matches your purpose: support deflection, retention uplift, expansion revenue, or qualified referrals. Review the scorecard on a fixed cadence (weekly glance, monthly cohort read). Benchmark depth and metric definitions are in `references/metrics-and-rituals.md`.
+
+## The artifact you emit
+
+Produce two files the user can apply directly: a `community-plan.md` (prose: purpose, platform rationale, structure, growth, metrics) and a machine-checkable `moderation-config.yaml`:
+
+```yaml
+platform: discord            # discord | telegram | circle
+purpose: "where indie game-devs trade WIP feedback so free players become paying supporters"
+north_star_metric: "monthly free→supporter conversions sourced from the server"
+onboarding_path:
+  - role-on-join
+  - rules-gate
+  - prompted-intro
+  - where-to-ask
+moderation:
+  layers:
+    native: "AutoMod preset + custom keyword rules, Medium verification"
+    bot: "specialized raid + scam-link bot"
+    human: "2 named mods, written ban rubric"
+rituals:
+  - name: "WIP Mondays"
+    cadence: "weekly"
+  - name: "Wins Fridays"
+    cadence: "weekly"
+```
+
+Then validate it:
+
+```bash
+scripts/verify.sh path/to/moderation-config.yaml
+```
+
+`verify.sh` checks the required keys exist, that `north_star_metric` is non-empty, that all three moderation layers are declared, and that at least one ritual has a cadence — it catches the most common defect (a "plan" with no purpose, no mod layers, or no rhythm). **Do not go live until it passes and the north-star plus at least one health metric (TTFR or DAU/MAU) are instrumented.**
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| Channel sprawl on day one | Empty channels read as "dead"; people leave | Start 4–6; split only on demonstrated overflow |
+| No purpose / no north-star | Nothing to design toward → graveyard | Run Step 0 gate before any structure |
+| `@everyone` for non-urgent posts | Trains members to mute → functionally gone | Opt-in announce role; reserve `@everyone` |
+| Buying members to "look big" | Negative-value: dilutes signal, wrecks DAU/MAU | Referral + intro loops; activate the real ones |
+| Ban-by-mood | Inconsistency destroys trust | Written warn→mute→kick→ban rubric |
+| Treating 90% lurkers as permanent | Leaves activation on the table | 90-9-1 is a range; move lurkers up a tier |
+| Monetizing on Circle before activation works | Charging for a dead room churns instantly | Prove rhythm + retention, then gate/monetize |
+| Broadcasting in a two-way space | Wrong tool; kills conversation | One-to-many → `../newsletter/SKILL.md` / `../social-publisher/SKILL.md` |