YGGDRASIL CLI

Deterministic governance engine for AI coding agents. Enforcement over suggestion.

Que es YGGDRASIL

YGGDRASIL es un motor de gobernanza que controla como los agentes IA escriben codigo. No sugiere buenas practicas — las impone. Si el agente intenta saltarse un paso (editar codigo sin haber pasado por discuss y plan, ejecutar rm -rf, hardcodear un secret), el sistema bloquea la operacion a nivel de sistema operativo con exit 2. El agente no recibe una advertencia — recibe un deny que no puede ignorar.

Nacio de una realidad simple: la IA sin proceso riguroso produce codigo que parece funcionar pero falla en produccion. Un agente sin restricciones genera codigo sin tests, sin validacion de seguridad, sin estructura, y el desarrollador acepta porque "funciona en local." YGGDRASIL cierra ese gap.

El Problema que Resuelve

Sin gobernanza, el desarrollo con IA funciona asi:

1. Le pides al agente que implemente una feature
2. El agente genera codigo que compila y parece correcto
3. No hay tests, o los tests no cubren edge cases
4. No hay revision de seguridad
5. No hay validacion contra los requisitos originales
6. El dev acepta el PR porque "funciona"
7. En produccion, el codigo falla con datos reales, input malicioso, o carga concurrente

Este patron se repite porque el agente optimiza para velocidad, no para calidad. Y el desarrollador no tiene herramientas para forzar un proceso sin depender de su propia disciplina.

Con YGGDRASIL, el agente DEBE seguir un proceso de 13 fases con 18 gates obligatorios. Cada fase tiene condiciones de entrada y salida. Si no se cumple un gate, no avanzas. No hay atajos. El enforcement es a nivel de OS — no se puede saltear ni ignorar.

Filosofia

Enforcement over suggestion

YGGDRASIL no es un linter que avisa. Es un sistema que bloquea. Los hooks usan exit 2 a nivel de shell — un hard deny que Claude Code no puede ignorar. Si estas en fase discuss, no puedes editar codigo fuente. Si no has pasado por testsGreen, no puedes entrar a review. Sin excepciones.

Deterministic state machine

Cada fase tiene gates de entrada y salida definidos en mapas declarativos. No hay ambiguedad sobre que viene despues ni que condiciones se necesitan. El estado vive en state.json, que solo se modifica via comandos CLI validados — la IA nunca lo edita directamente.

Learning loop

Los errores se convierten en reglas que bloquean activamente en el futuro. Un error detectado en retro se transforma en una regla hard (enforcement a nivel OS, zero tokens) o soft (contexto inyectado por fase y dominio). Los errores del proyecto 1 se convierten en bloqueos activos para el proyecto 2. El sistema aprende y se vuelve mas estricto con cada ciclo.

Como Funciona

El State Machine

idle ─> domain ─> discuss ─> research ─> plan ─> spec ─> build ─> review ─> verify ─> mutate ─> validate ─> retro ─> ship ─> idle

stateDiagram-v2
    [*] --> idle
    idle --> domain
    idle --> discuss
    domain --> discuss
    discuss --> research
    discuss --> plan
    research --> plan
    plan --> spec
    plan --> build
    spec --> build
    build --> review
    review --> verify
    verify --> mutate
    verify --> retro
    mutate --> validate
    validate --> retro
    retro --> ship
    ship --> idle
    idle --> [*]

Cada transicion de fase requiere que ciertos gates esten en passed o skipped. Sin gate passed, no avanzas. Los gates se marcan automaticamente al completar fases o manualmente con ygg gate:pass.

Gates (18 total)

