@damiangilgonzalez/harness 1.3.7

package/skills/wait-what/evals/cases.yaml

@@ -0,0 +1,32 @@
+skill: wait-what
+
+should_trigger:
+  - prompt: "Espera, ese ultimo mensaje no ha calado, vuelve a plantearlo."
+    why: "Disparador directo de wait-what."
+  - prompt: "Wait, that last message did not land, rephrase it."
+    why: "Disparador directo de wait-what."
+  - prompt: "Para, no he entendido bien lo que acabas de decir, explicalo de otra forma."
+    why: "Disparador directo de wait-what."
+  - prompt: "Creo que no me has entendido, vuelve a intentarlo."
+    why: "Disparador directo de wait-what."
+  - prompt: "Eso no es lo que pedi, replanteatelo."
+    why: "Disparador directo de wait-what."
+
+should_not_trigger:
+  - prompt: "Implementa la funcionalidad que describimos."
+    route_to: "implement"
+    why: "Implementar la funcionalidad es el trabajo de implement, no de wait-what."
+  - prompt: "Revisa el codigo de este PR."
+    route_to: "code-review"
+    why: "Revisar el codigo de un PR es el trabajo de code-review, no de wait-what."
+  - prompt: "Documenta esta decision de arquitectura."
+    route_to: "write-adr"
+    why: "Documentar una decision de arquitectura es el trabajo de write-adr, no de wait-what."
+  - prompt: "Genera tickets a partir de este plan."
+    route_to: "to-tickets"
+    why: "Generar tickets a partir de un plan es el trabajo de to-tickets, no de wait-what."
+
+capability:
+  - scenario: "El usuario indica que el ultimo mensaje del agente no encajo y pide replantearlo."
+    must_include:
+      - "replant"

