@damiangilgonzalez/harness 1.3.7

package/skills/code-review/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: code-review
+description: "Reviews changes from a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow the repo's documented coding standards?) and Spec (does the code match what the source issue/PRD asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work in progress, or asks to \\"review from X\\"."
+tags: ["code-review", "standards", "spec-compliance"]
+profiles: [core, ui, full]
+---
+
+Revisión en dos ejes del diff entre `HEAD` y un punto fijo que proporciona el usuario:
+
+- **Estándares** — ¿el código se ajusta a los estándares de codificación documentados de este repo?
+- **Spec** — ¿el código implementa fielmente el issue / PRD / spec de origen?
+
+Ambos ejes se ejecutan como **sub-agentes paralelos** para que no contaminen el contexto del otro, y luego esta skill agrega sus hallazgos.
+
+El issue tracker debería haberte sido proporcionado. Si falta `docs/agents/issue-tracker.md`, busca el spec de origen en las ubicaciones habituales del proyecto (`docs/`, `specs/`, `.scratch/`) o pregunta al usuario.
+
+## Proceso
+
+### 1. Fijar el punto fijo
+
+Lo que diga el usuario es el punto fijo — un SHA de commit, nombre de rama, tag, `main`, `HEAD~5`, etc. Si no especifica ninguno, pregúntalo.
+
+Captura el comando de diff una vez: `git diff <punto-fijo>...HEAD` (tres puntos, para que la comparación sea contra el merge-base). Anota también la lista de commits vía `git log <punto-fijo>..HEAD --oneline`.
+
+Antes de seguir, confirma que el punto fijo resuelve (`git rev-parse <punto-fijo>`) y que el diff no está vacío. Una ref inválida o un diff vacío debe fallar aquí — no dentro de dos sub-agentes paralelos.
+
+### 2. Identificar la fuente del spec
+
+Busca el spec de origen, en este orden:
+
+1. Referencias a issues en los mensajes de commit (`#123`, `Closes #45`, `!67` de GitLab, etc.) — recupéralas vía el flujo de `docs/agents/issue-tracker.md`.
+2. Una ruta que el usuario haya pasado como argumento.
+3. Un archivo PRD/spec bajo `docs/`, `specs/` o `.scratch/` que coincida con el nombre de la rama o la feature.
+4. Si no encuentras nada, pregunta al usuario dónde está el spec. Si dice que no hay, el sub-agente de **Spec** se salta y reporta "no hay spec disponible".
+
+### 3. Identificar las fuentes de estándares
+
+Cualquier cosa en el repo que documente cómo debe escribirse el código, como `CODING_STANDARDS.md` o `CONTRIBUTING.md`. (En este proyecto: `CLAUDE.md` y `docs/CARTA-MAGNA.md`.)
+
+Además de lo que el repo documente, el eje de Estándares siempre lleva el **smell baseline** de abajo — un conjunto fijo de code smells de Fowler (_Refactoring_, cap. 3) que aplica incluso cuando el repo no documenta nada. Dos reglas lo condicionan:
+
+- **El repo manda.** Un estándar documentado del repo siempre gana; donde el repo avale algo que el baseline marcaría, suprime el smell.
+- **Siempre es un juicio.** Cada smell es una heurística etiquetada ("posible Feature Envy"), nunca una violación dura — y, como cualquier estándar aquí, sáltate lo que el tooling ya imponga.
+
+Cada smell se lee *qué es* → *cómo arreglarlo*; contrástalo con el diff:
+
+- **Nombre misterioso (Mysterious Name)** — una función, variable o tipo cuyo nombre no revela qué hace o qué guarda. → renómbralo; si no sale un nombre honesto, el diseño está turbio.
+- **Código duplicado (Duplicated Code)** — la misma forma de lógica aparece en más de un hunk o archivo del cambio. → extrae la forma compartida, llámala desde ambos.
+- **Feature Envy** — un método que hurga en los datos de otro objeto más que en los suyos. → mueve el método a los datos que envidia.
+- **Grupos de datos (Data Clumps)** — los mismos pocos campos o params viajan siempre juntos (un tipo que quiere nacer). → agrúpalos en un solo tipo, pasa ese.
+- **Obsesión por primitivos (Primitive Obsession)** — un primitivo o string que hace de concepto de dominio que merece su propio tipo. → dale al concepto su propio tipo pequeño.
+- **Switches repetidos (Repeated Switches)** — el mismo `switch`/cascada de `if` sobre el mismo tipo se repite por el cambio. → reemplázalo con polimorfismo, o un mapa que ambos sitios compartan.
+- **Cirugía de escopeta (Shotgun Surgery)** — un cambio lógico obliga a ediciones dispersas en muchos archivos del diff. → reúne lo que cambia junto en un solo módulo.
+- **Cambio divergente (Divergent Change)** — un archivo o módulo se edita por varias razones no relacionadas. → divídelo para que cada módulo cambie por una sola razón.
+- **Generalidad especulativa (Speculative Generality)** — abstracción, parámetros o hooks añadidos para necesidades que el spec no tiene. → bórralo; vuelve a hacerlo inline hasta que aparezca una necesidad real.
+- **Cadenas de mensajes (Message Chains)** — navegación larga `a.b().c().d()` de la que el llamante no debería depender. → oculta el recorrido tras un método del primer objeto.
+- **Intermediario (Middle Man)** — una clase o función que casi solo delega hacia adelante. → córtala, llama al objetivo real directamente.
+- **Herencia rechazada (Refused Bequest)** — una subclase o implementador que ignora o sobrescribe casi todo lo que hereda. → suelta la herencia, usa composición.
+
+### 4. Lanzar ambos sub-agentes en paralelo
+
+Envía un único mensaje con dos llamadas a la herramienta `Agent`. Usa el subagente `general-purpose` para ambos.
+
+**Prompt del sub-agente de Estándares** — incluye:
+
+- El comando de diff completo y la lista de commits.
+- La lista de archivos-fuente de estándares que encontraste en el paso 3, **más el smell baseline del paso 3 pegado completo** — el sub-agente no tiene otro acceso a él.
+- El encargo: "Reporta — por archivo/hunk donde proceda — (a) cada lugar donde el diff viola un estándar documentado: cita el estándar (archivo + la regla); y (b) cualquier smell del baseline que detectes: nómbralo y cita el hunk. Distingue violaciones duras de juicios — las infracciones de estándar documentado pueden ser duras, pero los smells del baseline son siempre juicios, y un estándar documentado del repo prevalece sobre el baseline. Sáltate lo que el tooling imponga. Menos de 400 palabras."
+
+**Prompt del sub-agente de Spec** — incluye:
+
+- El comando de diff y la lista de commits.
+- La ruta o el contenido recuperado del spec.
+- El encargo: "Reporta: (a) requisitos que el spec pedía y que faltan o están parciales; (b) comportamiento en el diff que no se pidió (scope creep); (c) requisitos que parecen implementados pero cuya implementación parece incorrecta. Cita la línea del spec por cada hallazgo. Menos de 400 palabras."
+
+Si falta el spec, sáltate el sub-agente de Spec y anótalo en el reporte final.
+
+### 5. Agregar
+
+Presenta los dos reportes bajo los encabezados `## Estándares` y `## Spec`, verbatim o ligeramente limpiados. **No** fusiones ni reordenes los hallazgos — los dos ejes son deliberadamente separados (ver _Por qué dos ejes_).
+
+Termina con un resumen de una línea: total de hallazgos por eje, y el peor problema _dentro de cada eje_ (si lo hay). No elijas un único ganador entre ejes — eso es el reordenamiento que la separación existe para evitar.
+
+## Por qué dos ejes
+
+Un cambio puede pasar un eje y fallar el otro:
+
+- Código que sigue todos los estándares pero implementa lo equivocado → **Estándares pasa, Spec falla.**
+- Código que hace exactamente lo que pedía el issue pero rompe las convenciones del proyecto → **Spec pasa, Estándares falla.**
+
+Reportarlos por separado evita que un eje enmascare al otro.