| Gate | Que valida | Cuando se evalua | |------|-----------|-----------------| | domainModel | DOMAIN.md completo con DDD Event Storming | domain → discuss | | brainstorm | 7 rondas de brainstorm completadas | discuss → plan | | contextReady | CONTEXT.md generado con Architecture Checklist | discuss → plan | | researchComplete | Investigacion tecnica con subagente completada | research → plan | | planApproved | Plan de micro-tareas TDD revisado y aprobado | plan → build | | planChecked | Plan validado por plan-checker agent | plan → build | | acceptanceSpecs | Especificacion de aceptacion en Gherkin | spec → build | | testsRed | Tests escritos antes del codigo (TDD red phase) | build → review | | testsGreen | Todos los tests pasan | build → review | | refactored | Codigo refactorizado post-green | build → review | | reviewed | Code review 3 pasadas (quality + security + checks) | review → verify | | verified | Verificacion 4 niveles (tests, TS, BDD, UAT) | verify → retro | | mutationTested | Mutation testing con Stryker (break threshold 72%) | mutate → validate | | validated | Spec compliance check — BDD scenarios vs tests | validate → retro | | mjolnirClear | Security checks MJOLNIR pasados | review | | depsAuditClear | 0 dependencias con vulnerabilidades HIGH/CRITICAL | build → review | | semgrepClear | 0 vulnerabilidades severity ERROR en analisis estatico | build → review | | retroDone | Retrospectiva completada con AI_MISTAKES.md actualizado | retro → ship |

Modos de Ejecucion (6)

| Modo | Fases que ejecuta | Uso | |------|-------------------|-----| | full | Todas las 13 fases | Feature completa con maximo rigor | | standard | Salta domain, spec, mutate, validate | Feature normal — equilibrio entre rigor y velocidad | | quick | Salta domain, research, spec, mutate, validate | Fixes pequenos y cambios menores | | hotfix | Solo build → review → ship | Emergencias en produccion | | lab | Solo discuss → plan → build | Experimentacion libre | | improve | Solo discuss → plan → build → review | Refactoring y mejoras incrementales |

Cada modo define sus propios gates minimos para ship. En modo full, los 18 gates deben pasar. En modo hotfix, solo testsGreen, reviewed, y retroDone.

Hooks (Enforcement Real)

Los hooks son comandos CLI en TypeScript que se ejecutan automaticamente por Claude Code. Usan exit 2 a nivel de shell para bloquear operaciones — no es un warning, es un hard deny que el agente no puede ignorar. Cuestan zero tokens — se ejecutan fuera de la ventana de contexto.

| Hook | Evento | Que hace | |------|--------|---------| | ygg hook:session-start | SessionStart | Briefing + soft rules injection + domain risk warnings | | ygg hook:pre-edit | PreToolUse (Write/Edit) | Phase guards + TDD enforcement + secrets firewall (15 patterns) + state.json protection + hard rules | | ygg hook:bash-firewall | PreToolUse (Bash) | Bloquea comandos destructivos (rm -rf, DROP TABLE, git push --force, netcat, curl @file, find -delete, fork bombs) + hard rules | | ygg hook:post-tool | PostToolUse | Context monitor — tracking de tokens consumidos |

Secrets Firewall: Detecta secrets hardcodeados en write-time (no en ship-time). 15 pattern types: AWS keys, JWT tokens, Stripe keys, GitHub tokens, private keys, connection strings, passwords, y mas. Si escribes un secret, se bloquea inmediatamente.

Bash Firewall: Protegido contra ReDoS. Cobertura de exfiltration (netcat, curl @file). Flags separados detectados (rm -r -f). Multiline aware.

Learning Loop

El ciclo completo:

Error detectado en retro
    → Regla creada con `ygg retro:rule add`
        → Regla activa en futuras sesiones (hard o soft)
            → El mismo error nunca se repite

Hard rules — Se evaluan en TypeScript (zero tokens). El trigger es un regex que se evalua contra el path del archivo (pre-edit) o el comando bash (firewall). Si hay match, exit 2. Fail-closed: si rules.json no parsea, bloquea.

Soft rules — Se inyectan como contexto dinamico cuando son relevantes. Filtradas por fase y dominio. Se cargan en session-start y en transiciones mid-session. Fail-open: si rules.json no parsea, continua.

Las reglas nacen SOLO de ygg retro:rule add — siempre de un error real documentado, nunca inventadas en frio.

Cross-project learning: ~/.yggdrasil/global-mistakes.md acumula errores de todos los proyectos. Se inyecta automaticamente en cada sesion. Los errores del proyecto 1 protegen al proyecto 5.

Instalacion y Setup

npm install @raw_context/yggdrasil-cli

Requisitos

• Node.js >= 18.0.0
• TypeScript strict mode
• Claude Code (funciona en Antigravity o terminal directa)

Inicializar un proyecto

npx ygg init

El comando init es interactivo. Pregunta:

