Multi-Agent Orchestration

Multi-Agent Orchestration Patterns Guide

Companion del AI-First Engineering Framework v6.5

Version: 2.0.0 | Fecha: Marzo 2026 Fuentes: Anthropic Trends (2026), MachineLearningMastery “7 Agentic Trends” (Ene 2026), GuruSup Multi-Agent Comparison (Mar 2026), Turing “6 Frameworks” (Feb 2026), Google ADK (Dic 2025), OpenAI “Harness Engineering” (Feb 2026)

1. De Agente Único a Equipos de Agentes

“Single agents evolve into coordinated teams” — Anthropic, Trend #2 (2026)

1.1 Cuándo Usar Multi-Agent

Señal	Agente Único	Multi-Agent
Tarea dura < 15 min	✅	Overkill
Tarea cruza > 2 dominios	Pierde contexto	✅
Output necesita review especializado	Posible	✅ Más fiable
Paralelismo posible	No	✅ N tareas simultáneas
Context window > 80% lleno	Degrada	✅ Contextos frescos
Tarea > 1 hora	Compaction frecuente	✅ Sub-agents con scope

1.2 Patrones de Orquestación

PATRON 1: ORCHESTRATOR → WORKERS (Hub & Spoke)
┌──────────────┐
│ Orchestrator  │ ← Plan + Synthesize
│   (Lead)      │
└──┬───┬───┬───┘
   │   │   │
   ▼   ▼   ▼
┌──┐ ┌──┐ ┌──┐
│W1│ │W2│ │W3│  ← Implement tasks in parallel
└──┘ └──┘ └──┘

PATRON 2: PIPELINE (Sequential Handoff)
┌──────┐   ┌──────┐   ┌──────┐   ┌──────┐
│ Spec │──►│ Plan │──►│Build │──►│Review│
│Agent │   │Agent │   │Agent │   │Agent │
└──────┘   └──────┘   └──────┘   └──────┘

PATRON 3: REVIEW LOOP (Build + Critique)
┌──────────┐    code    ┌──────────┐
│  Builder  │──────────►│ Reviewer  │
│  Agent    │◄──────────│  Agent    │
└──────────┘  feedback  └──────────┘
     │ (iterate until approved)
     ▼
  ✅ Merge

PATRON 4: SPECIALIST SWARM
┌──────────────┐
│ Coordinator   │
└──┬───┬───┬───┘
   │   │   │
   ▼   ▼   ▼
┌────┐┌────┐┌────┐
│Arch││ QA ││Sec │  ← Each reviews same artifact
└────┘└────┘└────┘
   │   │   │
   ▼   ▼   ▼
┌──────────────┐
│   Merge      │ ← Synthesize all feedback
└──────────────┘

2. Agents del Framework

2.1 Catálogo

ID	Agent	Rol	Invocación	Context Scope
AG-01	@architect	Review arquitectura, ADRs, stack, AI partition	F04, F05	ADRs + config + code structure
AG-02	@qa_engineer	Tests, coverage, spec verification	F07	Tests + specs + code
AG-03	@security_reviewer	Security, compliance, PII, OWASP	F08	Full code + deps + infra
AG-04	@spec_writer	Genera/refina specifications	F01, F05	Requirements + domain docs
AG-05	@code_reviewer	Review de código AI-generated	F06	PR diff + guidelines
AG-06	@ops_engineer	Deploy, monitoring, incident response	F09	Infra config + logs

2.2 Nuevos Agents Recomendados

.claude/agents/spec_writer.md

# @spec_writer Agent

## Role
Generate and refine specifications from requirements.
Translate business intent into unambiguous technical specs.

## Capabilities
- Convert PRD/RFC into structured spec.md
- Generate OpenAPI specs from natural language
- Create Given/When/Then scenarios
- Identify ambiguities and ask clarifying questions

## Instructions
- Always use domain ubiquitous language
- Specs must be deterministic (no ambiguity)
- Include edge cases and error scenarios
- Reference existing ADRs for architectural constraints
- Output format: markdown with YAML code blocks

## Boundaries
- Do NOT write implementation code
- Do NOT make architecture decisions (defer to @architect)
- Always flag assumptions explicitly

.claude/agents/code_reviewer.md

# @code_reviewer Agent

## Role
Review AI-generated code for quality, consistency, and adherence
to project guidelines.

## Capabilities
- Review PRs for style, correctness, and security
- Verify code matches specification
- Check for common AI-generation anti-patterns
- Suggest improvements with specific code examples

## Review Checklist
1. Does the code match the spec?
2. Are there tests for all new functionality?
3. Does it follow project conventions (CLAUDE.md)?
4. Any security issues (injection, auth bypass, data leak)?
5. Is error handling comprehensive?
6. Are there AI hallucination artifacts (fake imports, non-existent APIs)?
7. Is the code maintainable by humans?

## Anti-Patterns to Flag
- Duplicate logic (AI often duplicates instead of extracting)
- Inconsistent naming (each generation uses different conventions)
- Over-engineering (AI loves abstractions)
- Missing error handling on happy path
- Fake/hallucinated library usage

3. Coordination Protocols

3.1 Message Contract Between Agents

# Formato estándar de handoff entre agentes
agent_message:
  from: "@architect"
  to: "@qa_engineer"
  type: "task_handoff"  # task_handoff | review_request | feedback | escalation
  timestamp: "2026-03-19T15:00:00Z"
  context:
    phase: "F06_Build"
    task_id: "TASK-042"
    files_involved:
      - src/api/search.ts
      - src/services/embedding.ts
    decisions_made:
      - "Using pgvector for embeddings (ADR-002)"
      - "Batch indexing, not real-time"
  request: |
    Implementation complete for search endpoint.
    Please generate tests covering:
    - Happy path: valid query returns results
    - Edge: empty query, special characters
    - Performance: response < 200ms for 10K docs
  constraints:
    - "Use vitest, not jest"
    - "Mock external embedding API"
    - "Min coverage: 85%"

3.2 Escalation Protocol

Level 0: Agent handles autonomously
  ↓ (agent uncertain OR destructive action)
Level 1: Agent asks lead orchestrator
  ↓ (orchestrator uncertain OR cross-domain impact)
Level 2: Agent asks human for decision
  ↓ (business/legal/ethical decision)
Level 3: Full stop — human takes over

3.3 Conflict Resolution

Cuando dos agentes dan recomendaciones contradictorias:

1. @architect says: “Use microservice for search”
2. @qa_engineer says: “Monolith is more testable”

Resolution: Defer to spec + ADRs. Si no hay ADR, escalar a humano para nueva ADR.

4. Parallel Execution Patterns

4.1 Feature Parallel

# Ejecutar 3 features en paralelo con git worktrees
git worktree add ../feature-auth feature/auth
git worktree add ../feature-search feature/search
git worktree add ../feature-dashboard feature/dashboard

# Cada worktree tiene su propio agente
# Agent 1 en ../feature-auth
# Agent 2 en ../feature-search
# Agent 3 en ../feature-dashboard

# Merge cuando todos terminen
git merge feature/auth feature/search feature/dashboard

4.2 Review Parallel (Specialist Swarm)

# Un PR es revisado por 3 agentes simultáneamente
# Cada uno con diferente skill activada

# Terminal 1: Architecture review
claude --skill /f04_architecture "Review PR #42 for architecture"

# Terminal 2: Security review
claude --skill /f08_security "Review PR #42 for security"

# Terminal 3: Test coverage review
claude --skill /f07_tevv "Review PR #42 test coverage"

# Humano sintetiza los 3 reviews

5. Sub-Agent Context Management

5.1 Context Budget

Cada sub-agent debe operar con contexto mínimo necesario:

Agent	Context necesario	Context prohibido
@architect	ADRs, config, structure	Tests, implementation details
@qa_engineer	Specs, tests, code under test	Infra, deploy config
@security_reviewer	All code, deps, infra config	Business requirements
@spec_writer	Requirements, domain docs	Implementation code
@code_reviewer	PR diff, guidelines, specs	Unrelated code

5.2 Output Compression

Cada sub-agent debe retornar output comprimido:

# Máximo: 1000-2000 tokens de output por sub-agent
output_format:
  summary: "1-2 sentences of overall assessment"
  findings:
    - severity: critical|high|medium|low
      location: "file:line"
      description: "What's wrong"
      suggestion: "How to fix"
  verdict: pass|fail|needs_review
  confidence: 0.0-1.0

6. Implementación Práctica

6.1 Claude Code Multi-Session

# Session 1: Orchestrator crea plan
claude "Read the spec at project/F05_contracts/.openspec/api-search.yaml
and create an implementation plan with 5 tasks.
Save to project/F06_build/plan-search.md"

# Session 2: Builder implementa task 1-3
claude "Read project/F06_build/plan-search.md.
Implement tasks 1-3. Run tests after each task."

# Session 3: Builder implementa task 4-5
claude "Read project/F06_build/plan-search.md.
Tasks 1-3 are done. Implement tasks 4-5."

# Session 4: Reviewer
claude --skill /f07_tevv "Review all changes in src/api/search.ts
against the spec. Check test coverage."

6.2 Automated Multi-Agent Pipeline

scripts/multi-agent-pipeline.py

#!/usr/bin/env python3
"""Pipeline multi-agent automatizado."""
import subprocess
import json

def run_agent(skill: str, prompt: str, timeout: int = 300) -> str:
    """Ejecuta un agente con skill específica."""
    result = subprocess.run(
        ["claude", "--skill", skill, "--output-format", "json", prompt],
        capture_output=True, text=True, timeout=timeout
    )
    return result.stdout

