ATL Inteliside¶
Motor de ejecucion de features para equipos de desarrollo. Toma milestones de GitHub Projects (creados por SDD-Wizards o SDD-Intake) e implementa la feature completa con un flujo estructurado: spec tecnica, implementacion TDD, verificacion contra ACs del PM y cierre automatico. Usa Engram como memoria compartida del equipo y subagentes aislados con context: fork para mantener limpia la ventana de contexto del orquestador.
Prerequisitos¶
- Claude Code instalado
- Engram instalado y configurado como memoria compartida del equipo (
brew install gentleman-programming/tap/engram) - GitHub CLI (
gh) instalado y autenticado (gh auth login) - Acceso al repositorio de GitHub del proyecto
- Labels ATL creados en el repo (9 labels — ver seccion de configuracion)
- Milestone con Feature Spec en GitHub Projects (creado por SDD-Wizards o SDD-Intake)
Skills¶
ATL Inteliside expone 12 skills organizados en un DAG (grafo dirigido aciclico) que cubre desde la ingesta del Feature Spec hasta el cierre del milestone. El orquestador coordina el flujo completo delegando cada fase a subagentes especializados. Los skills no se invocan directamente en uso normal — el orquestador los lanza en orden.
| Skill | Descripcion | Invocacion | Tools permitidos |
|---|---|---|---|
| orchestrador | Coordinador principal del DAG. Delega a subagentes, nunca ejecuta codigo. | /atl-inteliside:orchestrador [milestone] |
Read, Grep, Glob |
| sdd-from-github | Lee milestone de GitHub Projects y extrae el Feature Spec del PM. | Via atl-analyst | (hereda de atl-analyst) |
| sdd-init | Detecta stack tecnico del proyecto y configura Engram. | Via atl-analyst | (hereda de atl-analyst) |
| sdd-explore | Analiza codebase existente contra el Feature Spec para identificar que existe, que construir y conflictos. | Via atl-analyst | (hereda de atl-analyst) |
| sdd-propose | Genera propuesta formal con intent, alcance, enfoque tecnico y plan de rollback. | Via atl-analyst | (hereda de atl-analyst) |
| sdd-spec | Convierte la propuesta en delta spec con lenguaje RFC 2119 y escenarios Given/When/Then. | Via atl-architect | (hereda de atl-architect) |
| sdd-design | Documenta decisiones de arquitectura, patrones y restricciones de implementacion. Corre en paralelo con sdd-spec. | Via atl-architect | (hereda de atl-architect) |
| sdd-tasks | Descompone la feature en tasks atomicas por fases (Foundation, Core, Integration, UI, Testing) y crea issues en GitHub. | Via atl-architect | (hereda de atl-architect) |
| sdd-write-tests | Genera tests ANTES de que exista el codigo, basandose en la spec y Given/When/Then. Elimina sesgo AI-AI. | Via atl-test-writer | (hereda de atl-test-writer) |
| sdd-apply | Implementa el codigo real en modo TDD (RED, GREEN, REFACTOR). Pone los tests en verde. | Via atl-builder | (hereda de atl-builder) |
| sdd-verify | Valida implementacion en dos capas: ACs del PM (negocio) y RFs de la spec tecnica. Ejecuta tests reales. | Via atl-verifier | (hereda de atl-verifier) |
| sdd-archive | Cierra issues y milestone en GitHub, promueve conocimiento del pipeline al equipo en Engram. | Via atl-verifier | (hereda de atl-verifier) |
Agentes¶
El plugin usa una arquitectura de 5 subagentes aislados, cada uno con context: fork para que su ventana de contexto no contamine al orquestador. El orquestador nunca ejecuta codigo directamente — solo coordina y mantiene el estado del pipeline en Engram.
| Agente | Rol | Modelo | Tools | Notas |
|---|---|---|---|---|
| atl-analyst | Analisis y preparacion: ingesta, deteccion de stack, exploracion del codebase, propuesta de cambio | sonnet | Read, Grep, Glob, Bash (disallowed: Write, Edit, Agent) | Solo lectura. Cubre sdd-from-github, sdd-init, sdd-explore, sdd-propose. |
| atl-architect | Especificacion y planificacion: spec tecnica RFC 2119, diseno de arquitectura, decomposicion en tasks | sonnet | Read, Grep, Glob, Bash (disallowed: Edit, Agent) | Puede escribir issues en GitHub via Bash. Cubre sdd-spec, sdd-design, sdd-tasks. |
| atl-test-writer | Tests independientes antes de implementar, derivados de la spec y Given/When/Then | sonnet | Read, Write, Edit, Grep, Glob, Bash (disallowed: Agent) | Hooks PostToolUse: file-size-guard.sh, semantic-check.sh. Cubre sdd-write-tests. |
| atl-builder | Implementacion TDD: pone tests en verde, guarda patrones y bugs en Engram | inherit (modelo del parent) | Read, Write, Edit, Grep, Glob, Bash | Hooks PostToolUse: scope-guard-builder.sh, file-size-guard.sh. Hook Stop: run-tests-async.sh. Cubre sdd-apply. |
| atl-verifier | Verificacion contra ACs del PM y RFs tecnicos, cierre de GitHub, promocion de conocimiento | sonnet | Read, Grep, Glob, Bash (disallowed: Write, Edit, Agent) | Solo lectura. Cubre sdd-verify, sdd-archive. |
Flujo de trabajo¶
El pipeline sigue un DAG estricto donde cada fase depende de la anterior. El orquestador coordina y el dev interactua con comandos simples:
- Ingesta (
sdd-from-github): atl-analyst lee el milestone de GitHub Projects, extrae el Feature Spec del PM y lo persiste en Engram. - Inicializacion (
sdd-init): atl-analyst detecta el stack tecnico del proyecto (package.json, tsconfig, etc.) y configura el contexto compartido en Engram. - Exploracion (
sdd-explore): atl-analyst analiza el codebase contra el Feature Spec para identificar que ya existe, que hay que construir y posibles conflictos. - Propuesta (
sdd-propose): atl-analyst genera un documento formal con intent, alcance, enfoque tecnico y plan de rollback. El dev aprueba antes de continuar. - Spec + Design (
sdd-spec+sdd-design): atl-architect ejecuta ambos en paralelo. sdd-spec produce la delta spec tecnica con RFC 2119 y Given/When/Then. sdd-design documenta decisiones de arquitectura y patrones. - Tasks (
sdd-tasks): atl-architect descompone la feature en tasks atomicas organizadas en 5 fases (Foundation, Core, Integration, UI, Testing) y las crea como issues en GitHub. - Tests (
sdd-write-tests): atl-test-writer genera tests por fase ANTES de que exista el codigo, derivados de la spec. - Implementacion (
sdd-apply): atl-builder recibe los tests en rojo y escribe el minimo codigo para ponerlos en verde. Se ejecuta por fase (Foundation, Core, Integration, UI, Testing). - Verificacion (
sdd-verify): atl-verifier valida en dos capas — ACs del PM (negocio) y RFs de la spec tecnica. Un AC es COMPLIANT solo si existe un test que lo cubre Y pasa. - Archivo (
sdd-archive): atl-verifier cierra todos los issues y el milestone en GitHub, y promueve conocimiento del pipeline (patrones, decisiones, bugs) al proyecto de equipo en Engram.
Flujo tipico de comandos del dev:
/atl-inteliside:orchestrador feat-user-auth
/sdd-continue # explore -> propose
/sdd-continue # spec + design en paralelo
/sdd-continue # tasks (crea issues)
/sdd-apply Foundation
/sdd-apply Core
/sdd-apply Integration
/sdd-apply UI
/sdd-apply Testing
/sdd-verify
/sdd-archive
Contratos de datos¶
Engram¶
ATL Inteliside usa dos proyectos Engram separados para aislar el conocimiento permanente del equipo del estado efimero del pipeline de implementacion.
Proyecto de equipo (engram_project): Conocimiento permanente que sobrevive entre features. Todos los devs lo consultan. Topic keys principales:
| topic_key | Contenido | Quien escribe | Quien lee |
|---|---|---|---|
team/decisions/{tema} |
Decisiones de arquitectura | sdd-design, sdd-archive | sdd-explore, sdd-apply |
team/patterns/{area} |
Patrones de codigo establecidos | sdd-apply, sdd-archive | sdd-apply, sdd-explore |
team/bugs/{descripcion} |
Bugs resueltos con root cause | sdd-apply, sdd-verify | sdd-explore, sdd-apply |
team/completed/{feature} |
Historial de features completadas | sdd-archive | sdd-explore |
Proyecto de pipeline ({engram_project}/atl): Estado efimero del pipeline activo. Se limpia al archivar una feature. Topic keys principales:
| topic_key | Contenido | Quien escribe | Quien lee |
|---|---|---|---|
sdd/{feature}/feature-spec |
Feature Spec del PM | sdd-from-github | sdd-explore, sdd-verify |
sdd/{feature}/exploration |
Analisis del codebase | sdd-explore | sdd-propose |
sdd/{feature}/proposal |
Propuesta de cambio | sdd-propose | sdd-spec, sdd-design |
sdd/{feature}/spec |
Delta spec tecnica | sdd-spec | sdd-tasks, sdd-verify |
sdd/{feature}/design |
Decisiones de arquitectura | sdd-design | sdd-tasks, sdd-apply |
sdd/{feature}/tasks |
Tasks breakdown | sdd-tasks | sdd-apply, sdd-verify |
sdd/{feature}/test-plan/{phase} |
Test plan por fase | sdd-write-tests | sdd-apply, sdd-verify |
sdd/{feature}/current-task |
Progreso en tiempo real | sdd-apply | orchestrador |
sdd/{feature}/pipeline-state |
Estado del DAG | orchestrador | orchestrador |
sdd/{feature}/verify-report |
Reporte de verificacion | sdd-verify | sdd-archive |
project/github-context |
owner, repo, milestone | sdd-from-github | todos |
project/config |
Stack detectado, convenciones | sdd-init | todos |
Regla de aislamiento: solo sdd-archive promueve del pipeline al equipo (excepto sdd-design que escribe DAs y sdd-apply que escribe patterns/bugs directamente al equipo).
GitHub¶
ATL Inteliside consume milestones creados por SDD-Wizards o SDD-Intake y crea issues de tasks bajo ellos. El modelo de datos en GitHub sigue esta estructura:
- Milestone
feat-[nombre]: creado por el PM via SDD-Wizards. Contiene el Feature Spec completo en la descripcion. - Issues
task: [area] [nombre]: creados por sdd-tasks bajo el milestone. Cada issue tiene labelsatl-task,area:[backend|frontend|db|test]yatl:[pending|in-progress|done].
Labels requeridos (9 en total):
| Label | Color | Descripcion |
|---|---|---|
atl-task |
#0075ca |
Task generada por ATL |
area:backend |
#e4e669 |
Tarea de backend |
area:frontend |
#d93f0b |
Tarea de frontend |
area:db |
#0e8a16 |
Tarea de base de datos |
area:test |
#5319e7 |
Tarea de testing |
atl:pending |
#ededed |
Task pendiente |
atl:in-progress |
#fbca04 |
Task en progreso |
atl:done |
#0e8a16 |
Task completada |
atl-summary |
#cfd3d7 |
Resumen de la feature |
Hooks¶
ATL Inteliside incluye hooks a nivel de plugin y a nivel de agente para garantizar seguridad y calidad durante la ejecucion del pipeline.
Hooks a nivel de plugin (hooks/hooks.json):
| Evento | Matcher | Hook | Timeout | Proposito |
|---|---|---|---|---|
| PreToolUse | Bash |
block-destructive.sh | 10s | Bloquea comandos destructivos (rm -rf, git push --force, etc.) |
| PreToolUse | Agent |
circuit-breaker.sh | 15s | Previene loops descontrolados de subagentes |
| PostToolUse | Edit\|Write |
semantic-check.sh | 15s | Valida que ediciones sean semanticamente correctas |
Hooks a nivel de agentes (en frontmatter):
| Agente | Evento | Matcher | Hook | Proposito |
|---|---|---|---|---|
| atl-test-writer | PostToolUse | Write\|Edit |
file-size-guard.sh | Limita tamano de archivos escritos |
| atl-test-writer | PostToolUse | Write\|Edit |
semantic-check.sh | Valida semantica de tests |
| atl-builder | PostToolUse | Write |
scope-guard-builder.sh | Previene escritura fuera de scope |
| atl-builder | PostToolUse | Write |
file-size-guard.sh | Limita tamano de archivos |
| atl-builder | Stop | (sin matcher) | run-tests-async.sh (async) | Ejecuta tests al terminar (timeout 120s) |
Configuracion para proyectos¶
Agregar al CLAUDE.md del repositorio del proyecto:
## ATL Inteliside
engram_project: "nombre-proyecto-dev"
github_owner: "tu-org-o-usuario"
github_repo: "nombre-repo"
ATL deriva automaticamente el proyecto de pipeline: engram_pipeline = "{engram_project}/atl". Solo se configura engram_project.
Todos los devs del equipo deben usar exactamente el mismo valor de engram_project para compartir la memoria del equipo.
El template completo de CLAUDE.md incluye ademas:
- Descripcion del proyecto, stack y entorno de desarrollo
- Comandos frecuentes (dev, test, build, db)
- Convenciones de estructura de carpetas, naming y testing
- Variables de entorno requeridas
- References a rules de ATL (engram-protocol.md, subagent-architecture.md, atl-workflow.md, context-monitoring.md, team-rules.md)
Crear los labels ATL en GitHub antes del primer uso:
gh label create "atl-task" --color "0075ca" --description "Task generada por ATL Inteliside"
gh label create "area:backend" --color "e4e669"
gh label create "area:frontend" --color "d93f0b"
gh label create "area:db" --color "0e8a16"
gh label create "area:test" --color "5319e7"
gh label create "atl:pending" --color "ededed"
gh label create "atl:in-progress" --color "fbca04"
gh label create "atl:done" --color "0e8a16"
gh label create "atl-summary" --color "cfd3d7"
Integracion con Doc-Gen¶
Despues de implementar y verificar una feature con ATL, se recomienda correr doc-gen para mantener la documentacion del proyecto actualizada.
| Cuando | Comando |
|---|---|
| Despues de verificar una feature (sdd-verify) | /doc-gen:doc-modulo {path-del-modulo-afectado} |
| Despues de archivar un cambio (sdd-archive) | /doc-gen:doc-sync |
| Verificacion periodica | /doc-gen:doc-sync |
Limitaciones conocidas¶
- Un dev, una feature a la vez: No soporta trabajo simultaneo de multiples devs en el mismo milestone.
- Engram obligatorio: Sin Engram instalado, el plugin no puede funcionar — toda la comunicacion entre subagentes depende de la memoria compartida.
- GitHub Projects obligatorio: Los Feature Specs deben estar como milestones en GitHub. No soporta otros sistemas de gestion de proyectos.
- Contexto del orquestador: Aunque los subagentes corren en
context: fork, el orquestador puede acumular contexto. Se recomienda monitorear y considerar nueva sesion al superar 75%. - Sesgo AI-AI mitigado pero no eliminado: La separacion test-writer/builder reduce el sesgo, pero ambos comparten la misma spec como fuente. No reemplaza QA humano.
- Pipeline secuencial: Las fases del DAG son secuenciales (excepto spec+design en paralelo). No se pueden ejecutar features en paralelo dentro del mismo pipeline.
ATL Inteliside v1.0.0 — Marketplace Inteliside