feat: v1 — boilerplate WxO + web

Boilerplate completo para construir soluciones agénticas sobre IBM
watsonx Orchestrate (ADK 2.x) con una capa web encima.

Destilado de cotemar-poc-n1 y dun-casos-prueba. Incluye:

- 11 docs (best practices, architecture patterns, ADK cheatsheet,
  observability, tool authoring, deployment, RUNBOOK, DEPLOY_TO_NEW_WOX,
  known-issues con 16 errores reales y fix, eval strategy, INDEX)
- 13 templates WxO (orchestrator/specialist/single-meta agents,
  3 connections, KB + runbook, observable_tool decorator, coercion
  helpers, Python tools, OpenAPI spec, backend filter endpoint, webhook
  validator HMAC, MCP connection)
- 6 scripts (deploy idempotente con fallback ADK, undeploy, reset,
  check-adk-version, new-specialist scaffold, eval-agents runner)
- 4 eval pieces (linter de best practices, runner, smoke-test, direct
  backend probe) + scenario templates
- 8 subagentes Claude (.claude/agents/) — wxo-architect, wxo-agent-author,
  wxo-tool-author, runbook-author, mock-builder, backend-tool-builder,
  eval-author, web-layer-builder
- Skill bundle fit-wxo-bootstrap/ (SKILL.md + 3 templates) listo para
  copiar a ~/.claude/skills/
- Web layer default FastAPI+HTMX con vista timeline observable + endpoint
  receptor de trazas
- Docker compose Coolify-ready (healthcheck wget -qO-, sin labels Traefik,
  network split internal:true)
- CI Gitea workflow con lint + smoke

Best practices enforced por evals/lint_wxo_yaml.py:
- A1: máx 10 tools por agente
- A3: orchestrator sin tools de remediación
- A6: agente sin propósito (react sin tools ni KB)
- T1: @observable_tool obligatorio, no @tool directo
- T3: _compat shim inline en tools.py
- D1: docker-compose sin wget --spider
- I-005: OpenAPI con description per-operation
- I-009: sin labels Traefik manuales

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

skill/fit-wxo-bootstrap/templates/parallel-dispatch.md