1. Nombre del proyecto
2. Stack Next.js + Supabase + Tailwind? — Si aceptas, inyecta reglas especificas del stack en CLAUDE.md (App Router, RLS, dual Supabase clients, PKCE, Tailwind mobile-first, Vercel)
3. Frontend Premium Rules? — Reglas opinionadas para webs de agencia: Lenis smooth scroll, GSAP con ScrollTrigger, tipografia premium (Satoshi/DM Sans + Playfair/Cormorant), spacing con clamp(), performance targets (LCP < 2.5s, bundle < 200KB)

Que genera ygg init

proyecto/
├── CLAUDE.md                        # Instrucciones para Claude Code
├── .yggdrasil/
│   ├── state.json                   # Estado persistente (solo CLI lo modifica)
│   ├── commands/                    # 14 archivos .md con instrucciones por fase
│   │   ├── discuss.md               # 7 rondas + BDD + Architecture Checklist
│   │   ├── plan.md                  # Micro-tareas TDD con DAG
│   │   ├── build.md                 # TDD estricto per-task
│   │   ├── review.md               # Subagentes Opus (quality + security)
│   │   ├── verify.md               # 4 niveles de verificacion
│   │   ├── retro.md                # 5 secciones + Learning Loop
│   │   ├── ship.md                 # Checklist de entrega
│   │   └── ...                     # domain, research, spec, quick, hotfix, etc.
│   └── docs/
│       ├── DOMAIN.md                # Modelo de dominio (DDD)
│       ├── SCENARIOS.md             # Escenarios BDD
│       ├── AI_MISTAKES.md           # Errores conocidos de la IA
│       └── memory.md               # Patrones reutilizables
├── .claude/
│   ├── settings.json                # Configuracion de hooks
│   ├── hooks/                       # Enforcement hooks (delegados a CLI TypeScript)
│   └── agents/                      # 5 subagentes especializados
│       ├── brainstorm-challenger.md # CTO esceptico (Opus)
│       ├── code-reviewer.md         # Quality review (Opus)
│       ├── security-reviewer.md     # Security audit 3 fases (Opus)
│       ├── research-agent.md        # Investigacion codebase (Sonnet)
│       └── plan-checker-agent.md    # Validacion del plan (Sonnet)
└── yggdrasil.config.ts              # Config del stack

Si el proyecto ya tiene CLAUDE.md, el init hace merge inteligente — preserva el contenido existente y anade las secciones de YGGDRASIL.

Comandos

Slash Commands (Claude Code Skills)

Estos comandos se usan directamente en la conversacion con Claude Code:

| Comando | Que hace | |---------|---------| | /ygg-discuss | Inicia fase discuss — 7 rondas socraticas + BDD + Architecture Checklist | | /ygg-plan | Inicia fase plan — micro-tareas TDD con DAG y dependencias | | /ygg-build | Inicia fase build — TDD per-task por waves paralelas | | /ygg-review | Inicia fase review — subagentes Opus (quality + security) | | /ygg-verify | Inicia fase verify — 4 niveles de verificacion | | /ygg-retro | Inicia fase retro — retrospectiva + Learning Loop | | /ygg-ship | Inicia fase ship — checklist de entrega | | /ygg-quick | Modo quick — para fixes pequenos | | /ygg-hotfix | Modo hotfix — emergencias en produccion | | /ygg-status | Muestra estado actual del workflow | | /ygg-phase-next | Avanza a la siguiente fase | | /ygg-init | Inicializa YGGDRASIL en un proyecto |

CLI Commands

Estos comandos se ejecutan desde terminal o desde los hooks:

