fn_registry/dev/flows/0008-kanban-cpp-and-agent-workflows.md

name, id, status, created, updated, priority, risk, related_issues, apps, trigger, schedule, expected_runtime_s, tags, pattern

name	id	status	created	updated	priority	risk	related_issues	apps	trigger	schedule	expected_runtime_s	tags	pattern
kanban-cpp-and-agent-workflows	0008	pending	2026-05-18	2026-05-18	high	medium	0109 0112 0113 0114 0115 0116 0117 0118 0119	kanban_cpp kanban skill_tree agent_runner_api	ui-button		0	agents workflows dod worktrees cpp kanban llm	realtime-loop

Goal

Montar el stack para que agentes LLM trabajen issues/cards en paralelo, en worktrees aislados, con DoD obligatorio y evidencia adjunta. Tres apps colaboran:

• kanban_cpp (nueva, C++ ImGui) — clon visual de kanban_web con su propio backend Go (copia + operations.db independiente). Tablero pensado para conducir agentes, no humanos.
• skill_tree v2 (existente) — reemplaza el boton Claude fix (que abria terminal wt.exe) por Launch workflow que dispara un run remoto. Anade panel DoD evidence + timeline cross-app.
• agent_runner_api (nueva, service Go) — daemon que persiste workflows, crea worktrees, lanza claude --headless, valida DoD, expone HTTP + SSE. Source of truth de agent_runs.db.

El bucle final: humano clica card en kanban_cpp (o issue en skill_tree) -> agent_runner_api crea worktree auto/<id>-<slug> -> spawn agente -> agente trabaja + adjunta evidencia (screenshot, log, url) por cada item DoD -> humano valida en el panel DoD -> merge TBD a master.

Pre-requisitos

• Backend Go de apps/kanban/ funcional (HTTP API + WS + auth + migrations). YA.
• claude --dangerously-skip-permissions disponible en PATH del runner (host WSL).
• parallel-fix-issues skill como base para worktree spawning. YA.
• Frontmatter canonico de issues/flows (issue 0100). YA.
• Capability group agents definido (o crear).

Arquitectura

┌─────────────────┐      ┌─────────────────┐
│ kanban_cpp      │      │ skill_tree v2   │
│ (C++ ImGui)     │      │ (C++ ImGui)     │
│ Board/Cal/Dash  │      │ Tree + DoD pan  │
│ Agent runs      │      │ Timeline pan    │
│ Worktree mgr    │      │ DoD inspector   │
│ DoD inspector   │      │                 │
└────────┬────────┘      └────────┬────────┘
         │ HTTP+SSE                │ HTTP+SSE
         ├──────────────┬──────────┘
         │              │
         ▼              ▼
┌───────────────┐  ┌───────────────────────┐
│ kanban_cpp    │  │ agent_runner_api      │
│ backend Go    │  │ (service Go, :8486)   │
│ (copia, :8401)│  │ ┌───────────────────┐ │
│ operations.db │  │ │ agent_runs.db     │ │
└───────────────┘  │ │ - workflows       │ │
                   │ │ - runs            │ │
                   │ │ - worktrees       │ │
                   │ │ - dod_items       │ │
                   │ │ - dod_evidence    │ │
                   │ └───────────────────┘ │
                   │ spawn claude headless │
                   │ git worktree add/rm   │
                   │ TBD merge --no-ff     │
                   └───────────────────────┘

Decisiones cerradas con el usuario:

• kanban_cpp y kanban_web tienen backends Go independientes (copia identica, datos separados). NO sync.
• agent_runs.db vive en service nuevo agent_runner_api. Port dedicado (default :8486).
• Workflows = git worktree paralelos. Trunk-based development obligatorio (rama auto/<issue> -> PR -> merge master).
• DoD: declarado en frontmatter (dod_user: + nuevo dod_evidence_schema:), persistido en BD con tabla dod_evidence (un row por evidencia adjunta).