def pipeline(spec_path: str):
    """Pipeline: spec → plan → build → review → approve."""

    # Step 1: Plan
    plan = run_agent("/f04_architecture",
        f"Create implementation plan for {spec_path}")

    # Step 2: Build (can be parallelized)
    build = run_agent("/f06_build",
        f"Implement according to plan. Spec: {spec_path}")

    # Step 3: Parallel Reviews
    reviews = {}
    for skill, focus in [
        ("/f07_tevv", "test coverage and correctness"),
        ("/f08_security", "security vulnerabilities"),
    ]:
        reviews[skill] = run_agent(skill,
            f"Review implementation. Focus: {focus}")

    # Step 4: Synthesize
    all_clear = all("pass" in r.lower() for r in reviews.values())

    if all_clear:
        print("✅ All reviews passed. Ready for human review.")
    else:
        print("⚠️ Issues found. Review needed.")
        for skill, review in reviews.items():
            print(f"\n--- {skill} ---\n{review}")

if __name__ == "__main__":
    import sys
    pipeline(sys.argv[1])

7. Long-Running Agent Workflows

Fuente: Anthropic Agentic Coding Trends Trend #3 (2026) — “Agentes long-running construyen sistemas completos. Horizontes de tareas de minutos a dias.”

7.1 El Problema

Los agentes actuales trabajan bien en sesiones de 15-60 minutos. Pero tareas complejas (migraciones, re-arquitecturas, builds de features grandes) requieren horas o dias de trabajo continuo. Los retos:

• Context window se llena y compaction pierde informacion critica
• El agente pierde coherencia despues de muchas interacciones
• Fallos a mitad de sesion pueden perder horas de trabajo
• Sin checkpoints, no hay forma de revertir parcialmente

7.2 Patron: Checkpoint-Driven Long Session

┌─────────────────────────────────────────────────────────────────┐
│                  LONG-RUNNING SESSION (6h+)                     │
│                                                                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │ Phase 1  │─►│ Phase 2  │─►│ Phase 3  │─►│ Phase N  │       │
│  │ (60 min) │  │ (60 min) │  │ (60 min) │  │ (60 min) │       │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘       │
│       │              │              │              │              │
│   Checkpoint     Checkpoint     Checkpoint     Final            │
│   ┌────────┐    ┌────────┐    ┌────────┐    ┌────────┐         │
│   │ Commit │    │ Commit │    │ Commit │    │ Commit │         │
│   │ HANDOFF│    │ HANDOFF│    │ HANDOFF│    │ PR     │         │
│   │ /compact│   │ /compact│   │ /compact│   │ Report │         │
│   └────────┘    └────────┘    └────────┘    └────────┘         │
└─────────────────────────────────────────────────────────────────┘

7.3 Protocolo de Checkpoints

project/long_session_protocol.yaml

long_session:
  max_phase_duration_min: 60
  checkpoint_trigger:
    - "context_window > 70%"
    - "phase_complete"
    - "error_count > 3"
    - "manual_trigger"

  checkpoint_actions:
    1_commit: "git add -A && git commit -m 'checkpoint: [phase] [summary]'"
    2_handoff: "Write HANDOFF.md with current state"
    3_compact: "Execute /compact preserving key decisions"
    4_verify: "Run smoke tests to confirm checkpoint is stable"

  recovery:
    from_checkpoint: "git log --oneline -10 && cat HANDOFF.md"
    rollback: "git reset --hard [checkpoint-hash]"
    fresh_start: "New session reading HANDOFF.md"

  state_persistence:
    - HANDOFF.md          # Session state (required)
    - progress-tracker.md # Task completion tracking
    - decisions.log       # Decisions made (append-only)

7.4 Progress Tracker

Para sesiones largas, mantener un archivo de tracking que el agente actualiza:

<!-- progress-tracker.md — Auto-maintained by agent -->
# Long Session: Feature Search Implementation

## Plan (5 phases, ~5 hours)
- [x] Phase 1: Database schema + migrations (done, checkpoint c1a2b3)
- [x] Phase 2: Embedding service (done, checkpoint d4e5f6)
- [x] Phase 3: Search API endpoint (done, checkpoint g7h8i9)
- [ ] Phase 4: Frontend search UI (IN PROGRESS)
- [ ] Phase 5: Integration tests + performance

## Current Phase: 4
- Started: 2026-03-19T14:00:00Z
- Context window: 45%
- Errors encountered: 1 (resolved — CSS import path)
- Files modified this phase: src/ui/Search.tsx, src/ui/SearchResults.tsx

## Blockers
- None currently

## Decision Log
- [14:05] Using React Server Components for search (ADR-003)
- [14:22] Debounce search input at 300ms
- [15:10] Using Suspense boundary for loading state

7.5 Sesion-Relay Pattern (Multi-session continuity)

Cuando una sesion termina (por limite de context o tiempo), relay a nueva sesion:

# Sesion 1 termina — agente escribe HANDOFF.md automaticamente
# (via post_compaction hook o instruccion en compact instructions)

# Sesion 2 comienza leyendo el relay
claude --continue  # O nueva sesion:
claude "Lee HANDOFF.md y progress-tracker.md.
Continua desde Phase 4 del plan.
El checkpoint mas reciente es g7h8i9."

7.6 Monitoring de Sesiones Largas

# Metricas para sesiones de 6+ horas
long_session_metrics:
  - name: "Phases completed"
    target: ">= plan_phases"
  - name: "Checkpoint frequency"
    target: "every 45-60 min"
  - name: "Rollback count"
    target: "< 2 per session"
  - name: "Context resets"
    target: "< 3 per session"
  - name: "Human interventions"
    target: "< 1 per 2 hours"
  - name: "Test pass rate at checkpoints"
    target: ">= 90%"

---

8. Full Agent Autonomy Cycle

Fuente: OpenAI “Harness Engineering” (Feb 2026) — agentes que reproducen bugs, graban video, implementan fix, responden feedback, y mergean — todo autonomamente.

8.1 El Ciclo Completo

┌──────────────────────────────────────────────────────────────────┐
│              FULL AUTONOMY CYCLE (Advanced)                      │
│                                                                  │
│  1. VALIDATE     2. REPRODUCE     3. IMPLEMENT     4. VERIFY    │
│  ┌─────────┐    ┌─────────┐     ┌─────────┐     ┌─────────┐   │
│  │ Read bug │───►│ Repro   │────►│ Write   │────►│ Run all │   │
│  │ report   │    │ the bug │     │ the fix │     │ tests   │   │
│  └─────────┘    └────┬────┘     └─────────┘     └────┬────┘   │
│                      │                                  │        │
│                  Record video                      All pass?     │
│                  as evidence                    ┌──────┤         │
│                                                 │      │         │
│  5. SUBMIT       6. RESPOND      7. MERGE    No │   Yes │        │
│  ┌─────────┐    ┌─────────┐     ┌─────────┐    │  ┌───▼───┐   │
│  │ Open PR │───►│ Address │────►│ Auto-   │◄───┘  │ Back  │   │
│  │ + video │    │ feedback│     │ merge   │       │ to 3  │   │
│  └─────────┘    └─────────┘     └─────────┘       └───────┘   │
│                                                                  │
│  ⚡ Guardrails: circuit breakers, escalation, confidence gates  │
└──────────────────────────────────────────────────────────────────┘

8.2 Etapas del Ciclo

Etapa	Que hace el agente	Guardrails requeridos
1. Validate	Lee bug report/issue, entiende el problema, identifica archivos relevantes	Max 5 min; si no entiende, escalar
2. Reproduce	Corre tests, reproduce el bug, graba evidencia (logs, screenshots, video)	Max 10 min; si no reproduce, reportar
3. Implement	Escribe fix minimo (no refactoring extra), corre tests locales	Max 30 min; cambios en < 5 archivos
4. Verify	Corre test suite completa, verifica que no hay regresiones	Todos los tests deben pasar
5. Submit	Abre PR con descripcion, video de reproduccion, tests nuevos	PR template obligatorio
6. Respond	Lee feedback de reviewers (humanos u otros agentes), itera	Max 3 rondas de feedback
7. Merge	Auto-merge si confidence > threshold y reviews aprobados	Requiere approval explicito

8.3 Confidence Gates para Auto-Merge

# Configuracion de auto-merge por confianza
auto_merge:
  enabled: true  # Solo para tracks maduros

  confidence_gates:
    - gate: "all_tests_pass"
      weight: 0.30
      required: true  # Bloquea si falla

    - gate: "no_security_findings"
      weight: 0.20
      required: true

    - gate: "change_scope_small"
      weight: 0.15
      criteria: "files_changed <= 5 AND lines_changed <= 200"

    - gate: "agent_review_approved"
      weight: 0.15
      criteria: "@code_reviewer verdict == 'pass'"

    - gate: "spec_compliance"
      weight: 0.10
      criteria: "implementation matches spec"

    - gate: "no_golden_principle_violation"
      weight: 0.10
      criteria: "all golden principles pass"

  thresholds:
    auto_merge: 0.90      # Score >= 0.90 → auto merge
    human_review: 0.70     # 0.70-0.89 → human review required
    reject: 0.70           # < 0.70 → reject, escalate

  circuit_breakers:
    - "3+ auto-merges fallidos en 24h → desactivar auto-merge"
    - "Rollback de auto-merge → desactivar por 48h"
    - "Security finding en auto-merge → desactivar permanentemente hasta review"

8.4 Ralph Wiggum Loop (Iterate Until Satisfied)

Patron de OpenAI donde el agente itera sobre su propio output hasta convergencia:

# Pseudocodigo del Ralph Wiggum Loop
def ralph_wiggum_loop(task, max_iterations=5):
    """Iterate: build → review → fix → review → ... → converge."""

    result = agent_build(task)

    for i in range(max_iterations):
        review = agent_review(result)

        if review.verdict == "approved":
            return result  # Convergido

        if review.confidence < 0.3:
            escalate_to_human(task, result, review)
            return None  # Humano decide

        # Iterar
        result = agent_fix(result, review.feedback)

    # Max iterations — escalar
    escalate_to_human(task, result, "Max iterations reached")
    return None

8.5 Recomendacion por Track

