egutierrez
b9716a7cd6
Snapshot de WIP acumulado de sesiones previas antes de merge wave 1 del flow 0008 (kanban_cpp + agent_runner_api + DoD schema). Incluye: - dev/flows/0008-kanban-cpp-and-agent-workflows.md - dev/issues/0112-0119*.md (7 sub-issues) - WIP previo en cmd/fn/doctor.go, registry/*, modules/, cpp/, etc. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
158 lines
11 KiB
Markdown
158 lines
11 KiB
Markdown
---
|
|
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.
|