@@ -0,0 +1,171 @@
+# Dispatch paralelo de subagentes
+
+Cuando la topología está aprobada (Fase 4), lanzá TODOS los subagentes
+en paralelo (un único mensaje con múltiples `Agent` tool calls).
+
+## Patrón
+
+```
+Voy a lanzar N subagentes en paralelo para construir toda la solución.
+Cada uno escribe su pieza. Esto va a tomar 2-5 minutos.
+```
+
+Luego invocá EN UN SOLO MENSAJE algo así:
+
+```python
+# Pseudocódigo — el agente principal hace múltiples llamadas Agent() en paralelo
+
+# Por cada agente WxO en la topología:
+for agent in topology.agents:
+    Agent(
+        description=f"Write WxO agent YAML for {agent.name}",
+        subagent_type="wxo-agent-author",
+        prompt=f"""
+        Escribí el agent.yaml de WxO para:
+
+        role: {agent.role}
+        name: {agent.name}
+        display_name: "{agent.display_name}"
+        description: {agent.description}
+        domain: {agent.domain}
+        tools: {agent.tools}
+        collaborators: {agent.collaborators}
+        knowledge_base: {agent.kb or "none"}
+        client_name: {client}
+        business_context: {agent.business_context}
+        escalation_table: {agent.escalation_table or "none"}
+        examples: {agent.examples}
+
+        Guardalo en wxo/agents/{agent.name}.agent.yaml
+        Aplicá todas las reglas de docs/wxo-best-practices.md.
+        """
+    )
+
+# Por cada dominio (tools):
+for domain in topology.domains:
+    Agent(
+        description=f"Write tool wrappers for {domain.name}",
+        subagent_type="wxo-tool-author",
+        prompt=f"""
+        Escribí los tool wrappers para el dominio {domain.name}.
+
+        type: {domain.tool_type}
+        tools: {domain.tools}
+        external_system: {domain.external_system}
+
+        Aplicá:
+        - @observable_tool (regla T1)
+        - Coerción Pydantic (issue I-003)
+        - BASE_URL del env (regla T4)
+        - Compat shim inline si es Python (issue I-010)
+        """
+    )
+
+# Por cada runbook:
+for rb in topology.runbooks:
+    Agent(
+        description=f"Write runbook {rb.id}",
+        subagent_type="runbook-author",
+        prompt=f"""
+        Escribí el runbook {rb.id} — {rb.title}.
+
+        domain: {rb.domain}
+        trigger_description: {rb.trigger}
+        preconditions: {rb.preconditions}
+        steps: {rb.steps}
+        success_criteria: {rb.success}
+        escalation_table: {rb.escalation or "none"}
+
+        Guardalo en wxo/knowledge_base/runbooks/runbook-{rb.id}-{rb.slug}.txt
+        """
+    )
+
+# Por cada sistema externo a mockear:
+for sys in topology.mocks:
+    Agent(
+        description=f"Build mock for {sys.name}",
+        subagent_type="mock-builder",
+        prompt=f"""
+        Construí el mock FastAPI para {sys.name}.
+        endpoints: {sys.endpoints}
+        seed_data: {sys.seed_data}
+        behaviors: {sys.behaviors}
+        """
+    )
+
+# Por cada scenario de eval:
+for scn in topology.evals:
+    Agent(
+        description=f"Write eval scenario {scn.name}",
+        subagent_type="eval-author",
+        prompt=f"""
+        Escribí el eval scenario para {scn.agent}.
+
+        scenario_type: {scn.type}
+        runbook_id: {scn.runbook_id}
+        business_input: "{scn.input}"
+        expected_tool_calls_in_order: {scn.tool_calls}
+        expected_response_tokens: {scn.response_tokens}
+        expected_final_state: {scn.final_state}
+        forbidden_tool_calls: {scn.forbidden or []}
+        """
+    )
+
+# Web layer:
+Agent(
+    description="Build web layer",
+    subagent_type="web-layer-builder",
+    prompt=f"""
+    Construí la capa web para {client}.
+    mode: {topology.web_stack}    # A o B
+    landing: {topology.landing}
+    trace_view: {topology.trace_view}
+    """
+)
+
+# Si hay backend propio:
+if topology.has_backend:
+    Agent(
+        description="Build FastAPI backend with OpenAPI tools",
+        subagent_type="backend-tool-builder",
+        prompt=f"""
+        Construí el backend FastAPI para {client}.
+        endpoints: {topology.backend.endpoints}
+        db_schema: {topology.backend.schema}
+        audit_events: {topology.backend.audit_events}
+        """
+    )
+```
+
+## Mientras corren
+
+Mostrar al usuario:
+```
+🚀 Lanzados 12 subagentes en paralelo:
+  ✓ wxo-agent-author (orchestrator)
+  ✓ wxo-agent-author (specialist_ad)
+  ✓ wxo-agent-author (specialist_ops)
+  ✓ wxo-tool-author (ad)
+  ✓ wxo-tool-author (ops)
+  ✓ runbook-author (RB-01)
+  ✓ runbook-author (RB-02)
+  ✓ mock-builder (ad_mock)
+  ✓ mock-builder (ops_mock)
+  ✓ eval-author (scenario_reset)
+  ✓ eval-author (scenario_restart)
+  ✓ web-layer-builder
+
+Esperando resultados...
+```
+
+## Cuando todos terminan
+
+1. Listar archivos generados (`find <cliente>/ -newer .git -type f`)
+2. Correr lint:
+   ```bash
+   python3 evals/lint_wxo_yaml.py
+   ```
+3. Si hay errores, decidir si re-ejecutar el subagente que falló o pedir
+   ajustes manuales
+4. Mostrar al usuario un `tree -L 3` de lo que quedó
+5. Pasar a Fase 6 (recomendaciones)