package/skills/code-review/evals/cases.yaml

@@ -0,0 +1,32 @@
+skill: code-review
+
+should_trigger:
+  - prompt: "Revisa los cambios de esta rama desde el commit base."
+    why: "Disparador directo de code-review."
+  - prompt: "Necesito ver si este PR cumple los estandares del repo y la spec."
+    why: "Disparador directo de code-review."
+  - prompt: "Revisa desde main hasta mi rama actual."
+    why: "Disparador directo de code-review."
+  - prompt: "Review this branch against the repo's coding standards and the original spec."
+    why: "Disparador directo de code-review."
+  - prompt: "Comprueba si el codigo coincide con lo que pedia el issue."
+    why: "Disparador directo de code-review."
+
+should_not_trigger:
+  - prompt: "Revisa solo el trabajo sin commitear de la sesion actual."
+    route_to: "revision-de-cambios"
+    why: "Revisar solo el trabajo sin commitear es el trabajo de revision-de-cambios, no de code-review."
+  - prompt: "Implementa la funcionalidad que falta."
+    route_to: "implement"
+    why: "Implementar la funcionalidad es el trabajo de implement, no de code-review."
+  - prompt: "Escribe la spec de este cambio."
+    route_to: "to-spec"
+    why: "Escribir la spec de un cambio es el trabajo de to-spec, no de code-review."
+  - 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 code-review."
+
+capability:
+  - scenario: "El usuario quiere revisar una rama, PR o rango de commits frente a estandares y spec."
+    must_include:
+      - "estandares"

