Arquitectura

Mapa resumido

Agentes accionables

Agentes que Main puede invocar directo desde un activador explícito en CLAUDE.md, o que participan del loop de ejecución de un ticket.

Planner agente

Toma un objetivo o requerimiento, investiga el repositorio y produce un análisis más un set de tickets listos para ejecutar. No implementa código.

Activador: "planificá", "creá un plan", "diseñá la implementación de", "dividí en tickets"

• .claude/agents/planner.md
• 02-System/tickets.json
• 02-System/tech-tickets/

Coordinator agente

Entrypoint durable de los loops del proyecto: ejecuta tickets siguiendo el playbook de workflow_orchestrator, delega el sanity-check en sanity-auditor, o aplica el patrón genérico de orquestación. Coordina agentes, no escribe código.

Activador: "ejecutá TICKET-X", "implementá TICKET-X", ./run-ticket.sh

• .claude/agents/coordinator.md
• .claude/agents/workflow_orchestrator.md
• .claude/agents/coder.md
• .claude/agents/code-reviewer.md
• .claude/agents/sanity-auditor.md

Architect agente

Analiza la estructura y arquitectura de un proyecto (el propio por defecto, u otro si se le pasa un path) y devuelve un reporte estructural. Read-only, no implementa cambios.

Activador: "analizá la estructura", "análisis arquitectónico", "analizá el proyecto en <path>"

• .claude/agents/architect.md
• 02-System/ARCHITECTURE.md

Security Reviewer agente

Audita el código en busca de vulnerabilidades, malas configuraciones y violaciones de las reglas de seguridad documentadas (autorización de datos, auth, secrets, PII, validación de inputs). Solo reporta hallazgos con severidad; no implementa fixes.

Activador: "revisá seguridad", "auditá seguridad", "security review"

• .claude/agents/security-reviewer.md
• 02-System/ARCHITECTURE.md

Test Writer agente

Escribe y amplía suites de tests automatizados que cubren comportamiento existente. No implementa ni cambia features de producción.

Activador: "escribí tests para", "agregá cobertura de tests a"

• .claude/agents/test-writer.md
• tests/

Backlog Manager agente

Mantiene el backlog del proyecto: captura trabajo accionable descubierto durante planificación, implementación o revisión, deduplica contra tickets existentes y preserva prioridades y dependencias.

Activador: "capturá al backlog", "agregá al backlog", "creá un ticket para", o trabajo descubierto fuera del scope del ticket actual

• .claude/agents/backlog-manager.md
• 02-System/tickets.json
• .claude/rules/backlog-rule.md

Diagram Designer agente

Genera diagramas de arquitectura (ERD, flujos de proceso, stacks tecnológicos) a partir de especificaciones textuales usando Mermaid, y los renderiza a PNG/SVG.

Activador: "diagramá", "generá un ERD de", "generá un flujo de", "generá un diagrama de stack de"

• .claude/agents/diagram-designer.md
• npx @mermaid-js/mermaid-cli
• docs/diagrams/

GitHub Sync agente

Ejecuta operaciones de GitHub en nombre de Main: branches, commits, pull requests, issues y push. Opt-in: se niega y reporta si la integración con GitHub está deshabilitada.

Activador: "abrí un PR", "subí los cambios", "creá/actualizá el issue" (solo si GITHUB_ENABLED=true)

• .claude/agents/github-sync.md
• gh CLI

Content Generator agente

Opera el pipeline de generación de contenido en modo semi-asistido: decide qué paso correr (ingesta, borrador, orquestador multiproyecto), reporta estado y puede asistir la publicación. Nunca publica sin confirmación del usuario en la misma corrida.

Activador: "generá contenido", "creá un borrador de … en …", "generá para todas las plataformas", "¿qué se generó / qué falta / qué está publicado?", "marcá … como publicado", "publicá … en …", "asistí la publicación de …"

• .claude/agents/content-generator.md
• scripts/ingest_sessions.py
• scripts/generate_content.py
• scripts/run_content.py
• scripts/publish_content.py
• scripts/publish_note.py
• scripts/content_status.py

Ciclo de ejecución

Los agentes y el playbook que implementan y validan un ticket individual, orquestados por el coordinator.

Coder agente

Implementa tickets, especificaciones y planes de implementación aprobados, preservando la arquitectura y convenciones existentes. Es un implementador, no un arquitecto.

• .claude/agents/coder.md

Code Reviewer agente