Track	Nivel de autonomia recomendado	Justificacion
Solo	Stages 1-5 (sin auto-merge)	Humano revisa y mergea
Lean	Stages 1-6 (con human approval)	Auto-PR + feedback, human merge
Full	Stages 1-7 (full autonomy con gates)	Auto-merge para cambios de baja complejidad

8.6 Prerequisitos para Full Autonomy

Antes de habilitar el ciclo completo, verificar:

• Test suite con coverage > 85%
• CI pipeline < 10 min (feedback rapido)
• Golden Principles codificados y verificados mecanicamente
• @code_reviewer y @security_reviewer configurados
• Circuit breakers implementados
• Alertas de rollback configuradas
• Equipo ha operado en stages 1-5 por al menos 2 semanas
• Metricas de agent review agreement > 80%

Advertencia: Full Autonomy requiere inversion significativa en tooling (Harness Engineering). No es para todos los equipos ni todos los proyectos. Empezar con stages 1-5 y escalar gradualmente.

---

9. 7 Canonical Agentic Design Patterns

Fuentes: MachineLearningMastery “7 Agentic AI Design Patterns” (Ene 2026), AgileSoftLabs “ReAct Pattern” (Mar 2026), Anthropic “Building Effective Agents” (2025-2026)

La industria ha convergido en 7 patrones canonicos para agentes AI. Este framework los usa todos, pero no los nombraba explicitamente con la terminologia estandar. Esta seccion mapea cada patron a nuestras implementaciones.

9.1 Mapa de Patrones

#	Patron Canonico	Descripcion	En nuestro framework	Donde
1	ReAct (Reasoning + Acting)	El agente razona sobre la tarea, ejecuta una accion, observa el resultado, y repite	Loop principal de Claude Code: think → tool_call → observe → think	Sesion estandar
2	Reflection	El agente revisa su propio output y lo mejora iterativamente	Review Loop (Patron 3, seccion 1.2) + Ralph Wiggum Loop (8.4)	Multi-Agent + Autonomy
3	Tool Use	El agente invoca herramientas externas para obtener informacion o ejecutar acciones	MCP Integration (toda la MCP Guide) + built-in tools	MCP Guide + F06
4	Planning	El agente descompone una tarea compleja en sub-tareas antes de ejecutar	Plan Mode (Context Guide seccion 9) + Pipeline patron (1.2)	Context + Multi-Agent
5	Multi-Agent Collaboration	Multiples agentes especializados coordinan para resolver una tarea	Specialist Swarm (1.2) + Agents del framework (2.1)	Multi-Agent Guide
6	Sequential Workflows	Cadena de procesamiento donde cada paso alimenta al siguiente	Pipeline patron (1.2) + Long-running sessions (7.x)	Multi-Agent Guide
7	Human-in-the-Loop (HITL)	El agente escala a humanos para decisiones criticas o validacion	Escalation Protocol (3.2) + Confidence Gates (8.3)	Multi-Agent + Autonomy

9.2 Patron 1: ReAct (Reasoning + Acting)

El patron mas fundamental. El agente alterna entre razonamiento (pensar que hacer) y accion (ejecutar herramientas).

┌──────────────────────────────────────────────┐
│                 ReAct LOOP                     │
│                                                │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐  │
│  │  REASON  │──►│   ACT    │──►│ OBSERVE  │  │
│  │ "Necesito│   │ Read     │   │ "El file │  │
│  │  ver el  │   │ file.ts  │   │  tiene   │  │
│  │  codigo" │   │          │   │  un bug" │  │
│  └──────────┘   └──────────┘   └────┬─────┘  │
│       ▲                              │         │
│       └──────────────────────────────┘         │
│                 (repeat)                        │
│                                                │
│  EXIT CONDITIONS:                               │
│  - Tarea completada (tests pasan)              │
│  - Max iterations alcanzado                     │
│  - Error irrecuperable → escalate              │
└──────────────────────────────────────────────┘

Implementacion en el framework: Cada sesion de Claude Code ES un ReAct loop. No requiere configuracion adicional — es el comportamiento por defecto.

Optimizacion: Usar maxTurns en sub-agentes para limitar iteraciones y evitar loops infinitos.

9.3 Patron 2: Reflection

El agente critica su propio output antes de entregarlo. Mejora calidad significativamente para tareas complejas.

# Patron Reflection implementado con nuestro Review Loop
def reflection_pattern(task: str, max_reflections: int = 3):
    """Agente genera → se auto-evalua → mejora."""

    # Step 1: Generate initial output
    output = agent_build(task)

    for i in range(max_reflections):
        # Step 2: Self-reflect
        critique = agent_review(output, criteria=[
            "correctness",
            "spec_compliance",
            "code_quality",
            "edge_cases_covered",
        ])

        if critique.score >= 0.9:
            break  # Good enough

        # Step 3: Improve based on critique
        output = agent_fix(output, critique.feedback)

    return output

Mapping: Este patron es exactamente nuestro Review Loop (seccion 1.2, Patron 3) y el Ralph Wiggum Loop (seccion 8.4), combinados.

9.4 Patron 3: Tool Use

El agente extiende sus capacidades invocando herramientas externas.

# Tool Use hierarchy en nuestro framework
tool_layers:
  layer_1_builtin:
    description: "Herramientas nativas del agente"
    examples: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
    config: "Siempre disponibles"

  layer_2_mcp:
    description: "Herramientas via MCP Protocol"
    examples: ["Context7", "PostgreSQL", "GitHub", "project-tools"]
    config: ".claude/settings.json → mcpServers"

  layer_3_custom:
    description: "Herramientas personalizadas del proyecto"
    examples: ["validate_spec", "run_migration", "deploy_canary"]
    config: "MCP server propio (ver MCP Guide seccion 4)"

  layer_4_hooks:
    description: "Acciones automaticas pre/post tool use"
    examples: ["lint on Edit", "type-check on save"]
    config: ".claude/settings.json → hooks"

Best practice: Marcar herramientas con tool annotations (readOnly, destructive, idempotent) para que el agente tome decisiones informadas sobre riesgo.

9.5 Patron 4: Planning

El agente descompone la tarea antes de ejecutar. Critico para tareas > 15 minutos.

┌──────────────────────────────────────────────────────┐
│                 PLANNING PATTERN                       │
│                                                        │
│  ┌──────────┐   ┌──────────┐   ┌──────────────────┐  │
│  │ ANALYZE  │──►│   PLAN   │──►│     EXECUTE      │  │
│  │ Specs,   │   │ Break    │   │ Follow plan      │  │
│  │ context, │   │ into     │   │ step by step     │  │
│  │ codebase │   │ tasks    │   │ (checkpoint      │  │
│  └──────────┘   └──────────┘   │  between tasks)  │  │
│                                 └──────────────────┘  │
│                                                        │
│  Implementation: Plan Mode (Shift+Tab×2)               │
│  + Sequential Thinking MCP server                      │
│  + progress-tracker.md for long sessions               │
└──────────────────────────────────────────────────────┘

9.6 Patron 5: Multi-Agent Collaboration

Multiples agentes especializados trabajan juntos. Los patrones de orquestacion (seccion 1.2) son instancias de este patron.

Sub-patron	Nuestro nombre	Topologia
Hierarchical	Hub & Spoke (Patron 1)	Orchestrator → Workers
Sequential	Pipeline (Patron 2)	Agent → Agent → Agent
Peer Review	Review Loop (Patron 3)	Builder ↔ Reviewer
Broadcast	Specialist Swarm (Patron 4)	Coordinator → [Arch, QA, Sec]
Debate	(Nuevo en v6.2)	Agent A vs Agent B → Arbiter

Patron Debate (nuevo):

# Dos agentes debaten, un arbitro decide
# Agent A: propone solucion
claude --skill /f04_architecture "Proponer solucion para high-concurrency search"

# Agent B: critica y propone alternativa
claude --skill /f04_architecture "Critica esta solucion y propone alternativa: [output A]"

# Arbiter: sintetiza
claude "Evalua ambas propuestas. Elige la mejor o sintetiza. Criterios: performance, maintainability, cost."

9.7 Patron 6: Sequential Workflows

Cadena de procesamiento donde la salida de cada paso es la entrada del siguiente. Diferente a Pipeline en que los pasos pueden ser del mismo agente.

# Sequential Workflow: Code Generation Pipeline
sequential_workflow:
  name: "Feature Implementation"
  steps:
    - id: "spec_validate"
      action: "Validate and clarify spec"
      input: "spec.yaml"
      output: "validated_spec.yaml"
      agent: "@spec_writer"

    - id: "design"
      action: "Create technical design"
      input: "validated_spec.yaml"
      output: "design.md"
      agent: "@architect"

    - id: "implement"
      action: "Write code"
      input: "design.md + validated_spec.yaml"
      output: "src/**/*.ts"
      agent: "builder"

    - id: "test"
      action: "Write and run tests"
      input: "src/**/*.ts + validated_spec.yaml"
      output: "tests/**/*.test.ts"
      agent: "@qa_engineer"

    - id: "review"
      action: "Security + code review"
      input: "src/**/*.ts + tests/**/*.test.ts"
      output: "review_report.md"
      agent: "@security_reviewer + @code_reviewer"
      parallel: true

  error_handling:
    on_step_failure: "retry_once_then_escalate"
    on_pipeline_failure: "rollback_to_last_checkpoint"

9.8 Patron 7: Human-in-the-Loop (HITL)

El patron mas critico para produccion. El agente reconoce sus limites y escala a humanos.

# HITL configuration en nuestro framework
human_in_the_loop:
  # Cuando escalar automaticamente
  automatic_escalation:
    - trigger: "confidence < 0.7"
      action: "Ask human for confirmation"

    - trigger: "destructive_action AND no_tests"
      action: "Block and request human approval"

    - trigger: "security_finding.severity == 'critical'"
      action: "Stop work, alert human immediately"

    - trigger: "cost_estimate > $50"
      action: "Present estimate, wait for approval"

    - trigger: "touches_production_data"
      action: "Require explicit human authorization"

  # Mapping a nuestro Escalation Protocol (seccion 3.2)
  escalation_levels:
    level_0: "Agent autonomo — no necesita humano"
    level_1: "Agent pide confirmacion — humano aprueba/rechaza"
    level_2: "Agent presenta opciones — humano elige"
    level_3: "Agent se detiene — humano toma control completo"

  # MCP Elicitation (standard MCP feature)
  mcp_elicitation:
    enabled: true
    description: "Agente usa MCP elicitation para pedir input al humano mid-task"
    use_cases:
      - "Clarificar requisito ambiguo"
      - "Elegir entre dos enfoques validos"
      - "Confirmar operacion destructiva"