| Comando | Descripcion | |---------|-------------| | ygg init | Inicializa proyecto con scaffolding completo | | ygg status | Muestra fase actual, gates, modo, progreso | | ygg resume | Resume sesion con contexto previo | | ygg phase:next <phase> | Transiciona a la siguiente fase (valida gates) | | ygg phase:complete [desc] | Completa la fase actual y marca gates | | ygg gate:pass <gate> | Marca un gate como passed (valida fase actual) | | ygg check-edit <file> | Verifica si un archivo puede editarse en la fase actual | | ygg plan:check | Valida coherencia del plan con plan-checker agent | | ygg build:waves | Calcula waves paralelas con DAG (Kahn's algorithm) | | ygg build:task-start <id> | Inicia una tarea de build | | ygg build:task-done <id> | Completa una tarea de build | | ygg validate | Spec compliance — verifica BDD scenarios vs tests | | ygg domain:validate | Valida DOMAIN.md (DDD Event Storming) | | ygg analytics | Dashboard de metricas del workflow | | ygg retro:rule add | Crea regla del Learning Loop desde error de retro | | ygg retro:push-global | Sincroniza errores locales al global cross-project | | ygg semgrep:scan | Ejecuta analisis estatico con Semgrep | | ygg deps:audit | Ejecuta auditoria de dependencias | | ygg mjolnir:scan | Security scan dinamico (headers, HTTPS, secrets, RLS, deps) | | ygg context:track | Registra consumo de tokens de un tool call | | ygg context:check-read | Verifica si se puede leer un archivo (context budget) | | ygg context:status | Muestra estado del context monitor | | ygg session:prepare | Prepara contexto para una sesion nueva | | ygg install:skills | Instala los 12 slash commands como skills de Claude Code | | ygg rollback | Rollback al snapshot de estado anterior | | ygg hook:session-start | Hook de inicio de sesion (usado por Claude Code) | | ygg hook:pre-edit | Hook de pre-edicion (usado por Claude Code) | | ygg hook:bash-firewall | Hook de firewall bash (usado por Claude Code) | | ygg hook:post-tool | Hook post-tool (usado por Claude Code) |

Architecture Checklist (v1.2.0)

La fase discuss incluye una ronda obligatoria de arquitectura (Ronda 4) con 7 preguntas que DEBEN responderse antes de poder avanzar a plan:

1. Usuarios concurrentes — ¿Cuantos esperamos? (10? 100? 10.000?)
2. Datos sensibles / PII — ¿Hay datos sensibles? ¿Que tipo?
3. Fallo de servicios externos — ¿Que pasa si un servicio externo cae? (fallback, retry, degradacion graceful)
4. Estrategia de escalado — ¿Como se escala? (horizontal, vertical, cache, CDN)
5. Modelo de autenticacion — ¿Se necesita auth? ¿Que modelo? (roles, permisos, JWT, sessions)
6. Rate limiting — ¿Se necesita? ¿Donde? (API, auth, uploads)
7. Multi-tenancy — ¿Es multi-tenant? ¿Como se aislan los datos?

Si el usuario dice "no aplica" a alguna pregunta, se documenta explicitamente como N/A — [razon] en el checklist. No se deja en blanco.

Las respuestas se guardan en la seccion Architecture Checklist de CONTEXT.md. El gate contextReady no pasa hasta que las 7 preguntas esten respondidas. Esto asegura que el desarrollador piensa en escalabilidad, seguridad, y resiliencia ANTES de escribir una sola linea de codigo.

Security Gates (v1.2.0)

Semgrep Gate (semgrepClear)

Analisis estatico deterministico como primera capa antes del LLM review. Semgrep no alucina — encuentra patterns reales.

ygg semgrep:scan

• Rulesets: p/default, p/security-audit, p/owasp-top-ten
• Bloquea: severity ERROR (cualquier match = gate fail)
• Permite: severity WARNING e INFO (se documentan pero no bloquean)
• Reportes en .yggdrasil/reports/

Dependency Audit Gate (depsAuditClear)

Auditoria de dependencias contra vulnerabilidades conocidas.

ygg deps:audit

• Bloquea: vulnerabilidades HIGH y CRITICAL
• Permite: LOW y MODERATE (se documentan)
• Reportes en .yggdrasil/reports/

Ambos gates son requisito para entrar en fase review. Defense in depth: Semgrep (deterministico, zero tokens) + security-reviewer Opus (razonamiento profundo) = dos capas complementarias.

Herramientas Complementarias

WARDSTONES

4 skills de auditoria independiente, cada uno enfocado en una dimension. Scoring 0-10 con delta tracking:

| Skill | Dimension | Que audita | |-------|-----------|-----------| | MIMIR | Calidad | Build, tests, analisis estatico, arquitectura | | HEIMDALL | Seguridad | Secrets, deps, auth, headers, input validation, OWASP Top 10 | | BALDR | Frontend | WCAG, tipografia, imagenes, responsive, Core Web Vitals, animaciones | | FORSETI | DX | Onboarding, documentacion, CI/CD, error handling, contributor readiness |

MJOLNIR Lite

3 checks de seguridad dinamicos integrados como gate en YGGDRASIL:

• Security headers y HTTPS enforcement
• Secrets scanning (runtime)
• Dependency vulnerability check

Genera reporte en .yggdrasil/mjolnir-report.md. Exit 1 si hay findings critical/high.

Ejemplo de Workflow Completo

Walkthrough de una feature nueva en modo full:

1. Preparar sesion

ygg session:prepare

Genera session-context.md con estado actual, errores conocidos, y reglas activas.

2. Discuss (7 rondas)

/ygg-discuss

• Ronda 1 — Alcance y usuarios
• Ronda 2 — Diseno y experiencia visual (skip automatico si no hay UI)
• Ronda 3 — Edge cases y riesgos
• Ronda 4 — Architecture Checklist (7 preguntas obligatorias)
• Ronda 5 — Seguridad y datos
• Ronda 6 — Criterios de exito
• Ronda 7 — Abogado del diablo (subagente Opus challenger)

Genera: CONTEXT.md (con Architecture Checklist) + SCENARIOS.md (escenarios BDD en Gherkin). Gates: brainstorm ✅ + contextReady ✅

3. Research

/ygg-phase-next research

Subagente Sonnet investiga el codebase y dependencias relevantes. Gate: researchComplete ✅

4. Plan

/ygg-plan

Genera plan de micro-tareas TDD con DAG de dependencias. Plan-checker agent valida coherencia contra CONTEXT.md y RESEARCH.md. Gates: planApproved ✅ + planChecked ✅

5. Build (TDD per-task por waves)

/ygg-build

Tareas organizadas en waves paralelas (Kahn's algorithm). Cada tarea sigue el ciclo: test red → implementacion → test green → refactor. El hook TDD bloquea edicion de source code sin test editado primero. Gates: testsRed ✅ + testsGreen ✅ + refactored ✅

6. Security gates

ygg semgrep:scan     # 0 errors → semgrepClear ✅
ygg deps:audit       # 0 high/critical → depsAuditClear ✅

7. Review

/ygg-review

3 pasadas con subagentes Opus en contexto limpio (sin sesgo del build):

• Quality review — cruza con AI_MISTAKES.md + design consistency check
• Security review — pipeline 3 fases: mapeo → hipotesis → verificacion con evidencia (file:line + explotabilidad)
• Checks automaticos

Gate: reviewed ✅

8. Verify → Retro → Ship

/ygg-verify     # 4 niveles: tests, tsc --noEmit, BDD scenarios, UAT → verified ✅
/ygg-retro      # Retrospectiva + AI_MISTAKES.md + reglas Learning Loop → retroDone ✅
/ygg-ship       # Checklist de entrega ejecutado linea por linea → idle

El Learning Loop captura cualquier error del proceso y lo convierte en regla activa para la proxima feature.

Stats

| Metrica | Valor | |---------|-------| | Tests | 991 | | Archivos de test | 64 | | Gates | 18 | | Fases | 13 | | Modos de ejecucion | 6 | | LOC (source, sin tests) | ~10.800 | | Runtime dependencies | 7 | | Slash commands | 12 | | CLI commands | 29 | | Subagentes | 5 (3 Opus + 2 Sonnet) | | Hooks | 4 | | Secrets patterns | 15 | | TypeScript | strict, zero any | | I/O | Atomic writes (tmp + rename) en todo JSON critico | | Overhead de tokens | ~3.8% de la ventana util | | Auditorias independientes | 7 (4 code review + 3 E2E) | | Bypass attempts bloqueados | 10/10 (red team audit) | | Nota de auditoria | 8.2–8.75/10 | | Security warnings | 0 | | Veredicto final | GO — production ready, 0 blockers, 0 warnings |

Desarrollo

npm install          # Instalar dependencias
npm run build        # Compilar TypeScript
npm test             # Ejecutar 991 tests (Vitest)
npm run test:watch   # Tests en modo watch
npm run test:mutate  # Mutation testing (Stryker)
npm run dev          # TypeScript watch mode

Licencia

ISC

v1.2.0 — Semgrep gate, Dependency Audit gate, Architecture Checklist, 991 tests, 18 gates, production ready.

Jofre Atanet · Barcelona · 2026