claude-code-arcane 2.0.0 → 2.1.0

package/skills/second-brain/references/templates/vault-CLAUDE.md

@@ -0,0 +1,127 @@
+# <NOMBRE DEL VAULT>
+
+Vault de Obsidian usado como segundo cerebro. Este archivo es el contrato: Claude Code lo lee al inicio de cada sesión y de acá saca dónde va cada cosa. Si una convención cambia, se cambia acá primero.
+
+## Quién soy
+
+<Rol, en qué proyectos estoy, qué temas me interesan. Dos o tres líneas: sirve para que las síntesis tengan contexto y no sean genéricas.>
+
+## Rutas
+
+Contrato de rutas: los skills escriben en **roles**, y esta tabla dice qué carpeta es cada rol en este vault. Si cambiás una carpeta de lugar, se cambia acá y todo lo demás sigue funcionando.
+
+| Rol | Ruta en este vault |
+|---|---|
+| `inbox` | `_inbox` |
+| `daily` | `Reflect/Daily` |
+| `weekly` | `Reflect/Weekly` |
+| `monthly` | `Reflect/Monthly` |
+| `atomic` | `03_Resources` |
+| `hubs` | `Hubs` |
+| `projects` | `01_Projects` |
+| `areas` | `02_Areas` |
+| `archive` | `04_Archive` |
+| `templates` | `Templates` |
+
+Y tres archivos fijos en la raíz: este `CLAUDE.md` (el contrato), `hot.md` (el caché de contexto reciente, lo reescribe `/review-dump`) y `codebases.md` (el puente a los repos, si hay código).
+
+Un rol que este vault no usa se marca `(no usa)` en vez de borrar la fila: así queda explícito que la ausencia fue una decisión.
+
+Los scripts reciben esto por flag: `--role hubs=Hubs --role atomic=03_Resources`.
+
+## Estructura
+
+| Carpeta | Qué vive acá |
+|---|---|
+| `_inbox/` | Captura cruda, un archivo por día (`YYYY-MM-DD dump.md`). Sin estructura, sin tags, sin pensar. El sufijo evita que el nombre choque con el del daily. |
+| `Reflect/Daily/` | Síntesis del día (`YYYY-MM-DD.md`), la crea `/review-dump`. |
+| `Reflect/Weekly/` | Retrospectiva semanal (`YYYY-Www.md`). |
+| `Reflect/Monthly/` | Balance del mes (`YYYY-MM.md`). |
+| `01_Projects/` | Algo con deadline o resultado definido. Cuando cierra, va a `04_Archive/`. |
+| `02_Areas/` | Responsabilidad continua sin fecha de fin (salud, finanzas, un rol). |
+| `03_Resources/` | Notas atómicas: una idea por nota, plano, sin subcarpetas. |
+| `04_Archive/` | Cerrado. Nunca se borra nada, se archiva. |
+| `Hubs/` | Una nota por entidad que importa: persona, herramienta, concepto, empresa. |
+| `Bases/` | Vistas `.base`. |
+| `Templates/` | Mis plantillas. Claude no las edita. |
+
+## Contrato de frontmatter
+
+Todo campo que se escriba tiene que estar acá. Un campo que no está declarado no se inventa: se propone y se agrega primero.
+
+```yaml
+---
+created: YYYY-MM-DD        # ISO, nunca se reescribe
+type: daily                # daily | weekly | monthly | dump | atomic | hub | project | area | clip
+status: seed               # madurez, solo en atomic, hub y clip (ver abajo)
+tags: []
+---
+```
+
+### `status`: madurez de la nota
+
+Solo para `atomic`, `hub` y `clip`. Las notas periódicas (`daily`, `weekly`, `monthly`, `dump`) no lo llevan: son registro, no conocimiento, y no maduran.
+
+| Valor | Significa | Efecto |
+|---|---|---|
+| `seed` | Apenas plantada, incompleta a propósito | No cuenta como hueca. Si sigue `seed` a los 30 días, el audit la marca: una semilla que no crecio es la falla clasica del vault. |
+| `provisional` | Tiene cuerpo pero no la sostendría en una discusión | Default de una nota recién escrita con contenido |
+| `evergreen` | Dice lo que tiene que decir. Puede quedarse quieta años | **No cuenta como stale.** Es lo que distingue una nota que ya hizo su trabajo de una abandonada. |
+| `contested` | Contradice a otra nota del vault y no está resuelto | El audit la lista para que un review la mire. La contradicción se preserva, no se resuelve sola. |
+| `archived` | Cerrada | Fuera del alcance del audit, viva donde viva |
+
+Sin este campo el audit no puede distinguir una nota de referencia que terminó su trabajo de un stub que nunca creció, y reporta las dos como stale.
+
+**Los proyectos usan el mismo campo con otro vocabulario** (`activo | pausado | cerrado`): es su ciclo de vida, no su madurez. El audit solo interpreta los cinco valores de arriba, así que un `activo` le resulta inerte y el proyecto se evalúa como cualquier otra nota. Si eso te molesta, renombralo acá y el contrato manda.
+
+Campos adicionales por tipo:
+
+| `type` | Campos propios |
+|---|---|
+| `project` | `status: activo \| pausado \| cerrado`, `deadline` (opcional), `repos:` si tiene código |
+| `clip` | `source` (URL), `author` (opcional) |
+| `hub` | `aliases` (nombres alternativos de la entidad), `repos:` si la entidad tiene código |
+
+`repos:` es el puente al código: la lista de repos que implementan esa entidad. Se traduce a path local en `codebases.md`. **El vault apunta, no copia:** la arquitectura vive en el repo.
+
+## Reglas de link
+
+- **Los links van hacia arriba, nunca hacia abajo.** Dump linkea a hubs y proyectos. Daily linkea al dump. Weekly linkea a los dailies. Monthly linkea a los weeklies. Los backlinks de Obsidian dan la dirección inversa gratis.
+- **Ninguna nota se cierra sin al menos un `[[wikilink]]`.** Si no hay a qué linkearla, falta un hub file.
+- `[[wikilinks]]` para lo interno, `[texto](url)` solo para URLs externas.
+
+## Tareas
+
+Las tareas viven en la nota a la que pertenecen, no en una lista central. Una tarea de un proyecto vive en la nota del proyecto; una que apareció en el día vive en el dump de ese día.
+
+**Una tarea abierta no se arrastra al día siguiente.** Queda en su día marcada como cancelada (`- [-]`) y se crea de nuevo donde corresponda. No haber hecho algo un día es información.
+
+## Qué puede hacer Claude
+
+- Crear y editar notas, clasificar el dump, actualizar hub files, generar dailies/weeklies/monthlies, buscar en el vault, proponer links.
+
+## Qué no puede hacer Claude
+
+- Borrar notas (mueve a `04_Archive/`).
+- Renombrar o mover notas sin que yo lo apruebe.
+- Editar `Templates/` ni nada dentro de `.obsidian/`.
+- Escribir la sección de reflexión de los reviews: los hechos los sintetiza Claude, la interpretación la escribo yo.
+- Editar en masa: los cambios que afectan muchas notas van por `/vault-tidy` con approval.
+
+## Plugins instalados
+
+<Completado por `/second-brain setup` con la detección real. Lo que no está en esta lista no se usa en las notas.>
+
+## Quién escribe qué
+
+- **Autorado** (lo escribo yo, Claude no lo toca sin approval): dumps, notas atómicas, hubs, clips, proyectos, este archivo, y la `## Reflexión` de los reviews.
+- **Sintetizado** (Claude lo escribe con mi OK y queda como nota): dailies, weeklies, monthlies, el `## Historial` de los hubs.
+- **Proyectado** (Claude lo reescribe sin preguntar, es derivado y descartable): `hot.md`, `.vault-index.json`, las vistas `.base`. No los edito a mano porque se pisan.
+
+## Uso desde otros proyectos
+
+Otros repos pueden leer este vault. El orden de lectura es `hot.md` → búsqueda con `vault_index.py` → el hub del tema → la nota. **No se lee el vault para preguntas generales de programación**, y no se escribe en él desde otro proyecto salvo pedido explícito. Receta completa: `/second-brain link`.
+
+## Git
+
+Este vault es un repo git. Antes de una corrida que escribe varias notas, el árbol tiene que estar limpio: es el único undo confiable.