package/skills/codebase-onboarding/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: codebase-onboarding
+description: "Use when you land in an unfamiliar or inherited codebase and must get productive fast: a breadth-first map of entry points, request flow, module ownership, hidden side effects (cron, webhooks, workers) and churn hotspots, committed as CODEBASE-MAP.md. NOT a deep audit of one module (that is `analyze`) or chasing one failure (that is `debug`)."
+tags: [onboarding, codebase, code-mapping, legacy-code, architecture, reverse-engineering, hotspots]
+recommends: [write-adr, harness, init, knowledge-ops]
+origin: risco
+---
+
+# Codebase onboarding — get oriented fast, leave a map
+
+You have just landed in a codebase you did not write: a fresh clone, an inherited project, an acquired repo, an abandoned side project someone handed you. The instinct is to start reading files top-to-bottom. Resist it. That is how a week disappears and you still cannot answer "where does X happen". This skill runs a disciplined **breadth-first reconnaissance pass** and produces one durable artifact: a map a teammate can trust and you can re-read tomorrow.
+
+The payoff is measured. Engineers using AI to onboard reach the same milestones roughly **2x faster** — productive in 1–2 weeks instead of 4–6 — and the biggest gains are exactly in *searching for code, decoding undocumented patterns, and tracing data flows* (super-productivity.com, accessed 2026-06-02). That is what the recon pass below targets, in order.
+
+## Lead with the deliverable
+
+Before you grep a single line, know the target: a single living file, `CODEBASE-MAP.md`, committed at the repo root. You work *backward* from its sections — every recon step fills one. Minimal schema:
+
+```markdown
+# CODEBASE-MAP.md — <repo name>
+
+## Stack          # languages, framework + versions, package manager, run scripts
+## Entry points   # main / server bootstrap / route registration / CLI commands
+## Request flow   # one real path traced transport -> business logic -> persistence
+## Module ownership   # who owns transport / business logic / persistence / UI
+## Hidden behavior    # cron, webhooks, queue workers, event listeners, env branches
+## Hotspots       # most-churned + most-complex files = highest risk
+## How to run     # the exact commands to boot it and hit one path locally
+```
+
+Why a file and not a chat answer: a map that lives only in the conversation dies when the session ends, and the next agent re-does the work. The artifact is the point. `verify.sh` checks these sections exist (structure, not content).
+
+## Two operating rules
+
+1. **Breadth before depth.** First pass maps *where things are*, not *how they work*. You are drawing the subway map, not reading every passenger's diary. Depth is `analyze`/`debug` work, on demand, later. — Reading everything is the failure mode onboarding exists to replace.
+2. **Hypothesis before answer.** Spend ~5 minutes forming your own guess ("auth probably lives in `src/middleware`"), then grep to confirm or kill it. — Verifying a hypothesis builds the mental model that makes you fast; a handed-to-you answer does not stick (martinfowler.com, Böckeler, accessed 2026-06-02).
+
+## The recon pass — ordered
+
+Run these in order. Each step writes one map section. Stop escalating the moment the section is answerable.
+
+**a. Orient — read the manifest, size the repo.**
+Read the manifest(s) and lockfile, not the README first: `package.json` / `pyproject.toml` / `go.mod` / `Gemfile` / `pom.xml` tell you the real stack, framework version and run scripts; the lockfile tells you what is actually installed. Then size it:
+
+```bash
+scc --by-file --sort lines .   # LOC, complexity, COCOMO estimate per file
+```
+
+`scc` (Sloc Cloc and Code, pure-Go, v3.7.0 Apr 2026) is the fast structural counter of record — materially faster than cloc/tokei and it reports per-file complexity, which you reuse for hotspots. Why manifest-first: the README describes intent (often stale); the manifest describes reality.
+
+**b. Find the entry points.**
+Where does execution start? Look for `main`, the server bootstrap, route registration, CLI command definitions. Let the framework's convention guide you (Next.js `app/`/`pages/`, Express `app.use`/router mounts, Django `urls.py`, FastAPI `@app`/`APIRouter`, Rails `routes.rb`, Spring `@RestController`). See `references/recon-playbook.md` for per-ecosystem patterns.
+
+**c. Trace one real request end-to-end.**
+Pick a single meaningful path (a login, a checkout, the main CLI command) and follow it: transport (route/handler) → business logic → persistence → response. One path traced beats ten skimmed. This is the spine of the map.
+
+**d. Map module ownership.**
+For the directories `scc` flagged as large, label each: transport, business logic, persistence, UI, shared/util. You are answering "if I need to change pricing, which folder do I open" — the question teammates actually ask.
+
+**e. Hunt hidden behavior.**
+The bugs live in what runs *without* a request. Grep for cron schedules, webhook receivers, queue/background workers, event listeners and env-driven branches (see the appendix). Why this step is non-negotiable: side effects are invisible in a top-down read and they are where inherited codebases bite.
+
+**f. Rank hotspots.**
+Git churn is the cheapest risk signal — no extra tooling, and high-churn files are a proxy for "lacks tests/abstraction":
+
+```bash
+git log --format=format: --name-only --since=12.month \
+  | grep -v '^$' | sort | uniq -c | sort -nr | head -50
+```
+
+The richer move is **churn × complexity**: the top-right quadrant (changes constantly *and* is hard to read) is your real danger zone (understandlegacycode.com Hotspots, accessed 2026-06-02). Escalate to that — or to a tree-sitter dependency graph — only when grep + churn is not enough: `references/recon-playbook.md` has the churn×complexity recipe (code-maat) and when codegraph PageRank / FileScopeMCP earn their setup cost.
+
+**g. Confirm hands-on.**
+Run the app, walk one end-user journey, send a real request, watch the logs. Reading alone leaves the map unverified; a single real request validates the whole trace in step c.
+
+## Scope the effort
+
+Match the pass to the repo. Do not stand up heavy tooling on a small project.
+
+| Repo shape | Map fully | Skip / defer | Escalate to a graph tool? |
+| --- | --- | --- | --- |
+| Tiny (<20 files) | a, b, c, g | churn, ownership table | No — grep is faster than setup |
+| Single-service app | all a–g | — | Only if ownership is unclear after grep |
+| Large monorepo | a, b, then per-package c–f | mapping every package at once | Yes — codegraph PageRank to find the load-bearing packages |
+| Polyglot | a, b, c per language boundary | one unified flow diagram | Yes, if cross-language calls obscure the flow |
+
+## Command appendix
+
+Language-tagged, copy-ready. Per-ecosystem depth lives in `references/recon-playbook.md`.
+
+```bash
+# Size + complexity (reuse the complexity column for hotspots)
+scc --by-file --sort complexity .
+
+# Route registration (adjust per framework)
+rg -n "app\.(get|post|put|delete|use)\(|@app\.(get|post)|APIRouter|router\.(get|post)" --type-add 'web:*.{js,ts,py}' -tweb
+
+# Cron / scheduled jobs
+rg -n "cron|schedule|@scheduled|setInterval|celery\.beat|node-cron" -i
+
+# Webhook receivers
+rg -n "webhook|/hooks/|stripe.*signature|x-hub-signature" -i
+
+# Queue / background workers
+rg -n "queue|worker|bull|sidekiq|celery|sqs|rabbitmq|kafka|@task" -i
+
+# Env-driven branches (hidden config-conditional behavior)
+rg -n "process\.env\.|os\.environ|ENV\[|getenv" 
+```
+
+## Writing & maintaining the map
+
+- **Commit it.** `CODEBASE-MAP.md` at the repo root, in version control. A map outside the repo rots silently.
+- **Keep it living.** When the recon reveals you guessed wrong, fix the line — the map is the record of what is *true now*, not your first impression.
+- **Link out, do not duplicate.** The map says *what is*. For *why a choice was made*, write an ADR (`../decision-records/SKILL.md`). To scaffold project tooling and a wiki, that is `../harness/SKILL.md`. To write the agent-memory `CLAUDE.md`, that is `../init/SKILL.md` — onboarding is the broader recon that feeds it. For generic note/wiki capture, `../knowledge-ops/SKILL.md`.
+- **Hand off to depth tools.** Once the map exists, a deep correctness/security read of one module is `../analyze/SKILL.md`; chasing a specific failure through the system is `../debug/SKILL.md`. Onboarding builds the map you debug *with*.
+
+## Anti-patterns
+
+| Bad | Why it bites | Good |
+| --- | --- | --- |
+| Read every file top-to-bottom | Burns the week; you finish exhausted and still can't trace one request | Breadth-first: map locations first, depth on demand |
+| Trust the README over the code | READMEs drift; the manifest and the routes are the truth | Read manifest + lockfile first, confirm by grep |
+| Map everything at full depth | Analysis paralysis on a monorepo; you map dead modules | Trace one real flow end-to-end; expand only where needed |
+| Skip the run step | An unverified map is a hypothesis, not a map | Boot it, hit one path, watch logs before you trust the trace |
+| Map lives only in chat | Dies with the session; next agent redoes it | Write & commit `CODEBASE-MAP.md` |
+| Guess instead of grep | Confident-wrong is worse than slow-right | Form the hypothesis, then `rg` to confirm or kill it |
+| Stand up a tree-sitter MCP graph on a 5-file repo | Setup costs more than the whole recon | Reserve graph tools for large monorepos; grep + churn first |

