agents_and_robots/.claude/CLAUDE.md

# CLAUDE.md — agents_and_robots

Monorepo Go para bots Matrix autonomos. Modulo: `github.com/enmanuel/agents`.

**Homeserver:** `https://matrix-af2f3d.organic-machine.com` | **Server name:** `matrix-af2f3d.organic-machine.com`

## Los dos pilares — SIEMPRE APLICAR

### 1. Functional PRogramming: Pure core / Impure shell

```
pkg/        → PURO: tipos, funciones puras, cero side effects
shell/      → IMPURO: todo I/O (Matrix, LLM, SSH, filesystem)
devagents/  → runtime: Agent/Robot ensambla core + shell
agents/     → reglas puras por agente + config.yaml + prompts
tools/      → Def (puro) + Exec (impuro)
```

**Nunca** side effects en `pkg/`. El core produce `[]decision.Action` (datos puros), el shell los interpreta.

```
Matrix event → Parse (pure) → Evaluate rules (pure) → []Action (pure data)
            → Runner.Execute (impure) → efectos reales
```

### 2. TBD: Trunk-based development

**master** es el unico branch estable. Nunca trabajar directamente en master.

```
master ← siempre deployable
  ↑
  └── issue/<NNNN>-<slug>  ← rama efimera (horas)
        commits atomicos (feat:, fix:, test:, docs:, refactor:, chore:)
      merge --no-ff → master → push → delete branch
```

- `/git-branch` — crea rama desde master
- `/git-push` — tests → merge --no-ff → push → elimina rama
- Commits atomicos por bloque logico, titulo corto + cuerpo en espanol
- No WIP, no squash, no rebase -i

**Feature flags** (solo para features multi-issue): codigo completo y testeado, mergeado pero desactivado. Flag != WIP. Archivo: `dev/feature_flags.json`.

## Pipeline de creacion de agentes (12 pasos)

Todo agente/robot debe pasar por: scaffold → build → register → verify E2EE → [convert robot] → auto-avatar → display name → personalize → rebuild → start → health check → self-introduce. Los pasos 1-7 los ejecuta `create-full.sh`. Detalle completo en `.claude/rules/create_agent.md`.

Env var clave: `DEVELOPER_MATRIX_USERS` — el propio bot envia DM de bienvenida a estos usuarios.

## Pipeline de eliminacion de agentes (7 pasos)

Revierte todo lo que `create-full.sh` genera: validate → stop → deactivate Matrix → remove import → remove env vars → delete files → rebuild. Lo ejecuta `delete-full.sh`. Detalle completo en `.claude/rules/delete_agent.md`.

## Estructura

```
pkg/decision/          motor de reglas puro
pkg/llm/               tipos LLM puros
pkg/message/           parse/format mensajes
pkg/personality/       tipos de personalidad
pkg/skills/            tipos puros de skills + matching
shell/llm/             clientes LLM (anthropic, openai)
shell/matrix/          cliente Matrix (mautrix-go)
shell/ssh/             ejecutor SSH
shell/mcp/             cliente y servidor MCP (Model Context Protocol)
shell/skills/          loader (filesystem) + executor (scripts)
shell/effects/         Runner: []Action → side effects
shell/bus/             comunicacion inter-agente
devagents/types.go     Runner interface (comun a Agent y Robot)
devagents/runtime.go   Agent{}: ensambla core + shell (runtime completo con LLM)
devagents/robot.go     Robot{}: runtime ligero command-only (sin LLM, reglas, memoria)
agents/<id>/           agent.go (reglas puras) + config.yaml + prompts/system.md
agents/_specials/      agentes especiales del sistema (orchestrator, etc.)
tools/                 tool registry + tool implementations (subpackages)
tools/mcptools/        bridge: convierte MCP tools → tools.Tool
tools/skilltools/      tools para interactuar con skills (search, load, run)
skills/                contenido declarativo: SKILL.md + recursos (scripts, references, templates)
internal/config/       schema.go + loader.go
security/              grupos de usuarios/agentes + politicas de permisos (YAMLs)
cmd/launcher/          entrypoint principal (rulesRegistry)
cmd/agentctl/          CLI de gestion
crons/                 catálogo de automatizaciones nombradas (schedule.yaml + prompts)
knowledges/            base de conocimiento compartida entre agentes (*.md + SQLite FTS5)
dev-scripts/server/    start, stop, restart, ps, logs, dashboard
dev-scripts/agent/     new, register, verify, avatar, remove, delete-full, list
dev-scripts/cron/      new, list, apply — gestión de automatizaciones cron
dev-scripts/e2e/       install, run — E2E tests con Playwright
e2e/                   proyecto Node.js con Playwright (tests, fixtures, Element Web)
```

