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>

scripts/new-specialist.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Scaffolding de un nuevo specialist: copia los templates y rellena REPLACE_*.
+# Uso:
+#   ./scripts/new-specialist.sh <name> <domain>
+# Ejemplo:
+#   ./scripts/new-specialist.sh ad_specialist_acme identidad
+
+set -euo pipefail
+
+if [ $# -lt 2 ]; then
+  echo "Usage: $0 <specialist-name> <domain>"
+  echo "Example: $0 ad_specialist_acme identidad"
+  exit 1
+fi
+
+NAME="$1"
+DOMAIN="$2"
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+AGENT_FILE="$ROOT/wxo/agents/${NAME}.agent.yaml"
+TOOLS_FILE="$ROOT/wxo/tools/python/${DOMAIN}_tools.py"
+KB_FILE="$ROOT/wxo/knowledge_base/kb_${DOMAIN}.kb.yaml"
+CONN_FILE="$ROOT/wxo/connections/${DOMAIN}_connection.yaml"
+
+# Copiar agent template y reemplazar
+if [ ! -f "$AGENT_FILE" ]; then
+  cp "$ROOT/wxo/agents/_template-specialist.agent.yaml" "$AGENT_FILE"
+  sed -i.bak "s/REPLACE_specialist_name/${NAME}/g; s/REPLACE_DOMINIO/${DOMAIN}/g; s/REPLACE_domain/${DOMAIN}/g; s/REPLACE_kb_name/kb_${DOMAIN}/g" "$AGENT_FILE"
+  rm "${AGENT_FILE}.bak"
+  echo "✓ Created: $AGENT_FILE"
+else
+  echo "⚠  Already exists: $AGENT_FILE — skipping"
+fi
+
+if [ ! -f "$TOOLS_FILE" ]; then
+  cp "$ROOT/wxo/tools/python/_template_tools.py" "$TOOLS_FILE"
+  sed -i.bak "s/REPLACE_domain/${DOMAIN}/g" "$TOOLS_FILE"
+  rm "${TOOLS_FILE}.bak"
+  echo "✓ Created: $TOOLS_FILE"
+fi
+
+if [ ! -f "$KB_FILE" ]; then
+  cp "$ROOT/wxo/knowledge_base/_template.kb.yaml" "$KB_FILE"
+  sed -i.bak "s/REPLACE_kb_name/kb_${DOMAIN}/g; s/REPLACE_DOMINIO/${DOMAIN}/g" "$KB_FILE"
+  rm "${KB_FILE}.bak"
+  echo "✓ Created: $KB_FILE  (acordate de agregar los runbooks)"
+fi
+
+if [ ! -f "$CONN_FILE" ]; then
+  cp "$ROOT/wxo/connections/_template-keyvalue.yaml" "$CONN_FILE"
+  sed -i.bak "s/REPLACE_app_name/${DOMAIN}_demo/g; s/REPLACE_SISTEMA/${DOMAIN}/g" "$CONN_FILE"
+  rm "${CONN_FILE}.bak"
+  echo "✓ Created: $CONN_FILE"
+fi
+
+echo ""
+echo "Siguientes pasos:"
+echo "  1. Editar $AGENT_FILE  — rellenar REPLACE_* restantes"
+echo "  2. Editar $TOOLS_FILE  — implementar las tools de ${DOMAIN}"
+echo "  3. Crear runbook bajo wxo/knowledge_base/runbooks/ y referenciarlo en $KB_FILE"
+echo "  4. Si ${DOMAIN} no es un mock, considerá usar _template-apikey-header.yaml en lugar de keyvalue"
+echo "  5. Si ${NAME} debe ser collaborator de un orchestrator, agregalo allí"
+echo "  6. ./scripts/deploy-wxo.sh"