Importar un plan y preparar ejecucion local

Estado: guia operativa

Fecha: 2026-05-30

Para que sirve

Esta guia explica como convertir un backlog externo en un proyecto ejecutable dentro de Komandesk.

El caso tipico es:

existe un CSV con epicas y tareas;
existe una especificacion en Markdown;
el trabajo necesita un runner local porque debe operar sobre un repositorio o carpeta del usuario;
queremos dejar todo preparado, pero no ejecutar hasta que el runner este vivo.

El objetivo no es solo importar datos. El objetivo es dejar una cadena auditable:

plan -> fases -> tareas -> specs -> target local -> perfil/agente -> verificacion -> tiempo

Regla de seguridad

Importar no significa ejecutar.

Cuando una importacion prepara trabajo automatico con runner local, las tareas deben quedar en next, no en queued, hasta que existan estas tres condiciones:

el target local esta vinculado al proyecto;
el runner local tiene heartbeat reciente;
el modelo/agente anunciado por el runner coincide con el contrato de la tarea.

Esto evita que un worker remoto reclame tareas que requieren acceso a disco local.

Datos minimos

Antes de importar, confirma:

workspace correcto;
proyecto correcto;
departamento correcto;
plan activo actual y si debe archivarse;
fuente del backlog;
fuente de especificaciones;
ruta local autorizada;
agente deseado;
modelo operativo real;
modelo solicitado por negocio, si usa otro nombre;
criterio de done;
pruebas esperadas;
dependencias entre tareas;
estimacion de horas;
politica de despliegue por fase.

Si falta alguno de estos puntos, crea una tarea de preparacion y no importes en automatico todavia.

Formato recomendado de backlog

El CSV debe separar epicas y tareas. Un formato suficiente:


id,parent_id,semana,tipo,titulo,descripcion,criterios_aceptacion,pruebas,estimacion_horas,prioridad,dependencias,estado_inicial,runner,agente,modelo,razonamiento

P30-E01,,S1,epica,Base operativa,Definir tablero y reglas,Checklist activo,Revision semanal,0,Alta,,Todo,local,Codex,gpt-5,alto

P30-E01-T01,P30-E01,S1,tarea,Crear tablero,Crear vistas por estado,Las vistas existen,Revisar tablero,3,Alta,,Todo,local,Codex,gpt-5,alto

Reglas practicas:

id debe ser estable;
parent_id enlaza tarea con epica;
dependencias puede usar varios ids separados por |;
estimacion_horas debe existir aunque no se facture;
runner debe decir local si requiere disco del usuario;
modelo debe distinguir entre etiqueta solicitada y modelo operativo si no coinciden.

Formato recomendado de specs

El Markdown debe describir cada epica con:

objetivo;
alcance;
definicion de hecho;
riesgo principal;
mitigacion.

Ejemplo:


## P30-E01 - Base operativa



Objetivo:

- Crear disciplina de ejecucion desde el dia 1.



Alcance:

- Tablero, estados, checklist y evidencias.



Definicion de hecho:

1. Tablero activo.

2. Checklist aplicado.

3. Tareas con estimacion y evidencia.



Riesgo principal:

- Saltarse el checklist por urgencia.



Mitigacion:

- No cerrar tareas sin evidencia minima.

Que debe hacer la importacion automatica

Una importacion completa debe:

archivar, no borrar, el plan activo anterior si solo puede haber un plan activo;
crear el nuevo plan activo;
crear fases con objetivo, tareas, estimacion, QA y despliegue requerido;
crear tareas en next;
asignar execution = auto solo si existe contrato de ejecucion;
asignar agente, perfil, modelo y skills;
crear o actualizar target local_machine;
crear specs aprobadas por tarea;
guardar dependencias internas;
guardar la etiqueta de modelo solicitada si no coincide con el modelo real;
registrar una tarea de importacion cerrada;
registrar tiempo.

Contrato de tarea

Cada tarea automatizable debe incluir un execution_contract equivalente a:


{

  "preflight_required": true,

  "runner": "local",

  "requires_local_runner": true,

  "preferred_agent_slug": "codex",

  "preferred_model": "gpt-5",

  "requested_model_label": "ChatGPT Codex",

  "reasoning_effort": "high",

  "project_path": "/ruta/local/autorizada",

  "working_folder": ".",

  "required_targets": ["proyecto-local"],

  "depends_on": [123, 124],

  "acceptance_criteria": ["Criterio de aceptacion"],

  "tests": ["Prueba esperada"],

  "blocked_fallback": "Si no hay runner local activo, bloquear con causa concreta.",

  "completion": {

    "next_status": "review",

    "requires_evidence": true

  }

}