9.9 Decision Tree: Que Patron Aplicar

¿Es una tarea simple y directa?
  → SI → ReAct solo (patron por defecto)
  → NO ↓
¿Requiere planificacion (> 15 min, > 3 archivos)?
  → SI → Planning + ReAct
  → NO ↓
¿Requiere herramientas externas (DB, API, deploy)?
  → SI → Tool Use + ReAct
  → NO ↓
¿El output necesita alta calidad? (usuario final, produccion)
  → SI → Reflection (auto-review)
  → NO ↓
¿Involucra multiples dominios?
  → SI → Multi-Agent Collaboration
  → NO ↓
¿Es una cadena de pasos dependientes?
  → SI → Sequential Workflow
  → NO ↓
¿Tiene implicaciones de seguridad/costo/produccion?
  → SI → HITL gates
  → NO → ReAct basico

9.10 Combinaciones Comunes

Escenario	Patrones combinados	Ejemplo
Bug fix simple	ReAct	Lee error → find file → fix → test
Feature nueva	Planning + ReAct + Reflection	Plan → Build → Self-review → Fix
Migration	Planning + Multi-Agent + HITL	Plan → Parallel build → Human checkpoints
Security audit	Multi-Agent + Tool Use + HITL	Swarm reviews → tools scan → human final
Incident response	ReAct + Tool Use + Sequential	Read alert → investigate → fix → deploy

---

10. Multi-Agent Framework Comparison

Fuentes: GuruSup “Best Multi-Agent Frameworks 2026” (Mar 2026), Turing “6 Agent Frameworks” (Feb 2026), Reddit LangChain “Comprehensive Comparison” (Mar 2026), LevelUp “LangGraph vs CrewAI vs AutoGen” (Mar 2026)

10.1 Tabla Comparativa

Framework	Lenguaje	Licencia	Orquestacion	State Mgmt	Observability	MCP Support	Prod Ready
OpenAI Agents SDK	Python	MIT	Handoffs + guardrails	Built-in	Tracing nativo	Via tools	✅ Alta
LangGraph	Python/TS	MIT	Graph (nodos + edges)	Checkpointer	LangSmith	Via tools	✅ Alta
CrewAI	Python	MIT	Role-based crews	Shared memory	Callbacks	Limitado	⚠️ Media
AutoGen/AG2	Python	MIT	Conversation-driven	Shared context	Logging	Limitado	⚠️ Media
Google ADK	Python	Apache 2.0	Hierarchical agents	Tiered context	Cloud Trace	Nativo	✅ Alta
Claude Code SDK	Python/TS	Anthropic	Sub-agents + hooks	Session state	Logs + hooks	Nativo	✅ Alta

10.2 Decision Tree por Use Case

¿Tu ecosistema es Google Cloud?
  → SI → Google ADK (integracion nativa, tiered context)
  → NO ↓
¿Necesitas grafos de estado complejos (conditional branching, cycles)?
  → SI → LangGraph (state machine con checkpoints)
  → NO ↓
¿Usas Claude Code como agente principal?
  → SI → Claude Code SDK + Sub-agents (lo que este framework recomienda)
  → NO ↓
¿Necesitas role-based teams con poca configuracion?
  → SI → CrewAI (facil setup, role-based)
  → NO ↓
¿Necesitas conversaciones multi-agente dinamicas?
  → SI → AutoGen/AG2
  → NO → OpenAI Agents SDK (versatil, buenas guardrails)

10.3 Nota Importante

Nuestros patrones son framework-agnostic. Los 4 patrones de orquestacion (Hub&Spoke, Pipeline, Review Loop, Specialist Swarm) y los 7 patrones canonicos (ReAct, Reflection, Tool Use, Planning, Multi-Agent, Sequential, HITL) se implementan en CUALQUIER framework. Este framework usa Claude Code como referencia pero los principios aplican universalmente.

---

11. Tiered Context for Multi-Agent (Inspirado en Google ADK)

Fuente: Google ADK “Context-Aware Multi-Agent Framework” (Dic 2025)

11.1 El Problema

Cuando multiples agentes colaboran, el contexto se fragmenta:

• Cada agente tiene su propio context window
• Las decisiones de un agente no son visibles para otro
• No hay “memoria compartida” entre agentes
• El overhead de pasar contexto entre agentes crece exponencialmente

11.2 Solucion: 4 Tiers de Contexto

┌───────────────────────────────────────────────────────┐
│                  TIERED CONTEXT MODEL                   │
│                                                         │
│  Tier 4: SHARED STATE (Inter-Agent)                    │
│  ┌─────────────────────────────────────────────┐       │
│  │ ADRs, Golden Principles, Team Decisions      │       │
│  │ Visible por: TODOS los agentes               │       │
│  │ Mutabilidad: Solo por orchestrator           │       │
│  └─────────────────────────────────────────────┘       │
│                                                         │
│  Tier 3: USER STATE (Cross-Session)                    │
│  ┌────────────────────┐ ┌──────────────────────┐       │
│  │ User preferences   │ │ Project history       │       │
│  │ Accumulated         │ │ Past decisions        │       │
│  │ knowledge           │ │ Patterns learned      │       │
│  └────────────────────┘ └──────────────────────┘       │
│                                                         │
│  Tier 2: AGENT STATE (Per-Agent Persistent)            │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐               │
│  │@architect│ │@qa_eng   │ │@security │               │
│  │ ADR cache│ │ Test     │ │ Vuln DB  │               │
│  │ Stack    │ │ patterns │ │ OWASP    │               │
│  │ prefs    │ │ Coverage │ │ rules    │               │
│  └──────────┘ └──────────┘ └──────────┘               │
│                                                         │
│  Tier 1: SESSION STATE (Transient)                     │
│  ┌──────────────────────────────────────────────┐      │
│  │ Current conversation, open files, last error  │      │
│  │ Resets with each new session                  │      │
│  └──────────────────────────────────────────────┘      │
└───────────────────────────────────────────────────────┘

11.3 Implementacion Practica

# Tiered context configuration for multi-agent
tiered_context:
  tier_1_session:
    storage: "in_memory"
    lifetime: "session"
    max_tokens: 50000
    contents:
      - "Current conversation history"
      - "Open file buffers"
      - "Recent tool outputs"
    on_session_end: "Summarize → promote key items to tier_2"

  tier_2_agent:
    storage: "filesystem"  # .claude/agent_state/{agent_id}.json
    lifetime: "persistent"
    max_tokens: 10000
    contents:
      - "Agent-specific learned patterns"
      - "Frequently used files/paths"
      - "Cached analysis results"
    update_policy: "append_only + weekly_compaction"

  tier_3_user:
    storage: "project_memory"  # .claude/memory/ or Mem0
    lifetime: "persistent"
    max_tokens: 5000
    contents:
      - "User preferences and patterns"
      - "Historical decisions"
      - "Project-specific knowledge"
    update_policy: "on_significant_decision"

  tier_4_shared:
    storage: "git_tracked"  # CLAUDE.md, ADRs, project-config.yaml
    lifetime: "permanent"
    max_tokens: 8000
    contents:
      - "Architecture Decision Records"
      - "Golden Principles (never violate)"
      - "Team conventions"
      - "Compliance requirements"
    update_policy: "PR_required"
    writable_by: ["orchestrator", "human"]  # Sub-agents read-only

11.4 Context Flow Between Agents

Orchestrator recibe tarea
  ├── Lee Tier 4 (shared): ADRs, principios
  ├── Lee Tier 3 (user): historial de decisiones
  ├── Crea plan en Tier 1 (session)
  │
  ├── Invoca @architect
  │   ├── Recibe: Tier 4 (shared) + subset Tier 1 (task context)
  │   ├── Lee: Tier 2 (agent state: ADR cache)
  │   └── Output: 1000 tokens max → orchestrator
  │
  ├── Invoca @qa_engineer
  │   ├── Recibe: Tier 4 (shared) + subset Tier 1 (task context)
  │   ├── Lee: Tier 2 (agent state: test patterns)
  │   └── Output: 1000 tokens max → orchestrator
  │
  └── Sintetiza outputs en Tier 1 (session)
      └── Promueve decisiones importantes a Tier 3/4

11.5 Por Track

Tier	Solo	Lean	Full
Session	HANDOFF.md	Session state file	In-memory + persistence
Agent	N/A (1 agente)	.claude/agent_state/	Persistent store (DB/file)
User	CLAUDE.md manual	.claude/memory/	Mem0 / vector store
Shared	CLAUDE.md + ADRs	Git-tracked configs	Git + shared DB + event log

11.6 Google ADK State Management APIs

GAP-22: mapeo directo entre nuestro modelo de 4 tiers y las abstracciones de Google ADK para equipos que usen ADK en produccion.

Google ADK (Agent Development Kit) implementa el contexto tiered mediante tres servicios core:

┌──────────────────────────────────────────────────────┐
│           Google ADK State Management                 │
│                                                       │
│  SessionService ──── Tier 1 (Session) + Tier 2       │
│  │  .create_session(app_name, user_id)               │
│  │  .get_session(app_name, user_id, session_id)      │
│  │  session.state["key"] = value                     │
│  │  session.state["{app_name}:key"] = shared_value   │
│  │                                                    │
│  MemoryService ──── Tier 3 (User) + Tier 4           │
│  │  .search_memory(app_name, user_id, query)         │
│  │  Uses Vertex AI Search for retrieval              │
│  │  Automatic summarization of past sessions         │
│  │                                                    │
│  ArtifactService ── File/blob persistence            │
│  │  .save_artifact(session, name, data)              │
│  │  .load_artifact(session, name, version?)          │
│  │  Versioned, accessible cross-agent                │
└──────────────────────────────────────────────────────┘

