agents_and_robots/.claude/rules/index.md

Reglas del proyecto

Guias operativas para LLMs que trabajan en este codebase. Cada regla describe como ejecutar una tarea especifica respetando la arquitectura y convenciones del proyecto.

Reglas disponibles

Regla	Archivo	Cuando aplicarla
Crear agente	create_agent.md	Al crear un nuevo bot/agente Matrix completo
Crear herramienta	create_tool.md	Al añadir una nueva tool para LLM function calling
Crear comando	create_command.md	Al añadir un comando directo (!xxx) a un agente
Crear skill	create_skill.md	Al crear una nueva skill (flujo multi-paso declarativo)
Crear issue	create_issue.md	Al crear un nuevo issue/feature request en dev/issues/
Arreglar issue	fix_issue.md	Al implementar/arreglar un issue existente de dev/issues/

Cuando consultar las reglas

• Crear agente: cuando el usuario pida crear un nuevo bot, agente, o asistente. Incluye la estructura de archivos, reglas puras, config YAML, system prompt y registro en el launcher.
• Crear herramienta: cuando el usuario pida añadir una nueva herramienta/tool al sistema. Incluye el patron Def (puro) + Exec (impuro), registro en runtime.go y habilitacion en config.
• Crear comando: cuando el usuario pida añadir un comando directo (!xxx) a un agente. Los comandos se resuelven sin pasar por reglas ni LLM.
• Crear skill: cuando el usuario pida añadir una skill (flujo multi-paso declarativo). Las skills combinan tools, logica condicional y conocimiento de dominio en un SKILL.md con recursos opcionales.
• Crear issue: cuando el usuario pida crear un nuevo issue, feature request o task. Usa el template en .claude/templates/issue.md.
• Arreglar issue: cuando el usuario pida implementar, arreglar o trabajar en un issue existente. Incluye crear rama (/git-branch), implementar las tareas con tests, cerrar el issue, e integrar a master (/git-push).

Flujo de desarrollo — Trunk-based development (TBD)

El proyecto usa TBD estricto. master es el unico branch estable y siempre deployable. Nunca trabajar directamente en master.

master (trunk) ← siempre deployable
  ↑
  └── issue/<NNNN>-<slug>  ← rama efimera (horas, no dias)
        ├── commit: feat: ...
        ├── commit: test: ...
        └── commit: docs: ...
      merge --no-ff → master → push → delete branch

1. /git-branch — crea rama issue/<NNNN>-<slug> desde master actualizado
2. Implementar con commits atomicos por bloque logico (no WIP, no mezclar tipos)
3. /git-push — tests → merge --no-ff a master → push → eliminar rama

Commits

• Cada commit es atomico por bloque logico con prefijo: feat:, fix:, test:, docs:, refactor:, chore:
• Titulo corto + cuerpo largo en español
• No WIP: nunca commitear "wip", "tmp", codigo a medias
• No squash: --no-ff preserva commits; git log --first-parent da vista limpia
• No rebase -i: commits limpios desde el inicio

Feature flags (para features multi-issue)

Cuando una feature no cabe en una sola rama corta, desglosar en sub-issues. Cada sub-issue mergea codigo completo y testeado protegido por un feature flag (desactivado). Feature flag ≠ WIP — un flag protege codigo terminado, no codigo a medias.

Archivo: dev/feature_flags.json

Comandos

• /git-branch — crear rama de trabajo (.claude/commands/git-branch.md)
• /git-push — integrar rama a master y publicar (.claude/commands/git-push.md)

Filosofia completa documentada en CLAUDE.md seccion "Trunk-based development".

Principio general

Todas las reglas respetan el patron pure core / impure shell:

• pkg/ es puro — nunca añadir side effects
• shell/ es impuro — todo I/O va aqui
• agents/ compone ambos — reglas puras + ensamblado con shell
• tools/ sigue el mismo patron: Def (datos puros) + Exec (funcion impura)