chore: auto-commit (799 archivos)
- .claude/CLAUDE.md - .claude/commands/subagentes.md - .claude/rules/INDEX.md - .mcp.json - bash/functions/cybersecurity/analyze_dns.md - bash/functions/cybersecurity/audit_http_headers.md - bash/functions/cybersecurity/audit_ssh_config.md - bash/functions/cybersecurity/check_firewall.md - bash/functions/cybersecurity/detect_suspicious_users.md - bash/functions/cybersecurity/encrypt_file.md - ... Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
+110
-35
@@ -18,6 +18,33 @@ Registry personal de codigo reutilizable con busqueda FTS. Diseñado para compos
|
||||
|
||||
---
|
||||
|
||||
## Delegacion + Capability Groups (REGLA DURA — issue 0086)
|
||||
|
||||
Claude **multiplica capacidades** delegando creacion de funciones a `fn-constructor` y reusandolas inmediatamente. NO escribir logica reutilizable inline.
|
||||
|
||||
### Flujo obligatorio (mismo turno)
|
||||
|
||||
1. **Detectar gap**. Si vas a escribir >=5 lineas de logica reutilizable inline -> STOP.
|
||||
2. **Spawn `fn-constructor`** via `Agent(subagent_type="fn-constructor", ...)`. Sin preguntar al usuario.
|
||||
3. **Paralelo**: si hay >1 funcion independiente -> **una sola llamada al Agent tool con N tool_use blocks paralelos** en mismo mensaje. NO serializar.
|
||||
4. **Tag de grupo obligatorio** (`notebook`, `metabase`, `deploy`, etc.). Ver `docs/capabilities/INDEX.md`.
|
||||
5. **`fn index`** + **importar + invocar en mismo turno**. No dejar funcion huerfana recien creada.
|
||||
6. **Auto-verificar**: `fn doctor uses-functions` + `fn doctor unused` si tocas >=3 funciones nuevas.
|
||||
|
||||
### Capability groups
|
||||
|
||||
Cluster de >=3 funciones que comparten dominio operativo. Cada grupo tiene tag plano + pagina madre `docs/capabilities/<grupo>.md` con: lista de funciones, ejemplo canonico end-to-end, fronteras.
|
||||
|
||||
**Antes de buscar funciones sueltas en una tarea de dominio conocido:** lee `docs/capabilities/<grupo>.md` para cargar el cluster entero en un solo read. Filtro MCP: `mcp__registry__fn_search query="" tag="<grupo>"`.
|
||||
|
||||
Reglas completas: `.claude/rules/delegation.md` + `.claude/rules/capability_groups.md`.
|
||||
|
||||
### Telemetria CAPABILITY-GROWTH
|
||||
|
||||
Cada turno el hook `UserPromptSubmit` inyecta `CAPABILITY-GROWTH: created_this_session=X used=Y orphan=Z`. Si `orphan>0` -> integra la funcion antes de cerrar turno o documenta por que.
|
||||
|
||||
---
|
||||
|
||||
## Explorar el registry (OBLIGATORIO)
|
||||
|
||||
**SIEMPRE** consulta registry.db antes de escribir codigo, crear funciones, o responder sobre el registry. No uses grep/glob sobre archivos .go/.md — la BD es la fuente de verdad.
|
||||
@@ -39,56 +66,67 @@ Registry personal de codigo reutilizable con busqueda FTS. Diseñado para compos
|
||||
|
||||
Razones: menos tokens, output estructurado, FTS5 escapado bien (sin gotchas de `column:"valor"`), permisos pre-aprobados, no requiere `cd` ni paths absolutos a `registry.db`.
|
||||
|
||||
**Cuando si caer a `sqlite3` (Bash):** SOLO si el MCP no cubre el caso — JOINs custom entre tablas, agregaciones (`COUNT`/`GROUP BY`), introspeccion de schema (`.schema`, `PRAGMA table_info`), o columnas que el MCP no expone. En ese caso, los patrones FTS5 estan documentados abajo.
|
||||
**La BD contiene el codigo y la documentacion completa** de cada funcion y tipo en los campos `code`, `documentation` y `notes`. Tambien indexados en FTS5 — buscas dentro del codigo directamente. Para leer codigo: `mcp__registry__fn_code <id>`.
|
||||
|
||||
**La BD contiene el codigo y la documentacion completa** de cada funcion y tipo en los campos `code`, `documentation` y `notes`. Estos campos tambien estan indexados en FTS5, asi que puedes buscar dentro del codigo y la documentacion directamente. Para leer el codigo de una funcion: `mcp__registry__fn_code` (preferido) o `SELECT code FROM functions WHERE id = '...'` (fallback).
|
||||
### Ejemplos MCP (usa estos, NO sqlite3)
|
||||
|
||||
**Busquedas FTS5 (cuando uses sqlite3 como fallback):** Usa SIEMPRE la tabla FTS5 para buscar tanto por `name` como por `description`. Esto encuentra coincidencias parciales y similares que una busqueda exacta perderia. Usa operadores FTS5: `OR` para ampliar, `*` para prefijos, `NEAR` para proximidad.
|
||||
Cada llamada MCP se registra en `call_monitor` (issue 0085). Cada `sqlite3 registry.db "SELECT ..."` queda fuera del bucle reactivo y dispara el hook PreToolUse.
|
||||
|
||||
```bash
|
||||
# Busqueda FTS5 por nombre Y descripcion (USAR SIEMPRE ESTE PATRON)
|
||||
sqlite3 registry.db "SELECT id, kind, purity, description FROM functions WHERE id IN (SELECT id FROM functions_fts WHERE functions_fts MATCH 'name:slice OR description:slice') ORDER BY name;"
|
||||
```
|
||||
# Busqueda basica por nombre/descripcion (FTS5 detras)
|
||||
mcp__registry__fn_search query="slice"
|
||||
|
||||
# FTS5 con prefijo (encuentra slice, slicing, sliced...)
|
||||
sqlite3 registry.db "SELECT id, kind, purity, description FROM functions WHERE id IN (SELECT id FROM functions_fts WHERE functions_fts MATCH 'name:slic* OR description:slic*') ORDER BY name;"
|
||||
# Filtros: kind, purity, domain, lang
|
||||
mcp__registry__fn_search query="filter" kind="function" purity="pure" domain="core"
|
||||
|
||||
# FTS5 en tipos
|
||||
sqlite3 registry.db "SELECT id, algebraic, description FROM types WHERE id IN (SELECT id FROM types_fts WHERE types_fts MATCH 'name:result OR description:result') ORDER BY name;"
|
||||
# Prefijo FTS5 — encuentra slice/slicing/sliced
|
||||
mcp__registry__fn_search query="slic*"
|
||||
|
||||
# FTS5 por semantica de params (composabilidad)
|
||||
sqlite3 registry.db "SELECT id, json_extract(params_schema, '$.output') FROM functions WHERE id IN (SELECT id FROM functions_fts WHERE functions_fts MATCH 'params_schema:retornos');"
|
||||
# Buscar tipos
|
||||
mcp__registry__fn_search query="result" entity="types"
|
||||
|
||||
# Por dominio
|
||||
sqlite3 registry.db "SELECT id, purity, signature FROM functions WHERE domain = 'finance' ORDER BY name;"
|
||||
# Apps
|
||||
mcp__registry__fn_search query="kanban" entity="apps"
|
||||
|
||||
# Puras de un dominio
|
||||
sqlite3 registry.db "SELECT id, signature FROM functions WHERE domain = 'core' AND purity = 'pure' ORDER BY name;"
|
||||
# Listar dominios
|
||||
mcp__registry__fn_list_domains
|
||||
|
||||
# Tipos por dominio
|
||||
sqlite3 registry.db "SELECT id, algebraic, description FROM types WHERE domain = 'cybersecurity';"
|
||||
# Ver una entrada concreta (functions, types, apps, analysis, proposals...)
|
||||
mcp__registry__fn_show id="filter_slice_go_core"
|
||||
|
||||
# Dependencias
|
||||
sqlite3 registry.db "SELECT id, uses_functions, uses_types FROM functions WHERE uses_functions != '[]';"
|
||||
# Codigo fuente de una funcion/tipo
|
||||
mcp__registry__fn_code id="filter_slice_go_core"
|
||||
|
||||
# Proposals pendientes
|
||||
sqlite3 registry.db "SELECT id, kind, status, title FROM proposals WHERE status = 'pending';"
|
||||
# Quien consume una funcion (consumidores indexados via uses_functions)
|
||||
mcp__registry__fn_uses id="filter_slice_go_core"
|
||||
|
||||
# Schema completo
|
||||
sqlite3 registry.db ".schema"
|
||||
# Proposals (pending, approved, ...)
|
||||
mcp__registry__fn_proposal action="list" status="pending"
|
||||
mcp__registry__fn_proposal action="show" id="<proposal_id>"
|
||||
|
||||
# Diagnostico read-only del registry (artefacts/services/sync/uses-functions/unused/cpp-apps)
|
||||
mcp__registry__fn_doctor subcommand="artefacts"
|
||||
mcp__registry__fn_doctor subcommand="sync"
|
||||
```
|
||||
|
||||
**Regla:** Si necesitas saber si algo existe o hay algo similar, usa `mcp__registry__fn_search` (preferido) o consulta FTS5 con sqlite3 (fallback). No asumas que no existe sin consultar primero.
|
||||
**Escapado FTS5 (gotcha cuando pasas query libre):** valores con `-`, `.`, `:`, espacios rompen el parser FTS5 si los expones como `column:valor`. El MCP escapa por defecto, pero si construyes una `query` con sintaxis FTS5 explicita, encierra el valor en comillas dobles:
|
||||
|
||||
**Escapado FTS5 (gotcha):** despues de `column:` el valor debe ser un solo token alfanumerico ASCII (underscores OK). Cualquier otro caracter (`-`, `.`, `:`, espacios) rompe el parser con `no such column: X` o `syntax error near "."`. Encierra el valor en comillas dobles dentro del MATCH:
|
||||
|
||||
```bash
|
||||
# MAL: description:single-page → "no such column: page"
|
||||
# MAL: description:embed.FS → 'syntax error near "."'
|
||||
# BIEN:
|
||||
sqlite3 registry.db "SELECT id FROM functions WHERE id IN (SELECT id FROM functions_fts WHERE functions_fts MATCH 'description:\"single-page\" OR description:\"embed.FS\"');"
|
||||
```
|
||||
# MAL: query="description:single-page" -> "no such column: page"
|
||||
# BIEN
|
||||
mcp__registry__fn_search query='description:"single-page" OR description:"embed.FS"'
|
||||
mcp__registry__fn_search query='description:"react router"'
|
||||
```
|
||||
|
||||
Tokens multi-palabra tambien necesitan comillas: `description:"react router"`.
|
||||
### Excepciones autorizadas para sqlite3 directo
|
||||
|
||||
`sqlite3 registry.db` SOLO es legitimo si el MCP no expone la consulta:
|
||||
|
||||
- Introspeccion de schema: `.schema`, `.tables`, `PRAGMA table_info(...)`, `PRAGMA index_list(...)`.
|
||||
- Agregaciones: `COUNT(*)`, `GROUP BY`, `SUM(...)`, `AVG(...)`.
|
||||
- JOINs custom entre tablas (ej. `functions JOIN unit_tests ON ...`) no expuestos por el MCP.
|
||||
|
||||
Cualquier `SELECT ... FROM functions/types/apps/proposals WHERE ...` plano se hace via MCP. El hook PreToolUse avisa si ve `sqlite3 registry.db "SELECT ..."`.
|
||||
|
||||
### Schema rapido
|
||||
|
||||
@@ -109,7 +147,7 @@ Tokens multi-palabra tambien necesitan comillas: `description:"react router"`.
|
||||
- `entity_type`: app, analysis, project, vault
|
||||
- `status`: active, missing, archived
|
||||
- Se puebla con `fn sync`, NO con `fn index`
|
||||
- Consultas: `SELECT * FROM pc_locations WHERE pc_id = 'home-wsl'`
|
||||
- Consultas: `mcp__registry__fn_doctor subcommand="sync"` (drift PC vs disco) o `sqlite3 registry.db "SELECT ... GROUP BY pc_id"` SOLO para agregaciones que el MCP no expone
|
||||
|
||||
**FTS5 (columnas buscables):**
|
||||
- `functions_fts`: id, name, description, tags, signature, domain, example, notes, documentation, code, params_schema
|
||||
@@ -118,6 +156,43 @@ Tokens multi-palabra tambien necesitan comillas: `description:"react router"`.
|
||||
|
||||
---
|
||||
|
||||
## Como invocar funciones del registry (CANONICO)
|
||||
|
||||
Tres patrones, uno por caso de uso. Toda invocacion del agente se loguea en `projects/fn_monitoring/apps/call_monitor/operations.db` para alimentar el bucle reactivo (issue 0085).
|
||||
|
||||
| Caso de uso | Patron canonico | Cuando usar |
|
||||
|---|---|---|
|
||||
| **Inspeccionar** registro (buscar, leer codigo, ver dependencias, dominios) | `mcp__registry__fn_search` / `fn_show` / `fn_code` / `fn_uses` / `fn_list_domains` | SIEMPRE para descubrimiento. Reemplaza `sqlite3 registry.db "SELECT ..."` inline. |
|
||||
| **Ejecutar** UNA funcion o pipeline con sus args | `mcp__registry__fn_run <id> [args]` (preferido) o `./fn run <id> [args]` (fallback CLI) | Cuando hay UN id conocido a lanzar. Despacho automatico por lenguaje. Salida estructurada. |
|
||||
| **Componer** ad-hoc varias funciones con logica intermedia | Heredoc `python/.venv/bin/python3 - <<'PYEOF' ... PYEOF` IMPORTANDO funciones del registry | Solo cuando hay loops/conditionals/dispatch entre N funciones. Las funciones del registry **se importan**, no se reescriben. |
|
||||
|
||||
Regla decisiva: antes de cada bloque de codigo, decide caso. Si dudas entre 2 y 3, casi siempre es 2 (un MCP run con args). Si el caso 3 se repite con el mismo shape >5 veces entre sesiones, **es candidato a pipeline** en `python/functions/pipelines/`.
|
||||
|
||||
### Antipatrones prohibidos
|
||||
|
||||
| Patron | Por que es malo | Sustituir por |
|
||||
|---|---|---|
|
||||
| `sqlite3 registry.db "SELECT ..."` para buscar funciones/tipos | Salta MCP, FTS5 gotchas, sin trazabilidad. Hook PreToolUse ya avisa. | `mcp__registry__fn_search` |
|
||||
| `python -c "import metabase; print(dir(metabase))"` o `help(metabase)` para descubrir helpers | La fuente de verdad es el registry, no el `__init__.py` | `mcp__registry__fn_search "metabase"` + `mcp__registry__fn_show <id>` |
|
||||
| Heredoc que reescribe logica que ya existe como funcion del registry | Reinvento + perdida de capitalizacion | Buscar primero; si falta, delegar a `fn-constructor` (no escribir inline) |
|
||||
| `client._http.request(...)` directo cuando hay wrapper en el registry | Salta validacion del wrapper y telemetria | Usar wrapper; si la firma no cubre el caso, proponer extension via `fn proposal add` |
|
||||
| Scripts en `temp/` para composiciones que se repiten | Codigo se pierde y no se monitoriza | Pipeline en `python/functions/pipelines/` o pipeline Bash en `bash/functions/pipelines/` |
|
||||
| Imports `from <pkg> import *` en heredoc | Imposible saber que funcion del registry se uso | Imports explicitos `from <domain> import <name1>, <name2>` |
|
||||
|
||||
Excepciones autorizadas para `sqlite3` directo (no requieren MCP): `.schema`, `.tables`, `PRAGMA table_info`, `COUNT(*) GROUP BY`, JOINs custom entre tablas que el MCP no expone.
|
||||
|
||||
### Trazabilidad y bucle reactivo
|
||||
|
||||
Hook `PostToolUse` en `.claude/settings.local.json` parsea cada comando Bash + cada `mcp__registry__*` y escribe en la `operations.db` del call_monitor. Datos consumidos por:
|
||||
|
||||
1. **Tab "Claude usage" en `registry_dashboard`** — top funciones, latencias, error rate, huerfanas con `calls_90d=0`.
|
||||
2. **Fase MEJORAR del bucle reactivo** — patrones inline repetidos generan proposals `new_function` con evidencia (session_ids + snippets). Funciones con error_rate alto y muchas llamadas suben en prioridad de bugfix.
|
||||
3. **Auditoria de reglas** — assertions sobre `violation_count`, `mcp_ratio`, `heredoc_repetition`. Si fallan critical → proposal "actualizar CLAUDE.md / prompt del agente".
|
||||
|
||||
Datos sensibles: solo se guarda `args_hash`, NUNCA valores concretos de argumentos.
|
||||
|
||||
---
|
||||
|
||||
## Estructura
|
||||
|
||||
```
|
||||
@@ -237,7 +312,7 @@ Entornos usados automaticamente:
|
||||
|
||||
## Añadir funciones
|
||||
|
||||
1. Consulta la BD para verificar que no existe algo similar
|
||||
1. `mcp__registry__fn_search query="<nombre|desc>"` para verificar que no existe algo similar
|
||||
2. Crea dos archivos segun el lenguaje:
|
||||
- Go: `functions/{domain}/{name}.go` + `.md`
|
||||
- Python: `python/functions/{domain}/{name}.py` + `.md`
|
||||
|
||||
Reference in New Issue
Block a user