Revisa el código ya implementado para un ticket o historia de usuario. Reporta solo bugs concretos, regresiones, problemas de seguridad/autorización, tests faltantes, code smells y problemas de mantenibilidad. No implementa fixes.

• .claude/agents/code-reviewer.md

Sanity Auditor agente

Orquesta un chequeo multiagente de arquitectura, seguridad, calidad de código, tests y salud del backlog; consolida el resultado con fecha de última corrida y propone mejoras como tickets.

• .claude/agents/sanity-auditor.md
• scripts/sanity_report.py
• monitoring/sanity/sanity.json
• SANITY.md

workflow_orchestrator (playbook) agente

Playbook de ejecución de un ticket: define el ciclo implement → review → fix → re-review → done con coder y code-reviewer. No es un agente que se invoque directo ni que spawnee sub-agents; lo lee y ejecuta el coordinator.

• .claude/agents/workflow_orchestrator.md
• .claude/agents/coder.md
• .claude/agents/code-reviewer.md

Runners

Scripts de shell que invocan la CLI de Claude Code para ejecutar tickets, en modo individual, por lotes en paralelo, o para el sanity-check.

run-ticket.sh runner

Ejecuta un único ticket vía la CLI claude en modo headless, y actualiza su estado en el registro automáticamente tras la corrida (marca blocked con motivo si la interrupción vino de un error de infraestructura).

• run-ticket.sh
• 02-System/tickets.json
• claude CLI

run-parallel.sh runner

Ejecuta tickets ready en oleadas paralelas respetando depends_on, invocando run-ticket.sh como unidad atómica. Corre un chequeo best-effort de scopes de escritura solapados antes de lanzar cada oleada.

• run-parallel.sh
• run-ticket.sh
• 02-System/tickets.json
• .claude/rules/execution-rule.md

run-sanity.sh runner

Dispara el sanity-check de ingeniería del proyecto, delegando en el agente sanity-auditor.

• run-sanity.sh
• .claude/agents/sanity-auditor.md
• scripts/sanity_report.py

Skills

Comandos de usuario a nivel global (~/.claude/commands/) que este proyecto usa para el protocolo de sesión y las torres de control multiproyecto.

/iniciar skill

Re-dispara explícitamente el protocolo de arranque de sesión, útil tras un /clear o cuando el hook SessionStart no corrió.

• ~/.claude/commands/iniciar.md
• .claude/rules/session-rule.md

/salir skill

Cierra el contenido de la sesión activa: actualiza Trabajo realizado, Próximos pasos y demás secciones de docs/sessions/{alias}.md.

• ~/.claude/commands/salir.md
• docs/sessions/

/project-status skill

Muestra el estado actual de todos los proyectos del toolkit (tickets, git, costos).

• ~/.claude/commands/project-status.md
• ~/.claude/scripts/projects_status.py

/scrum skill

Evalúa el estado de los proyectos del toolkit y produce un plan de acción priorizado, como un scrum master técnico.

• ~/.claude/commands/scrum.md
• ~/.claude/scripts/projects_status.py

/mapa skill

Torre de control read-only con el scope general de todos los proyectos 2026Q3_* y sus blockers en conjunto, en una sola pantalla.

• ~/.claude/commands/mapa.md
• ~/.claude/scripts/mapa.py

Scripts

Scripts Python de scripts/ agrupados por flujo: mapa del sistema, sanity-check, gestión de tickets, pipeline de contenido y operación del sitio.

system_map.py script

Genera el mapa del sistema: un diagrama de flujo Mermaid del toolkit de agentes a partir del inventario real del proyecto (agentes, runners, skills).

• scripts/system_map.py
• .claude/agents/
• run-ticket.sh
• run-parallel.sh
• run-sanity.sh
• ~/.claude/commands/
• docs/diagrams/

sanity_report.py script

Registra y renderiza el sanity-check de ingeniería del proyecto: actualiza monitoring/sanity/sanity.json (fuente de verdad) y su render legible SANITY.md.

• scripts/sanity_report.py
• monitoring/sanity/sanity.json
• SANITY.md

Gestión de tickets (register_ticket.py, update_ticket_status.py) script

Registra tickets nuevos y actualiza el estado de tickets existentes en el registro centralizado, de forma idempotente y con notas persistentes.

• scripts/register_ticket.py
• scripts/update_ticket_status.py
• 02-System/tickets.json

Pipeline de contenido (ingest_sessions → generate_content / run_content → publish_content / publish_note → mark_blog_published, content_status, channel_metrics) script

Cadena semi-asistida que va de las sesiones de proyectos hermanos a un borrador de contenido, y de ahí a la publicación asistida o por API, con reporte de estado y métricas de canal.

