ComandeskHelp Inicio

OPS Playbook — Plantillas y Subagentes

Ver tambien:

  • docs/README.md
  • docs/ops-daily-mode.md
  • docs/sa-ops-system/README.md
  • docs/sa-ops-system/operating-modes.md
  • docs/sa-ops-system/prd-operating-mode-selector.md

1) Objetivo

Este documento define como usar subagentes (profiles) y plantillas (task_templates) para ejecutar trabajo repetible con calidad alta y trazabilidad completa.

Metas:

  • Menos tiempo de setup por tarea.
  • Mismo nivel de calidad entre ejecuciones.
  • Entregables visibles y auditables en OPS.
  • Orquestacion multi-modelo sin perder control.

2) Modelo mental rapido

  • Agent: runtime que ejecuta (ej. opencode, hermes, codex, claudecode).
  • Subagente / Profile: rol funcional (estrategia de skills + modelo por defecto + metadata).
  • Plantilla: receta reutilizable para crear instancias de tarea.
  • Instancia: tarea concreta creada desde plantilla o manual.

Relacion recomendada:

  • task define objetivo y contexto concreto.
  • profile define estilo de ejecucion.
  • agent define runtime tecnico.
  • model define nivel de razonamiento/coste.

2.1) Flujo hibrido escritorio / dispatcher

OPS acepta dos vias de ejecucion para tareas de IA:

  • Dispatcher automatico: un worker reclama tareas queued, ejecuta el runtime configurado y devuelve output/contexto a OPS.
  • Reclamo desde escritorio: un operador abre la tarea en OPS y la ejecuta desde una app local con sesion, credenciales y repos ya disponibles.

Ambas vias deben cumplir el mismo contrato de salida: comentario final, evidencia visible, tiempo registrado y documentacion actualizada si cambia el sistema.

Cuando conviene escritorio:

  • La tarea depende de credenciales o sesiones locales que no deben copiarse al VPS.
  • Hay que usar contexto local amplio, repos abiertos o una app de escritorio con modelos ya autenticados.
  • La tarea requiere supervision humana estrecha.

Cuando conviene dispatcher:

  • La tarea es repetible, acotada y tiene credenciales configuradas en OPS.
  • Debe ejecutarse sin que el operador tenga la maquina abierta.
  • Forma parte de una plantilla recurrente estable.

Bloque Instrucciones para agente:

Toda tarea que pueda ser reclamada manualmente o despachada debe incluir, en la descripcion o en contexto, un bloque operativo con:

  • agente preferente
  • perfil
  • modelo preferente
  • modo de ejecucion
  • proyecto y target
  • contexto operativo
  • criterio de terminado
  • donde registrar resultado y tiempo
  • que hacer si se bloquea

La UI de OPS ofrece el boton + Instrucciones agente en crear tarea y en la edicion de descripcion. Ese bloque viaja con task.description, por lo que lo leen tanto el dispatcher como un agente reclamado desde escritorio.

Contrato estructurado:

  • En detalle de tarea, Contrato de ejecucion guarda JSON en tasks.execution_contract.
  • En plantillas, task_templates.execution_contract permite que las instancias recurrentes nazcan con contrato.
  • El contrato efectivo combina workspace, profile, template y task.
  • Para tareas estrictas, activar preflight_required=true y completar agente/modelo preferente, criterios de aceptacion y fallback de bloqueo.

3) Politica vigente de modelos

Principal (calidad)

  • Default global para perfiles core: gpt-5

- coder

- reviewer

- marketer

- designer

- mockup-chatgpt5

Rutina (coste/velocidad con gate)

  • coder-routine-minimax -> minimax/MiniMax-M2.7
  • coder-routine-qwen-local -> local-qwen3.6-coder
  • coder-routine-gemma4-local -> local-gemma4

Regla dura:

  • Toda tarea rutinaria con impacto relevante requiere gate final con MODEL-03 (Reviewer GPT-5) antes de cierre.

4) Contrato de salida (obligatorio)

Para evitar tareas "ejecutadas" sin entregable visible:

  1. Publicar entregable en Contexto de la tarea (no solo checkpoint launcher).
  2. Publicar comentario corto que apunte al contexto (ej. "ver entrada #82").
  3. Si hay filesystem disponible, guardar archivo y publicar ruta.