package/skills/codebase-onboarding/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — codebase-onboarding
+
+These cases are split into routing checks and a capability rubric, run through the repo's standard skill-eval harness. The `should_trigger` and `should_not_trigger` prompts validate the description's routing: each `should_trigger` prompt must select this skill (including the non-obvious hotspot/hidden-behavior and Spanish phrasings), and each `should_not_trigger` prompt must route to the named sibling (`analyze`, `harness`, `decision-records`, `debug`, `init`) instead — that is how we confirm the boundary lines hold. The `capability` block is graded by a model against the `must_include` rubric, not asserted by a script: given an unfamiliar Node/Express + Postgres repo, the run is judged on whether it produced a breadth-first map (stack, entry points, one traced flow, ownership, a hidden side effect, churn hotspots, run instructions) written to `CODEBASE-MAP.md` — and crucially did *not* read the repo line-by-line. Run the whole file with the harness; there is no separate setup.

package/skills/codebase-onboarding/evals/cases.yaml

@@ -0,0 +1,69 @@
+skill: codebase-onboarding
+
+# Prompts that MUST load `codebase-onboarding`. This is the breadth-first
+# reconnaissance skill: it maps an unfamiliar/inherited codebase (entry points,
+# request/data flow, module ownership, hidden side effects, hotspots) into a
+# committed CODEBASE-MAP.md. Several prompts deliberately avoid "onboarding" to
+# test that the intent — orientation in code you didn't write — is the trigger.
+should_trigger:
+  - prompt: "I just cloned this repo and have no idea where anything is — help me get oriented."
+    why: "Canonical cold-start: fresh clone, no mental model, needs breadth-first orientation — the core job."
+
+  - prompt: "I inherited this project from a dev who left. Map it out before I change anything."
+    why: "Inherited/legacy framing with the explicit 'map before touching' instinct this skill enforces."
+
+  - prompt: "Where does the business logic actually live in this codebase, versus the transport layer?"
+    why: "Module-ownership question (recon step d) phrased without naming the skill."
+
+  - prompt: "What happens behind the scenes when a request hits /checkout — any cron jobs or webhooks involved?"
+    why: "Non-obvious hidden-side-effects framing (step e) plus a request trace (step c); side effects are invisible in a top-down read."
+
+  - prompt: "acabo de heredar este repo y no sé por dónde empezar, mápamelo."
+    why: "Spanish, inherited codebase, explicit 'map it' — same cold-start intent in another language."
+
+  - prompt: "Which files are the dangerous ones here — the stuff that changes constantly and nobody understands?"
+    why: "Hotspot/churn×complexity framing (step f); 'changes constantly' is the churn signal, 'nobody understands' is complexity."
+
+  - prompt: "Give me a high-level architecture map of this monorepo so I can find the load-bearing packages."
+    why: "Large-monorepo recon that escalates to a structural-importance graph — the decision-table large-repo row."
+
+# NEAR-MISS prompts that must NOT load `codebase-onboarding`. Each routes to the
+# genuinely correct sibling. The recurring trap: anything that audits depth,
+# scaffolds tooling, records a decision, or chases a specific failure rather than
+# building breadth-first orientation.
+should_not_trigger:
+  - prompt: "Review this PR diff for correctness bugs before we merge."
+    route_to: "none"
+    why: "Depth audit of a specific change, not breadth orientation of an unfamiliar repo; no dedicated skill owns this generic diff review."
+
+  - prompt: "Set up 01-TOOLS and docs and generate the root CLAUDE.md for this workspace."
+    route_to: "harness"
+    why: "Operational tooling/wiki scaffolding, not understanding — onboarding produces a map, not a tooling layer."
+
+  - prompt: "Write an ADR for why we picked Postgres over Mongo."
+    route_to: "write-adr"
+    why: "Capturing the 'why' of a decision is write-adr's job; the map captures 'what is', not the rationale."
+
+  - prompt: "The login flow throws a 500 intermittently — find the bug."
+    route_to: "external:superpowers-systematic-debugging"
+    why: "Chasing a specific failure through the system is superpowers' systematic-debugging; onboarding builds the map you debug with, it does not root-cause."
+
+  - prompt: "Create the initial CLAUDE.md memory file for this repo."
+    route_to: "init"
+    why: "Narrow single-file agent memory; onboarding is the broader recon that feeds init, not the file write itself."
+
+capability:
+  - scenario: >
+      Given an unfamiliar Node/Express + Postgres repo (no prior context), produce
+      the onboarding map without reading every file line-by-line.
+    must_include:
+      - "Identifies stack + framework version from package.json and the lockfile, not the README first"
+      - "Sizes the repo with scc (per-file LOC/complexity)"
+      - "Locates the entry point and route registration (app.get/post/use or router mounts)"
+      - "Traces one real request end-to-end: transport handler -> business logic -> persistence"
+      - "Labels module ownership (transport / business logic / persistence / UI)"
+      - "Surfaces at least one hidden behavior (cron / webhook / queue worker / listener) via ripgrep"
+      - "Ranks hotspots using the git churn one-liner (and notes churn×complexity as the richer move)"
+      - "States the exact commands to run it locally and hit one path"
+      - "Writes results into CODEBASE-MAP.md with the required sections (Stack, Entry points, Request flow, Module ownership, Hidden behavior, Hotspots, How to run)"
+      - "Does NOT attempt a line-by-line full read; works breadth-first"