Mapeo ADK → Nuestro Modelo de 4 Tiers

Nuestro Tier	ADK Abstraction	ADK API	Scope Key Prefix
Tier 1: Session	session.state["key"]	SessionService	Sin prefijo (local)
Tier 2: Agent	session.state["{agent_name}:key"]	SessionService	{agent_name}: prefix
Tier 3: User	MemoryService.search_memory()	MemoryService	Per user_id
Tier 4: Shared	session.state["{app_name}:key"]	SessionService	{app_name}: prefix

Implementacion ADK en Python

adk_context_management.py

"""Google ADK tiered context — mapeo a nuestro modelo de 4 tiers."""
from google.adk.agents import Agent
from google.adk.sessions import InMemorySessionService, DatabaseSessionService
from google.adk.memory import InMemoryMemoryService
from google.adk.artifacts import InMemoryArtifactService

# --- Tier 1 & 2: Session State ---
# InMemorySessionService para desarrollo, DatabaseSessionService para produccion
session_service = InMemorySessionService()  # Dev
# session_service = DatabaseSessionService(db_url="postgresql://...")  # Prod

session = session_service.create_session(
    app_name="ai-first-framework",
    user_id="dev-user-1",
    state={
        # Tier 1 — Session state (sin prefijo, transient)
        "current_task": "implement search endpoint",
        "open_files": ["src/api/search.ts", "tests/search.test.ts"],

        # Tier 2 — Agent-specific state ({agent_name}: prefix)
        "architect:adr_cache": ["ADR-001", "ADR-002"],
        "qa_engineer:test_patterns": ["unit", "integration", "contract"],
        "security:last_scan": "2026-03-19T10:00:00Z",

        # Tier 4 — Shared state ({app_name}: prefix, visible por todos)
        "ai-first-framework:golden_principles": [
            "startup < 800ms",
            "no span > 2s",
            "zero DB from handlers",
        ],
        "ai-first-framework:architecture": "microservices + event-driven",
    }
)

# --- Tier 3: User Memory (cross-session) ---
memory_service = InMemoryMemoryService()  # Dev
# En produccion: usa Vertex AI Search backed MemoryService

# El MemoryService resume automaticamente sesiones pasadas
# y permite busqueda semantica sobre el historial del usuario
results = memory_service.search_memory(
    app_name="ai-first-framework",
    user_id="dev-user-1",
    query="What architectural decisions were made about search?"
)
# Retorna: resumen de decisiones de sesiones anteriores

# --- Agent Definition con State Access ---
architect_agent = Agent(
    name="architect",
    model="gemini-2.5-pro",
    instruction="""You are a software architect.
    Access shared state via state['ai-first-framework:golden_principles'].
    Your agent state is in state['architect:adr_cache'].
    Never modify keys without your prefix except shared app keys.""",
    tools=[...],
)

# --- Artifact Service (file persistence across sessions) ---
artifact_service = InMemoryArtifactService()

# Guardar artefacto versionado (ej: ADR generado por architect agent)
artifact_service.save_artifact(
    session=session,
    filename="adr-003-search-strategy.md",
    artifact=types.Part.from_text("# ADR-003: Vector Search Strategy\n...")
)

# Recuperar artefacto (desde cualquier agente con acceso a la sesion)
adr = artifact_service.load_artifact(
    session=session,
    filename="adr-003-search-strategy.md"
)

ADK State Scoping Rules

# Reglas de scoping para multi-agent en ADK
adk_state_scoping:

  # Estado sin prefijo → solo el agente actual lo ve
  session_local:
    example: "state['current_step'] = 3"
    visibility: "current_agent_only"
    tier: "Tier 1 (Session)"

  # Estado con prefijo {agent_name}: → persistente por agente
  agent_scoped:
    example: "state['architect:preference'] = 'event-driven'"
    visibility: "that_specific_agent"
    tier: "Tier 2 (Agent)"
    persistence: "across_sessions_if_DB_backed"

  # Estado con prefijo {app_name}: → visible por TODOS los agentes
  app_shared:
    example: "state['my-app:golden_principles'] = [...]"
    visibility: "all_agents_in_app"
    tier: "Tier 4 (Shared)"
    write_policy: "orchestrator_only_recommended"

  # MemoryService → busqueda semantica sobre historial
  user_memory:
    access: "memory_service.search_memory(app, user, query)"
    visibility: "all_agents_for_that_user"
    tier: "Tier 3 (User)"
    update_policy: "automatic_on_session_close"

Migration Path: Claude Code → ADK

Feature	Claude Code (Actual)	Google ADK
Session state	HANDOFF.md + /memory	session.state
Agent state	.claude/agent_state/	state["{agent}:key"]
User memory	.claude/memory/	MemoryService
Shared state	CLAUDE.md + ADRs	state["{app}:key"]
Artifacts	Git-tracked files	ArtifactService
State persistence	Filesystem	DB-backed SessionService

Recomendacion: iniciar con InMemorySessionService para prototipos; migrar a DatabaseSessionService para produccion. El modelo de 4 tiers es framework-agnostico — funciona tanto con Claude Code como con ADK, LangGraph, o CrewAI.

---

12. Anti-Patrones

Anti-patron	Problema	Solución
”SaFe en solo mode”	Demasiados roles para 1 persona	Máximo 3-4 agents activos
Agents sin boundaries	Se pisan unos a otros	Context scope estricto por agent
Sin compression	Orchestrator ahogado en output	Max 2000 tokens por sub-agent
Sequential cuando paralelo	Lento sin necesidad	Identificar independencias, paralelizar
Sin escalation protocol	Agent loops infinitos	Escalation levels claros
Orchestrator hace todo	Bottleneck	Delegate, don’t do

13. Metricas de Orquestacion

Métrica	Target	Cómo medir
Agent utilization	> 70%	Tiempo activo / tiempo total
Parallel efficiency	> 2x vs sequential	Tiempo paralelo / tiempo secuencial
Escalation rate	< 15%	Escalations / total decisions
Review agreement	> 80%	Agents que coinciden / total agents
Context efficiency	< 50% window used	Tokens usados / tokens disponibles
Human intervention rate	< 20%	Human steps / total steps

14. Durable Execution Patterns para Long-Running Agents (v6.4 — GAP-10)

Fuentes: LangGraph Checkpointing (Mar 2026), Microsoft Durable Task Framework (Feb 2026), Temporal.io Agent Workflows (Ene 2026), Rhesis.ai “Long-Running Agentic Workflows” (Mar 2026)

Los frameworks de agentes convergen en durable execution — la capacidad de persistir estado de workflows que duran horas o dias, con recuperacion automatica ante fallos. Esta seccion documenta los patrones para equipos que implementen workflows agenticos de larga duracion.

14.1 Problema

Los agentes clasicos operan en una sola session (minutos). Pero workflows reales pueden durar horas o dias:

• Migration de base de datos con validacion iterativa
• Code review + fix + re-review cycles
• Generacion de documentacion para proyecto completo
• Onboarding de nuevo microservicio (infra + code + tests + deploy)
• Evaluacion continua de modelo en produccion

Si el agente falla a mitad de un workflow de 4 horas, perder todo el progreso es inaceptable.

14.2 Patrones de Durable Execution

Patron 1: Checkpoint & Resume

El patron mas fundamental. El agente persiste su estado despues de cada paso significativo.

┌─────────────────────────────────────────────────────────┐
│  Durable Agent Workflow                                  │
│                                                          │
│  Step 1: Analyze ──→ 💾 Checkpoint 1                    │
│  Step 2: Plan    ──→ 💾 Checkpoint 2                    │
│  Step 3: Build   ──→ ❌ FALLO (OOM, timeout, crash)    │
│                                                          │
│  ... restart ...                                         │
│                                                          │
│  📂 Load Checkpoint 2                                    │
│  Step 3: Build   ──→ 💾 Checkpoint 3  ✅               │
│  Step 4: Test    ──→ 💾 Checkpoint 4                    │
│  Step 5: Deploy  ──→ ✅ Completado                      │
└─────────────────────────────────────────────────────────┘

Implementacion por framework:

Framework	Mecanismo	Storage
LangGraph	checkpointer (built-in)	SQLite, PostgreSQL, Redis
Microsoft Durable Task	DurableTask.OrchestrationContext	Azure Storage, SQL Server
Temporal.io	Event sourcing automatico	Temporal Server (Cassandra/PostgreSQL)
Custom	YAML state files en disco	Filesystem, S3, GCS

# Ejemplo: Checkpoint state structure
checkpoint:
  workflow_id: "migration-db-v2"
  step_completed: 3
  total_steps: 7
  state:
    analyzed_tables: ["users", "orders", "products"]
    migration_plan: "project/F06_build/migration_plan.yaml"
    completed_migrations: ["users", "orders"]
    pending_migrations: ["products"]
  context:
    tokens_used: 45000
    cost_usd: 1.23
    elapsed_seconds: 7200
  metadata:
    created_at: "2026-03-20T10:00:00Z"
    last_checkpoint: "2026-03-20T12:00:00Z"
    agent: "migration-agent-v1"
    retry_count: 0

Patron 2: Saga Pattern para Workflows Multi-Agent

Cuando un workflow involucra multiples agentes, cada uno con responsabilidades distintas, el patron Saga coordina la secuencia con compensaciones si un paso falla.

┌─────────────────────────────────────────────────────────┐
│  Saga: Deploy New Microservice                           │
│                                                          │
│  1. @architect → Design    ✅  (compensar: delete spec) │
│  2. @builder   → Implement ✅  (compensar: revert PR)   │
│  3. @qa        → Test      ❌  (FALLO: tests fallan)    │
│                                                          │
│  → Compensar Step 2: revert PR                          │
│  → Compensar Step 1: archive spec                       │
│  → Notificar humano con contexto del fallo              │
└─────────────────────────────────────────────────────────┘