Ejemplo de rutas sugeridas:

  • Handbook/clients/{cliente}/projects/{proyecto}/deliverables/web/01-briefing.md
  • Handbook/clients/{cliente}/projects/{proyecto}/deliverables/web/06-mockup.md
  • ~/Downloads/ops-deliverables/{task_id}-{slug}.md (fallback local)

Nota:

  • OPS hoy no expone storage de artefactos dedicado. El canal oficial es context/comments + referencia de ruta.

5) Como diseñar un subagente robusto

Checklist:

  1. Slug claro: kebab-case y orientado a un tipo de tarea.
  2. Default model: acorde al nivel de riesgo.
  3. Skills minimas: solo las necesarias para ese rol.
  4. Metadata util:

- quality_gate_required

- quality_gate_profile

- allowed_scopes

- forbidden_scopes

- preferred_agent

  1. Output policy: siempre visible en contexto.

Antipatrones:

  • Un profile para todo (termina sin foco).
  • Meter skills de mas "por si acaso".
  • Cerrar tareas AI sin evidencia visible.

6) Como diseñar plantillas que realmente escalen

Estructura base recomendada:

  1. Objetivo
  2. Input minimo requerido
  3. Entregables esperados (lista cerrada)
  4. Reglas y limites
  5. Salida visible obligatoria

Buenas practicas:

  • active=false por defecto para nuevas plantillas (fase prueba).
  • Ejecutar 1-2 demos, validar output y luego activar.
  • Versionar por fase (ej. WEB-01, WEB-02, ...).

Selector guiado (UI, recomendado):

  • Usa el boton Selector guiado en la vista Recurrentes.
  • Responde 4 campos (area, resultado, execution, preferencia de modelo).
  • OPS rankea y recomienda top plantillas para evitar eleccion "a ciegas".
  • Si una plantilla sugerida esta pausada, activala o ajustala antes de ejecutar.

Ficha de proyecto + preflight:

  • Completa la ficha minima del proyecto en Specs y PRD (business, audience, offer, primary_goal, brand_tone, constraints, reference_material).
  • Al ejecutar una plantilla, OPS valida preflight con esa ficha.
  • Si faltan campos criticos, bloquea ejecucion por defecto y permite force solo cuando sea intencional.

7) Pipeline web recomendado (plantillas)

Secuencia creada en OPS:

  • WEB-01 Briefing estrategico
  • WEB-02 Sitemap + arquitectura
  • WEB-03 SEO map
  • WEB-04 Copy por pagina
  • WEB-05 Plan de imagenes + prompts
  • WEB-06 Mockup visual
  • WEB-07 HTML Tailwind v4
  • WEB-08 QA visual/responsive/a11y
  • WEB-09 Handoff Bricks/WordPress

Uso eficiente:

  • No saltar fases salvo caso obvio.
  • Cada fase consume la salida de la fase anterior.
  • Si falta input critico, bloquear con pregunta concreta antes de seguir.

8) Plantillas de politica de modelos

Para rutinas internas:

  • MODEL-01 Minimax rutina
  • MODEL-02 Qwen local rutina
  • MODEL-04 Gemma4 local rutina
  • MODEL-03 Gate final GPT-5 Reviewer

Workflow recomendado:

  1. Ejecutar tarea con MODEL-01/02/04.
  2. Dejar output visible + riesgos.
  3. Ejecutar MODEL-03 para dictamen final.
  4. Cerrar solo con evidencia aprobada.

9) API minima de operacion

Crear profile:


POST /api/profiles

Crear plantilla:


POST /api/task-templates

Instanciar plantilla:


POST /api/task-templates/:id/run

Preflight de plantilla:


GET /api/task-templates/:id/preflight

Ficha de proyecto:


GET /api/projects/:id/intake-profile

PUT /api/projects/:id/intake-profile

Añadir salida visible:


POST /api/tasks/:id/context

POST /api/tasks/:id/comments

10) Criterio de done

Una tarea AI esta lista para done cuando:

  • Tiene entregable visible en contexto/comentario.
  • Cumple checklist de la plantilla.
  • Si aplica, paso por gate de calidad GPT-5.
  • No quedan dudas criticas abiertas.

Si no cumple esto, debe quedarse en review o waiting.