package/skills/codebase-onboarding/references/recon-playbook.md

@@ -0,0 +1,57 @@
+# Recon playbook — per-ecosystem patterns & escalation
+
+Offloaded depth for the recon pass in `../SKILL.md`. Pull the rows you need; do not run them all.
+
+## Entry points & hidden side effects by ecosystem
+
+### Node / Express / Next.js
+- **Entry**: `package.json` `scripts.start`/`dev` → the bootstrap file (`server.js`, `src/index.ts`). Next.js: routes are files under `app/` (route handlers `route.ts`) or `pages/api/`.
+- **Routes**: `rg -n "app\.(get|post|put|delete|use)\(|router\.(get|post|use)\(" src`
+- **Side effects**: `setInterval`, `node-cron`, BullMQ (`new Queue`/`Worker`), `EventEmitter.on(`, Next.js `middleware.ts`, `instrumentation.ts`, and `next.config` rewrites/redirects.
+
+### Python / Django / FastAPI
+- **Entry (Django)**: `manage.py` → `settings.ROOT_URLCONF` → `urls.py` trees. **FastAPI**: the `FastAPI()` instance + `APIRouter` includes; `uvicorn` target in the run command.
+- **Routes**: `rg -n "@app\.(get|post|put|delete)|APIRouter|path\(|re_path\(|router\.register" .`
+- **Side effects**: Celery (`@shared_task`, `celery.beat` schedule), Django signals (`@receiver`, `post_save`), management commands (`management/commands/`), `apps.py` `ready()`, middleware list in settings.
+
+### Ruby / Rails
+- **Entry**: `config/routes.rb`, `config/application.rb`, initializers in `config/initializers/`.
+- **Side effects**: Sidekiq/ActiveJob workers (`app/jobs`, `*_worker.rb`), `whenever` cron schedule, ActiveRecord callbacks (`after_save`, `before_create`), `config/schedule.rb`.
+
+### Go
+- **Entry**: `func main()` (find with `rg -n "func main\(\)"`), the router setup (`chi`, `gin`, `mux`, stdlib `http.HandleFunc`).
+- **Side effects**: goroutines launched at boot (`go func()`), `time.Ticker`/`cron`, `init()` functions (run before main, easy to miss).
+
+### JVM / Spring Boot
+- **Entry**: the `@SpringBootApplication` main class; `application.yml`/`.properties` for active profiles.
+- **Routes**: `rg -n "@RestController|@RequestMapping|@GetMapping|@PostMapping" src`
+- **Side effects**: `@Scheduled`, `@EventListener`, `@PostConstruct`, `@KafkaListener`/`@RabbitListener`, `@Async`.
+
+### PHP / Laravel
+- **Entry**: `routes/web.php`, `routes/api.php`, `public/index.php`.
+- **Side effects**: `app/Console/Kernel.php` schedule, jobs in `app/Jobs`, model events/observers (`app/Observers`), event listeners in `EventServiceProvider`.
+
+## Churn × complexity (the richer hotspot signal)
+
+Git churn alone ranks files by change frequency. Multiply by complexity to find the true danger zone — files that change constantly *and* are hard to read.
+
+```bash
+# 1. Churn (revisions per file) over a year, via code-maat
+git log --pretty=format:'[%h] %an %ad %s' --date=short --numstat --since=12.month > /tmp/log.txt
+java -jar code-maat.jar -l /tmp/log.txt -c git2 -a revisions > /tmp/churn.csv
+
+# 2. Complexity per file (reuse scc, or indentation as a cheap proxy)
+scc --by-file --format csv . > /tmp/complexity.csv
+```
+
+Join the two CSVs on filename; the **top-right quadrant** (high revisions, high complexity) is where bugs concentrate and where tests are missing. Start refactoring/test-writing there, not in the file that merely looks ugly. (adamtornhill/code-maat; understandlegacycode.com Hotspots Analysis; accessed 2026-06-02.)
+
+## When to bring in a tree-sitter dependency graph
+
+Grep + churn answers most first-pass questions. Reach for a structural graph only when the codebase is large enough that "who depends on this" is no longer obvious by eye.
+
+- **codegraph** (tree-sitter + PageRank, no embeddings/GPU): one-shot ranking of files by structural importance, biased toward query keywords. Prefer this one-shot rank for onboarding — it is fast and stateless. (github.com/tarunms7/codegraph)
+- **FileScopeMCP**: scores each file 0–10 by how many things depend on it — a quick "what is load-bearing" lens. (github.com/admica/FileScopeMCP)
+- **Heavier MCP-native graphs** (codegraph-ai/CodeGraph: ~42 MCP tools across 38 languages; tree-sitter-analyzer): full function/class/import + call/inheritance graphs. Powerful, but standing up a persistent MCP graph server during *first-pass* onboarding is usually overkill — defer until the map exists and you have a concrete deep-dive question. (accessed 2026-06-02.)
+
+**Rule of thumb**: if the repo is under a few hundred files, a tree-sitter graph costs more setup than it saves. Use it for monorepos and for finding the load-bearing packages, not for a service you can grep through in ten minutes.

