---
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/<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.
