commit 3231b657190146e60939138311828a3f563a9ebd Author: rikrdo Date: Sat Apr 11 17:34:57 2026 +0200 Add reusable context template diff --git a/CULTURA-AGENTE.template.md b/CULTURA-AGENTE.template.md new file mode 100644 index 0000000..15e88f2 --- /dev/null +++ b/CULTURA-AGENTE.template.md @@ -0,0 +1,39 @@ +# Cultura del Agente IA + +## Manifiesto +- Idioma por defecto: **{{LANGUAGE}}**. +- Tono: **{{TONE}}**; evita rodeos, ofrece acciones concretas. +- Autonomía: ejecuta los pasos razonables sin pedir permiso, consulta solo cuando la instrucción sea ambigua o requiera credenciales nuevas. +- No repitas preguntas: consulta `memory.md` y `context/` antes de interactuar con el usuario. + +## Checklist de arranque +1. Lee `agents.md` → `memory.md` → la ficha relevante dentro de `context/` (mínimo `context/README.md`). +2. Revisa `todowrite` y actualiza tareas si el usuario agregó nuevas instrucciones. +3. Identifica si la acción toca infraestructura crítica (bastiones, Traefik, Kubernetes) y planea la cadena bastión → nodo → servicio. + +## Regla de preguntas +- Formula **una sola** pregunta a la vez, incluye el plan propuesto y la opción recomendada. +- Si puedes asumir un default razonable sin riesgo, procede e informa en el resumen. + +## Flujo de trabajo esperado +- Documenta cambios con referencias de archivo (`ruta/archivo.ext:línea`). +- Usa `todowrite` para gestionar tareas multistep; marca estados en cuanto cambien. +- Ofrece resúmenes breves y próximos pasos solo cuando agreguen valor. + +## Gestión del contexto modular +- Cada vez que aparezca un dominio nuevo, crea una ficha `context/.md`, enlázala en `context/README.md` y menciona el cambio en `memory.md`. +- Antes de preguntar por datos ya documentados, busca en `context/` y `memory.md`. + +## Seguridad y operaciones +- Evita comandos destructivos (formateos, reinicios masivos, cambios de firewall) sin aprobación explícita. +- Valida siempre que estás en el host correcto (`hostname`, `pwd`) antes de ejecutar acciones sensibles. +- Usa el bastión `{{BASTION_NAME}}` (`{{BASTION_HOST}}`, usuario `{{BASTION_USER}}`, clave `{{BASTION_KEY}}`) como salto hacia la red interna y respeta las rutas de ProxyJump configuradas. + +## Herramientas obligatorias +- `todowrite` para seguimiento. +- `opencode session list` para recuperar contexto histórico antes de iniciar temas repetidos. +- Herramientas específicas del stack (p.ej., `./n8n-agent` cuando trabajes con workflows n8n). + +## Mantenimiento de la cultura +- Si la organización adopta nuevas normas, actualiza este archivo y referencia los cambios en `agents.md`. +- Evita modificar el tono/idioma a menos que el usuario lo indique explícitamente. diff --git a/README.md b/README.md new file mode 100644 index 0000000..6db9ab4 --- /dev/null +++ b/README.md @@ -0,0 +1,26 @@ +# Context Template + +Plantilla reutilizable para replicar el sistema de memoria modular usado en esta instancia de OpenCode. Copia estos archivos a cualquier workspace y ajústalos con tus datos para garantizar que los agentes mantengan la misma cultura de trabajo. + +## Contenido +- `CULTURA-AGENTE.md`: manifiesto de comportamiento (idioma, tono, flujo, reglas de seguridad). +- `agents.template.md`: guía operativa para agentes (referencia a cultura y contexto modular). +- `memory.template.md`: memoria persistente con placeholders para datos locales. +- `context/`: fichas modulares (infraestructura, redes, herramientas) listas para personalizar. +- `config.example.json`: variables sugeridas para reemplazar placeholders. +- `scripts/render.sh`: script opcional que genera archivos finales sustituyendo variables. + +## Uso rápido +1. Clona este repositorio (`git clone git@gitea.rikrdo.com:rikrdo/context-template.git`). +2. Copia `config.example.json` → `config.json` y rellena los campos. +3. Ejecuta `./scripts/render.sh config.json /ruta/del/workspace` para generar `agents.md`, `memory.md` y `context/` con tu información. +4. Revisa cada ficha, completa datos que no cubra el script (por ejemplo, routers Traefik) y enlaza los archivos en tu repositorio. + +## Filosofía +- Mantener una única “cultura” de agente: profesional, proactiva, sin repetir preguntas. +- Documentar cada dominio en fichas específicas para minimizar el contexto necesario. +- Escalar fácilmente añadiendo nuevas fichas y actualizando el índice sin reescribir toda la memoria. + +## Próximos pasos +- Completar `config.yml` con los datos de la nueva instancia. +- Integrar esta plantilla en tus repos (p.ej. importarla a Gitea) y automatizar su despliegue en nuevos proyectos. diff --git a/agents.template.md b/agents.template.md new file mode 100644 index 0000000..f606413 --- /dev/null +++ b/agents.template.md @@ -0,0 +1,34 @@ +# Guía para agentes de OpenCode + +## Principios +- Idioma: {{LANGUAGE}}. +- Tono: {{TONE}}. +- Sigue la cultura descrita en `CULTURA-AGENTE.md` y úsala como contrato de trabajo. + +## Flujo base +1. Lee `memory.md` y `context/README.md` al iniciar la sesión. +2. Identifica la ficha relevante (hosts, Traefik, n8n, etc.) y úsala como fuente primaria para no repetir preguntas. +3. Documenta acciones y resultados con referencias de archivo. +4. Usa `todowrite` para declarar tareas multi-paso y mantener transparencia. + +## Infraestructura y seguridad +- El bastión principal es `{{BASTION_NAME}}` (`{{BASTION_HOST}}`). Usa `ProxyJump` y la clave `{{BASTION_KEY}}` para llegar a la red interna `{{PRIMARY_NETWORK}}`. +- Antes de diagnosticar servicios, explica la cadena bastión → nodo → servicio. +- Evita acciones destructivas sin visto bueno explícito. + +## Contexto modular +- `context/README.md` es el índice. Cada ficha cubre un dominio (infraestructura, docker, scripts, n8n, etc.). +- Si detectas un dominio nuevo, crea una ficha siguiendo la convención y enlázala desde el índice y `memory.md`. + +## Memoria y hábitos +- `memory.md` almacena preferencias permanentes del usuario (idioma, tono, flujos preferidos, servicios críticos). Revísalo antes de hacer preguntas. +- Mantén este sistema agnóstico del modelo para que cualquier instancia de OpenCode pueda adoptar la misma cultura. + +## Herramientas clave +- `./scripts/render.sh` (en este template) permite generar estos archivos en nuevos workspaces usando `config.json`. +- `opencode session list` para revisar sesiones históricas y evitar repetir análisis. +- `./n8n-agent` cuando trabajes con workflows; respeta el protocolo de investigación (search → get → validate). + +## Entregables +- Ofrece resúmenes concretos, referencias a archivos y próximos pasos solo cuando aporten valor. +- Cuando termines tareas significativas, sugiere validaciones opcionales (tests, despliegues) si aplica. diff --git a/config.example.json b/config.example.json new file mode 100644 index 0000000..bac3c53 --- /dev/null +++ b/config.example.json @@ -0,0 +1,15 @@ +{ + "language": "español", + "tone": "profesional, directo", + "user_name": "rikrdo", + "workspace_root": "/home/rikrdo", + "bastion_name": "rikrdo-01", + "bastion_host": "49.13.26.80", + "bastion_user": "root", + "bastion_key": "~/.ssh/id_rsa_mi_book", + "primary_network": "192.168.18.0/24", + "vm_summary": "vm-docker (192.168.18.100) y hestia (192.168.18.248)", + "traefik_entrypoint": "/mnt/docker/traefik", + "n8n_knowledge_path": "~/n8n-knowledge", + "additional_contexts": "git, docker, scripts, opencode" +} diff --git a/context/README.template.md b/context/README.template.md new file mode 100644 index 0000000..f273a8e --- /dev/null +++ b/context/README.template.md @@ -0,0 +1,24 @@ +# Contexto modular de OpenCode + +Este directorio organiza el conocimiento por dominio para evitar leer `memory.md` completo cuando la tarea afecta solo a un área específica. + +## Estructura inicial +- [Infraestructura y hosts](hosts.md) +- [Traefik y frontales](traefik.md) +- [Cron y health-checks](cron.md) +- [Programa de formación n8n](n8n.md) +- [Repos locales](git.md) +- [Entornos Docker](docker.md) +- [Scripts y plantillas](scripts.md) +- [Sesiones de OpenCode](opencode.md) +- [Otros contextos](otros.md) · Ajusta esta ficha para cubrir {{ADDITIONAL_CONTEXTS}} u otros dominios. + +## Convenciones +- Mantén cada ficha agnóstica del modelo; solo hechos verificables (IPs, puertos, rutas, comandos). +- Cuando aparezca un dominio nuevo, crea `context/.md`, enlázalo aquí y cita la actualización en `memory.md`. +- Usa enlaces relativos para navegar sin depender del editor. + +## Flujo recomendado +1. Lee `agents.md` → `memory.md` → la ficha específica antes de actuar. +2. Actualiza fichas y memoria cuando haya cambios persistentes (nueva VM, router, cronjob, etc.). +3. Si una ficha crece demasiado, divídela en archivos temáticos y enlázalos desde aquí. diff --git a/context/cron.template.md b/context/cron.template.md new file mode 100644 index 0000000..fe36edb --- /dev/null +++ b/context/cron.template.md @@ -0,0 +1,18 @@ +# Cronjobs y health-checks + +## Monitorización +- Documenta aquí herramientas como Uptime Kuma, Pulse, Prometheus, etc. +- Indica dónde residen (host, contenedor) y qué servicios vigilan. + +## Cron por host +| Host | Root crontab | `/etc/cron.d` | Notas | +| --- | --- | --- | --- | +| {{BASTION_NAME}} | (ej. sin crontab personalizado) | `e2scrub_all`, ... | Ajustar según entorno | +| ... | ... | ... | ... | + +## Scripts programados +- Lista scripts propios (`network_inventory.sh`, backups, etc.), ubicación y periodicidad. + +## Auditoría +- Comando sugerido: `ssh host "crontab -l"` y `cat /etc/cron.d/*`. +- Documenta nuevos hallazgos aquí y enlaza scripts relevantes en `context/scripts.md`. diff --git a/context/docker.template.md b/context/docker.template.md new file mode 100644 index 0000000..82f8acf --- /dev/null +++ b/context/docker.template.md @@ -0,0 +1,19 @@ +# Entornos Docker (`{{WORKSPACE_ROOT}}/docker`) + +## Estructura +- `projects/`: cada carpeta contiene un stack con su `docker-compose.yml`. +- `vscode/`: entorno remoto de VSCode (si aplica). + +## Tabla de proyectos +| Carpeta | Descripción | +| --- | --- | +| ejemplo | Plantilla multi-servicio | +| ... | ... | + +Completa esta lista con tus stacks reales (odoo, devshell, etc.). + +## Procedimiento común +1. `cd` al proyecto. +2. Revisa `.env` + `docker-compose.yml`. +3. `docker compose up -d` y documenta cambios relevantes aquí. +4. Si el stack requiere Traefik/domínios, enlázalo en `context/traefik.md`. diff --git a/context/git.template.md b/context/git.template.md new file mode 100644 index 0000000..93fe8f0 --- /dev/null +++ b/context/git.template.md @@ -0,0 +1,16 @@ +# Repositorios locales (`{{WORKSPACE_ROOT}}/git`) + +## Guía +- Cada proyecto debe incluir su `README.md`/`AGENTS.md` con instrucciones específicas. +- Antes de trabajar, ejecuta `git status` y respeta las ramas definidas por el proyecto. + +## Inventario +- Lista aquí tus repos clave (infraestructura, aplicaciones, plantillas) con una breve descripción. +- Ejemplo: + - `ai-template` · plantilla para agentes IA. + - `wireguard-install.sh` · script para instalar WireGuard. + +## Buenas prácticas +1. No mezclar archivos de distintos proyectos. +2. Documentar nuevos repos agregando su descripción aquí. +3. Si un repo define reglas globales, anótalas también en `memory.md`. diff --git a/context/hosts.template.md b/context/hosts.template.md new file mode 100644 index 0000000..d999e73 --- /dev/null +++ b/context/hosts.template.md @@ -0,0 +1,20 @@ +# Infraestructura y hosts + +## Cadena de acceso +- Bastión obligatorio: `{{BASTION_NAME}}` (`{{BASTION_HOST}}`, usuario `{{BASTION_USER}}`, clave `{{BASTION_KEY}}`). +- Usa `ProxyJump` para alcanzar la red interna `{{PRIMARY_NETWORK}}`. +- Scripts recomendados: revisa `context/scripts.md` para túneles (`home_lan_tunnel.sh`, etc.). + +## VPS / servicios públicos +| Alias | IP/Host | Rol | Notas | +| --- | --- | --- | --- | +| bastion | {{BASTION_HOST}} | Proxy principal | Alojado en {{BASTION_NAME}}. | +| ... | ... | ... | Añade según tu entorno | + +## Red interna +- Documenta aquí tus clusters (Kubernetes, Proxmox, Raspberry, etc.) con usuarios y puertos. +- Ejemplo: `vm-docker` ({{VM_SUMMARY}}) para stacks Docker. + +## Cómo extender +- Añade filas/tablas por cada host importante. +- Si un host expone servicios vía Traefik, enlázalo con `context/traefik.md`. diff --git a/context/n8n.template.md b/context/n8n.template.md new file mode 100644 index 0000000..4b7208b --- /dev/null +++ b/context/n8n.template.md @@ -0,0 +1,17 @@ +# Contexto n8n + +## Ruta de referencia +- Base de conocimiento: `{{N8N_KNOWLEDGE_PATH}}`. +- Estructura recomendada: `modules/`, `labs/`, `presentations/`, `resources.md`. + +## Niveles sugeridos +1. Fundamentos +2. Integraciones y datos +3. Automatización avanzada +4. Operaciones / DevOps + +Adapta los nombres y rutas según tu programa interno. + +## Uso +- Antes de crear materiales, revisa esta carpeta para evitar duplicar contenido. +- Agrega nuevas rutas (por ejemplo, módulos específicos de IA) y referencia aquí. diff --git a/context/opencode.template.md b/context/opencode.template.md new file mode 100644 index 0000000..1c20f12 --- /dev/null +++ b/context/opencode.template.md @@ -0,0 +1,14 @@ +# Sesiones y configuración de OpenCode + +## Binarios y rutas +- CLI: `~/.opencode/bin/opencode`. +- Config/cache: `~/.opencode/`, `~/.config/opencode/`, `~/.cache/opencode/`. + +## Historial de sesiones +- Comando: `/home//.opencode/bin/opencode session list`. +- Usa este listado para recuperar contexto histórico antes de iniciar tareas repetidas. +- Exporta sesiones relevantes con `opencode export ` y archívalas si aportan aprendizaje. + +## Buenas prácticas +- Consulta sesiones anteriores antes de abrir un tema ya tratado. +- Documenta aquí los IDs/títulos más útiles como referencia rápida. diff --git a/context/otros.template.md b/context/otros.template.md new file mode 100644 index 0000000..010ae03 --- /dev/null +++ b/context/otros.template.md @@ -0,0 +1,7 @@ +# Otros contextos + +Usa esta ficha para dominios adicionales (por ejemplo, `k8s`, `inventory`, `security`). + +- Título sugerido: `context/.md`. +- Describe ubicación, comandos recurrentes y procedimientos. +- Enlaza cualquier nuevo archivo desde `context/README.md` y resume el cambio en `memory.md`. diff --git a/context/scripts.template.md b/context/scripts.template.md new file mode 100644 index 0000000..8f65167 --- /dev/null +++ b/context/scripts.template.md @@ -0,0 +1,16 @@ +# Scripts y plantillas (`{{WORKSPACE_ROOT}}/scripts`) + +## Contenido típico +- Plantillas de proyectos (`agents-template`, `natural`, etc.). +- Utilidades de red (`home_lan_tunnel.sh`, `network_inventory.sh`). +- Backups (`*.sql`, herramientas específicas). + +## Documentación +- Describe cada script relevante: propósito, dependencias, comandos de ejecución. +- Ejemplo: + - `home_lan_tunnel.sh`: crea túneles SSH hacia la LAN. + - `network_inventory.sh`: genera reportes en `~/inventory/`. + +## Buenas prácticas +- Leer cada `README.md` antes de ejecutar scripts. +- Actualizar esta ficha cuando agregues nuevos generadores/plantillas. diff --git a/context/traefik.template.md b/context/traefik.template.md new file mode 100644 index 0000000..38798f7 --- /dev/null +++ b/context/traefik.template.md @@ -0,0 +1,26 @@ +# Traefik y frontales + +## Despliegue +- Ubicación: `{{TRAEFIK_ENTRYPOINT}}` en `{{BASTION_NAME}}`. +- EntryPoints estándar: `web` (80) redirige a `websecure` (443) con certificados de Let's Encrypt. +- Configuración dinámica: `dynamic/routers.yml`, `dynamic/services.yml`, `dynamic/middlewares.yml`. + +## Middlewares comunes +- `redirect-www-to-root` +- `authelia-forwardauth` +- `public-chain` +- `security-headers` +- Ajusta esta lista según tus necesidades y documenta cualquier middleware nuevo. + +## Routers +Describe aquí tus dominios clave, por ejemplo: + +| Router | Host | Backend | Middlewares | +| --- | --- | --- | --- | +| ejemplo | `app.example.com` | `http://192.168.0.10:8080` | `redirect-www-to-root`, `authelia-forwardauth` | + +## Procedimiento de cambios +1. Edita los YAML en `dynamic/`. +2. Valida sintaxis (`yamllint` o `docker compose config`). +3. Reinicia/recarga Traefik (`docker compose up -d traefik`). +4. Actualiza esta ficha con el nuevo router/servicio y enlaza al host correspondiente. diff --git a/memory.template.md b/memory.template.md new file mode 100644 index 0000000..b117a72 --- /dev/null +++ b/memory.template.md @@ -0,0 +1,33 @@ +# Memoria Persistente + +## Preferencias de interacción +- Idioma: {{LANGUAGE}}. +- Tono: {{TONE}}. +- El usuario espera agentes autónomos que solo hagan preguntas cuando falte información crítica. +- Antes de responder, revisa este archivo, `agents.md` y las fichas relevantes de `context/` para evitar repeticiones. + +## Hábitos y procesos +- Describe siempre la cadena bastión → nodo → servicio cuando trabajes con infraestructura. +- Usa `todowrite` para tareas extensas y marca estados inmediatamente. +- Resume entregables con referencias de archivo (`ruta/archivo:línea`). + +## Infraestructura conocida +- Bastión principal: `{{BASTION_NAME}}` (`{{BASTION_HOST}}`, usuario `{{BASTION_USER}}`, clave `{{BASTION_KEY}}`). +- Red interna: `{{PRIMARY_NETWORK}}`. +- VMs principales: {{VM_SUMMARY}}. +- Ajusta/añade nodos en `context/hosts.md` según evolucione el entorno. + +## Monitorización, proxy y túneles +- Traefik vive en `{{TRAEFIK_ENTRYPOINT}}`; routers y middlewares se documentan en `context/traefik.md`. +- Usa túneles SSH/`autossh` según los scripts documentados en `context/scripts.md`. +- Servicios críticos (Authelia, Uptime Kuma, Pulse, etc.) se describen en sus fichas. + +## Contexto modular +- `context/README.md` actúa como índice. Mantén fichas para hosts, Traefik, cron, n8n, git, docker, scripts, opencode y {{ADDITIONAL_CONTEXTS}}. +- Cuando surja un dominio nuevo, crea una ficha `context/.md`, enlázala en el índice y resume el cambio aquí. +- Programa de formación n8n (si aplica) se encuentra en `{{N8N_KNOWLEDGE_PATH}}` y se resume en `context/n8n.md`. + +## Recordatorios operativos +- No ejecutes comandos destructivos sin confirmación explícita. +- Verifica conectividad hacia el bastión antes de culpar a la red interna. +- Documenta cualquier cambio estable (nuevos hosts, rutas, cronjobs) en la ficha correspondiente y en esta memoria. diff --git a/scripts/render.sh b/scripts/render.sh new file mode 100755 index 0000000..001b31e --- /dev/null +++ b/scripts/render.sh @@ -0,0 +1,81 @@ +#!/usr/bin/env bash +set -euo pipefail + +if [[ $# -ne 2 ]]; then + echo "Uso: $0 config.json /ruta/destino" >&2 + exit 1 +fi + +CONFIG_PATH="$1" +DEST_PATH="$2" +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +TEMPLATE_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" + +if [[ ! -f "$CONFIG_PATH" ]]; then + echo "Config no encontrada: $CONFIG_PATH" >&2 + exit 1 +fi + +python3 - "$CONFIG_PATH" "$DEST_PATH" "$TEMPLATE_ROOT" <<'PY' +import json, sys, pathlib, shutil + +config_path = pathlib.Path(sys.argv[1]).expanduser().resolve() +dest_root = pathlib.Path(sys.argv[2]).expanduser().resolve() +template_root = pathlib.Path(sys.argv[3]).resolve() + +with open(config_path) as f: + config = json.load(f) + +def flatten(prefix, value, store): + if isinstance(value, dict): + for k, v in value.items(): + flatten(f"{prefix}{k.upper()}_", v, store) + elif isinstance(value, list): + store[prefix[:-1]] = ", ".join(str(v) for v in value) + else: + store[prefix[:-1]] = str(value) + +replacements = {} +for key, val in config.items(): + if isinstance(val, (dict, list)): + flatten(f"{key.upper()}_", val, replacements) + else: + replacements[key.upper()] = str(val) + +def render_text(text: str) -> str: + for key, value in replacements.items(): + text = text.replace(f"{{{{{key}}}}}", value) + return text + +template_paths = [ + "CULTURA-AGENTE.template.md", + "agents.template.md", + "memory.template.md", + "context/README.template.md", + "context/hosts.template.md", + "context/traefik.template.md", + "context/cron.template.md", + "context/n8n.template.md", + "context/git.template.md", + "context/docker.template.md", + "context/scripts.template.md", + "context/opencode.template.md", + "context/otros.template.md", +] + +for rel in template_paths: + template = template_root / rel + if not template.exists(): + print(f"Aviso: {rel} no existe, omitiendo", file=sys.stderr) + continue + relative = template.relative_to(template_root) + target_name = relative.name.replace(".template", "") + target_rel = relative.parent / target_name + target_path = dest_root / target_rel + target_path.parent.mkdir(parents=True, exist_ok=True) + content = template.read_text() + rendered = render_text(content) + target_path.write_text(rendered) + print(f"Renderizado {target_rel}") + +PY