fit-boilerplate-wox/skill/fit-wxo-bootstrap/SKILL.md

---
name: fit-wxo-bootstrap
description: Genera una solución completa basada en fit-boilerplate-wox para un cliente o caso de uso nuevo. Conversa para entender el caso, decide la topología WxO (cuántos agentes, qué dominios, qué tipo de tools, qué stack web), y dispara subagentes Claude en paralelo que escriben agentes, tools, runbooks, mocks, evals y la capa web. Triggers — usá este skill cuando el usuario diga "quiero arrancar una solución WxO nueva", "armá un proyecto desde el boilerplate", "necesito generar agentes para [cliente]", "bootstrap WxO", "fit-boilerplate", o cualquier variación de bootstrappear una solución agéntica sobre watsonx Orchestrate.
---

# fit-wxo-bootstrap

Skill conversacional para arrancar una nueva solución agéntica sobre
**watsonx Orchestrate (ADK 2.x)** usando `fit-boilerplate-wox` como base.

Es el complemento del boilerplate: el repo trae las plantillas y subagentes,
y esta skill orquesta la conversación con el usuario y el lanzamiento
paralelo de subagentes para construir la solución.

## Cuándo se invoca

- "Quiero arrancar una solución WxO nueva para [cliente]"
- "Bootstrap el boilerplate para [caso de uso]"
- "Armá los agentes para [descripción]"
- "Necesito generar el esqueleto WxO para [cliente]"

## Flujo de la skill

### Fase 1 — Entender el caso

Pregunto al usuario:

1. **¿Qué cliente / caso de uso?**
   - Si es un cliente FIT existente, sugerirle usar las skills hermanas
     `prep-reunion` o `consulta-fichas` para traer contexto.
   - Si es un caso de uso ya conocido, capturar el contexto en una nota.

2. **¿Tenés contexto adicional para compartir?** (transcripción, email,
   licitación, dibujo de arquitectura, etc.)
   - Si sí, leerlo y resumirlo.
   - Si no, seguir.

3. **Dominios identificados** — listar los que YO veo y pedir confirmación.

### Fase 2 — Decidir topología (con `wxo-architect`)

Llamar al subagente `wxo-architect` (de `.claude/agents/wxo-architect.md`
del boilerplate) pasándole la descripción del caso. Recibir su propuesta
de:
- Topología (Single / Multi-Specialist / Meta-Tool / Multi-Capa)
- Agentes con nombre + tools + KB sí/no + collaborators
- Tipo de tools por dominio (Python / OpenAPI / MCP)
- Stack web sugerido
- Runbooks a escribir
- Evals scenarios mínimos

**Mostrarle al usuario la propuesta completa** y pedir confirmación o
ajustes. Iterar hasta que apruebe.

### Fase 3 — Clonar el boilerplate

```bash
git clone https://gitea.fitlabs.dev/farentsen/fit-boilerplate-wox.git <cliente>
cd <cliente>
rm -rf .git && git init
```

Personalizar:
- `README.md` con el nombre del cliente / caso
- `.env.example` con los placeholders correctos
- Borrar las plantillas REPLACE_* que NO se van a usar

### Fase 4 — Dispatch paralelo de subagentes

Lanzar EN UN SOLO MENSAJE (paralelo) los subagentes que correspondan
según la topología aprobada:

- **1 instancia de `wxo-agent-author`** por cada agente (orchestrator + N specialists)
- **1 instancia de `wxo-tool-author`** por cada dominio (con type Python/OpenAPI/MCP según corresponda)
- **1 instancia de `runbook-author`** por cada runbook
- **1 instancia de `mock-builder`** por cada sistema externo a mockear
- **1 instancia de `backend-tool-builder`** si la solución tiene backend propio
- **1 instancia de `eval-author`** por cada scenario de eval planificado
- **1 instancia de `web-layer-builder`** para la capa web (modo A o B según se decidió)

Cada subagente devuelve el archivo correspondiente. Mientras corren,
informar al usuario el progreso.

### Fase 5 — Validación

Una vez que todos terminaron:
1. Correr `python3 evals/lint_wxo_yaml.py` — debe pasar
2. Correr `./scripts/check-adk-version.sh`
3. Revisar visualmente la estructura final con `tree -L 3`
4. Mostrar al usuario lo que se generó

### Fase 6 — Recomendaciones finales

Invocar `claude-code-setup:claude-automation-recommender` sobre el repo
recién generado para sugerir hooks y agentes extra específicos del proyecto.

Si hay cambios significativos, invocar `code-review:code-review` antes
del commit inicial.

### Fase 7 — Commit inicial + instrucciones de deploy

```bash
git add . && git commit -m "feat: bootstrap from fit-boilerplate-wox

Cliente: <X>
Topología: <Y>
Agentes: <lista>
Generado con fit-wxo-bootstrap skill."
```

Mostrar al usuario los **pasos manuales restantes**:

1. `cp .env.example .env` y rellenar
2. `python3.12 -m venv .venv-wxo && source .venv-wxo/bin/activate`
3. `pip install ibm-watsonx-orchestrate==2.1.0`
4. `orchestrate env add ... && orchestrate env activate ...`
5. `./scripts/deploy-wxo.sh`
6. Capturar IDs del orchestrator (live env)
7. Pegar IDs en `web/.../index.html` + `.env`
8. WxO Console → Embed Security OFF
9. `./evals/smoke-test.sh`

## Buenas prácticas que la skill enforce

Heredadas de `docs/wxo-best-practices.md` del boilerplate:

1. **Máx 10 tools por agente.** Si la propuesta del `wxo-architect`
   tiene un agente con >10 tools, parar y pedir split.
2. **Domain specialists, no todistas.** Si veo agentes que mezclan
   dominios, separar.
3. **Orchestrator nunca remedia.** Tools del orchestrator: solo ticketing
   + escalación.
4. **KB es opcional.** No forzar KB en agentes API-driven.
5. **Conexiones en draft Y live.**
6. **OpenAPI con description + security per-op.**
7. **Tools observables por default** (`@observable_tool`, no `@tool` directo).
8. **Coerción Pydantic** en todo input model.

## Skills hermanas que esta skill puede invocar

- `prep-reunion` — si el cliente ya existe en Outline/HubSpot
- `consulta-fichas` — para traer experiencia previa con tecnologías similares
- `fit-analisis-inicial` — si vale la pena armar un deck cliente-facing antes de codear
- `claude-code-setup:claude-automation-recommender` — sugerir automations al final
- `code-review:code-review` — review del esqueleto generado
- `feature-dev:feature-dev` — para agregar features después del bootstrap

## Templates incluidos en la skill

Ver `templates/` en este directorio:
- `templates/conversation-guide.md` — ejemplo de cómo guiar la conversación
- `templates/architect-prompt-template.md` — qué pasarle al subagente architect
- `templates/parallel-dispatch.md` — cómo lanzar todos los subagentes en paralelo

## Cuando NO usar esta skill

- Si el usuario quiere modificar una solución existente → usar `feature-dev`
- Si el usuario quiere debuggear un problema → usar `general-purpose` + `docs/known-issues.md`
- Si el usuario quiere review de código → usar `code-review`

## Output esperado

Al terminar, el usuario tiene:
- Un repo local `<cliente>/` listo para commitear a Gitea
- Todos los YAMLs, tools, runbooks, mocks, evals, web generados
- Pasos manuales de deploy claramente listados
- Un agente orquestador + N especialistas listos para `orchestrate ... import`
- Un linter que ya pasa