--- name: kanban-cpp-and-agent-workflows id: 0008 status: pending created: 2026-05-18 updated: 2026-05-18 priority: high risk: medium related_issues: [0109, 0112, 0113, 0114, 0115, 0116, 0117, 0118, 0119] apps: - kanban_cpp - kanban - skill_tree - agent_runner_api trigger: ui-button schedule: "" expected_runtime_s: 0 tags: [agents, workflows, dod, worktrees, cpp, kanban, llm] pattern: 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/-` -> 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/` -> 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- -b auto/-`. - Lanza subprocess `claude --dangerously-skip-permissions -p ""` 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/.md`. 2. Por cada item DoD: implementa -> ejecuta -> captura evidencia: - Tipo `screenshot`: `wt.exe ...` o `import` -> path PNG en `agent_runs//evidence/.png`. - Tipo `log`: `tee` output a `agent_runs//evidence/.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//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//evidence//validate`). 3. Cuando todos validados: - `agent_runner_api` ejecuta `cd && git merge --no-ff auto/` (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-` + `git branch -D auto/`. 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//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.