• scripts/ingest_sessions.py
• scripts/generate_content.py
• scripts/run_content.py
• scripts/publish_content.py
• scripts/publish_note.py
• scripts/mark_blog_published.py
• scripts/content_status.py
• scripts/channel_metrics.py
• content/drafts/
• content/blog/
• content/state/publish_status.json

Operación del sitio (export_suscriptores.py, borrar_cuenta.py, verificar_auth_supabase.py) script

Tareas administrativas manuales del sitio: exportar la lista de suscriptores, borrar una cuenta a pedido, y verificar el setup de Supabase Auth.

• scripts/export_suscriptores.py
• scripts/borrar_cuenta.py
• scripts/verificar_auth_supabase.py
• Supabase

Reglas

Reglas de conducta activas en .claude/rules/ que se aplican de forma continua a todos los agentes, no solo durante la ejecución de un ticket puntual.

backlog-rule regla

Captura continua de trabajo futuro detectado durante planificación, implementación o revisión hacia el backlog del proyecto.

• .claude/rules/backlog-rule.md
• 02-System/tickets.json

changelog-rule regla

Mantiene CHANGELOG.md actualizado ante cada cambio significativo de comportamiento, estructura o interfaz.

• .claude/rules/changelog-rule.md
• CHANGELOG.md

decisiones-rule regla

Registra cada decisión técnica o tecnológica consecuente como un ADR en 02-System/decisions/, con su estado en el registro decisions.json.

• .claude/rules/decisiones-rule.md
• 02-System/decisions/
• 02-System/decisions.json

execution-rule regla

Define la ejecución de tickets como un batch paralelo por oleadas vía run-parallel.sh una vez que todo el set de tickets del objetivo está generado y ready.

• .claude/rules/execution-rule.md
• run-parallel.sh
• run-ticket.sh

frontmatter-rule regla

Define la convención de clasificación por frontmatter (domain, type, status, owner) para los documentos Markdown gestionados del proyecto.

• .claude/rules/frontmatter-rule.md

session-rule regla

Protocolo de arranque de sesión: decide cuándo retomar o crear una sesión, qué mostrar y qué se escribe en docs/sessions/.

• .claude/rules/session-rule.md
• docs/sessions/
• docs/sessions.md

site-updates-rule regla

Mantiene site/src/_data/actualizaciones.json actualizado ante cada cambio visible del sitio, publicación de una nota o cambio de sistema perceptible por un lector del blog.

• .claude/rules/site-updates-rule.md
• site/src/_data/actualizaciones.json
• site/scripts/validate-actualizaciones.js

Artefactos

Los archivos y directorios persistentes que registran el estado del sistema: tickets, historial de cambios, decisiones, sesiones, mapas, salud de ingeniería y contenido publicado.

Registro de tickets artefacto

Fuente de verdad para localizar tickets y consultar su estado, con el contenido detallado de cada ticket en archivos individuales.

• 02-System/tickets.json
• 02-System/tech-tickets/

CHANGELOG.md artefacto

Registro legible por humanos de qué cambió y cuándo, independiente de git; se actualiza en cada cambio significativo de comportamiento.

• CHANGELOG.md

Registro de decisiones (ADR) artefacto

Registro durable del porqué de las decisiones técnicas y tecnológicas del proyecto, con su estado de vigencia en decisions.json.

• 02-System/decisions/
• 02-System/decisions.json

Sesiones artefacto

Contexto completo de cada unidad de trabajo documentada (objetivo, decisiones, próximos pasos), con un índice liviano de todas las sesiones.

• docs/sessions/
• docs/sessions.md

Mapa del sistema artefacto

Diagrama de flujo Mermaid del toolkit de agentes y su metadata de frescura (conteos, fingerprint de inputs), regenerado por system_map.py.

• docs/diagrams/
• scripts/system_map.py

Sanity-check artefacto

Estado de salud de ingeniería del proyecto por check, con snapshot del backlog y mejoras propuestas; SANITY.md es su render legible.

• monitoring/sanity/sanity.json
• SANITY.md

Contenido publicado artefacto

Las notas de blog ya escritas y el estado de su publicación por plataforma (blog, dev.to, y las demás plataformas soportadas).

• content/blog/
• content/state/publish_status.json

El sitio artefacto

El blog público First Class: sitio estático Eleventy, desplegado en Vercel, con auth y comentarios sobre Supabase.

• site/
• Eleventy
• Vercel
• Supabase