fit-boilerplate-wox/README.md

fit-boilerplate-wox

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

Este repositorio es el punto de partida canónico para cualquier solución estilo cotemar-poc-n1 o dun-casos-prueba: trae estructura, plantillas, scripts, documentación y subagentes Claude pre-configurados para que vos arranques con un cliente nuevo en minutos, no días.

---

¿Qué hay acá?

Pieza	Para qué sirve
wxo/	Plantillas de agentes, conexiones, tools (Python/OpenAPI/MCP) y KBs
web/_default_fastapi_htmx/	Capa web por defecto (FastAPI + HTMX + Jinja). Swap por React/Next/etc. si el caso lo pide
mocks/_example_mock/	Ejemplo de mock externo (FastAPI con healthcheck correcto para Coolify/Traefik)
scripts/	Deploy idempotente, undeploy, evals, smoke test, scaffolding de specialists
evals/	Linter de buenas prácticas + scenarios + smoke tests + runner
docs/	Cheatsheet ADK 2.x, best practices, deployment guide, runbook, known issues
.claude/agents/	7 subagentes Claude (architect, agent-author, tool-author, etc.)
.gitea/workflows/ci.yml	CI con lint + evals

---

Quick start

# 1. Clonar
git clone https://gitea.fitlabs.dev/farentsen/fit-boilerplate-wox.git mi-cliente
cd mi-cliente
rm -rf .git && git init

# 2. Conversar con Claude usando el skill fit-wxo-bootstrap
#    (instalalo primero en ~/.claude/skills/ — ver más abajo)
#    El skill te pregunta qué construís, decide la topología, y dispara
#    subagentes Claude en paralelo para escribir agentes/tools/runbooks/evals.

# 3. Revisar lo que generó la skill, ajustar, y desplegar:
./scripts/check-adk-version.sh
./scripts/deploy-wxo.sh

---

Skill fit-wxo-bootstrap

Bajo skill/fit-wxo-bootstrap/ hay un skill bundle listo para instalar:

cp -r skill/fit-wxo-bootstrap ~/.claude/skills/

Reinicia Claude Code y el skill queda disponible. Invocalo con:

"Quiero arrancar una solución WxO nueva para [cliente/caso de uso]"

La skill te lleva por las decisiones de arquitectura y delega la escritura a subagentes Claude que corren en paralelo.

---

Filosofía del template

1. WxO es el motor multi-agéntico fijo. Todo lo demás es swap-able. El stack web (FastAPI+HTMX, Next, Remix, lo que sea) puede cambiar según el caso. WxO no.

2. Buenas prácticas se enforcean, no se sugieren. evals/lint_wxo_yaml.py falla el CI si:

   • Algún agente tiene >10 tools
   • El orchestrator declara tools de remediación (reset_password, restart_service, etc.)
   • Un agente con style: react no tiene KB ni tools (sin propósito)
   • Una tool no usa el decorator @observable_tool
   • Falta el _compat.py inline
   • Algún docker-compose.yml usa wget --spider
   • Algún OpenAPI no tiene description per-operation
   • Algún schema Pydantic de tool no tiene @field_validator(mode="before")

3. Cada tool es observable por defecto. El decorator @observable_tool emite trazas estructuradas (inputs, outputs, latency, side effects, observed state). El web layer las consume y las muestra en una vista timeline. Las evals las usan para validar que el agente llamó las tools correctas en el orden correcto.

4. Cuatro tipos de agente, no uno. Procedural (con runbook KB), API-driven (sin KB, todos OpenAPI), MCP-driven (sin KB, herramientas vía MCP server), híbrido.

5. Dos modos de tool wrapper.

   • Mock externo (estilo cotemar): Python @tool que llama HTTP a un mock separado
   • Backend integrado (estilo dun): tu propio backend FastAPI expone un OpenAPI filtrado que WxO importa directamente. Más rápido para producción real.

---

Documentación

Doc	Propósito
docs/INDEX.md	Doc de docs — empezá acá
docs/adk-2x-cheatsheet.md	Comandos ADK 2.x + YAML schemas + gotchas
docs/wxo-best-practices.md	Las 30+ reglas codificadas, con el "por qué"
docs/architecture-patterns.md	Árbol de decisión: ¿1 agente o N? ¿KB o no? ¿OpenAPI o Python?
docs/observability-pattern.md	El contrato @observable_tool + write_audit
docs/tool-authoring-guide.md	Python vs OpenAPI vs MCP — cuándo usar cuál
docs/deployment-guide.md	Deploy genérico (parametrizable a cualquier tenant)
docs/DEPLOY_TO_NEW_WOX.md	Cold start playbook (provision → secrets → backend → wox → smoke test)
docs/RUNBOOK.md	Operación: URLs, monitoring, recovery, rotation, troubleshooting
docs/known-issues.md	Errores reales con su fix (recursion_limit, llama bug, Coolify Traefik, etc.)
docs/eval-strategy.md	4 capas de eval: nativa, agente, runbook, web
INSTRUCCIONES.md	Quickstart de 5 pasos

---

Origen

Destilado de dos PoCs reales de FIT México:

• cotemar-poc-n1 — Mesa N1 multi-agente (1 orquestador + 3 specialists) con runbooks + KBs + mocks
• dun-casos-prueba — QA Studio con OpenAPI integrado + audit_logs + webhook HMAC + meta-tool

Cada lección aprendida en esos dos repos vive acá como código, plantilla o validador de CI.