No incluyas secretos en el contrato.

Estructura del plan importado

El plan que se crea en Komandesk no deberia ser una copia plana del CSV. Debe ordenar el trabajo para que se pueda ejecutar, revisar y auditar.

Estructura recomendada:

Titulo: nombre del producto o proyecto y ciclo.
Objetivo: resultado del ciclo.
Estado: active si sustituye al plan actual.
Fases: una por epica o bloque operativo.
Guardrails: reglas de seguridad, ejecucion y revision.
Fuente: rutas o referencias del CSV/Markdown original.
Politica de ejecucion: next primero, queued solo tras preflight.

Cada fase debe incluir:

source_id: id estable de origen;
semana o bloque temporal;
nombre;
objetivo;
alcance;
definicion de hecho;
tareas hijas;
estimacion total;
pruebas;
riesgo;
mitigacion;
si requiere deploy;
criterio para pasar a la siguiente fase.

Ejemplo conceptual:


{

  "source_id": "P30-E01",

  "week": "S1",

  "name": "Base operativa",

  "objective": "Dejar preparado el proyecto para ejecutar con seguridad.",

  "scope": ["plan", "tareas", "specs", "target local"],

  "done_definition": [

    "Hay un solo plan activo.",

    "Todas las tareas tienen spec.",

    "No hay tareas en queued."

  ],

  "estimate_hours": 24,

  "deploy_required": true,

  "risk": "Ejecutar antes de tener runner fresco.",

  "mitigation": "Mantener tareas en next hasta preflight.",

  "tasks": [

    {

      "source_id": "P30-E01-T01",

      "title": "Crear tablero operativo",

      "status": "next",

      "execution": "auto",

      "runner": "local",

      "model": "gpt-5"

    }

  ]

}

Como transformar epicas en fases

Una epica del backlog debe convertirse en fase si:

agrupa varias tareas dependientes;
tiene un objetivo verificable;
puede cerrarse con evidencia;
representa una semana, milestone o bloque de trabajo;
tiene riesgos propios.

No conviertas cada tarea en fase. Eso crea planes largos y poco utiles.

Tampoco metas todo en una sola fase. Si todo depende de todo, el plan no ayuda a decidir por donde empezar.

Como crear buenas tareas desde el plan

Al importar o crear manualmente, cada tarea debe poder leerse de forma independiente.

Una buena tarea derivada del plan debe tener:

titulo accionable;
descripcion con contexto suficiente;
fase padre;
estimacion;
prioridad;
dependencias;
criterio de aceptacion;
prueba;
estado inicial;
modo de ejecucion;
agente/perfil;
modelo operativo;
target si toca entorno o disco;
spec o brief;
fallback si no puede continuar.

Checklist antes de crearla:

La tarea tiene un unico resultado principal.
No mezcla discovery, implementacion y deploy si son riesgos distintos.
Se puede verificar sin interpretar intenciones.
Tiene una salida esperada: done, review o waiting.
Si requiere humano, no queda en queued.
Si requiere runner local, no queda en queued hasta heartbeat fresco.
Si depende de otra tarea, la dependencia esta en el contrato.
Si usa un modelo con nombre comercial, tambien guarda el modelo operativo real.

Ejemplos de tareas buenas y malas

Mala:

"Validar builders".

Problemas:

no dice que builder;
no dice que escenario;
no dice evidencia;
no dice si puede escribir cambios;
no dice cuando parar.

Buena:

"Validar Bricks create/edit con escenario hero"

Descripcion:

"Ejecutar el escenario hero en Bricks usando tokens y clases globales. Confirmar que no se regenera la pagina completa, que no aparece CSS inline innecesario y que la lectura posterior del arbol coincide con el plan."

Criterios:

"La seccion hero se crea o edita sin perder estructura."
"La verificacion post-write devuelve PASS o bloqueo justificado."
"La salida incluye evidencia de lectura final."

Prueba:

"Comparar plan vs arbol Bricks final y registrar conversion-status."

Estado inicial:

next, no queued, hasta que el runner local este activo.

Granularidad recomendada

Usa estas reglas al dividir:

Si requiere una decision humana distinta, separa tarea.
Si toca otro entorno, separa tarea.
Si tiene otra prueba principal, separa tarea.
Si puede bloquear a otras, separa tarea y crea dependencia.
Si dura mas de medio dia, probablemente es fase o epic.
Si dura menos de 10 minutos y no deja evidencia, probablemente es comentario o checklist.