package/skills/wayfinder/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: wayfinder
+description: "Plans a huge chunk of work — more than fits in a single agent session — as a shared map of decision tickets in the repo's issue tracker, and resolves them one at a time until the path to the destination is clear."
+tags: ["planning", "issue-tracker", "large-scale-work"]
+disable-model-invocation: true
+profiles: [core, ui, full]
+---
+
+Ha llegado una idea difusa — demasiado grande para una sola sesión de agente, y envuelta en niebla: todavía no se ve el camino de aquí al **destino**. El wayfinding trata de encontrar ese camino, no de embestir contra el destino. Esta skill traza el camino como un **mapa compartido** en el issue tracker del repo, y luego trabaja sus **tickets de decisión** — preguntas cuya resolución es una decisión, no porciones de una construcción a ejecutar — de uno en uno hasta que la ruta está clara.
+
+El destino varía en cada esfuerzo, y nombrarlo es el primer acto de trazado — le da forma a cada ticket. Puede ser una spec para entregar e iterar, una decisión que cerrar antes de que empiece la planificación, o un cambio hecho en el sitio como una migración de estructura de datos. El mapa es agnóstico al dominio — trabajo de ingeniería, contenido de un curso, lo que encaje con la forma.
+
+## Planifica, no ejecutes
+
+Wayfinder es **planificación** por defecto: cada ticket resuelve una decisión, y el mapa está terminado cuando el camino está claro — no queda nada que decidir antes de que alguien vaya y haga la cosa. La tentación de simplemente ponerse a hacer el trabajo suele ser la señal de que has llegado al borde del mapa y toca hacer el traspaso. Un esfuerzo puede anular esto en sus **Notas** — llevando la ejecución al propio mapa — pero, salvo eso, produce decisiones, no entregables.
+
+## Refiérete por nombre
+
+Todo mapa y todo ticket es un issue, así que tiene un **nombre** — su título. En todo lo que lee la persona — narración, Decisiones-hasta-ahora del mapa — refiérete a él por ese nombre, nunca por un id, número o slug pelado. Un muro de `#42, #43, #44` es ilegible; los nombres se leen de un vistazo. El id y la URL no desaparecen — un nombre envuelve su enlace — pero viajan *dentro* del nombre, nunca lo sustituyen.
+
+## El Mapa
+
+El mapa es un único issue en el issue tracker de este repo, etiquetado `wayfinder:map` — el artefacto canónico. Sus tickets son issues hijos del mapa.
+
+El mapa es un **índice**, no un almacén. Lista las decisiones tomadas y apunta a los tickets que guardan su detalle; una decisión vive en exactamente un sitio — su ticket — así que el mapa nunca la reescribe, solo la resume y enlaza.
+
+**Dónde viven físicamente el mapa, sus tickets hijos, el bloqueo y las consultas de frontera es específico del tracker.** El tracker de este repo es **GitHub Issues** (org `symplia-tech`), accedido con la CLI `gh`. Consulta la sección "Operaciones de wayfinding" más abajo para saber cómo _este_ repo las expresa. Si trabajas sin acceso a GitHub, recurre al tracker de markdown local (fallback, también descrito abajo).
+
+### El cuerpo del mapa
+
+El mapa entero en baja resolución, cargado una vez por sesión. Los tickets abiertos **no** se listan — son issues hijos abiertos, encontrados por consulta.
+
+```markdown
+## Destino
+
+<cómo se ve llegar al final de este mapa — la spec, decisión o cambio hacia el que este esfuerzo encuentra su camino. Una o dos líneas; cada sesión se orienta hacia esto antes de elegir un ticket.>
+
+## Notas
+
+<dominio; skills que cada sesión debería consultar; preferencias permanentes de este esfuerzo>
+
+## Decisiones hasta ahora
+
+<!-- el índice — una línea por ticket cerrado: lo justo para juzgar relevancia, luego se hace zoom al enlace para el detalle que el ticket guarda -->
+
+- [<título del ticket cerrado>](enlace) — <resumen de una línea de la respuesta>
+
+## Aún sin especificar
+
+<!-- ver "Niebla de guerra": niebla dentro del alcance que aún no puedes convertir en ticket; gradúa a medida que la frontera avanza -->
+
+## Fuera de alcance
+
+<!-- ver "Fuera de alcance": trabajo descartado más allá del destino; cerrado, nunca gradúa -->
+```
+
+### Tickets
+
+Cada ticket es un **issue hijo** del mapa; el id del issue en el tracker es su identidad. Su cuerpo es la pregunta, dimensionada a una sesión de agente de 100K tokens:
+
+```markdown
+## Pregunta
+
+<la decisión o investigación que este ticket resuelve>
+```
+
+Cada ticket lleva una etiqueta `wayfinder:<tipo>` — una de `research`, `prototype`, `grilling`, `task` (ver [Tipos de ticket](#tipos-de-ticket)).
+
+Una sesión **reclama** un ticket asignándolo al dev que dirige el mapa, **primero**, antes de cualquier trabajo, para que las sesiones concurrentes lo salten. Ese asignado _es_ la reclamación: un ticket abierto y sin asignar está sin reclamar.
+
+El bloqueo usa la relación de dependencia **nativa** del tracker — esencial porque renderiza la frontera _visualmente_ en la propia UI del tracker, para que la persona vea qué es tomable sin abrir el mapa. Solo un tracker que carezca de bloqueo nativo cae al convenio en el cuerpo. Un ticket está **desbloqueado** cuando todo ticket que lo bloquea está cerrado; la **frontera** son los hijos abiertos, desbloqueados y sin reclamar — el borde de lo conocido.
+
+La respuesta no es parte del cuerpo — se registra al resolver (ver [Trabajar el mapa](#trabajar-el-mapa)). Los activos creados al resolver un ticket se enlazan desde el issue, no se pegan dentro.
+
+## Tipos de ticket
+
+Todo ticket es o bien **HITL** — human in the loop, trabajado *con* una persona que habla por sí misma — o **AFK**, conducido por el agente en solitario. Un ticket HITL solo se resuelve a través de ese intercambio en vivo; el agente nunca sustituye el lado humano (un agente de grilling que responde sus propias preguntas ha roto esto).
+
+- **Research** (AFK): Leer documentación, APIs de terceros, o recursos locales como bases de conocimiento para sacar a la luz un hecho del que depende una decisión. Se resuelve con un **subagente** `/research`. Úsalo cuando se requiere conocimiento fuera del directorio de trabajo actual.
+- **Prototype** (HITL): Subir la fidelidad de la discusión creando un artefacto concreto, barato y tosco al que reaccionar — un esquema, un boceto, un stub, o código de UI/lógica vía la skill `/prototype`. Enlaza el prototipo como activo. Úsalo cuando "cómo debería verse" o "cómo debería comportarse" es la pregunta clave.
+- **Grilling** (HITL): Conversación vía las skills `/grilling` y `/domain-modeling`, una pregunta cada vez. El caso por defecto.
+- **Task** (HITL o AFK): Trabajo manual que debe ocurrir antes de que una *decisión* pueda tomarse — nada que decidir, prototipar ni investigar, pero la discusión está bloqueada hasta que esté hecho. Darse de alta en un servicio para poder juzgar su API, provisionar accesos, mover datos para poder ver su forma. Este es el único tipo que *hace* en vez de decidir — y se gana su sitio por desbloquear una decisión, no por entregar el destino. El agente lo conduce en solitario donde puede (AFK); si no, entrega a la persona un checklist preciso (HITL). Se resuelve cuando el trabajo está hecho; la respuesta registra qué se hizo y cualquier hecho resultante (ubicación de credenciales, nuevas URLs, conteos de filas) del que dependan tickets posteriores.
+
+## Niebla de guerra
+
+El mapa está _deliberadamente_ incompleto: no traces lo que aún no puedes ver. Más allá de los tickets vivos está la **niebla de guerra** — la vista tenue de decisiones e investigaciones que intuyes que vienen pero aún no puedes fijar, porque penden de preguntas todavía abiertas. Resolver un ticket despeja la niebla que tiene delante, graduando lo que ahora es especificable en tickets frescos — de uno en uno, hasta que el camino al destino está claro y no quedan tickets.
+
+La sección **Aún sin especificar** del mapa es donde se escribe esa vista tenue: la pregunta sospechada, el área a revisitar más tarde. Es la frontera aún no descubierta _hacia_ el destino — todo lo de aquí está dentro de alcance, solo que no lo bastante nítido para ticketizar. Escribe tan flojo o tan completo como la vista permita; sirve además de señal para los colaboradores que leen hacia dónde se dirige el esfuerzo.
+
+**¿Niebla o ticket?** La prueba es si puedes enunciar la pregunta con precisión ahora — _no_ si puedes responderla ahora.
+
+- **Ticket cuando** la pregunta ya es nítida — aunque esté bloqueada y aún no puedas actuar sobre ella.
+- **Aún sin especificar cuando** todavía no puedes formularla con esa nitidez. No pre-cortes la niebla en piezas del tamaño de un ticket: es más gruesa que un ticket, y un parche puede graduar en varios tickets, o en ninguno, cuando la frontera lo alcance.
+
+**Aún sin especificar** excluye lo ya decidido (Decisiones hasta ahora), lo que ya es un ticket vivo, y lo que está fuera de alcance (la sección siguiente).
+
+## Fuera de alcance
+
+La niebla solo se acumula _hacia_ el destino. El destino fija el alcance, así que el trabajo más allá de él está **fuera de alcance** — no es niebla, y no pertenece a **Aún sin especificar**. Tiene su propia sección **Fuera de alcance** en el mapa: trabajo que has descartado conscientemente de _este_ esfuerzo. El alcance, no la nitidez, lo lleva aquí.
+
+El trabajo fuera de alcance nunca gradúa — la frontera se detiene en el destino — así que solo vuelve si el destino se redibuja, y entonces como un esfuerzo fresco, no una reanudación.
+
+Descartar algo por alcance es un acto de scoping, no un paso en la ruta. Cuando un ticket que ya existe resulta estar más allá del destino — mal encajado al trazar, o expuesto por una resolución — **ciérralo** (un ticket cerrado está inequívocamente fuera de la frontera) y deja una línea en la sección **Fuera de alcance**: el resumen más por qué está fuera de alcance, enlazando el ticket cerrado. Se queda fuera de **Decisiones hasta ahora**, que registra la ruta realmente recorrida — un límite de alcance no es un paso en ella.
+
+## Invocación
+
+Dos modos. En cualquiera de los dos, **nunca resuelvas más de un ticket por sesión** — con la excepción de los tickets de research.
+
+### Trazar el mapa
+
+La persona invoca con una idea difusa.
+
+1. **Nombra el destino.** Corre una sesión de `/grilling` y `/domain-modeling` para fijar hacia qué encuentra su camino este mapa — la spec, decisión o cambio. El destino fija el alcance, así que se establece primero.
+2. **Mapea la frontera.** Vuelve a interrogar, esta vez **en anchura**: despliégate por todo el espacio en lugar de profundizar en un solo hilo, sacando a la luz las decisiones abiertas y los primeros pasos tomables ahora. **Si esto no saca niebla** — el camino al destino ya está claro, el viaje entero es lo bastante pequeño para una sesión — no necesitas un mapa. Para y pregunta a la persona cómo quiere proceder.
+3. **Crea el mapa** (etiqueta `wayfinder:map`): Destino y Notas rellenos, Decisiones-hasta-ahora vacío, la niebla esbozada en **Aún sin especificar**.
+4. **Crea los tickets que puedas especificar ahora** como issues hijos del mapa — luego cablea las aristas de bloqueo en una **segunda pasada** (los issues necesitan ids antes de poder referenciarse). El cableado los ordena en la frontera y en los bloqueados; todo lo que aún no puedes especificar se queda en la niebla — la sección **Aún sin especificar**.
+5. **Dispara los subagentes de research.** Por cada ticket `research` que acabas de crear, levanta un subagente `/research` para resolverlo en paralelo, capturando sus hallazgos en una rama desechable `research/<nombre>` con un puntero de contexto desde el ticket.
+6. Para — trazar es el trabajo de una sesión; no resuelve ningún ticket a mano.
+
+### Trabajar el mapa
+
+La persona invoca con un mapa (URL o número). Un ticket es **opcional** — sin él, tú eliges la siguiente decisión, no la persona.
+
+1. Carga el **mapa** — la vista de baja resolución, no cada cuerpo de ticket.
+2. Elige el ticket. Si la persona nombró uno, úsalo. Si no, toma el primer ticket de la frontera en orden. **Reclámalo**: asígnatelo antes de cualquier trabajo.
+3. Resuélvelo — **haz zoom según haga falta**: trae el cuerpo completo de cualquier ticket relacionado o cerrado bajo demanda; invoca las skills que nombra el bloque `## Notas`. En caso de duda, usa `/grilling` y `/domain-modeling`.
+4. Registra la resolución: publica la respuesta como un **comentario de resolución**, **cierra** el issue, y **añade un puntero de contexto** a las Decisiones-hasta-ahora del mapa.
+5. Añade los tickets recién surgidos (crear-luego-cablear); gradúa cualquier niebla que la respuesta haya hecho especificable, limpiando cada parche graduado de **Aún sin especificar** para que viva solo como su nuevo ticket. Si la respuesta revela que un ticket — este u otro — está más allá del destino, **descártalo por alcance** en vez de resolverlo en la ruta. Si la decisión invalida otras partes del mapa, actualiza o borra esos tickets.
+
+La persona puede correr tickets desbloqueados en paralelo, así que espera que otras sesiones editen el tracker de forma concurrente.
+
+## Operaciones de wayfinding (GitHub Issues vía `gh`)
+
+Mapeo concreto de cada operación abstracta al tracker de este repo. GitHub Issues soporta sub-issues nativos y relaciones de dependencia ("blocked by").
+
+| Operación | Cómo | Comando de referencia |
+|---|---|---|
+| Crear el mapa | Issue con etiqueta `wayfinder:map` | `gh issue create --title "<nombre>" --label wayfinder:map --body "<cuerpo>"` |
+| Crear un ticket | Issue hijo del mapa con `wayfinder:<tipo>` | `gh issue create --title "<pregunta>" --label wayfinder:grilling` y enlazarlo como sub-issue del mapa |
+| Etiquetas de tipo | `wayfinder:research` · `wayfinder:prototype` · `wayfinder:grilling` · `wayfinder:task` | Crear las etiquetas una vez con `gh label create` |
+| Reclamar un ticket | Autoasignarse el issue | `gh issue edit <n> --add-assignee @me` |
+| Bloqueo | Relación nativa "blocked by" entre issues (sub-issues/dependencias); fallback: línea `Blocked by: #<n>` en el cuerpo | UI de GitHub o API GraphQL |
+| Consultar frontera | Issues hijos abiertos, sin asignar y desbloqueados | `gh issue list --label wayfinder:grilling --state open --assignee ""` (filtra bloqueados a mano) |
+| Registrar resolución | Comentario + cerrar | `gh issue comment <n> --body "<respuesta>"` y `gh issue close <n>` |
+
+Si no hay acceso a GitHub Issues, usa el **fallback de markdown local**: un único fichero `wayfinder-map.md` como mapa, y un fichero por ticket bajo `.wayfinder/tickets/<id>-<slug>.md`; el bloqueo se expresa con una línea `Bloqueado por: <id>` en el cuerpo del ticket, y la frontera se calcula leyendo los tickets abiertos cuyos bloqueadores están todos cerrados.

package/skills/wayfinder/evals/cases.yaml

@@ -0,0 +1,32 @@
+skill: wayfinder
+
+should_trigger:
+  - prompt: "Este bloque de trabajo es enorme, planificalo como un mapa de tickets."
+    why: "Disparador directo de wayfinder."
+  - prompt: "Necesito resolver este trabajo de decision en decision hasta terminarlo."
+    why: "Disparador directo de wayfinder."
+  - prompt: "Ayudame a planificar algo que no cabe en una sola sesion."
+    why: "Disparador directo de wayfinder."
+  - prompt: "Plan this huge chunk of work as a shared map of decision tickets."
+    why: "Disparador directo de wayfinder."
+  - prompt: "Quiero un mapa compartido de tickets para este proyecto grande."
+    why: "Disparador directo de wayfinder."
+
+should_not_trigger:
+  - prompt: "Implementa un ticket pequeno que ya esta bien definido."
+    route_to: "implement"
+    why: "Implementar el codigo es el trabajo de implement, no de wayfinder."
+  - prompt: "Escribe un solo ticket para una tarea concreta."
+    route_to: "to-tickets"
+    why: "Escribir un solo ticket es el trabajo de to-tickets, no de wayfinder."
+  - prompt: "Revisa los cambios de una rama."
+    route_to: "revision-de-cambios"
+    why: "Revisar los cambios de una rama es el trabajo de revision-de-cambios, no de wayfinder."
+  - prompt: "Documenta una decision de arquitectura puntual."
+    route_to: "write-adr"
+    why: "Documentar una decision de arquitectura puntual es el trabajo de write-adr, no de wayfinder."
+
+capability:
+  - scenario: "El usuario tiene un bloque de trabajo demasiado grande para una sesion."
+    must_include:
+      - "ticket"

package/skills/webhooks/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: webhooks
+description: "Use when building the receiving end of a webhook — a provider-agnostic endpoint that proves pushed events are authentic and never processes one twice: raw-body HMAC, ~5-min replay window, idempotency on the event id, fast-ack-then-queue. NOT the Stripe-Signature scheme (that is stripe), NOT outbound clients you call (that is api-connector-builder)."
+tags: [webhooks, inbound-webhooks, hmac-verification, idempotency, signature-verification, queue, connectors]
+recommends: [stripe, email-connector, api-connector-builder, automation-flows, redis, secure-coding]
+profiles: []
+origin: risco
+---
+
+# Webhooks — the inbound front door that survives retries and forgeries
+
+You are building the side of a webhook that *receives*. Some external system
+pushes an HTTP POST at your endpoint; your job is to prove it is real, refuse to
+act on it twice, and answer fast. That is the whole mandate.
+
+This skill is provider-agnostic — it teaches the mechanics every webhook source
+shares, not any one vendor's event catalog — and it ends at "enqueued." What
+happens to the event afterward is a different job:
+
+- The Stripe-specific scheme (`Stripe-Signature`, `t=,v1=`, `stripe listen`,
+  the event model) → `../stripe/SKILL.md`.
+- Email bounce/complaint webhooks where the point is suppression state →
+  `../email-connector/SKILL.md`.
+- The *outbound* client that calls someone else's API → `api-connector-builder`.
+- Multi-step orchestration after the event lands → `automation-flows`.
+- Broker/queue tuning (BullMQ concurrency, DLQ ops) → `redis`.
+- Constant-time compare, secret handling, supply-chain hygiene →
+  `../secure-coding/SKILL.md`.
+
+## The pipeline
+
+These five stages run in exactly this order. Each one exists to protect the one
+after it; reorder them and you either trust forged data or waste work.
+
+| # | Stage | Why it precedes the next |
+|---|-------|--------------------------|
+| 1 | Read the **raw body** | Parsing first destroys the bytes the signature was computed over. Capture the raw buffer before any JSON parse. |
+| 2 | **Verify the signature** | Until this passes, every field in the body is attacker-controlled. Verify before you read anything. |
+| 3 | Check the **timestamp window** | A cheap reject of replayed-but-valid payloads, before you touch a datastore. |
+| 4 | **Dedupe** on the event id | At-least-once delivery means duplicates are normal. Mark it seen before doing work, not after. |
+| 5 | **Persist/enqueue → `2xx`** | Hand the event to durable storage, then ack. The ack means "I own this now." |
+
+**Delivery is at-least-once, never exactly-once.** Every major provider retries
+on non-2xx or timeout, so duplicate deliveries are normal traffic and idempotency
+is required, not a nice-to-have.
+
+## Verify the signature
+
+**Verify over the raw bytes, never over re-serialized JSON.** Re-serializing a
+parsed object reorders keys and normalizes whitespace, so the HMAC you compute
+no longer matches the one the sender computed. This is the single most common
+cause of "signature fails even though the secret is right."
+
+```js
+// Bad — body was parsed, so the bytes are gone. HMAC will never match.
+app.post("/webhooks", express.json(), (req, res) => {
+  const expected = sign(JSON.stringify(req.body)); // reordered, re-spaced
+});
+
+// Good — keep the raw buffer for the HMAC; parse only after verifying.
+app.post("/webhooks", express.raw({ type: "*/*" }), (req, res) => {
+  const raw = req.body; // a Buffer, the exact bytes received
+  if (!verify(raw, req.headers)) return res.sendStatus(400);
+  const event = JSON.parse(raw.toString("utf8"));
+});
+```
+
+**Compare signatures in constant time.** A normal `===`/`==` short-circuits on
+the first differing byte, which leaks how much of the signature an attacker
+guessed correctly. Use `crypto.timingSafeEqual` (Node) or `hmac.compare_digest`
+(Python). The buffers must be equal length, so guard that first.
+
+The cross-vendor **Standard Webhooks** spec (adopted by Svix, Clerk, Resend,
+Brex and others) defines the scheme this skill defaults to: headers
+`webhook-id`, `webhook-timestamp`, `webhook-signature`; the signature is
+`base64(HMAC-SHA256(secret, "{id}.{timestamp}.{body}"))`, version-prefixed as
+`v1,<sig>`, and the header may carry **space-separated** signatures so a secret
+can be rotated without dropped deliveries — accept the request if **any** match.
+
+```js
+import crypto from "node:crypto";
+
+function verify(raw, headers) {
+  const id = headers["webhook-id"];
+  const ts = headers["webhook-timestamp"];
+  const secret = process.env.WEBHOOK_SECRET; // never a literal
+  const signed = `${id}.${ts}.${raw.toString("utf8")}`;
+  const expected = crypto
+    .createHmac("sha256", Buffer.from(secret, "base64"))
+    .update(signed)
+    .digest("base64");
+  // header is "v1,<sig> v1,<sig2>"; accept if any matches (secret rotation)
+  return String(headers["webhook-signature"] || "")
+    .split(" ")
+    .map((part) => part.split(",")[1])
+    .some((sig) => sameLength(sig, expected) &&
+      crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)));
+}
+const sameLength = (a = "", b = "") => a.length === b.length;
+```
+
+```python
+import hmac, hashlib, base64, os
+
+def verify(raw: bytes, headers) -> bool:
+    secret = base64.b64decode(os.environ["WEBHOOK_SECRET"])  # never a literal
+    signed = f'{headers["webhook-id"]}.{headers["webhook-timestamp"]}.'.encode() + raw
+    expected = base64.b64encode(hmac.new(secret, signed, hashlib.sha256).digest()).decode()
+    sent = headers.get("webhook-signature", "")
+    for part in sent.split(" "):          # space-separated for rotation
+        sig = part.split(",", 1)[-1]
+        if hmac.compare_digest(sig, expected):  # constant time
+            return True
+    return False
+```
+
+Per-provider header formats (Stripe `t=,v1=`, GitHub `X-Hub-Signature-256`,
+Shopify base64 HMAC, Slack `v0=`, Svix) all map onto the same primitive —
+mapping table and per-language verify primitives in
+`references/signature-schemes.md`.
+
+## Timestamp & replay
+
+A valid signature does not stop a replay: an attacker who captures one delivery
+can re-send the exact bytes, signature intact. Bound it with a timestamp.
+
+**Reject any event whose `webhook-timestamp` is more than ~5 minutes from now.**
+That five-minute window is the de-facto industry value (Benchling and others
+recommend it). The Standard Webhooks spec mandates that you perform *a*
+tolerance check but does not fix the number — pick a small one.
+
+```js
+const skewSeconds = Math.abs(Date.now() / 1000 - Number(ts));
+if (skewSeconds > 300) return res.sendStatus(400); // outside the 5-min window
+```
+
+The timestamp window bounds *how long* a captured payload is replayable; the
+idempotency check (next section) stops *exact* replays that arrive inside the
+window. You need both — neither alone is enough.
+
+## Idempotency
+
+**The idempotency key is the provider's stable event id** (`webhook-id`, or for
+Stripe `event.id`) — never a hash of the body or your own generated id. Mark it
+seen *before* doing the work, so a retry that arrives mid-processing is caught.
+
+Two stores, same idea:
+
+| Store | Mechanism | TTL / lifetime |
+|-------|-----------|----------------|
+| Relational DB | `INSERT` the event id into a table with a **UNIQUE** constraint; a duplicate insert throws → skip | Keep the row at least as long as the retry window |
+| Redis | `SET key val NX EX <ttl>` — `SETNX` returns false if already present → skip | TTL **≥ the provider's retry window** (hours to days) |
+
+**The dedupe TTL must outlive the provider's entire retry schedule.** Retries
+are exponential and capped — a provider may redeliver hours or days later. If
+your key expires first, that late retry looks brand-new and you process twice.
+
+```js
+// Insert-then-process: the UNIQUE insert is the gate. Do work only if we won it.
+try {
+  await db.query("INSERT INTO seen_events (id) VALUES ($1)", [id]);
+} catch (e) {
+  if (e.code === "23505") return res.sendStatus(200); // already seen → ack, skip
+  throw e;
+}
+await queue.add("process", { id, event });
+res.sendStatus(200);
+```
+
+Prefer **insert-then-process** over **process-then-mark**. Marking after the
+work leaves a window where two concurrent deliveries both pass the "have I seen
+it?" check and both run. Let the UNIQUE constraint (or `NX`) be the lock.
+
+## Fast-ack & queue
+
+Heavy synchronous work inside the handler causes provider timeouts and a storm
+of retries. Return `2xx` as soon as the event is durably stored or enqueued,
+then do the real work in a background worker. The status code is a contract with
+the sender:
+
+| You return | Meaning to the provider | Use it when |
+|------------|-------------------------|-------------|
+| `2xx` | "I own this now" | After enqueue/persist — **even if** downstream processing later fails. Recover failures from your own queue, not by asking for a redelivery. |
+| `4xx` | Permanent reject, do not retry | Bad/forged signature (`400`/`401`), or a payload you will never accept. A retry of a forged request is still forged. |
+| `5xx` / timeout | "Try again" | A genuine transient failure *before* you took ownership (e.g. the queue itself is down). |
+
+Once work is in the queue, handle failures there: bounded retries with backoff,
+then route exhausted jobs to a **dead-letter queue / poison shelf** for manual
+inspection. Do not let a poison event loop forever or block the queue head.
+Queue/broker tuning itself (concurrency, DLQ wiring) is `redis`'s job.
+
+## Framework raw-body recipes
+
+Capturing the raw body is framework-specific and is the usual culprit behind
+"mismatch though the secret is correct." One line each; full recipes in
+`references/framework-raw-body.md`:
+
+- **Express** — mount `express.raw({ type: "*/*" })` on the webhook route only;
+  do not let a global `express.json()` consume it first.
+- **Next.js App Router** — read `await req.text()` (or `req.arrayBuffer()`) in
+  the route handler; the App Router does not auto-parse, but `await req.json()`
+  discards the raw bytes, so verify off the text.
+- **FastAPI / Starlette** — `await request.body()` for the raw `bytes`; do not
+  type the handler param as a Pydantic model (that parses for you).
+- **Hono** — `await c.req.text()` before any `c.req.json()`.
+- **Serverless (Lambda/Vercel/Cloudflare)** — disable body parsing / read the
+  raw stream; base64-decode if the platform wraps the body.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|--------------|--------------|------------|
+| HMAC over parsed/re-serialized JSON | Key reorder + whitespace break the signature ("works with the right secret but still fails") | Verify over the raw bytes captured before parsing |
+| `===` / `==` on the signature | Timing side-channel leaks the secret byte by byte | `crypto.timingSafeEqual` / `hmac.compare_digest` |
+| Heavy synchronous work in the handler | Provider times out → retry storm → duplicate processing | Fast-ack: verify → dedupe → enqueue → `2xx`, work in a worker |
+| Ack before persisting/enqueueing | `2xx` means "I own it"; if you crash now the event is lost forever (provider won't retry a 2xx) | Persist or enqueue *first*, then return `2xx` |
+| No dedupe / dedupe on a body hash | At-least-once delivery double-processes; body hashes drift across redeliveries | UNIQUE-constraint or `SETNX` on the provider's stable event id |
+| Dedupe TTL shorter than the retry window | A late retry looks new and runs again | TTL ≥ the provider's full retry schedule (hours–days) |
+| Signing secret hard-coded in source | Leaks in git history; can't rotate | Read from env; accept space-separated sigs for rotation |
+| Returning `200` on a bad signature | Silently swallows forged traffic and masks misconfig | `400`/`401` on signature failure |
+| Skipping the timestamp check | Valid-but-replayed payloads sail through | Reject outside the ~5-min window |
+
+## Verify your handler
+
+`scripts/verify.sh` is a read-only heuristic linter. Run it from the root of the
+project that contains your handler; it scans candidate files and prints
+PASS/WARN/FAIL per invariant (raw-body verify, constant-time compare, timestamp
+check, secret-from-env, dedupe-on-event-id). A WARN means "I could not find
+evidence," which on a clean tree is expected and exits `0`.

package/skills/webhooks/evals/README.md

@@ -0,0 +1,15 @@
+# Evals — webhooks
+
+These cases are descriptive routing/capability checks, not an automated test
+suite. To run them, feed each `should_trigger` prompt to the skill router and
+confirm `webhooks` is selected (the `why` explains the intent, including the
+non-obvious raw-body and fast-ack symptoms); feed each `should_not_trigger`
+prompt and confirm the router picks the named sibling in `route_to` instead
+(these guard the boundaries against `stripe`, `email-connector`,
+`api-connector-builder`, `automation-flows` and `redis`). The `capability` case
+is graded by generation: have the skill produce the Express handler and check
+the output against the `must_include` rubric — every line should be present
+(raw-body HMAC, constant-time compare, 5-min window, dedupe-on-event-id with a
+TTL that outlives retries, 2xx-after-enqueue, secret-from-env, 400/401 on a bad
+signature). `scripts/verify.sh` is a complementary static linter for those same
+invariants against real handler files; it is advisory, not part of this eval.

package/skills/webhooks/evals/cases.yaml

@@ -0,0 +1,46 @@
+skill: webhooks
+
+should_trigger:
+  - prompt: "We need to receive webhooks from a provider and process them without dropping events or double-processing. Where do I start?"
+    why: "Core inbound flow: receive + dedupe + safe processing is the skill's whole mandate (verify → timestamp → dedupe → fast-ack)."
+  - prompt: "My webhook signature verification keeps failing even though the signing secret is definitely correct. What am I missing?"
+    why: "Non-obvious. The classic raw-body trap — verifying over re-serialized JSON instead of the raw bytes. The skill names this exact symptom."
+  - prompt: "The provider keeps retrying and our handler ends up running the same event twice. How do we make it idempotent?"
+    why: "At-least-once delivery + idempotency on the stable event id is a flagship section; phrased as a symptom, not jargon."
+  - prompt: "How do I do a constant-time signature compare and a timestamp/replay check on an incoming webhook?"
+    why: "Verify mechanics: timingSafeEqual / compare_digest plus the ~5-min tolerance window are core content."
+  - prompt: "Verificar la firma del webhook entrante y evitar procesar el mismo evento dos veces — ¿cómo lo monto en Express?"
+    why: "Spanish trigger covering signature verification + idempotency, the two central invariants."
+  - prompt: "Our webhook endpoint times out under load and the sender hammers it with retries. How do we ack fast and move the work off the request?"
+    why: "Non-obvious framing of the fast-ack-then-queue pattern; the timeout→retry-storm chain is the reason the pattern exists."
+  - prompt: "What status code should I return from a webhook handler when the signature is bad versus when my downstream save fails?"
+    why: "Status-code semantics (2xx = I own it, 4xx = forged/no-retry, 5xx = genuine retry) is a dedicated decision table."
+
+should_not_trigger:
+  - prompt: "Verify a Stripe webhook with the Stripe-Signature header and handle checkout.session.completed in my SaaS."
+    route_to: stripe
+    why: "Stripe's specific t=,v1= scheme, event model and stripe listen CLI belong to the specialized skill; webhooks covers only the generic case."
+  - prompt: "Handle Resend and SendGrid bounce and complaint webhooks so our suppression list stays clean."
+    route_to: email-connector
+    why: "The point is deliverability suppression state, not generic receive-and-verify mechanics."
+  - prompt: "Build a client that calls the GitHub REST API with auth, pagination and retries on the requests we initiate."
+    route_to: api-connector-builder
+    why: "That is the outbound client (we call them), the opposite direction from an inbound receiver."
+  - prompt: "After an order webhook lands, branch across Slack, the database and an email in a multi-step flow with conditions."
+    route_to: automation-flows
+    why: "Post-landing orchestration; webhooks ends at 'enqueued' and the flow engine takes over from there."
+  - prompt: "Tune our BullMQ worker concurrency and set up a dead-letter queue in Redis."
+    route_to: redis
+    why: "Broker/queue operations, not the front-door receiver; webhooks enqueues but does not own broker tuning."
+
+capability:
+  - scenario: "Implement an inbound webhook endpoint for a generic Standard-Webhooks provider in Node/Express that receives an event, proves it is authentic, refuses to process it twice, and acks fast — then describe where the real work runs."
+    must_include:
+      - "HMAC is computed over the RAW request body (raw buffer/text), not over JSON.parse(req.body) or a re-serialized object"
+      - "constant-time comparison via crypto.timingSafeEqual (not === / ==), with an equal-length guard"
+      - "timestamp tolerance check (~5 minutes) rejecting stale/replayed deliveries"
+      - "dedupe on the provider's stable event id (webhook-id) via a UNIQUE constraint or Redis SETNX, marked before processing"
+      - "dedupe TTL must outlive the provider's retry window (hours to days)"
+      - "returns 2xx only after the event is persisted/enqueued, then does the work in a background worker"
+      - "signing secret read from an environment variable, never a hard-coded literal"
+      - "bad/forged signature returns 400 or 401, not 200"

package/skills/webhooks/references/framework-raw-body.md

@@ -0,0 +1,97 @@
+# Getting the raw body, per framework
+
+If your signature check fails but the secret is correct, you are almost always
+verifying over a **re-serialized** body instead of the raw bytes the sender
+signed. Each framework hides the raw body somewhere different. The rule is the
+same everywhere: **capture the raw bytes, verify, and only then parse.**
+
+## Express
+
+A global `express.json()` consumes the stream, so by the time your handler runs
+the original bytes are gone. Mount `express.raw()` on the webhook route only.
+
+```js
+import express from "express";
+const app = express();
+app.use(express.json()); // fine for the rest of the app
+
+// Webhook route gets RAW, mounted before/instead of the global parser for this path.
+app.post("/webhooks", express.raw({ type: "*/*" }), (req, res) => {
+  const raw = req.body; // Buffer — exact bytes
+  if (!verify(raw, req.headers)) return res.sendStatus(400);
+  const event = JSON.parse(raw.toString("utf8"));
+  // dedupe + enqueue + res.sendStatus(200)
+});
+```
+
+If a global parser already ran, recover the bytes with a `verify` callback:
+`express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } })`.
+
+## Next.js (App Router)
+
+Route handlers do **not** auto-parse, but `await req.json()` reads the stream and
+discards the raw bytes. Read the text instead and parse it yourself after
+verifying.
+
+```ts
+// app/api/webhooks/route.ts
+export async function POST(req: Request) {
+  const raw = await req.text(); // raw string; do NOT call req.json() first
+  const headers = Object.fromEntries(req.headers);
+  if (!verify(raw, headers)) return new Response("bad sig", { status: 400 });
+  const event = JSON.parse(raw);
+  // dedupe + enqueue
+  return new Response("ok", { status: 200 });
+}
+```
+
+(Pages Router differs: set `export const config = { api: { bodyParser: false } }`
+and read the stream — prefer the App Router handler above.)
+
+## FastAPI / Starlette
+
+Typing the parameter as a Pydantic model parses the body for you and throws away
+the bytes. Take the raw `bytes` from the `Request`.
+
+```python
+from fastapi import FastAPI, Request, Response
+app = FastAPI()
+
+@app.post("/webhooks")
+async def webhooks(request: Request):
+    raw = await request.body()  # bytes — do not declare a model param
+    if not verify(raw, request.headers):
+        return Response(status_code=400)
+    event = json.loads(raw)
+    # dedupe + enqueue
+    return Response(status_code=200)
+```
+
+## Hono
+
+```ts
+app.post("/webhooks", async (c) => {
+  const raw = await c.req.text(); // before any c.req.json()
+  if (!verify(raw, c.req.header())) return c.text("bad sig", 400);
+  const event = JSON.parse(raw);
+  return c.text("ok", 200);
+});
+```
+
+## Serverless (Lambda / Vercel / Cloudflare Workers)
+
+- **AWS Lambda (API Gateway / function URL):** the body arrives as a string in
+  `event.body`; if `event.isBase64Encoded` is true, `Buffer.from(event.body,
+  "base64")` first. Verify over that, never over a parsed object.
+- **Vercel Functions:** disable the body parser for the route and read the raw
+  stream (Edge runtime: `await req.text()`).
+- **Cloudflare Workers:** `await request.text()` / `await request.arrayBuffer()`
+  in the `fetch` handler; the body is unbuffered, so read it once.
+
+## Common traps
+
+- A reverse proxy or middleware that re-encodes the body (gzip, charset
+  normalization) changes the bytes after the sender signed them — verify before
+  any transform, and disable response/transit re-encoding on the webhook path.
+- Reading the body stream twice: many runtimes let you read it once. Capture the
+  raw bytes into a variable and reuse that variable for both verify and parse.