## E2E Tests

Tests end-to-end con Playwright contra Element Web + homeserver real. Proyecto Node.js separado en `e2e/`.

```bash
./dev-scripts/e2e/install.sh          # instalar dependencias
cp e2e/.env.example e2e/.env          # configurar credenciales
./dev-scripts/e2e/run.sh              # ejecutar tests (headless)
./dev-scripts/e2e/run.sh --headed     # con browser visible
```

- **Fixtures**: `e2e/fixtures/` — login E2EE (`element-auth.ts`), helpers de room (`matrix-room.ts`)
- **Tests**: `e2e/tests/` — login, assistant-bot, asistente-2, test-bot, test-personality, create-bot-pipeline, create-agent-pipeline
- **Assertions flexibles** para respuestas LLM (no-deterministicas), estrictas para commands (`!help`, `!ping`)
- Documentacion completa: `e2e/README.md`

## Reglas operativas

Guias detalladas en `.claude/rules/index.md`:

| Regla | Cuando |
|-------|--------|
| `create_agent.md` | Crear nuevo bot/agente/robot |
| `create_tool.md` | Añadir tool para function calling |
| `create_command.md` | Añadir comando !xxx |
| `delete_agent.md` | Eliminar un bot/agente/robot |
| `create_issue.md` | Crear issue en dev/issues/ |
| `fix_issue.md` | Implementar un issue existente |

## Agentes y Robots

Dos tipos de runtime: **Agent** (completo, con LLM) y **Robot** (ligero, solo comandos).
Config: `agent.type: "agent"` (default) o `agent.type: "robot"`.
Templates: `agents/_template/` (agent) y `agents/_template_robot/` (robot).

**Convención `_` prefijo**: los directorios con prefijo `_` en `agents/` son del sistema, no agentes desplegables. Incluye: `_template`, `_template_robot`, `_specials`.

| ID | Tipo | LLM | Descripcion |
|----|------|-----|-------------|
| assistant-bot | agent | GPT-4o | Asistente general, DMs |
| asistente-2 | agent | GPT-4o | Asistente con tools |
| test-bot | robot | — | Robot de prueba (E2E tests pipeline) |
| test-personality | agent | GPT-4o | Pirata espacial (E2E tests personalidad) |

## Build

- Go 1.23.5 (`/usr/local/go/bin`), siempre compilar con `-tags goolm`
- CGO_ENABLED=0 (pure-Go SQLite via modernc, shim en `cmd/launcher/sqlite.go`)
- Secrets via env vars (`.env.example`), nunca commitear `.env`

## Seguridad

Protecciones contra prompt injection y abuso de tools (issue 0019):

- **`pkg/sanitize/`** — deteccion pura de patrones de injection en mensajes entrantes
- **Tools deny-by-default** — allowlist vacia = todo denegado (file, ssh, http, matrix)
- **Path traversal** — EvalSymlinks + prefix validation en `tools/file/`
- **SSRF** — bloqueo de IPs privadas en `tools/http/`
- **SSH** — AllowedCommands allowlist + validacion de sintaxis shell en `tools/ssh/`
- **Rate limiting** — por room en `tools/registry.go` via `security.tool_rate_limit`
- **System prompts** — seccion anti-injection obligatoria (template en `.claude/templates/security-prompt.md`)
- **`storage.base_path`** — permite aislar datos de runtime fuera del arbol del proyecto
- **`claude_code.working_dir`** — aislamiento del subproceso `claude -p` fuera del repo (default: tmpdir)

Config YAML relevante: `security.sanitize.*`, `security.tool_rate_limit.*`, `storage.base_path`, `claude_code.working_dir`
Documentacion completa: `docs/security.md`

## Preferencias

- Espanol en configs/comentarios de dominio, ingles en codigo Go
- FP estricto, sin abstraccion prematura
- Trunk-based, Gitea como remote
- Arquitectura propia, sin frameworks de agentes externos
- Issues en `dev/issues/`, docs internas en `dev/README.md`