Flow

Trigger 1: humano dispara workflow desde UI

1. En skill_tree clica issue -> boton Launch workflow (sustituye Claude fix).
   • POST http://localhost:8486/api/runs con {issue_id, mode: "fix-issue", dod_items: [...]}.
2. O en kanban_cpp arrastra card a columna Doing (agent) -> mismo endpoint con {card_id, kanban_app: "kanban_cpp"}.
3. agent_runner_api:
   • Crea row en agent_runs (status=pending).
   • git worktree add ../wt-<run_id> -b auto/<issue>-<slug>.
   • Lanza subprocess claude --dangerously-skip-permissions -p "<prompt con DoD items + worktree path>" en background.
   • Devuelve run_id + URL SSE para stream de progreso.

Trigger 2: agente trabaja en worktree

1. Agente lee DoD items del prompt + dev/issues/<id>.md.
2. Por cada item DoD: implementa -> ejecuta -> captura evidencia:
   • Tipo screenshot: wt.exe ... o import -> path PNG en agent_runs/<run_id>/evidence/<item_id>.png.
   • Tipo log: tee output a agent_runs/<run_id>/evidence/<item_id>.log.
   • Tipo url: ruta de service deployado (ej. http://localhost:8401/board).
   • Tipo cmd: comando + stdout esperado, ej. fn doctor cpp-apps -> 0 errors.
3. POST http://localhost:8486/api/runs/<run_id>/evidence por cada item -> persiste en dod_evidence.
4. SSE empuja progress a UIs conectadas (kanban_cpp + skill_tree refrescan timeline).

Trigger 3: humano valida DoD

1. Panel DoD inspector (kanban_cpp + skill_tree): muestra checklist DoD + evidencia por item.
2. Humano aprueba item por item (POST /api/runs/<run_id>/evidence/<id>/validate).
3. Cuando todos validados:
   • agent_runner_api ejecuta cd <main_repo> && git merge --no-ff auto/<issue> (o abre PR Gitea si configurado).
   • Limpia worktree.
   • Status -> done.

Trigger 4: rollback / abort

1. Humano clica Abort en cualquier UI.
2. agent_runner_api: kill subprocess + git worktree remove --force ../wt-<run_id> + git branch -D auto/<issue>.
3. Run status -> aborted.

Sub-issues que abre

#	Titulo	Tipo	Notas
0112	kanban_cpp app + backend copia	app	Scaffolder /new-cpp-app kanban_cpp + cp -r apps/kanban/backend apps/kanban_cpp/backend + 6 panels (Board/Cal/Dash/Runs/Worktrees/DoD). Trio app.md (columns-3 accent #a855f7)
0113	agent_runner_api service + agent_runs.db	app	Service Go :8486, tag service, migrations en apps/agent_runner_api/migrations/ (001 workflows + 002 runs + 003 worktrees + 004 dod_items + 005 dod_evidence)
0114	DoD evidence schema canonico	feature	Anade dod_evidence_schema: al frontmatter de issues/flows. Cada item: {id, kind: screenshot|log|url|cmd, expected, required: bool}. Validator en audit_dod_schema_go_infra
0115	Worktree launcher con DoD	feature	Funcion agent_launch_worktree_go_infra (impure): git worktree add + spawn claude + tail stderr. Reemplaza logica inline de parallel-fix-issues
0116	skill_tree: replace Claude-fix por Launch workflow	feature	Modificar apps/skill_tree/main.cpp. Remove spawn_claude_terminal. Anade POST a :8486/api/runs. Toggle setting legacy_claude_fix para fallback temporal
0117	DoD evidence panel (componente C++ reutilizable)	feature	Nueva funcion dod_evidence_panel_cpp_viz en cpp/functions/viz/. Render screenshots (stb_image), logs (selectable_text), urls (ShellExecute), cmds (output expected vs actual). Reusable kanban_cpp + skill_tree
0118	Agent runs timeline panel	feature	Nueva funcion agent_runs_timeline_cpp_viz. Lee SSE de agent_runner_api, lista runs ordenados por started_at, color por status. Reusable cross-app
0119	kanban_cpp sync issues + flows como cards	feature	Backend lee dev/issues/*.md + dev/flows/*.md, expone 2 boards (Issues + Flows). PATCH frontmatter writes back. Watcher fsnotify. Click Launch invoca agent_runner_api

Issue 0109 (skill_tree roadmap) ya existe -> se actualiza con dependencia hacia 0116/0117/0118.

DoD tecnico (Acceptance: corre + Tecnico: vive solo) se redacta dentro de cada sub-issue. Aqui solo vive el DoD user-facing del flow como capacidad.

Definition of Done (user-facing, 4 surfaces obligatorios)

Flow = capacidad de usuario. DoD tecnico (migrations, e2e_checks, uses_functions, build cross-compile, capability groups) vive en los sub-issues 0110-0116, NO aqui.

• Surface 1 (kanban_cpp board): usuario abre kanban_cpp.exe desde el App Hub, ve board con columnas + cards de su backend independiente. Drag card a columna Doing (agent) arranca un agente; ve barra de progreso en panel Agent runs sin tocar terminal.
• Surface 2 (skill_tree Launch workflow): usuario clica Launch workflow sobre un nodo issue, ve toast run_id=... + nueva entrada en panel Timeline. El boton viejo Claude fix (terminal externa) ya no aparece (o queda detras de feature flag OFF). Cero wt.exe abierto.
• Surface 3 (DoD inspector): usuario abre cualquier run desde kanban_cpp o skill_tree, ve N items DoD con: estado (pending/done/validated/failed), thumbnail screenshot, snippet log, link clickable url, output cmd vs expected. Boton Validate por item; al validarlos todos, el run pasa a merged y el worktree desaparece.
• Surface 4 (Timeline cross-app): panel Timeline en skill_tree muestra runs de skill_tree + kanban_cpp + futuras apps en una sola lista. Filtros por status / app / fecha. Click en run abre el detalle con los items DoD y sus evidencias.

Gotchas

• Backend copia kanban: operations.db independiente. Auth tokens (users table) NO se replican entre apps por defecto — cada app tiene sus usuarios. Decidir si compartir tabla auth o duplicar (decision: duplicar, evita coupling).
• Worktree + pre-commit hooks: comparten .git/hooks/ con main. Si un hook llama scripts via path absoluto, ejecuta version main. Mismo gotcha que autonomous_loop.md -> aplicar fixes EN el worktree, nunca en main.
• claude headless en WSL: --dangerously-skip-permissions necesario; salida a stderr/stdout debe quedar en agent_runs/<run_id>/agent.log para auditoria. NO subir log a repo.
• Screenshots desde WSL apuntan a /mnt/c/... o nombre Windows -> el panel DoD lee paths con wslpath cuando hace falta.
• Trio app.md obligatorio en kanban_cpp/app.md: ver feedback_app_trio_required.md. Sin description + icon.phosphor + icon.accent, hub queda gris.
• dod_user: ya existe en frontmatter (issue 0102) — NO renombrar. Anadimos dod_evidence_schema: como bloque hermano que declara la forma de cada evidencia.
• skill_tree mantiene Claude fix legacy detras de feature flag legacy_claude_fix durante 1-2 semanas para rollback rapido (ver feature_flags.md).

Telemetria esperada

• agent_runner_api registra cada run, cada evidence, cada validate en su propia operations.db (entities + executions). Cross-cut con call_monitor via tag agent_run.
• Metrica Reg % debe SUBIR: agentes en worktree usan funciones del registry para todo (screenshots, log capture, validators). Inline -> proposal automatica.
• Metrica nueva agent_runs.dod_pass_rate = validated_items / total_dod_items por run. Threshold inicial 0.8.