Patron 3: Timer & Schedule Workflows

Para workflows que requieren esperas entre pasos (ej: esperar a que CI termine, esperar aprobacion humana).

# workflow: scheduled-eval
steps:
  - id: "trigger-eval"
    action: "run_eval_suite"
    schedule: "0 2 * * *"        # 2am diario

  - id: "wait-for-results"
    action: "wait"
    timeout: "30m"

  - id: "analyze-results"
    action: "compare_with_baseline"
    on_regression: "alert_team"

  - id: "update-scorecard"
    action: "update_eval_scorecard"
    artifact: "project/F07_tevv/eval_scorecard.yaml"

14.3 Recomendaciones por Track

Aspecto	Solo	Lean	Full
Checkpointing	⬜ Archivo YAML local	✅ SQLite/Redis	✅ PostgreSQL/Temporal
Recovery	Manual restart	Auto-resume desde ultimo checkpoint	Auto-resume + retry policy
Compensaciones	❌ No requerido	⬜ Basico (revert)	✅ Saga completa
Timer workflows	❌ No requerido	⬜ Cron basico	✅ Scheduler dedicado
Observabilidad	Console logs	Structured logs + metricas	Tracing distribuido
Max workflow duration	< 1 hora	< 8 horas	Ilimitado

14.4 Anti-Patrones de Durable Execution

Anti-patron	Problema	Solucion
Estado solo en memoria	Crash = perdida total	Checkpoint despues de cada paso costoso
Checkpoint cada linea	Overhead masivo, lento	Checkpoint en boundaries logicos
Sin limites de retry	Loop infinito de reintentos	max_retries: 3, exponential backoff
Estado monolitico	Checkpoint de 100MB, lento	Solo delta, referencias a artifacts
Sin timeout global	Workflow zombie corriendo dias	workflow_timeout configurable
Compensaciones implicitas	Fallo parcial deja estado corrupto	Compensaciones explicitas por paso

14.5 Configuracion en project-config.yaml

# Agregar en project-config.yaml si se usan durable workflows
workflows:
  durable_execution:
    enabled: false                # true si se usan workflows de larga duracion
    checkpoint_backend: "yaml"    # yaml | sqlite | postgresql | temporal
    checkpoint_dir: ".checkpoints/"
    max_workflow_duration: 3600   # segundos (1 hora default)
    retry_policy:
      max_retries: 3
      backoff: "exponential"      # fixed | linear | exponential
      initial_delay: 5            # segundos
    cleanup:
      retain_completed: 7         # dias
      retain_failed: 30           # dias

---

15. Self-Healing Pipeline — Patron de Auto-Reparacion (NUEVO — Cerrando GAP G4)

Fuentes: BCG Platinion Dark Software Factory Pilar 5 (Mar 2026), AWS AI-DLC (2026), Anthropic Agentic Coding Trends (Trend 3-4)

15.1 Que es un Self-Healing Pipeline

Un Self-Healing Pipeline es un pipeline CI/CD donde agentes diagnostican y reparan automáticamente fallos sin intervención humana. Es el paso natural de la automatización L2→L3 en una Software Factory.

PIPELINE TRADICIONAL:                    SELF-HEALING PIPELINE:

Test falla → Build rojo → Dev investiga  Test falla → Agent diagnostica →
→ Dev corrige → Push → Re-run            Agent corrige → Re-run → Si pasa: merge
(horas/dias)                              (minutos)
                                         Si no pasa en 3 intentos → Escala a humano

15.2 Arquitectura del Self-Healing Pipeline

┌──────────────────────────────────────────────────────────┐
│                 SELF-HEALING PIPELINE                      │
│                                                            │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌────────┐│
│  │  DETECT   │──►│ DIAGNOSE │──►│   FIX    │──►│VALIDATE││
│  │           │   │          │   │          │   │        ││
│  │ CI fails  │   │ Agent    │   │ Agent    │   │ Re-run ││
│  │ Test red  │   │ reads    │   │ generates│   │ full   ││
│  │ Lint err  │   │ logs,    │   │ patch,   │   │ test   ││
│  │ Type err  │   │ traces,  │   │ commits  │   │ suite  ││
│  │ Sec scan  │   │ diffs    │   │ fix      │   │        ││
│  └──────────┘   └──────────┘   └──────────┘   └───┬────┘│
│       ▲                                            │      │
│       │              ┌──────────┐                  │      │
│       │              │  DEPLOY  │◄─────────────────┘      │
│       │              │  or      │    (si pasa)            │
│       │              │  ESCALATE│                          │
│       │              └────┬─────┘                          │
│       │                   │                                │
│       └───────────────────┘  (si falla 3x → humano)       │
└──────────────────────────────────────────────────────────┘

15.3 Las 5 Fases del Self-Healing

Fase 1: DETECT (Detección automática)

El pipeline detecta fallos en cualquier etapa:

Tipo de fallo	Señal	Prioridad de healing
Test unitario falla	pytest exit 1, jest --fail	Alta — auto-heal
Lint / format error	eslint, ruff, prettier fallo	Alta — auto-heal
Type error	tsc, mypy, pyright fallo	Alta — auto-heal
Build falla	npm run build error	Media — auto-heal con contexto
Security scan	pip-audit, npm audit advisory	Media — evaluar severidad
Integration test	API contract violation	Baja — necesita más contexto
Performance regression	Latency > threshold	Baja — escalar a humano

Fase 2: DIAGNOSE (Diagnóstico inteligente)

El agente analiza el fallo con contexto completo:

# diagnosis_context.yaml — lo que el agente recibe
diagnosis:
  trigger: "ci_failure"
  pipeline_stage: "test"

  inputs:
    - error_log: "{{ CI log output }}"
    - failed_tests: ["test_user_auth.py::test_login_invalid"]
    - diff: "{{ git diff desde último green build }}"
    - file_changed: ["src/auth/login.py", "tests/test_user_auth.py"]
    - related_specs: ["project/F05_contracts/api_auth.yaml"]
    - last_green_commit: "abc123"

  constraints:
    max_diagnosis_time: "2min"
    max_files_to_read: 20
    read_only: true  # Fase de diagnóstico es read-only

Prompt de diagnóstico del agente:

Analiza el fallo de CI. Tu tarea es SOLO diagnosticar, NO corregir aún.

1. Lee el error log y los tests que fallaron
2. Lee el diff desde el último build verde
3. Identifica la CAUSA RAÍZ (no el síntoma)
4. Clasifica: { simple_fix | complex_fix | needs_human | false_positive }
5. Si simple_fix: describe el cambio exacto necesario
6. Si needs_human: explica por qué no puedes arreglarlo

Output en JSON: { category, root_cause, confidence, proposed_fix_description }

Fase 3: FIX (Reparación autónoma)

Solo se ejecuta si category == "simple_fix" y confidence >= 0.8:

fix_policy.yaml

self_healing:
  auto_fix_allowed:
    - "test_assertion_mismatch"     # Test esperaba valor diferente
    - "import_missing"               # Falta import
    - "type_error_simple"            # Tipo incorrecto en argumento
    - "lint_format"                  # Formatting/linting
    - "dependency_version_bump"     # Patch version update
    - "schema_migration"            # Schema change simple

  escalate_to_human:
    - "architectural_change"         # Cambio de diseño
    - "security_vulnerability"       # Vulnerabilidad de seguridad
    - "data_loss_risk"              # Riesgo de pérdida de datos
    - "performance_regression"       # Degradación de performance
    - "multi_service_impact"        # Afecta múltiples servicios
    - "confidence_below_threshold"  # Confianza < 0.8

  constraints:
    max_lines_changed: 50           # Si el fix cambia > 50 líneas → escalar
    max_files_changed: 5            # Si toca > 5 archivos → escalar
    max_fix_attempts: 3             # Máximo 3 intentos antes de escalar
    require_test_for_fix: true      # Cada fix debe incluir/actualizar test
    branch: "auto-fix/{{ issue_id }}"  # Fix en branch separado

Fase 4: VALIDATE (Revalidación completa)

# Después del fix, re-ejecutar TODO el test suite, no solo el test que falló
validation:
  steps:
    - name: "Re-run failed tests"
      command: "pytest {{ failed_test_files }} -v"
      must_pass: true

    - name: "Re-run full test suite"
      command: "pytest --full-suite"
      must_pass: true

    - name: "Re-run linting"
      command: "ruff check . && mypy ."
      must_pass: true

    - name: "Re-run security scan"
      command: "pip-audit && bandit -r src/"
      must_pass: true

    - name: "Verify no regression"
      command: "pytest --benchmark-compare"
      warn_on_regression: true

  on_validation_pass:
    action: "auto_merge"  # o "request_human_review" dependiendo del nivel

  on_validation_fail:
    action: "escalate_to_human"
    notify: ["#engineering", "@oncall"]

Fase 5: DEPLOY o ESCALATE

SI validation pasa:
  └→ L1-L2: Crear PR con label "auto-fix" + request review
  └→ L3+:   Auto-merge si pasa todos los gates

SI validation falla (3 intentos):
  └→ Crear issue con diagnóstico completo
  └→ Notificar al equipo con:
      - Error original
      - 3 intentos de fix con diffs
      - Razón de cada fallo
      - Recomendación del agente
  └→ Rollback automático al último green commit

15.4 Implementación con GitHub Actions

.github/workflows/self-healing.yaml

name: Self-Healing Pipeline
on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