package/skills/vault-audit/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: vault-audit
+description: "Reporte de salud del vault de Obsidian via script Python: huerfanas, links roto, notas stale, tag sprawl, nombres duplicados y frontmatter fuera de contrato. Read-only, no escribe nada. Triggers: auditar el vault, salud del vault, notas huerfanas, links roto, vault audit, que tan sano esta mi vault."
+argument-hint: "[--vault <path>] [--stale-days N] [--seed-days N] [--exempt <dir>] [-n 0]"
+category: "pkm"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Vault Audit - Salud del vault
+
+Medís el estado real del vault y explicás qué significan los números. **Este skill es read-only:** no escribe ni una línea en el vault. Los arreglos necesitan approval del usuario y los aplica `/vault-tidy`.
+
+Flags: `$ARGUMENTS`
+
+## Fase 1 - Correr el script
+
+El conteo lo hace Python, no vos: leer nota por nota para contar links cuesta cientos de miles de tokens en un vault real y da números peores.
+
+```bash
+python .claude/skills/vault-audit/scripts/vault_audit.py "<vault>" --format json
+```
+
+Flags útiles: `--stale-days N` (default 180), `--hollow-words N` (default 30), `--task-days N` (default 7), `--seed-days N` (default 30), `--require <campo>` (repetible, default `created` y `type`), `--exempt <carpeta>` (repetible, default `Templates` y `04_Archive`), `-n 0` para no truncar listas, `--audit-all` para auditar también las carpetas exentas.
+
+El script solo lee el filesystem: sin dependencias, corre sobre miles de notas en segundos.
+
+**Los defaults no son la verdad del vault: el `CLAUDE.md` lo es.** Antes de correr, leer su contrato y traducirlo a flags: los campos de frontmatter a `--require`, y los roles `templates` y `archive` a `--exempt`. Auditar un vault adoptado con los defaults produce hallazgos falsos (sus plantillas aparecen como huérfanas huecas) y esconde los reales.
+
+## Fase 2 - Interpretar
+
+Un hallazgo no es un problema hasta que sabés por qué está ahí. Las lecturas que importan:
+
+| Hallazgo | Qué suele significar | Cuándo NO es un problema |
+|---|---|---|
+| `orphans` | Notas que nadie linkea y que no linkean nada: el síntoma del vault-cementerio | Casi nunca. Es el hallazgo que más vale atacar. |
+| `no_backlinks` | Nada apunta a la nota, aunque ella sí apunta a otras | Notas de entrada (dashboards, hubs de primer nivel) |
+| `broken_links` | Link a una nota que no existe. Los `aliases` del frontmatter ya se resuelven, igual que en Obsidian, así que un `[[Nacho]]` que apunta al hub "Ignacio Martinez" no aparece acá | **Un link roto es muchas veces una intención, no un error:** es la nota que el usuario todavía no escribió. Distinguí typo de intención antes de proponer nada. |
+| `ambiguous_names` | Dos archivos con el mismo nombre en carpetas distintas | Nunca: hace que todo `[[link corto]]` a ese nombre resuelva de forma impredecible. Es el hallazgo más urgente aunque parezca menor. |
+| `stale` | Sin tocar en 180 días o más. Las `evergreen` **no** aparecen acá: ya dijeron lo que tenían que decir | Referencia que ya hizo su trabajo pero que nadie marcó `evergreen` todavía |
+| `stale_seeds` | Notas en `seed` hace más de 30 días | Casi nunca. Es la falla clásica del vault: las semillas nunca maduran. Es más grave que una huérfana porque no se ve. |
+| `contested` | Notas marcadas como contradictorias y sin resolver | Nunca es un error del vault: es el vault haciendo su trabajo. Va al `/review-monthly`, no a `/vault-tidy`. |
+| `hollow` | Menos de 30 palabras | Semilla reciente. Dejala crecer. |
+| `single_use_tags` | Tags usados una sola vez | Inocuo salvo que sean cientos: ahí hay confusión de vocabulario, no organización. |
+| `stale_open_tasks` | Tareas abiertas en un día que ya cerró | Es la regla de arrastre incumplida: había que cancelarlas en su día. |
+| `missing_frontmatter` | Campos del contrato ausentes | Notas viejas anteriores al contrato |
+| `orphan_attachments` | Imágenes y PDFs que nadie embebe | Ocupan espacio, no rompen nada |
+
+El campo `status` del contrato (`seed | provisional | evergreen | contested | archived`) es lo que hace accionables a `stale` y `hollow`: sin él, una nota de referencia que ya cumplió y un stub abandonado se reportan igual. `counts.by_status` te dice cuánto del vault está declarado y cuánto no.
+
+Dos métricas de tendencia valen más que cualquier lista: **`avg_links_per_note`** (si es baja, el vault es un archivo de documentos, no una red de ideas) y **`orphan_rate`**. Compará contra el monthly anterior si existe.
+
+## Fase 3 - Reportar
+
+1. Los conteos primero, en una tabla corta. Sin adornos.
+2. Los 3 a 5 hallazgos que valen la pena, ordenados por impacto real: `ambiguous_names` y `orphans` arriba, `hollow` y `single_use_tags` abajo o directamente omitidos si son ruido.
+3. **Si el reporte trae `truncated`, decirlo con el total real.** Un reporte truncado que no se anuncia se lee como un vault sano, y esa es la única mentira que este skill no puede cometer.
+4. Cerrar con una recomendación concreta: qué arreglaría primero y por qué.
+
+Audit COMPLETE cuando el usuario sabe los números, cuáles importan y cuál es el primer arreglo.
+
+## Reglas
+
+- No escribir en el vault. Ni una nota, ni un frontmatter, ni un link. Para eso está `/vault-tidy`.
+- No dramatizar los números: un vault de 2000 notas con 40 huérfanas está sano.
+- No proponer plugins como solución a un problema de higiene: menos plugins es más sano.
+- No sugerir borrar nada. El vocabulario es archivar.
+- Sin guiones largos en el reporte.
+
+## Handoff
+
+Con el reporte listo, el siguiente paso es `/vault-tidy` para aplicar los arreglos elegidos con approval item por item. Si el audit muestra muchas huérfanas del mismo tema, el arreglo real es `/hub-note` para el hub que falta. `/review-monthly` corre este audit como parte del cierre del mes.