La Máquina
Lo que conecta el trabajo y la mentalidad. Un único directorio core/ escrito a mano, con herramientas y hooks en TypeScript, se proyecta en cada CLI. Una vez instalados, esos scripts (no el modelo) controlan la máquina de estado, el enrutamiento, las puertas y la traza de auditoría que hacen determinístico el proceso anterior.
3.1Un harness sobre otro harness
Un CLI como Claude Code ya es un harness: le entrega al modelo herramientas, subagentes y hooks de ciclo de vida. No reemplazamos eso. Construimos un segundo harness encima de él. El motor AI-DLC es un conjunto de scripts TypeScript que se conectan a esos mismos puntos de extensión y convierten un asistente en bruto en un proceso guiado por metodología. La metodología se escribe una vez, neutral respecto al harness, y luego se proyecta a la forma de cada CLI.
bun scripts/package.ts regenera cada dist/<harness>/ commiteado desde el único core/.Cómo se ve cada dist
Cada harness recibe el mismo motor; solo cambia el envoltorio para corresponder a cómo ese CLI carga herramientas, agentes y hooks.
dist/claude/.claude/
Claude Code. Hooks registrados en settings.json; los agentes son archivos .md ; el motor corre bajo bun.
dist/kiro/.kiro/
Kiro CLI e IDE. El mismo motor, accedido a través de un shim adaptador. Kiro entrega el contexto de los hooks de forma diferente, así que un pequeño adaptador lo normaliza.
dist/codex/.codex/
Codex CLI. La configuración es TOML; los hooks viven en hooks.json; los agentes se emiten en la forma que Codex espera.
La superficie del harness controla
· El orquestador SKILL.md (per-harness).
· manifest.ts, que dice cómo core se mapea a este CLI.
· Registro de hooks en la configuración del CLI.
Core controla
· El motor (aidlc-orchestrate.ts, aidlc-state.ts).
· Cada etapa, agente, sensor, archivo de conocimiento.
· La metodología. Ningún harness recibe trato especial.
core/ (or harness/<name>/), ejecutas el empaquetador, y cada árbol dist/ se regenera. Los usuarios copian dist/<harness>/ a su proyecto. Portar a un nuevo CLI es una proyección, no una reescritura.3.2El bucle de control
El corazón del harness. El orquestador nunca decide qué hacer a continuación. Le pregunta al motor. aidlc-orchestrate.ts next lee el estado y devuelve una directivatipada; el conductor ejecuta exactamente eso, y luego vuelve a next. El enrutamiento vive en la herramienta, no en el modelo.
next → una directiva → ejecutar → next. Las transiciones de estado viven en herramientas, así que el bucle es reproducible y auditable.3.3Hooks: permanecer en el bucle entre turnos
Los hooks son cómo el motor mantiene el control incluso entre los turnos del modelo. El CLI los dispara en eventos de ciclo de vida, y cada uno es un pequeño script bun . La mayoría son observadores (registran y nunca alteran el flujo). Uno es alterador de flujo: puede bloquear o redirigir lo que sucede a continuación.
Stop es el que altera el flujo hoy.| Hook | Evento | Rol |
|---|---|---|
session-start | SessionStart | Inicializa el contexto del workspace; ejecuta el paso de composición de plugins. |
mint-presence | UserPromptSubmit | Registra la presencia humana: prueba de que una persona estuvo aquí en este turno. |
audit-logger | PostToolUse | Anexa el evento canónico de auditoría por cada escritura que cambia estado. |
sensor-fire | PostToolUse | Despacha los sensores determinísticos. |
runtime-compile | PostToolUse | Recompila el grafo de runtime para que el próximo next lea estado actualizado. |
sync-statusline | PostToolUse | Muestra en vivo el estado de fase / etapa / puerta. |
log-subagent | SubagentStop | Rastrea ejecuciones delegadas a subagentes. |
validate-state | PreCompact | Protege la integridad del estado antes de que el contexto se resuma. |
stop | Stop | Flow-altering. Impone el bucle de reenvío para que el flujo no se detenga silenciosamente. |
session-end | SessionEnd | Cierra la sesión limpiamente. |
PreToolUse guarda de alcance de lectura del revisor) está en revisión. Bloquea a un revisor delegado de leer unidades hermanas. Mismo patrón: imposición determinística de una regla que antes era solo prosa.3.4Los scripts que dirigen el espectáculo
El harness es en realidad un conjunto de scripts core/tools/aidlc-*.ts , cada uno un pequeño CLI que el conductor llama. El estado nunca cambia excepto a través de uno de ellos, y esa única regla es lo que hace una ejecución determinística y auditable. orchestrate es el cerebro; todo lo demás lo apoya.
| Script | Rol |
|---|---|
orchestrate | El motor. Lee el estado del flujo + el grafo compilado y responde "¿qué sigue?" como una directiva tipada. Todo el enrutamiento vive aquí; el modelo no planifica, despacha. |
graph | Verdad estructural. El grafo de definición de las 32 etapas: dependencias, fases, qué agente lidera cada etapa. Compilado, no editable en tiempo de ejecución. |
runtime | Espejo del plano de datos. Materializa runtime-graph.json desde la traza de auditoría + notas por etapa. La imagen en vivo de lo realmente hecho, mantenida fresca para que el próximo next lea la realidad actual. |
state | Transitions. approve / reject / skip / scope-change, cada uno con las guardas de presencia humana. El único escritor del archivo de estado del flujo. |
audit / log | El registrador. Cada cambio de estado anexa un evento canónico a una traza de solo anexado (más un registro de Q&A / decisiones). Esto es lo que hace una ejecución reproducible y explicable después del hecho. |
bolt / swarm | Autonomy. Construcción paralela por unidad en worktrees aisladas, con el árbitro de convergencia que decide qué vuelve al merge. |
sensor* | Verification. Verificaciones determinísticas después de una escritura: secciones requeridas, cobertura upstream, lint, tipos. |
SKILL.md) se mantienen sincronizados: el trabajo del motor es emitir exactamente la secuencia de directivas que el flujo en prosa ya produce, para que el control migre a código determinístico sin cambiar el comportamiento.La Mente
El juicio detrás de ese trabajo. El razonamiento viene de tres capas conectadas: conocimiento (lo que se sabe), agentes (quién razona), y skills (el flujo que siguen). Así es como una etapa se convierte en pensamiento experto, antes de que la máquina imponga algo.
2.1Las cinco capas
Todo en core/ se organiza en cinco capas. La frontera entre ellas es lo que impide que el modelo improvise las partes que deben permanecer determinísticas, mientras lo deja razonar libremente en las que deben serlo.
| Capa | Vive en | Qué contiene |
|---|---|---|
| Reglas / Memoria | memory/ | Guardrails de organización, equipo y proyecto + método por fase. Autoaprendizaje: las correcciones humanas se vuelven reglas persistentes. |
| Agentes | agents/*.md | 14 personas expertas de dominio. Todas llevan disallowedTools: Task, así que solo el conductor delega. |
| Conocimiento | knowledge/ | Referencia de la metodología: compartida (principios, taxonomía de auditoría) y por agente (patrones, pruebas). |
| Skills | skills/aidlc/ | El orquestador SKILL.md, el protocolo de etapa y 32 archivos de etapa en 5 fases. |
| Hooks | hooks/*.ts | La superficie de control (cubierta en La Máquina). |
2.2Cómo se conectan
Cuando el motor dice "ejecuta esta etapa", cuatro capas encajan en el contexto del conductor. La etapa nombra a su agente líder; la persona del agente define la voz; el protocolo de etapa trae el conocimiento; reglas restringen el conjunto. La salida es un artefacto, juzgado en una puerta.
Dos modos de ejecución
Inline: el conductor adopta la persona del agente y hace el trabajo en contexto (la mayoría de las etapas). Subagente: trabajo pesado y aislado delegado a través de la frontera Task (ingeniería inversa, generación de código).
Una única costura de delegación
Solo el conductor posee Task. Cada agente lleva disallowedTools: Task, así que ningún agente crea sus propios subagentes. La delegación es una puerta única y controlada.
2.3Los agentes
14 archivos: 11 personas expertas de dominio que lideran o apoyan etapas, 2 agentes de solo revisión que desafían en la puerta, y 1 compositor de flujo adaptativo.
Product
líder
intención, historias, alcance
Design
líder
mockups, UX
Architect
líder
viabilidad, diseño de app + NFR
AWS Platform
líder
infraestructura, aprovisionamiento
Developer
líder
ingeniería inversa, generación de código
DevSecOps
apoyo
modelo de amenazas, diseño seguro
Compliance
apoyo
GRC, clasificación de datos
Delivery
líder
equipo, planificación, handoff
Pipeline / Deploy
líder
CI/CD, releases
Operations
líder
observabilidad, incidentes
Quality
líder
build y pruebas
Architecture Reviewer
solo revisión
desafía el diseño en la puerta
Product Lead
solo revisión
la voz del cliente en la puerta
Composer
adaptativo
arma un plan de etapas a medida
2.4Reglas de autoaprendizaje
La capa de memoria no es estática. Cuando un humano corrige el flujo, esa corrección puede volverse una regla persistente a nivel de organización, equipo o proyecto, para que el mismo error no se repita en la siguiente ejecución. El conocimiento es referencia; las reglas son restricciones aprendidas.
org.md
valores por defecto del framework
team.md
prácticas afirmadas
project.md
sobrescrituras del proyecto
phases/*.md
método por fase
El Trabajo
Empieza por la salida, ya que todo lo demás existe para producirla. 32 etapas en 5 fases forman el grafo completo; un scope lo colapsa a la forma correcta para la tarea; puertas, presencia, y la autonomía acotada controlan cuánto permanece un humano en el bucle.
1.1Fases y etapas
El motor recorre 32 etapas en orden de grafo, con puertas entre ellas. Dos se ejecutan como subagentes delegados (pesadas, aisladas); el resto se ejecuta inline en la voz del conductor.
1.2Tipos de flujo: un grafo, muchas formas
El mismo grafo de 32 etapas colapsa a la forma correcta para la tarea. Un scope marca cada etapa como EXECUTE o SKIP, así un bugfix no es arrastrado por investigación de mercado y un PoC omite operaciones. Las etapas omitidas permanecen en el grafo (el doctor aún las valida), solo no se ejecutan. Haz clic en un alcance para ver su forma.
Y es adaptativo
Los nueve alcances nombrados son puntos de partida, no un menú fijo. El composer (un agente) lee tu tarea real, o un escaneo de un código existente, y crea una cuadrícula personalizada de EXECUTE/SKIP cuando ningún preset encaja. Así la forma del flujo se elige por tarea, no se fuerza a una plantilla. Un bugfix de un archivo ejecuta 7 etapas; un producto greenfield completo ejecuta las 32; cualquier cosa intermedia es un alcance nombrado o uno que el composer arma en el momento.
1.3Qué tan cerca permanece un humano en el bucle
Este es el verdadero control. Cuatro mecanismos mantienen a un modelo no determinístico produciendo un proceso determinístico y auditable, y el humano decide cuánta holgura darle.
GATE Aprobación entre etapas
El motor emite una gate en cada frontera. El flujo no puede avanzar hasta que un humano apruebe o pida una revisión. La puerta nombra la próxima etapa real, no una suposición.
PRESENCIA Prueba de que un humano estuvo aquí
El mint-presence hook registra cada turno humano. La aprobación de la puerta lo verifica, y una aprobación sin turno humano desde que la puerta se abrió es rechazada. Cierra las trampas del sello automático y del abandono.
AUDITORÍA Cada transición es un evento
Los cambios de estado fluyen por herramientas que anexan a una traza de solo anexado. La taxonomía es canónica y probada contra desvíos. Una ejecución se reproduce y explica solo desde los shards.
SENSORES Verificación determinística
Después de que una etapa escribe, los sensores se disparan: secciones requeridas presentes, upstream cubierto, lint + tipos limpios. Verificaciones de máquina junto al juicio del modelo.
La autonomía es opt-in y acotada
Construcción puede ejecutar un swarm, trabajo paralelo por unidad en worktrees git aisladas, pero solo después de que un humano establece explícitamente la autonomía en autonomous. Aun así, el árbitro de convergencia (aidlc-bolt) es dueño del veredicto: un lote solo vuelve al merge si está verde e íntegro. Los verbos que remodelan el plan (recompose, scope-change) son rechazados bajo autonomía, ya que no hay humano en la puerta para aprobar una nueva forma. Cambia a gated y el humano vuelve a estar en cada puerta.
Los Controles
Ningún comportamiento está fijo en el código. En qué modelo corre cada agente, cuánto razona, hacia dónde apunta en Bedrock, cuánto permanece un humano en el bucle: todo es configuración que el cliente controla. Costo y rigor son ajustes, no cambios de código.
4.1settings.json, el panel de control
La distribución de Claude Code incluye un settings.json que el cliente copia y edita. Contiene cuatro cosas que importan: dónde se resuelven los modelos, el modelo de la sesión, el esfuerzo de razonamiento y los registros de hooks (cubiertos en La Máquina).
[1m] es el sufijo de la variante de contexto de 1 millón de tokens, un sabor más caro de cada modelo. Quitarlo (usando la ventana estándar) reduce el costo sin cambiar de nivel, siempre que los artefactos quepan.4.2Selección de modelo: niveles, no IDs de modelo
Los agentes nunca nombran un modelo concreto. Nombran un nivel (opus, sonnet, haiku, fable) y el bloque env resuelve cada nivel a un ID real de modelo de Bedrock. Cambia una línea en env y todo agente en ese nivel se mueve, sin tocar un solo archivo de agente.
La política por defecto es 9 agentes en Opus, 5 en Sonnet: el trabajo más pesado de diseño y build en Opus, revisión y coordinación en Sonnet.
| Nivel | Agentes |
|---|---|
opus ×9 | architect, aws-platform, product, design, developer, devsecops, compliance, quality, composer |
sonnet ×5 | architecture-reviewer, product-lead, delivery, pipeline-deploy, operations |
model: en el frontmatter del agente. Una grafía antigua (modelOverride:) era ignorada silenciosamente por Claude Code, así que los niveles no se aplicaban. Eso ya está corregido, y la política por defecto Opus/Sonnet se respeta.4.3Las palancas de costo y rigor
Tres controles mueven el costo, de lo quirúrgico a lo contundente. Todos son ediciones de configuración, sin código.
Modelo de la sesión
"model": "opus[1m]" → "sonnet[1m]". Baja el orquestador + cada etapa inline a un nivel más barato. La palanca más grande.
Nivel de esfuerzo
"effortLevel": "xhigh" → high / medium. Recorta tokens de razonamiento en todo. Un motor de costo tan fuerte como el modelo.
Nivel por agente
Edita el model:de un agente, o reapunta un nivel completo en env. Quirúrgico: mantén fuertes a los revisores, lleva a los agentes de apoyo a algo más barato.
[1m] por la ventana estándar, o reapunta OPUS a un ID de Sonnet para correr agentes "opus" en Sonnet globalmente sin editar ningún agente.4.4Flags de comportamiento y entorno
Más allá de los modelos, las variables de entorno ajustan de dónde lee el motor sus piezas y qué tan estrictas son las guardas. Algunas que vale la pena conocer:
| Flag | Efecto |
|---|---|
AWS_AIDLC_DEFAULT_SCOPE | El alcance en que empieza un flujo nuevo (por defecto: workshop). |
CLAUDE_CODE_USE_BEDROCK / AWS_REGION | Enruta a Bedrock y elige la región. |
AIDLC_USE_SWARM | Habilita la ruta de swarm autónomo de Construcción. |
AIDLC_SKIP_HUMAN_PRESENCE_GUARD | Válvula de escape solo para pruebas de la verificación de presencia. Nunca para ejecuciones reales. |
AIDLC_*_DIR (etapas, reglas, sensores, …) | Apunta el motor a árboles de código alternativos. Así el harness se mantiene reubicable y testeable. |
Los Verbos
Realmente hay una sola puerta: /aidlc. No escribas nada y descubre qué hacer a continuación; escribe una flag y salta, reanuda o remodela. Las skills de etapa son atajos de conveniencia sobre la misma puerta. Todo lo de abajo es lo que un usuario realmente escribe.
5.1La puerta única
La mayor parte del tiempo solo describes lo que quieres, o escribes /aidlc sin argumento, y el motor decide el próximo movimiento. Las flags son para cuando quieres dirigir.
| Comando | Qué hace |
|---|---|
/aidlc "construye el servicio de autenticación" | Describe el trabajo en palabras simples. El motor detecta el alcance automáticamente e inicia el flujo. |
/aidlc | Sin argumento: ejecuta el próximo movimiento que el motor nombre. Es el "sigue adelante" de todos los días. |
/aidlc --resume | Retoma un flujo estacionado. El motor limpia el marcador de estacionamiento y continúa donde se detuvo. |
/aidlc --status | Solo lectura. Muestra fase, etapa, puerta actuales y qué está bloqueando el flujo. No cambia nada. |
/aidlc --help | Todos los comandos y alcances. |
/aidlc --version | La versión del framework. |
5.2Dirigiendo el plan
Estos cambian dónde está el flujo o qué forma tiene. Los saltos mueven el cursor; alcance y profundidad remodelan la ejecución. Bajo Construcción autónoma los verbos que remodelan el plan son rechazados (sin humano en la puerta).
| Comando | Qué hace |
|---|---|
/aidlc --stage <id> | Salta a una etapa por slug o número (code-generation o 3.5). |
/aidlc --phase <name> | Salta a la primera etapa dentro del alcance de una fase (construction o 3). |
/aidlc --scope <scope> | Establece o cambia el alcance. Solo, o combinado con --stage/--phase. |
/aidlc --depth <level> | Sobrescribe la profundidad: minimal, standard, o comprehensive. |
/aidlc compose "<task>" | Pide al composer crear una cuadrícula personalizada de EXECUTE/SKIP cuando ningún preset encaja. Él propone; tú apruebas en una puerta. |
recompose --skip <a,b> --add <c> (verbo del motor) | Alterna etapas pendientes entre EXECUTE/SKIP en un flujo en ejecución. Validado estrictamente, auditado como RECOMPOSED. Se accede a través de la puerta de composición, no se ejecuta a mano. |
park (verbo del motor) | Se detiene limpiamente en una frontera entre etapas para una sesión futura. Reanuda con --resume. |
recompose, park) tú mismo. El conductor los ejecuta cuando la directiva del motor los nombra; están listados para que la traza de auditoría y el flujo de remodelación tengan sentido.5.3Espacios e intenciones
A espacio es un contexto de memoria (reglas de organización/equipo/proyecto); una intent es una cosa que estás construyendo dentro de él. Puedes tener varias intenciones en un espacio y alternar entre ellas.
| Comando | Qué hace |
|---|---|
/aidlc space | Lista espacios, o cambia a uno. |
/aidlc space-create <name> | Crea un espacio. Siembra sus propias memory/ (organización, equipo, proyecto, fases) copiadas del predeterminado. |
/aidlc intent | Lista intenciones en el espacio activo, o cambia la intención activa. |
5.4Inspección y salud
Lentes de solo lectura. Ninguna muta el estado del flujo ni emite eventos de auditoría.
| Comando | Qué hace |
|---|---|
/aidlc --doctor | Chequeo de salud de hooks, configuración, estructura de directorios y caídas de hooks registradas. |
/aidlc --detect | Escanea el workspace (greenfield vs brownfield, lenguajes, proyectos anidados, submódulos). |
/aidlc replay (skill) | Una narrativa de la sesión para stakeholders, desde la traza de auditoría. Solo terminal, no escribe nada. |
/aidlc session-cost (skill) | Agregados determinísticos: duración, resultados de etapas, disparos de sensores, aprendizajes capturados. |
/aidlc outcomes-pack (skill) | Un documento de traspaso al cierre del flujo. Escribe OUTCOMES.md, nunca toca el estado. |
5.5Skills — atajos sobre la misma puerta
Las skills son conveniencias tipadas. Una skill de alcance incorpora un alcance para que omitas la detección; una skill de etapa única ejecuta una etapa aislada sin avanzar el flujo principal. Cada una es empaquetado sobre un comando /aidlc que también funciona por sí solo.
Skills de alcance
/aidlc-feature, -mvp, -bugfix, -security-patch. Lo mismo que /aidlc --scope <x>, sin paso de detección.
Skills de etapa única
/aidlc-code-generation, -functional-design, y una por etapa. Ejecuta --stage <x> --single: la etapa más su puerta, y luego se detiene. El cursor del flujo principal nunca se toca.
Skills de sesión
/aidlc-init, -compose, -replay, -session-cost, -outcomes-pack. Auxiliares de ciclo de vida alrededor de una ejecución.
/aidlc command.