jobs:
  self-heal:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.workflow_run.head_branch }}

      - name: Download CI failure logs
        uses: actions/download-artifact@v4
        with:
          name: ci-logs
          run-id: ${{ github.event.workflow_run.id }}

      - name: Agent Diagnose
        id: diagnose
        run: |
          # Enviar logs + diff al agente de diagnóstico
          claude --print "Diagnose this CI failure. Output JSON only." \
            --context ci-logs/test-output.log \
            --context <(git diff HEAD~1) \
            > diagnosis.json

          category=$(jq -r .category diagnosis.json)
          confidence=$(jq -r .confidence diagnosis.json)
          echo "category=$category" >> $GITHUB_OUTPUT
          echo "confidence=$confidence" >> $GITHUB_OUTPUT

      - name: Agent Fix
        if: steps.diagnose.outputs.category == 'simple_fix' && steps.diagnose.outputs.confidence >= 0.8
        run: |
          git checkout -b auto-fix/${{ github.run_id }}

          # Agente genera el fix
          claude --print "Apply the fix described in diagnosis.json. Only modify necessary files." \
            --context diagnosis.json \
            --allowedTools edit,read,bash

          git add -A
          git commit -m "fix(auto-heal): $(jq -r .root_cause diagnosis.json)"

      - name: Re-validate
        if: steps.diagnose.outputs.category == 'simple_fix'
        run: |
          # Re-ejecutar test suite completo
          npm test || pytest --full-suite

      - name: Create Auto-Fix PR
        if: success()
        run: |
          git push origin auto-fix/${{ github.run_id }}
          gh pr create \
            --title "fix(auto-heal): $(jq -r .root_cause diagnosis.json)" \
            --body "## Auto-Heal Report\n\n$(cat diagnosis.json | jq .)" \
            --label "auto-fix,needs-review"

      - name: Escalate if failed
        if: failure()
        run: |
          gh issue create \
            --title "🚨 Self-Heal Failed: $(jq -r .root_cause diagnosis.json)" \
            --body "Auto-heal attempted 3 fixes but none passed validation.\n\nDiagnosis:\n$(cat diagnosis.json | jq .)" \
            --label "needs-human,self-heal-failed"

15.5 Metricas del Self-Healing Pipeline

Métrica	Descripción	Target L2	Target L3+
Auto-heal success rate	% de fallos resueltos sin humano	≥ 40%	≥ 70%
Mean time to heal (MTTH)	Tiempo desde fallo hasta fix merged	< 30min	< 10min
False fix rate	% de auto-fixes que introducen nuevos bugs	≤ 5%	≤ 2%
Escalation rate	% de fallos escalados a humano	≤ 60%	≤ 30%
Healing attempts/fix	Intentos promedio antes de resolver	≤ 2.0	≤ 1.5
Rollback from auto-fix	% de auto-fixes revertidos post-merge	≤ 3%	≤ 1%

15.6 Circuit Breakers del Self-Healing

circuit_breakers.yaml

self_healing_circuit_breakers:
  - name: "consecutive_failures"
    trigger: "3 auto-fixes consecutivos fallidos"
    action: "disable self-healing por 24h, notificar tech lead"

  - name: "security_finding"
    trigger: "security scan encuentra vulnerability en auto-fix"
    action: "revert inmediato, disable self-healing, notificar security lead"

  - name: "cost_spike"
    trigger: "costo de tokens del self-heal > $50 por fix"
    action: "escalar a humano, revisar diagnóstico prompt"

  - name: "scope_creep"
    trigger: "auto-fix modifica > 50 líneas o > 5 archivos"
    action: "rechazar fix, crear PR draft para review humano"

  - name: "regression_loop"
    trigger: "auto-fix resuelve test A pero rompe test B"
    action: "rollback, crear issue con análisis de ambos tests"

15.7 Anti-Patrones

Anti-patrón	Riesgo	Solución
Auto-heal todo	Fixes complejos incorrectos, deuda técnica	Allowlist estricta de tipos de fix
Sin validación completa	Fix que pasa un test pero rompe otros	Siempre re-run suite completa
Sin circuit breakers	Loop infinito de fix→fail→fix	Max 3 intentos + cost cap
Auto-merge sin review en L1-L2	Código malo llega a producción	Solo auto-merge en L3+ con gates
Sin rollback automático	Fix roto en producción	Rollback antes de escalar

15.8 Progresión por Nivel de Autonomía

Nivel	Detect	Diagnose	Fix	Validate	Deploy
L0 Assisted	CI alertas	Humano	Humano	Humano	Humano
L1 Structured	CI + Agent	Agent sugiere	Humano implementa	CI automático	Humano aprueba
L2 Governed	Agent monitora	Agent diagnostica	Agent propone PR	CI + gates	Humano review
L3 Autonomous	Agent detecta	Agent diagnostica	Agent aplica fix	Suite completa	Auto-merge (con gates)
L4 Dark Factory	Continuo 24/7	Inmediato	Autónomo	Autónomo + production smoke	Autónomo con rollback

---

16. Coordinacion Nativa Multi-Agente (v7.5)

Fuentes: Claude Code Agent Teams (2026), Factory-Native FAB coordination patterns, Swarming patterns (seccion 4)

Cuando multiples FABs operan simultaneamente sobre un mismo proyecto, necesitan mecanismos de coordinacion para evitar conflictos, comunicarse entre si, y dividir el trabajo de forma eficiente. Esta seccion define los patrones nativos de coordinacion que el framework provee, implementados como convenciones de filesystem (sin dependencias externas).

16.1 File-Locking para Task Claims

Multiples FABs pueden intentar reclamar la misma tarea. El patron de file-locking usa el filesystem como mecanismo de exclusion mutua.

Patron: .fab-claims/TASK-ID.lock — archivos de lock con FAB ID y timestamp.

.fab-claims/
  INTENT-2026-001.lock    ← FAB-alpha owns this task
  INTENT-2026-003.lock    ← FAB-beta owns this task

Formato del lock file:

{
  "fab_id": "fab-alpha",
  "claimed_at": "2026-03-24T10:00:00Z",
  "heartbeat_at": "2026-03-24T11:30:00Z",
  "task_id": "INTENT-2026-001",
  "phase": "F06_Build"
}

Reglas de locking:

Regla	Descripcion
First-write wins	El primer FAB que crea el .lock file es el owner
Heartbeat required	El FAB actualiza heartbeat_at en cada checkpoint (cada 60 min)
Timeout release	Si no hay heartbeat en 2x el intervalo (120 min), el lock se considera abandonado
Explicit release	El FAB elimina el .lock file al completar la tarea
No force-acquire	Un FAB nunca debe sobreescribir un lock activo de otro FAB

Deteccion de locks abandonados:

heartbeat_interval = 60 min (de .fab-config.yaml → checkpoint_interval_min)
timeout = 2 × heartbeat_interval = 120 min

SI (now - heartbeat_at) > timeout:
  → Lock abandonado → cualquier FAB puede reclamar
  → Registrar en .fab-inbox/lead/ el evento de timeout

16.2 Inbox-Based Communication

Los FABs se comunican via mensajes JSON depositados en directorios inbox. No requiere servicios externos — solo el filesystem.

Patron: .fab-inbox/FAB-ID/ — cada FAB tiene su propio directorio de inbox.

.fab-inbox/
  fab-alpha/
    2026-03-24T10-00-00Z_task_assignment.json
    2026-03-24T11-30-00Z_review_request.json
  fab-beta/
    2026-03-24T10-05-00Z_task_assignment.json
  lead/
    2026-03-24T11-00-00Z_status_update.json

Tipos de mensaje:

Tipo	Emisor tipico	Receptor tipico	Descripcion
task_assignment	Lead	Worker	Asignar subtarea a un FAB
status_update	Worker	Lead	Reportar progreso o bloqueo
artifact_ready	Worker	Worker o Lead	Artefacto disponible para consumo
help_request	Worker	Lead o Specialist	Solicitar ayuda en un tema
review_request	Worker	Reviewer	Solicitar review de codigo/artefacto

Formato de mensaje:

{
  "id": "MSG-2026-001",
  "from": "fab-alpha",
  "to": "fab-beta",
  "type": "review_request",
  "timestamp": "2026-03-24T11:30:00Z",
  "payload": {
    "task_id": "INTENT-2026-001",
    "phase": "F06_Build",
    "files": ["src/api/search.ts", "tests/search.test.ts"],
    "message": "Search endpoint implementation complete. Please review."
  },
  "priority": "normal"
}

Reglas de comunicacion:

• El lead agent lee todos los inboxes para mantener visibilidad global
• Los workers leen solo su propio inbox
• Los mensajes son append-only — nunca se modifican, solo se agregan nuevos
• Los mensajes procesados se mueven a .fab-inbox/FAB-ID/processed/
• El lead puede enviar mensajes broadcast creando el mismo archivo en multiples inboxes

16.3 Task Decomposition

Cuando un lead agent recibe un intent complejo, lo descompone en subtareas independientes que pueden ejecutarse en paralelo.

Patron: intent/subtasks/SUBTASK-NNN.yaml — cada subtarea es un intent con referencia al padre.

intent/
  INTENT-2026-001.yaml          ← Intent padre (feature completa)
  subtasks/
    SUBTASK-001.yaml            ← F04 Architecture (FAB-architect)
    SUBTASK-002.yaml            ← F05 Contracts (FAB-spec)
    SUBTASK-003.yaml            ← F06 Build: API layer (FAB-alpha)
    SUBTASK-004.yaml            ← F06 Build: UI layer (FAB-beta)
    SUBTASK-005.yaml            ← F07 Tests (FAB-qa)

Estructura de subtarea:

intent/subtasks/SUBTASK-003.yaml

subtask:
  id: "SUBTASK-003"
  parent_intent: "INTENT-2026-001"
  assigned_fab: "fab-alpha"
  phase: "F06_Build"
  description: "Implementar search API endpoint con pgvector"
  assigned_files:
    - "src/api/search.ts"
    - "src/services/embedding.ts"
  dependencies:
    - subtask_id: "SUBTASK-001"
      status: "completed"  # Debe completarse antes
    - subtask_id: "SUBTASK-002"
      status: "completed"
  acceptance_criteria:
    - "GET /api/search?q=term returns results"
    - "Response time < 200ms for 10K documents"
    - "Tests with coverage >= 85%"
  status: "in_progress"

