# 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

```bash
# 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:

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

---

## Origen

Destilado de dos PoCs reales de FIT México:
- [`cotemar-poc-n1`](https://gitea.fitlabs.dev/farentsen/cotemar-poc-mesa-n1) — Mesa N1 multi-agente (1 orquestador + 3 specialists) con runbooks + KBs + mocks
- [`dun-casos-prueba`](https://gitea.fitlabs.dev/farentsen/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.