Ejemplo de division:

Fase: "Reliabilidad builders".
Tarea 1: "Definir bateria comun de escenarios".
Tarea 2: "Validar Bricks create/edit".
Tarea 3: "Validar Elementor create/edit".
Tarea 4: "Validar Gutenberg blocks/patterns".
Tarea 5: "Registrar regresiones visuales".

Cada tarea tiene prueba propia, pero todas responden a la fase.

Definition of ready para importacion

Antes de considerar que una tarea importada esta lista para ejecutar:

tiene spec aprobada;
tiene execution_contract;
tiene blocked_fallback;
tiene dependencias resueltas o declaradas;
tiene target si toca disco, sitio o deploy;
tiene runner requerido identificado;
tiene agente y modelo compatibles;
tiene criterio de aceptacion verificable;
tiene prueba;
no requiere decision humana pendiente.

Si no cumple esto, puede existir en next, pero no debe pasar a queued.

Verificacion automatica

Despues de importar, comprueba:

hay exactamente un plan activo para el proyecto;
el plan anterior quedo archivado si fue sustituido;
el numero de fases coincide con el backlog;
el numero de tareas coincide con el backlog;
cada tarea tiene spec aprobada;
todas las tareas importadas estan en next;
ninguna tarea quedo en queued por accidente;
el target local esta activo;
el perfil/agente esta activo;
no hay runner local fresco si todavia no se ha emparejado;
health y smoke final pasan.

Consulta conceptual:


SELECT

  COUNT(*) FILTER (WHERE status = 'next' AND execution = 'auto') AS ready_tasks,

  COUNT(*) FILTER (WHERE status = 'queued') AS accidental_queue

FROM tasks

WHERE project_id = :project_id

  AND deleted_at IS NULL

  AND execution_contract->>'source' = :import_source;

accidental_queue debe ser 0 hasta que el runner local este listo.

Pasar de preparado a ejecutable

Solo pasa tareas de next a queued cuando:

el runner local aparece como active;
last_seen_at es reciente;
OPS_RUNNER_ALLOWED_PATHS contiene la ruta del proyecto;
SUPPORTED_AGENT_SLUGS contiene el agente requerido;
SUPPORTED_MODELS contiene o equivale al modelo requerido;
el doctor del runner pasa en modo online;
la primera tarea es pequena y reversible.

Empieza por una tarea de preflight o por la primera tarea menos peligrosa. No empieces por conversiones, deploys, borrados o migraciones.

Procedimiento manual equivalente

Si prefieres hacerlo sin importacion automatica:

Abre el workspace correcto.
Abre o crea el proyecto.
Archiva el plan activo anterior si el nuevo ciclo lo sustituye.
Crea el nuevo plan con fases y criterios de QA.
Crea el target local desde Readiness o Despliegues.
Crea el perfil o subagente que ejecutara el trabajo.
Crea cada tarea en next.
Marca execution = auto solo cuando el contrato este completo.
Anade spec aprobada a cada tarea.
Anade dependencias entre tareas.
Registra estimacion de horas.
Crea una tarea de control para la importacion manual.
Registra el tiempo invertido.
Ejecuta la verificacion.
Empareja el runner local.
Ejecuta primero un preflight.
Si pasa, mueve una tarea a queued.

Cierre por fase

Cada fase deberia cerrarse con:

tareas en done o decision documentada;
evidencias en la tarea;
tiempo registrado;
pruebas ejecutadas;
riesgos pendientes;
changelog o docs actualizadas;
deploy solo si la fase lo requiere.

Si una fase no puede desplegarse, documenta la razon y deja la siguiente tarea en waiting, no en done.

Errores comunes

importar directo a queued;
no archivar el plan anterior y dejar dos planes contradictorios;
no crear specs;
confundir modelo solicitado con modelo operativo disponible;
crear target local sin runner vivo y asumir que ya se puede ejecutar;
omitir dependencias;
no registrar tiempo de la importacion;
cerrar tareas sin evidencia;
dejar rutas locales privadas en docs publicas.

Resultado esperado

Al terminar, el proyecto debe poder probarse de forma controlada:

el plan esta activo;
las tareas estan listas pero no disparadas;
el runner local sabe que ruta puede tocar;
el humano puede revisar specs antes de ejecutar;
cualquier persona puede reproducir el proceso manualmente si no quiere usar la importacion automatica.