Merge strategy: cada FAB trabaja en su propio branch. Al completar, crea un PR hacia el branch del intent padre. El lead agent (o humano) revisa y mergea.

main
  └─ intent/INTENT-2026-001      ← branch del intent
       ├─ fab-alpha/subtask-003   ← branch del FAB
       ├─ fab-beta/subtask-004    ← branch del FAB
       └─ fab-qa/subtask-005      ← branch del FAB

16.4 Merge Wall Prevention: File-Level Ownership

Referencia: patrones de Swarming (seccion 4.1) y Feature Parallel (4.2).

El patron de file-level ownership previene conflictos de merge asignando archivos/directorios a FABs especificos. Ningun FAB modifica archivos asignados a otro.

Patron: .fab-ownership.yaml — mapa de archivos a FAB IDs.

# .fab-ownership.yaml — Generado por lead agent al descomponer tareas
ownership:
  intent_id: "INTENT-2026-001"
  generated_at: "2026-03-24T10:00:00Z"
  generated_by: "fab-lead"

  assignments:
    - fab_id: "fab-alpha"
      files:
        - "src/api/search.ts"
        - "src/services/embedding.ts"
      directories:
        - "src/api/"

    - fab_id: "fab-beta"
      files:
        - "src/ui/Search.tsx"
        - "src/ui/SearchResults.tsx"
      directories:
        - "src/ui/search/"

    - fab_id: "fab-qa"
      files:
        - "tests/api/search.test.ts"
        - "tests/ui/search.test.tsx"
      directories:
        - "tests/"

  shared_files:
    # Archivos que multiples FABs pueden necesitar leer (pero NO modificar sin coordinacion)
    - "src/types/search.ts"      # Types compartidos — modificar via PR al lead
    - "package.json"              # Dependencies — lead coordina cambios

Reglas de ownership:

• Cada FAB solo modifica archivos asignados a el
• Archivos shared_files requieren coordinacion via mensaje al lead
• Si un FAB necesita un archivo asignado a otro, envia help_request al lead
• El lead puede reasignar archivos dinamicamente actualizando .fab-ownership.yaml

16.5 Patrones de Coordinacion

Patron 1: Pipeline Secuencial (FAB-1 → FAB-2 → FAB-3)

Cada FAB ejecuta una fase y pasa el resultado al siguiente. Ideal para workflows donde cada paso depende del anterior.

FAB-architect    FAB-builder     FAB-qa
┌──────────┐    ┌──────────┐    ┌──────────┐
│ F04 Arch │───►│ F06 Build│───►│ F07 Test │
│ ADRs,    │    │ Code     │    │ Tests,   │
│ design   │    │ impl     │    │ coverage │
└──────────┘    └──────────┘    └──────────┘
     │               │               │
  artifact_ready  artifact_ready  status_update
  → fab-builder   → fab-qa        → lead

Configuracion en .fab-coordination.yaml:

mode: pipeline
agents:
  - id: "fab-architect"
    role: "architect"
    assigned_phases: ["F04"]
  - id: "fab-builder"
    role: "builder"
    assigned_phases: ["F05", "F06"]
  - id: "fab-qa"
    role: "qa"
    assigned_phases: ["F07"]

Patron 2: Parallel Fan-Out / Fan-In (Lead → N Workers → Lead Merges)

El lead descompone la tarea, N workers ejecutan en paralelo, el lead merge los resultados. Ideal para features grandes divisibles por componente.

         FAB-lead (decompose)
        ┌──────────────┐
        │  Descomponer  │
        │  en subtareas │
        └──┬───┬───┬───┘
           │   │   │
           ▼   ▼   ▼
        ┌──┐ ┌──┐ ┌──┐
        │W1│ │W2│ │W3│  ← Workers en paralelo
        └──┘ └──┘ └──┘
           │   │   │
           ▼   ▼   ▼
        ┌──────────────┐
        │  FAB-lead    │
        │  merge PRs   │
        └──────────────┘

Configuracion:

mode: parallel
lead_agent: "fab-lead"
agents:
  - id: "fab-worker-1"
    role: "builder"
    assigned_files: ["src/api/"]
  - id: "fab-worker-2"
    role: "builder"
    assigned_files: ["src/ui/"]
  - id: "fab-worker-3"
    role: "builder"
    assigned_files: ["src/services/"]
merge_strategy: pr_per_agent

Patron 3: Specialist Routing (Architect → Builder → QA)

Variante del pipeline donde cada FAB tiene un rol especializado con sus propios agents y skills activados.

FAB-architect         FAB-builder          FAB-security
(@architect agent)    (builder skills)     (@security_reviewer)
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ Design +     │────►│ Implement +  │────►│ Security     │
│ ADR + review │     │ Test         │     │ audit        │
└──────────────┘     └──────────────┘     └──────────────┘

Configuracion:

mode: specialist
agents:
  - id: "fab-architect"
    role: "architect"
    assigned_phases: ["F04"]
  - id: "fab-builder"
    role: "builder"
    assigned_phases: ["F05", "F06"]
  - id: "fab-security"
    role: "security"
    assigned_phases: ["F08"]

Patron 4: Peer Review (FAB-1 writes, FAB-2 reviews)

Dos FABs trabajan en ciclo: uno implementa, otro revisa. El ciclo se repite hasta convergencia (ver Ralph Wiggum Loop, seccion 8.4).

FAB-builder              FAB-reviewer
┌──────────┐   code     ┌──────────┐
│ Implement│───────────►│  Review  │
│          │◄───────────│          │
└──────────┘  feedback  └──────────┘
     │ (iterate until approved)
     ▼
   ✅ PR ready

Configuracion:

mode: pipeline  # Pipeline de 2 con ciclo
agents:
  - id: "fab-builder"
    role: "builder"
    assigned_phases: ["F06"]
  - id: "fab-reviewer"
    role: "reviewer"
    assigned_phases: ["F07"]
merge_strategy: pr_per_agent

16.6 Configuracion: .fab-coordination.yaml

La coordinacion multi-agente se configura en .fab-coordination.yaml en la raiz del proyecto. Este archivo define el modo de coordinacion, los agentes participantes, y las convenciones de comunicacion.

scripts/schemas/fab_coordination.schema.json

# .fab-coordination.yaml — ver seccion 16 de Multi_Agent_Orchestration_Guide
coordination:
  mode: "single"           # single | pipeline | parallel | specialist
  lead_agent: "fab-lead"   # FAB ID del agente lider (requerido si mode != single)

  agents:
    - id: "fab-lead"
      role: "lead"
      assigned_phases: ["F01", "F02", "F03", "F04"]
      assigned_files: []

  communication:
    inbox_dir: ".fab-inbox"
    claims_dir: ".fab-claims"
    ownership_file: ".fab-ownership.yaml"

  merge_strategy: "pr_per_agent"  # pr_per_agent | sequential_merge | trunk_based

Ver template completo en project-template/.fab-coordination.yaml.

16.7 Herramienta: fab-coordinator.py

El script scripts/fab-coordinator.py implementa los patrones de esta seccion como CLI:

# Ver estado de todos los FABs activos
python3 scripts/fab-coordinator.py status --project-dir .

# Reclamar una tarea
python3 scripts/fab-coordinator.py claim INTENT-2026-001 --fab-id fab-alpha

# Liberar una tarea
python3 scripts/fab-coordinator.py release INTENT-2026-001 --fab-id fab-alpha

# Enviar mensaje a otro FAB
python3 scripts/fab-coordinator.py send fab-beta review_request \
  --fab-id fab-alpha --payload '{"task_id":"INTENT-2026-001","files":["src/api/search.ts"]}'

# Leer inbox
python3 scripts/fab-coordinator.py inbox --fab-id fab-alpha

# Descomponer un intent en subtareas
python3 scripts/fab-coordinator.py decompose intent/INTENT-2026-001.yaml --fab-id fab-lead

16.8 Metricas de Coordinacion Multi-Agente

Metrica	Descripcion	Target
Claim collision rate	% de claims donde 2+ FABs compiten	< 5%
Message latency	Tiempo entre envio y lectura de mensaje	< 5 min
Merge conflict rate	% de PRs con conflictos de merge	< 10%
Ownership violation rate	% de commits que tocan archivos de otro FAB	0%
Subtask completion rate	% de subtareas completadas vs planificadas	> 90%
Coordination overhead	Tiempo en coordinacion vs ejecucion	< 15%

16.9 Anti-Patrones de Coordinacion

Anti-patron	Problema	Solucion
Sin ownership file	Merge conflicts constantes	Generar .fab-ownership.yaml antes de fan-out
Lead agent bottleneck	Lead no procesa inboxes a tiempo	Lead checkpoint cada 30 min en modo multi-agent
Subtareas acopladas	Un FAB espera a otro constantemente	Descomponer en unidades verdaderamente independientes
Sin heartbeat	Locks abandonados bloquean tareas	Heartbeat en cada checkpoint (60 min)
Broadcast excesivo	Ruido en inboxes, FABs ignoran mensajes	Solo mensajes relevantes, usar tipos especificos
Sin merge strategy	Cada FAB mergea cuando quiere, conflictos	Definir merge_strategy en .fab-coordination.yaml

---

Documento generado como companion operativo del AI-First Engineering Framework v7.5 — GAP-22 (ADK Tiered Context) cerrado en Sprint 4, GAP-10 (Durable Execution Patterns) cerrado en v6.4, GAP-G4 (Self-Healing Pipeline) cerrado en v6.7, Coordinacion Nativa Multi-Agente agregada en v7.5. Patrones canonicos basados en: MachineLearningMastery (Ene 2026), AgileSoftLabs (Mar 2026), GuruSup (Mar 2026), Turing (Feb 2026), Google ADK (Dic 2025), OpenAI Harness Engineering (Feb 2026), BCG Platinion Dark Software Factory (Mar 2026), Claude Code Agent Teams (2026)