package/skills/codebase-onboarding/scripts/verify.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# verify.sh — structural check for the codebase-onboarding artifact.
+#
+# Validates that a CODEBASE-MAP.md contains the required sections. This is a
+# STRUCTURE check, not a content-correctness check (this is a process skill;
+# its real rigor is the capability eval). Read-only: it never writes or edits.
+#
+# Usage:   verify.sh [path-to-map]      (default: ./CODEBASE-MAP.md)
+# Exit 0:  map present with all required sections, OR no map yet (nothing to
+#          check — an empty/clean target must not produce a false failure).
+# Exit 1:  map present but missing one or more required sections.
+
+set -euo pipefail
+
+MAP="${1:-CODEBASE-MAP.md}"
+
+# No artifact yet => nothing to validate. Clean target, exit 0 (no false fail).
+if [[ ! -f "$MAP" ]]; then
+  echo "OK: no $MAP yet — nothing to verify (run the recon pass to produce one)."
+  exit 0
+fi
+
+# Required section headers. Each entry is an extended-regex alternation so that
+# reasonable wording variants (e.g. "Request flow" / "Data flow") still pass.
+declare -a SECTIONS=(
+  "Stack"
+  "Entry points?"
+  "Request flow|Data flow"
+  "Module ownership"
+  "Hidden behavior|Hidden behaviour|Side effects?"
+  "Hotspots?"
+  "How to run|Running locally"
+)
+
+missing=()
+for pat in "${SECTIONS[@]}"; do
+  # Match a markdown heading line (## ...) containing the pattern, case-insensitive.
+  if ! grep -Eiq "^#{1,6}[[:space:]].*(${pat})" "$MAP"; then
+    # Use the first alternative as the human-readable label.
+    missing+=("${pat%%|*}")
+  fi
+done
+
+if (( ${#missing[@]} > 0 )); then
+  echo "FAIL: $MAP is missing required section(s):" >&2
+  for m in "${missing[@]}"; do
+    echo "  - $m" >&2
+  done
+  echo "Required: Stack, Entry points, Request flow, Module ownership, Hidden behavior, Hotspots, How to run." >&2
+  exit 1
+fi
+
+echo "OK: $MAP has all required sections."
+exit 0

package/skills/cold-outreach/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: cold-outreach
+description: "Use when writing a cold email or LinkedIn DM to a stranger and its cadence: first-touch copy under a word ceiling, 4-7 step bump sequences, per-inbox volume and warm-up limits, the compliant opt-out footer. NOT SPF/DKIM/DMARC setup (that is email-deliverability), NOT sourcing the list (that is lead-gen), NOT life after a reply (that is sales-pipeline)."
+tags: [cold-email, outreach, sequences, deliverability, sales]
+recommends: [lead-gen, sales-pipeline, email-deliverability, proposals, marketing]
+origin: risco
+---
+
+# Cold Outreach — The Words and the Cadence of the Cold Touch
+
+*You write the message a stranger actually replies to, and the sending rhythm that keeps the mailbox provider delivering it. You do not set up DNS, source the list, or run the CRM.*
+
+This skill owns two things and only two: 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, the compliant footer). Everything upstream and downstream belongs to a sibling — route by naming the owner, do not improvise their job:
+
+| The ask | Owner | Why it is not here |
+|---|---|---|
+| Find / scrape / qualify the prospect list or ICP | `lead-gen` | This skill assumes you already have a verified recipient. |
+| Set up SPF, DKIM, DMARC, a tracking domain, or diagnose DNS-level spam landing | `email-deliverability` | This skill *applies* the provider rules to cadence; it does not configure auth. |
+| Manage what happens after a reply — stages, tasks, CRM hygiene, close forecast | `sales-pipeline` | The moment a reply lands the relationship leaves this skill. |
+| Write the proposal / SOW / pricing after a prospect engages | `proposals` | A cold touch earns a conversation, not a contract. |
+| Inbound launch emails, nurture to an opted-in list, marketing-site copy | `marketing` (`../marketing/SKILL.md`) | Opted-in and broadcast copy is a different game from a 1:1 cold touch. |
+| Actually wire the send through Gmail/an ESP API or a scheduler | `email-connector` / `google-workspace` | This skill produces text + a plan; it does not push the send. |
+
+## The reply-rate reality (calibrate before you write)
+
+Cold email is a low-yield channel by nature, and most "improve my copy" requests are really "stop fighting the math." Set expectations against the 2026 band:
+
+- **Average reply rate ≈ 3.43%.** Top quartile ≈ 5.5%. Elite (top 10%) ≈ 10.7%+. *(Instantly Cold Email Benchmark Report 2026, accessed 2026-06-02.)*
+- So **5-10% is solid, 10%+ is excellent, under 2% means something upstream is broken** — usually the list or the deliverability, not the prose.
+
+The two levers that actually move the number, in order:
+
+1. **Relevance** — the right person, with a real reason you reached out *now*. A perfect email to the wrong list still dies.
+2. **Deliverability** — if it lands in spam, copy is irrelevant. This is why cadence and volume (below) are part of *this* skill's job even though the DNS plumbing is not.
+
+Cleverness ranks a distant third. Do not sell wit; sell relevance, delivered.
+
+## Diagnosing a failing campaign — read the metric, then fix the right lever
+
+Most rescue requests describe a *symptom*, not a cause, and the instinct (theirs and a naive agent's) is to rewrite the prose. Usually the prose is the wrong lever. Diagnose by the **earliest broken metric in the funnel** — fix that one, ignore everything downstream of it, because a downstream number can't be read until the upstream one is healthy.
+
+| Symptom the user reports | The number that's actually broken | Almost never the cause | What to fix, in order |
+|---|---|---|---|
+| "Bounces / lands in spam / domain flagged" | Bounce > 2% or sudden deliverability drop | Copy | List hygiene → `lead-gen`; sending auth + warm-up → `email-deliverability`. Stop sending until fixed. |
+| "Low open rate" (< ~30-40% on a verified list) | Delivery + subject line | Body copy (they never saw it) | First confirm it's not spam-foldering (a deliverability tell). If delivery is fine, the **subject and from-name** are the only things they saw — rewrite those, leave the body alone. |
+| "Good opens, ~zero replies" | The hook + the CTA | Subject (it worked) / volume | The INFER line is generic or the CTA isn't binary. Re-derive the hook (four-line bridge); make the ask one yes/no question. This is the #1 misdiagnosed case. |
+| "Replies but all negative / 'not interested'" | Targeting or timing, not wording | The email itself | You're reaching the wrong role or the wrong moment — a `lead-gen` ICP problem. Polishing the copy won't convert a person with no need. |
+| "First email gets replies, sequence doesn't" | The follow-ups repeat instead of adding an angle | The cadence length | Each step must add ONE new angle (proof → new pain → breakup). Delete any step that restates step 1. Confirm the breakup exists. |
+| "It all works at 20/day, dies when I scale" | Per-inbox volume / reputation | Copy | Don't raise per-inbox volume — add inboxes and hold 20-50/day each. See the cadence table. |
+
+The governing rule: **the prose is the lever only when opens are healthy and replies are absent.** If opens are low, the prose is unread; if replies are negative, the prose found the wrong person. Name the broken metric back to the user before you touch a word — it's the single highest-value thing this skill does that an unaided agent skips.
+
+## Anatomy of a first touch
+
+Hard constraints for the opening email:
+
+- **Under ~80 words.** Elite performers stay below this; brevity plus a single binary CTA beats a long multi-CTA email. *(Instantly Benchmark 2026.)*
+- **One observed hook** — a specific, real signal about *them* (a launch, a job post, a number from their site). Not "I came across your company."
+- **One binary CTA** — a yes/no question they can answer in one tap ("Worth a 15-min look next week?"), not "let me know your thoughts" and not two asks.
+- **Subject line under ~6 words, no clickbait, no "Re:" fakery.** It should read like a colleague wrote it, not a campaign.
+
+Bad → Good rewrite:
+
+```text
+BAD (78 words, no real hook, vague + double CTA, spam-flavored):
+Subject: Quick question + a free guide for you!!
+
+Hi there, I hope this email finds you well! I came across your company
+and was really impressed by what you're doing in the space. We help
+companies like yours grow faster with our cutting-edge platform. I'd
+love to hop on a call to walk you through it, or I can send over a free
+guide — whatever works! Let me know your thoughts. Looking forward to
+hearing from you!
+
+GOOD (49 words, one signal, one binary CTA):
+Subject: your March hiring for 3 SREs
+
+Hi Dana — saw Acme is hiring three SREs this quarter. Usually that means
+on-call pain is outrunning the team. We cut alert noise ~40% for two
+infra teams your size in their first month.
+
+Worth a 15-min look next week — yes or no?
+```
+
+The Good version names a real signal (`{{signal}}`), states one concrete outcome (`{{outcome}}`), and asks one binary question. No greeting filler, no "free", no double ask.
+
+## Deriving the hook — the four-line bridge (this is the hard part)
+
+"Use a real signal" is advice everyone gives and almost nobody executes. The reason a personalized email still reads generic is that the writer names the signal and then jumps straight to a generic pain ("...so you probably want to grow faster"). The skill of a cold open is the **inference chain** from an observable fact to a pain the reader silently agrees with. Build it in four lines, on paper, before you write a word of copy:
+
+1. **OBSERVE** — the raw, checkable fact. ("Acme posted 3 SRE reqs in Q1.") It must be something you could screenshot. If you can't cite where you saw it, it is not a signal.
+2. **INFER** — the operational consequence a person *in that role* feels. ("3 SRE openings unfilled for a quarter = the on-call rotation is thin and the existing team is absorbing the pages.") This is the line bare agents skip. The inference must be specific to the role and non-obvious enough that the reader thinks "how did they know that" — not "everyone says that."
+3. **BRIDGE** — connect the inference to the one thing you do. ("We cut the page volume so a thin rotation survives without the missing hires.") Not your whole value prop — the single slice that maps to *this* inference.
+4. **PROVE** — one comparable, with a number if you have it. ("~40% fewer alerts for two infra teams your size, month one.")
+
+The first-touch body is literally lines 2→3→4 in order; line 1 becomes the subject. If the INFER line is generic, the email is generic no matter how many merge fields you add. **Test the INFER line in isolation: would it be false for a competitor in the same situation? If it is true of everyone, it is a platitude — go back to the OBSERVE step and pick a sharper fact.**
+
+Two boundaries on the OBSERVE line, because both are unrecoverable once sent: keep it **professional, public and business-relevant** ("saw you're hiring 3 SREs" is relevant; "saw you were at the lake house last weekend" is surveillance), and **never invent it** — a fabricated "I loved your recent post on X" that does not exist destroys trust on contact.
+
+When the user hands you only a company name and no signal, do not invent one. Ask for (or, if you have web access, look up) one of these signal classes, ranked by reply lift: a **hiring/role-change** signal > a **funding/launch/news** signal > a **tech-stack or job-description detail** > a **public number from their own site/report** > a **shared context** (mutual, group, event). A generic industry trend ("AI is changing your space") is not a signal and never clears the INFER test. If no true signal exists at all, that is a `lead-gen` targeting gap, not a copy task. Worked OBSERVE→INFER→BRIDGE→PROVE chains across six industries live in `references/hook-derivation.md`.
+
+## The sequence — decision table
+
+A first email captures **~58% of replies; steps 2-7 add the remaining ~42%**, and reply rates fall off sharply after the 5th email. *(Instantly Benchmark 2026.)* So the sequence is non-optional, but it is short. **4-7 touches, 2-4 days apart, each adding ONE new angle** — never "just bumping this up."
+
+| Step | Day offset | Angle (one new thing) | CTA |
+|---|---|---|---|
+| 1 | 0 | The observed signal + outcome | Binary yes/no |
+| 2 | +3 | A proof point / mini case study | Same binary ask, reframed |
+| 3 | +7 | A different pain or angle on the value | Lower-friction ask (a resource, not a call) |
+| 4 | +12 | Social proof or a relevant comparison | Binary ask |
+| 5 (breakup) | +18 | Permission to stop — "should I close the file?" | One-question close |
+| 6-7 (optional) | +25 / +35 | New trigger only if one genuinely appeared | Re-open, binary |
+
+Rules that make the table work:
+
+- **Stop at 5 unless a real new trigger appears.** Replies past the 5th email are thin; do not pad to 7 for its own sake.
+- **The breakup (step 5) is the highest-converting follow-up after step 1** — it gives a graceful out and often gets the "actually, yes" reply. Always include it.
+- **One angle per step.** If step 3 just restates step 1, delete step 3.
+- **Keep follow-ups in the same thread** (reply to your own first email) so context travels with the touch.
+
+## Channel adaptation — email vs LinkedIn
+
+| Dimension | Cold email | LinkedIn |
+|---|---|---|
+| First-touch length | ≤ ~80 words | Connection note ≤ ~300 chars; DM ~3-4 sentences |
+| Hook source | A site/news/hiring signal | One specific profile signal (a post, a role change, a shared group) |
+| CTA | Binary yes/no question | Soft — a question or a relevant share, not a pitch in the note |
+| Volume ceiling | 20-50/day per inbox (see below) | ~100 connection requests/week free, **safer under 80**, rolling weekly |
+| Reply benchmark | ~3.43% avg, 10%+ elite | ~6-7% avg, 10%+ excellent |
+
+*(LinkedIn figures: Skylead / Kondo / Expandi 2025-2026 guides, accessed 2026-06-02.)*
+
+On LinkedIn the connection note must **not** pitch — earn the connection on a real signal, then make the ask in the first DM after they accept.
+
+Reusable skeletons for both channels — first-touch + 4-step bump, with every variable slot (`{{signal}}`, `{{outcome}}`, `{{proof}}`) marked — live in `references/templates.md`. Start from a skeleton, then fill every slot with a *real* value before sending. An unfilled slot is a defect, not a placeholder to ship.
+
+## Sending cadence & deliverability guardrails
+
+You own the *cadence* side of deliverability; the DNS/auth side is `email-deliverability`. Apply these limits to the plan you hand the user:
+
+- **Per inbox: 20-50 cold sends/day even after warm-up.** The technical Gmail ceiling is ~100, but cold mail should stay well under it. Need more volume? Add inboxes, do not raise the per-inbox number.
+- **New-domain warm-up ramp** (warm-up mail counts toward the daily cap):
+
+| Week | Sends/day per inbox |
+|---|---|
+| 1 | ~10-20 |
+| 2 | ~20-35 |
+| 3 | ~35-50 |
+| 4+ | ~50-65 (hold cold sends at 20-50) |
+
+- **Bounce rate under 2%.** A higher bounce means the list is stale → that is a `lead-gen` problem, not a copy problem.
+- **Spam-complaint rate under 0.3%; Google advises under 0.1%.** One-click unsubscribe (RFC 8058: `List-Unsubscribe` + `List-Unsubscribe-Post`) is required for bulk senders to Gmail/Yahoo; Outlook applied the same from 2025-05-05, with Gmail/Yahoo enforcement ramping from Nov 2025. *(Google Workspace "Email sender guidelines"; Security Boulevard 2025-11; Proofpoint 2025 — accessed 2026-06-02.)*
+
+If the user asks you to *configure* the `List-Unsubscribe` header, SPF, or DKIM, stop and route to `email-deliverability` — you specify that the opt-out must exist and be one-click; that skill wires the header.
+
+## Compliance footer (every cold send needs one)
+
+| Requirement | CAN-SPAM (US) | GDPR (EU B2B) |
+|---|---|---|
+| Sender identity | Accurate From/Reply-To, honest subject | Same |
+| Postal address | A physical mailing address, required | Recommended; identify the controller |
+| Opt-out | Clear opt-out, honored within 10 business days | Honored without undue delay (treat as 24-48h) |
+| Legal basis | Not consent-based; truthful + opt-out suffices | Art. 6(1)(f) legitimate interest **with a documented LIA** |
+| Penalty | Up to $53,088 per email (Jan 2025) | Up to €20M or 4% of global revenue |
+
+*(Instantly compliance guide / Puzzle Inbox; litemail.ai / complydog GDPR guides 2026 — accessed 2026-06-02.)*
+
+EU enforcement varies — UK ICO and France CNIL are permissive for B2B; Germany and Poland are stricter (Poland often requires prior consent). When the recipient is in the EU, write the footer for the strictest plausible jurisdiction. The full footer wording, the LIA checklist, and the CASL/Australia matrix → `references/compliance-footer.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| Blast 200/day from one new inbox | Trips spam filters; tanks domain reputation in days | Ramp per the table; hold 20-50/day; split across inboxes |
+| Pitch in sentence one | No earned relevance; reads like a billboard | Lead with the observed signal, earn the ask |
+| Two CTAs ("call OR I'll send a guide") | Splits the decision; lowers reply rate | One binary yes/no ask per email |
+| "Just following up" / "circling back" with no new angle | Adds noise, not value; trains them to ignore you | Each step adds one new angle or it is deleted |
+| Name-only mail merge or spintax (`{Hi\|Hey}`) as "personalization" | Recipients see the template underneath | One true `{{signal}}` per first touch or do not send |
+| No opt-out / no postal address | CAN-SPAM/GDPR violation; complaint-rate spike | Always append the compliant footer |
+| Subject like "Quick question!!" or "FREE" | Clickbait + spam-trigger words land you in spam | ≤6 plain words that read like a coworker wrote them |
+| Padding to 7 steps for completeness | Replies past step 5 are thin; you just annoy | Stop at the breakup unless a real new trigger appears |
+| "I hope this email finds you well" opener | The classic AI/template tell; wastes the first line | Open on the signal — your first 6 words are the hook |
+
+To self-check a drafted email or sequence file, run `scripts/verify.sh path/to/draft.md` — it flags missing opt-out, multiple CTAs, over-ceiling word count, and spam/AI-tell phrases (read-only).