claude-code-arcane 1.2.0 → 1.3.0

package/skills/cv-ats-export/scripts/cv_export.py

@@ -0,0 +1,306 @@
+"""
+cv_export.py — Export Markdown CVs to ATS-compliant PDF.
+
+Converts a Markdown CV to styled HTML and prints it with headless Chrome/Edge
+(selectable text, single column, A4). No Obsidian, LaTeX or design tool needed.
+
+Usage (from anywhere; the script locates the career workspace):
+    python cv_export.py                          # all base CVs (CV - *.md)
+    python cv_export.py "CV - Acme - Backend"    # a single CV (with/without .md)
+    python cv_export.py --workspace ./career-workspace "CV - Acme"
+
+Workspace resolution order:
+    1. --workspace <path> flag
+    2. CAREER_WORKSPACE env var
+    3. walk up from the cwd looking for a folder containing "02-CVs" (or "02 - CVs")
+    4. the current working directory
+
+Output path:
+    - If frontmatter has `archivo_pdf`, the PDF is written to that path
+      relative to the CVs folder (<workspace>/02-CVs/<archivo_pdf>).
+    - Otherwise it goes to <workspace>/02-CVs/exports/<name>.pdf, where
+      <name> is the frontmatter field `archivo_final` if present, else the
+      .md filename with the "CV - " prefix stripped.
+
+Supported Markdown (what CVs use):
+  # ## ### headings · **bold** · *italic* · [text](url) · - bullets · ---
+  A single line break inside a paragraph becomes <br> (Obsidian-like).
+"""
+
+import html
+import os
+import re
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+# Possible names for the CVs folder (portable + Obsidian-style with spaces).
+CV_DIR_NAMES = ["02-CVs", "02 - CVs"]
+
+BROWSERS = [
+    # Windows
+    r"C:\Program Files\Google\Chrome\Application\chrome.exe",
+    r"C:\Program Files (x86)\Google\Chrome\Application\chrome.exe",
+    r"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe",
+    r"C:\Program Files\Microsoft\Edge\Application\msedge.exe",
+    # macOS
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+    # Linux
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+    "/usr/bin/chromium",
+    "/usr/bin/chromium-browser",
+    "/usr/bin/microsoft-edge",
+]
+
+# ATS-friendly print style: single column, selectable text, A4.
+CSS = """
+@page { size: A4; margin: 18mm 16mm 18mm 16mm; }
+body {
+  font-family: "Calibri", "Arial", "Helvetica", sans-serif;
+  font-size: 10.5pt; line-height: 1.35; color: #000; background: #fff;
+  margin: 0; padding: 0;
+}
+h1 { font-size: 18pt; font-weight: 700; margin: 0 0 2pt 0; padding: 0; }
+h2 {
+  font-size: 12pt; font-weight: 700; text-transform: uppercase;
+  letter-spacing: 0.5pt; border-bottom: 0.5pt solid #000;
+  padding: 0 0 1pt 0; margin: 10pt 0 5pt 0;
+  page-break-after: avoid;
+}
+h3 { font-size: 11pt; font-weight: 700; margin: 6pt 0 2pt 0; padding: 0; page-break-after: avoid; }
+p  { margin: 2pt 0; page-break-inside: avoid; }
+ul, ol { margin: 2pt 0 4pt 0; padding-left: 16pt; }
+li { margin: 1pt 0; page-break-inside: avoid; }
+strong { font-weight: 700; }
+a { color: #000; text-decoration: none; }
+hr { border: none; border-top: 0.5pt solid #000; margin: 6pt 0; }
+"""
+
+
+def find_cv_dir(start):
+    """Walk up from `start` looking for a directory containing a CVs folder."""
+    cur = Path(start).resolve()
+    for base in [cur, *cur.parents]:
+        for name in CV_DIR_NAMES:
+            cand = base / name
+            if cand.is_dir():
+                return cand
+    return None
+
+
+def resolve_cv_dir(workspace_arg):
+    # 1. explicit --workspace
+    if workspace_arg:
+        ws = Path(workspace_arg).resolve()
+        for name in CV_DIR_NAMES:
+            if (ws / name).is_dir():
+                return ws / name
+        # maybe they passed the CVs dir directly
+        if ws.name in CV_DIR_NAMES and ws.is_dir():
+            return ws
+        print(f"[ERROR] No CVs folder ({' / '.join(CV_DIR_NAMES)}) under: {ws}")
+        sys.exit(1)
+    # 2. env var
+    env = os.environ.get("CAREER_WORKSPACE")
+    if env:
+        for name in CV_DIR_NAMES:
+            if (Path(env) / name).is_dir():
+                return Path(env).resolve() / name
+    # 3. walk up from cwd
+    found = find_cv_dir(Path.cwd())
+    if found:
+        return found
+    # 4. cwd fallback
+    print("[ERROR] Could not locate a CVs folder. Use --workspace <path>.")
+    sys.exit(1)
+
+
+def strip_frontmatter(text):
+    """Return (frontmatter_dict, body). Flat key: value frontmatter."""
+    fm = {}
+    if text.startswith("---"):
+        end = text.find("\n---", 3)
+        if end != -1:
+            for line in text[3:end].strip().splitlines():
+                if ":" in line:
+                    k, _, v = line.partition(":")
+                    fm[k.strip()] = v.strip().strip('"')
+            text = text[end + 4:]
+    return fm, text.lstrip("\n")
+
+
+def inline(s):
+    """Inline markdown -> HTML (escape first, then links/bold/italic)."""
+    s = html.escape(s, quote=False)
+    s = re.sub(r"\[([^\]]+)\]\(([^)]+)\)", r'<a href="\2">\1</a>', s)
+    s = re.sub(r"\*\*(.+?)\*\*", r"<strong>\1</strong>", s)
+    s = re.sub(r"(?<!\*)\*([^*\n]+)\*(?!\*)", r"<em>\1</em>", s)
+    return s
+
+
+def md_to_html(md):
+    out = []
+    paragraph = []
+    in_list = False
+
+    def flush_paragraph():
+        if paragraph:
+            out.append("<p>" + "<br>".join(inline(l) for l in paragraph) + "</p>")
+            paragraph.clear()
+
+    def close_list():
+        nonlocal in_list
+        if in_list:
+            out.append("</ul>")
+            in_list = False
+
+    for raw in md.splitlines():
+        line = raw.rstrip()
+        stripped = line.strip()
+
+        if not stripped:
+            flush_paragraph()
+            close_list()
+            continue
+
+        m = re.match(r"^(#{1,3})\s+(.*)", stripped)
+        if m:
+            flush_paragraph()
+            close_list()
+            level = len(m.group(1))
+            out.append(f"<h{level}>{inline(m.group(2))}</h{level}>")
+            continue
+
+        if re.match(r"^(-{3,}|\*{3,})$", stripped):
+            flush_paragraph()
+            close_list()
+            out.append("<hr>")
+            continue
+
+        m = re.match(r"^[-*]\s+(.*)", stripped)
+        if m:
+            flush_paragraph()
+            if not in_list:
+                out.append("<ul>")
+                in_list = True
+            out.append(f"<li>{inline(m.group(1))}</li>")
+            continue
+
+        close_list()
+        paragraph.append(stripped)
+
+    flush_paragraph()
+    close_list()
+    return "\n".join(out)
+
+
+def find_browser():
+    for path in BROWSERS:
+        if Path(path).exists():
+            return path
+    return None
+
+
+def export(md_path, browser, cv_dir, export_dir):
+    text = md_path.read_text(encoding="utf-8")
+    fm, body = strip_frontmatter(text)
+
+    if fm.get("archivo_pdf"):
+        pdf_path = cv_dir / fm["archivo_pdf"]
+    else:
+        name = fm.get("archivo_final") or md_path.stem.replace("CV - ", "")
+        pdf_path = export_dir / f"{name}.pdf"
+    pdf_path.parent.mkdir(parents=True, exist_ok=True)
+
+    doc = (
+        "<!DOCTYPE html><html><head><meta charset='utf-8'>"
+        f"<title>{html.escape(md_path.stem)}</title>"
+        f"<style>{CSS}</style></head><body>"
+        + md_to_html(body)
+        + "</body></html>"
+    )
+
+    with tempfile.NamedTemporaryFile(
+        "w", suffix=".html", delete=False, encoding="utf-8"
+    ) as tmp:
+        tmp.write(doc)
+        tmp_path = Path(tmp.name)
+
+    try:
+        result = subprocess.run(
+            [
+                browser,
+                "--headless=new",
+                "--disable-gpu",
+                "--no-pdf-header-footer",
+                f"--print-to-pdf={pdf_path}",
+                tmp_path.as_uri(),
+            ],
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+        if result.returncode != 0 or not pdf_path.exists():
+            print(f"[ERROR] {md_path.name}: browser exit {result.returncode}")
+            print(result.stderr[-500:] if result.stderr else "(no stderr)")
+            return False
+    finally:
+        tmp_path.unlink(missing_ok=True)
+
+    size_kb = pdf_path.stat().st_size // 1024
+    print(f"[OK] {md_path.name} -> {pdf_path} ({size_kb} KB)")
+    return True
+
+
+def parse_args(argv):
+    workspace = None
+    names = []
+    i = 0
+    while i < len(argv):
+        a = argv[i]
+        if a == "--workspace":
+            i += 1
+            workspace = argv[i] if i < len(argv) else None
+        elif a.startswith("--workspace="):
+            workspace = a.split("=", 1)[1]
+        else:
+            names.append(a)
+        i += 1
+    return workspace, names
+
+
+def main():
+    workspace, names = parse_args(sys.argv[1:])
+
+    browser = find_browser()
+    if not browser:
+        print("[ERROR] Chrome/Edge not found in standard paths. Install one or edit BROWSERS.")
+        sys.exit(1)
+
+    cv_dir = resolve_cv_dir(workspace)
+    export_dir = cv_dir / "exports"
+
+    if names:
+        targets = []
+        for n in names:
+            p = cv_dir / (n if n.endswith(".md") else n + ".md")
+            if not p.exists():
+                print(f"[ERROR] Not found: {p}")
+                sys.exit(1)
+            targets.append(p)
+    else:
+        targets = sorted(cv_dir.glob("CV - *.md"))
+
+    if not targets:
+        print(f"[ERROR] No CVs (CV - *.md) found in {cv_dir}.")
+        sys.exit(1)
+
+    ok = all([export(t, browser, cv_dir, export_dir) for t in targets])
+    sys.exit(0 if ok else 1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/cv-tailor/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: cv-tailor
+description: "Tailor a CV to a specific job description: extract ATS keywords, decide what to emphasize vs downplay, and rewrite achievement bullets in the offer's vocabulary, starting from a role profile. Triggers: adaptar CV, custom CV, tailor resume, CV para esta oferta, optimizar CV para ATS, matchear CV con job description."
+argument-hint: "[job-url | path-to-jd | application-note]"
+category: "career"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit, WebFetch
+---
+
+# CV Tailor — Adaptar el CV a la oferta
+
+Tomás un job description y el perfil base del usuario, y producís un **CV custom** que matchea con los filtros automáticos (ATS) y con la lectura humana del hiring manager. No reescribís la verdad — la reorganizás y la traducís al vocabulario de la oferta.
+
+## Inputs
+
+- **El job description** (URL → usá WebFetch, o texto pegado, o una nota de `03-Aplicaciones/`).
+- **El perfil base**: `01-Perfiles/<Role>.md` (derivado del maestro vía `/master-profile derive`). Si no existe, sugerir crearlo.
+- **Research del contacto/empresa** si existe en `04-Empresas/` y `05-Contactos/`.
+
+## Proceso
+
+### 1. Analizar la oferta
+- Extraer **keywords literales** del JD: tecnologías, metodologías, responsabilidades, soft skills, seniority. Literal importa — el ATS hace matching de strings (ej: si piden "React.js" no asumas que "React" matchea igual).
+- Detectar **must-have vs nice-to-have**.
+- Detectar **señales de cultura / ángulo** (startup vs enterprise, code-forward, ownership, etc.).
+- Ver `references/ats-keywords.md` para cómo extraer y mapear keywords.
+
+### 2. Mapear contra el perfil
+- Por cada must-have: ¿qué experiencia/proyecto del perfil lo cubre? Marcar gaps honestos.
+- Decidir **qué resaltar** (lo que más alinea, arriba y con más espacio) y **qué bajar de volumen** (lo irrelevante para este rol).
+
+### 3. Reescribir
+- Reordenar experiencia y proyectos hacia el rol.
+- Reescribir bullets de logros usando el vocabulario de la oferta, manteniendo número→contexto→resultado.
+- Inyectar keywords de forma natural (en bullets reales, no en un "keyword stuffing" detectable).
+- Ajustar el headline/summary al rol exacto.
+
+### 4. Score before/after
+- Calcular un **match rate** aproximado: % de keywords/requisitos del JD presentes en el CV, **antes** vs **después** del tailoring.
+- Reportar el delta ("match 48% → 81%") y qué keywords se cubrieron.
+- **Flag de keyword stuffing:** marcar cualquier inserción que a un revisor humano le suene forzada o poco natural — el objetivo es pasar el ATS *y* leer bien para una persona.
+
+### 5. Producir el CV custom
+- Crear/actualizar la nota en `02-CVs/CV - <Empresa> - <Rol>.md` usando el template `CV Custom` (`Templates/CV Custom.md`).
+- Completar frontmatter (`perfil_base`, `aplicacion`, `empresa`, `archivo_pdf`).
+- Documentar las decisiones (keywords, qué se resaltó/bajó) en las secciones del template — sirve para la entrevista y para iterar.
+- El cuerpo del CV en sí debe quedar listo para `/cv-ats-export` (markdown limpio: `# nombre`, `## secciones`, bullets, `---`).
+
+## Formato del CV (ATS-friendly)
+
+- **Una columna.** Sin tablas, sin cajas de texto, sin columnas — los ATS las leen mal.
+- Secciones estándar con headers claros: Summary, Experience, Skills, Projects, Education.
+- Fechas consistentes (MM/YYYY).
+- Sin gráficos ni imágenes para el contenido crítico.
+- Verbos de acción + métricas.
+
+## Idioma
+
+CV en **inglés** para roles internacionales/remotos globales; **español** si la oferta/empresa es hispanohablante. Ante la duda, preguntar.
+
+## Reglas
+
+- Nunca inventar experiencia, fechas o métricas. Tailoring = reorganizar y traducir, no mentir.
+- No keyword-stuffing: cada keyword debe vivir en un bullet verdadero.
+- Un CV custom por postulación — no pisar el perfil base ni el maestro.
+- Después de generar el `.md`, recordar al usuario correr `/cv-ats-export` para el PDF.
+
+## Handoff
+
+Pedí aprobación (approval) antes de escribir el CV custom. Cuando el `.md` está READY, el siguiente paso es `/cv-ats-export` para generar el PDF ATS y `/cover-letter` para el mensaje.

package/skills/cv-tailor/references/ats-keywords.md

@@ -0,0 +1,46 @@
+# ATS Keywords — Cómo extraer y mapear
+
+Los Applicant Tracking Systems (Greenhouse, Lever, Workday, Workable, etc.) hacen un primer filtro automático antes de que un humano vea el CV. Entender cómo "leen" cambia el resultado.
+
+## Cómo funciona un ATS (modelo mental)
+
+- Parsea el CV a texto plano y lo indexa.
+- Hace matching de **strings** y variantes contra la oferta y/o contra criterios del recruiter.
+- Rankea o filtra candidatos por densidad/relevancia de keywords y por campos estructurados (título, fechas, ubicación).
+- **Lo que rompe el parseo:** tablas, columnas, text boxes, headers/footers con datos, gráficos, iconos en lugar de texto, PDFs escaneados (imagen).
+
+## Extracción de keywords del JD
+
+1. **Hard skills / tecnologías** — lenguajes, frameworks, DBs, cloud, herramientas. Copiá la forma **literal** (React.js ≠ React ≠ ReactJS para un match exacto; cuando puedas, incluí la variante que usa la oferta).
+2. **Responsabilidades / verbos** — "design REST APIs", "lead a team", "CI/CD pipelines".
+3. **Metodologías** — Agile, Scrum, TDD, clean architecture.
+4. **Seniority y años** — "5+ years", "senior", "lead".
+5. **Soft skills explícitos** — communication, ownership, cross-functional.
+6. **Señales de cultura / frases gatillo** — ej. "code-forward", "startup mentality", "high autonomy". Suelen indicar qué valoran y dan ángulo para el summary y la cover letter.
+
+## Mapeo contra el perfil
+
+| Keyword del JD | ¿Lo tengo? | Dónde lo demuestro (bullet/proyecto) | Acción |
+|---|---|---|---|
+| React.js | Sí | "Built React + TS frontends @ X" | resaltar arriba |
+| Kubernetes | Parcial | exposición en CI/CD | mencionar honesto |
+| Go | No | — | gap; no inventar |
+
+- **Must-have que tenés** → arriba, con espacio, con la palabra exacta.
+- **Must-have parcial** → mencionar con honestidad ("exposure to…").
+- **Must-have que no tenés** → gap real; no lo inventes. Decidí si igual aplicás.
+
+## Inyección natural (no stuffing)
+
+- Cada keyword vive en un **bullet verdadero** con contexto y resultado.
+- Una sección "Skills" lista las tecnologías (bien para el ATS), pero las importantes también deben aparecer en la experiencia (bien para el humano y para el ranking).
+- Evitá listas de 40 tecnologías sin contexto: lee como relleno y diluye el ranking.
+
+## Checklist de formato ATS-safe
+
+- [ ] Una sola columna, sin tablas/text boxes.
+- [ ] Headers de sección estándar (Experience, Skills, Education…).
+- [ ] Fechas consistentes MM/YYYY.
+- [ ] Texto seleccionable (no imagen) — el export de `/cv-ats-export` ya lo garantiza.
+- [ ] Nombre del archivo profesional (`Nombre_Apellido_Empresa.pdf`).
+- [ ] Contacto en el cuerpo, no en el header/footer del documento.

package/skills/dotnet-architecture/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: dotnet-architecture
+description: "Arquitectura de backends .NET: Vertical Slice Architecture (features) y Clean Architecture (capas), con guía de cuándo usar cada una, estructura, patrones (MediatR/Result/outbox) y anti-patterns. Usar al diseñar o revisar la estructura de un proyecto ASP.NET Core."
+category: "backend"
+argument-hint: "[vertical-slice|clean|when-to-use]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# dotnet-architecture — VSA & Clean Architecture para .NET
+
+Dos enfoques production-ready para estructurar un backend ASP.NET Core. No son excluyentes: muchos proyectos
+usan Clean Architecture en el borde y slices verticales adentro. Esta skill ayuda a **elegir** y a aplicar
+cada uno correctamente.
+
+## MANDATORY WORKFLOW
+
+**No imponer arquitectura por moda. Elegir según complejidad del dominio y vida del proyecto.**
+
+### Step 0: Elegir enfoque (`when-to-use`)
+
+| Señal | Recomendación |
+|-------|---------------|
+| CRUD, prototipos, APIs chicas, dominio fino, equipo chico | **Vertical Slice** (o single project) |
+| Dominio complejo, reglas de negocio ricas, long-lived, varios equipos | **Clean Architecture** |
+| Necesitás aislar el dominio de frameworks/DB para test y reemplazo | **Clean Architecture** |
+| Querés velocidad y bajo overhead de indirección | **Vertical Slice** |
+
+> Evitá Clean Architecture para CRUD simple: los proyectos extra y la indirección cuestan más de lo que aportan
+> cuando la lógica de negocio es delgada. Empezá con Vertical Slice y migrá si el dominio crece.
+
+### Step 1: Aplicar la estructura
+
+- **Vertical Slice:** un folder por feature/use-case; cada slice tiene su request, handler, validator y endpoint juntos. Ver `references/project-structure.md`.
+- **Clean Architecture:** proyectos `Domain → Application → Infrastructure → Api`; las dependencias apuntan **hacia adentro**, nunca al revés. Ver `references/project-structure.md`.
+
+### Step 2: Patrones idiomáticos
+
+Leer `references/patterns.md`: MediatR/handlers por use-case, `IApplicationDbContext` (exponer EF Core sin repos
+genéricos), pipeline behaviors (validación/logging/transacción), Result pattern en vez de excepciones para flujo,
+y outbox pattern para consistencia entre DB y eventos.
+
+### Step 3: Revisar contra anti-patterns + checklist
+
+- `references/anti-patterns.md` — repos genéricos sobre EF Core, fat controllers, dependencias que apuntan hacia afuera, lógica de dominio en Infrastructure.
+- `references/checklist.md` — verificación de cierre antes de dar la estructura por buena.
+
+Antes de aplicar una reestructuración significativa, confirmar el approach con el usuario (Question → Decision → Approval). Si todo el checklist pasa → arquitectura **COMPLIANT**.
+
+## Resumen de enfoques
+
+| Aspecto | Vertical Slice | Clean Architecture |
+|---------|----------------|--------------------|
+| Eje de organización | Feature / use-case | Capa técnica |
+| Proyectos | 1 (+ tests) | 4 (Domain/App/Infra/Api) |
+| Acoplamiento entre features | Bajo (slices independientes) | Mediado por Application |
+| Overhead inicial | Bajo | Alto |
+| Mejor para | CRUD, features, velocidad | Dominios complejos, long-lived |
+| Riesgo | Duplicación entre slices | Sobre-ingeniería |
+
+## Próximos pasos
+
+Definida la arquitectura → `/dotnet-scaffold` para generar el proyecto, y `/dotnet-best-practices` para revisar el código contra las 40 reglas.
+
+---
+
+_Inspirado en [ardalis/CleanArchitecture](https://github.com/ardalis/CleanArchitecture), [nadirbad/VerticalSliceArchitecture](https://github.com/nadirbad/VerticalSliceArchitecture) y la guía de Vertical Slice de [Milan Jovanović](https://www.milanjovanovic.tech/blog/vertical-slice-architecture-dotnet). Adaptado al formato Arcane._

package/skills/dotnet-architecture/references/anti-patterns.md

@@ -0,0 +1,12 @@
+# Anti-Patterns
+
+- **`IRepository<T>` / `IUnitOfWork` genérico sobre EF Core** — el `DbContext` ya es repositorio (`DbSet<>`) y Unit of Work (`SaveChangesAsync`); envolverlo agrega indirección sin valor y te tapa LINQ/Include/proyecciones.
+- **Fat controllers / endpoints con lógica de negocio** — el endpoint solo traduce HTTP ↔ request y mapea el resultado; las reglas van en el handler/dominio, no en el controlador.
+- **Dependencias apuntando hacia afuera** — `Domain` referenciando `Infrastructure` o EF Core rompe la regla de dependencias: el dominio deja de ser testeable y reemplazable.
+- **Application anémica que solo reenvía a repos** — si el handler no hace más que `return repo.Get(id)`, la capa no aporta nada; movés lógica de negocio real al dominio/handler o eliminás la indirección.
+- **Filtrar entidades EF como respuestas de API** — exponer entidades de persistencia acopla el contrato HTTP al schema de la DB y arrastra lazy-loading/ciclos; devolvé DTOs en el borde.
+- **Forzar Clean Architecture en un CRUD simple** — cuatro proyectos y pipeline behaviors para listar y guardar registros es sobre-ingeniería; empezá con Vertical Slice o single project.
+- **Service locator estático / `BuildServiceProvider()` en `Program.cs`** — construir el provider a mano crea grafos duplicados y dependencias ocultas; registrá todo en el contenedor y dejá que resuelva por constructor.
+- **Un `Services/` y `Controllers/` gigantes** — organizar por tipo técnico dispersa cada feature en cinco carpetas; organizá por feature/slice para que un caso de uso viva junto.
+
+_Ref: https://www.milanjovanovic.tech/blog/vertical-slice-architecture-dotnet · https://github.com/ardalis/CleanArchitecture · https://learn.microsoft.com/en-us/ef/core/dbcontext-configuration/_

package/skills/dotnet-architecture/references/checklist.md

@@ -0,0 +1,19 @@
+# Checklist
+
+Verificá antes de dar la estructura por buena.
+
+- [ ] Las dependencias apuntan hacia adentro: `Api → Infrastructure → Application → Domain`
+- [ ] `Domain` no tiene `<ProjectReference>` ni paquetes de framework (sin EF, sin ASP.NET)
+- [ ] No hay `IRepository<T>` / `IUnitOfWork` genérico envolviendo EF Core
+- [ ] EF Core se expone vía `IApplicationDbContext` en Application, implementado en Infrastructure
+- [ ] En Vertical Slice, cada slice es autocontenido (request + handler + validator + endpoint)
+- [ ] Los slices no dependen entre sí (acoplamiento solo vía `Common`/`Infrastructure`)
+- [ ] DTOs en el borde: ninguna entidad EF se devuelve como respuesta de API
+- [ ] Cada handler tiene una sola responsabilidad (un caso de uso por archivo)
+- [ ] `Program.cs` es solo composition root (DI + pipeline + map endpoints), sin lógica de negocio
+- [ ] La validación corre en un pipeline behavior, no repetida en cada endpoint
+- [ ] Fallos esperados se modelan con `Result<T>`/`ErrorOr`, no con excepciones de flujo
+- [ ] Las migraciones EF Core están versionadas en git
+- [ ] El enfoque elegido (VSA vs Clean) corresponde a la complejidad real del dominio
+
+_Ref: https://github.com/ardalis/CleanArchitecture · https://github.com/nadirbad/VerticalSliceArchitecture · https://www.milanjovanovic.tech/blog/clean-architecture-folder-structure_

package/skills/dotnet-architecture/references/patterns.md

@@ -0,0 +1,118 @@
+# Patrones Idiomáticos (.NET 10 / ASP.NET Core)
+
+## Handler por caso de uso
+
+Un request (record) + un handler. Con MediatR o con un sender hand-rolled mínimo.
+
+```csharp
+public sealed record CreateOrder(Guid CustomerId, decimal Amount) : IRequest<Result<Guid>>;
+
+internal sealed class CreateOrderHandler(IApplicationDbContext db)
+    : IRequestHandler<CreateOrder, Result<Guid>>
+{
+    public async Task<Result<Guid>> Handle(CreateOrder cmd, CancellationToken ct)
+    {
+        var order = Order.Create(cmd.CustomerId, cmd.Amount);
+        db.Orders.Add(order);
+        await db.SaveChangesAsync(ct);
+        return order.Id;
+    }
+}
+```
+
+## IApplicationDbContext (EF Core detrás de una interfaz, sin repo genérico)
+
+Exponé el `DbContext` a través de una interfaz en `Application`; implementala en
+`Infrastructure`. El `DbContext` ya es Unit of Work + repositorio: no lo envuelvas.
+
+```csharp
+// Application/Common/IApplicationDbContext.cs
+public interface IApplicationDbContext
+{
+    DbSet<Order> Orders { get; }
+    DbSet<Customer> Customers { get; }
+    Task<int> SaveChangesAsync(CancellationToken ct = default);
+}
+
+// Infrastructure/Persistence/AppDbContext.cs
+public sealed class AppDbContext(DbContextOptions<AppDbContext> options)
+    : DbContext(options), IApplicationDbContext
+{
+    public DbSet<Order> Orders => Set<Order>();
+    public DbSet<Customer> Customers => Set<Customer>();
+}
+```
+
+## Pipeline behaviors (validación, logging, transacción)
+
+Cross-cutting concerns alrededor de cada handler, sin ensuciar la lógica.
+
+```csharp
+public sealed class ValidationBehavior<TReq, TRes>(IEnumerable<IValidator<TReq>> validators)
+    : IPipelineBehavior<TReq, TRes> where TReq : notnull
+{
+    public async Task<TRes> Handle(TReq req, RequestHandlerDelegate<TRes> next, CancellationToken ct)
+    {
+        foreach (var v in validators)
+        {
+            var result = await v.ValidateAsync(req, ct);
+            if (!result.IsValid) throw new ValidationException(result.Errors);
+        }
+        return await next();
+    }
+}
+```
+
+Un `TransactionBehavior` similar abre `BeginTransactionAsync` antes de `next()` y
+hace commit/rollback alrededor: el UnitOfWork vive acá, no en repos a mano.
+
+## Result pattern para fallos esperados
+
+No tires excepciones para flujo de negocio esperado (not found, validación, conflicto).
+Devolvé `Result<T>` (o `ErrorOr<T>`) y mapealo a HTTP en el endpoint.
+
+```csharp
+public readonly record struct Error(string Code, string Message);
+
+public async Task<Result<OrderDto>> Handle(GetOrder q, CancellationToken ct)
+{
+    var order = await db.Orders.FindAsync([q.Id], ct);
+    return order is null
+        ? new Error("Order.NotFound", "Order no existe")
+        : order.ToDto();
+}
+```
+
+## Outbox pattern (consistencia DB + eventos)
+
+Para publicar eventos de forma confiable: persistí el evento en una tabla `Outbox`
+**dentro de la misma transacción** que el cambio de datos. Un background worker
+(`BackgroundService`) lee la tabla y publica al broker; así nunca queda el estado
+guardado sin el evento ni el evento sin el estado.
+
+## TypedResults en minimal API endpoints
+
+El endpoint es delgado: traduce HTTP ↔ request y mapea el `Result` a status code.
+
+```csharp
+public static class OrderEndpoints
+{
+    public static void Map(this IEndpointRouteBuilder app)
+    {
+        var group = app.MapGroup("/orders").WithTags("Orders");
+
+        group.MapPost("/", async (CreateOrder cmd, ISender sender, CancellationToken ct) =>
+        {
+            var result = await sender.Send(cmd, ct);
+            return result.IsError
+                ? TypedResults.Problem(result.FirstError.Message)
+                : TypedResults.Created($"/orders/{result.Value}", result.Value);
+        });
+    }
+}
+```
+
+`TypedResults` da el tipo de respuesta exacto (útil para OpenAPI y tests) en vez del
+`Results` no tipado.
+
+_Ref: https://www.milanjovanovic.tech/blog/internal-vs-public-apis-in-clean-architecture · https://github.com/ardalis/CleanArchitecture · https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis/responses_