kanban/CHAT_PLAN.md

Plan: Chat lateral con tools sobre todo el kanban

Objetivo

Panel de chat a la derecha (Mantine AppShell.Aside) que conversa con un LLM y manipula el kanban via tool-calling: crear/renombrar/mover/borrar columnas y tarjetas, consultar metricas (tiempo en columna, historial), explicar el board, etc.

Arquitectura

+---------------------------+----------------+
|        Board (DnD)        |   Chat Aside   |
|                           |                |
|   Cols / Cards            |  msg msg msg   |
|                           |  [input...]    |
+---------------------------+----------------+
            |                     |
            v                     v
       /api/...            /api/chat (SSE)
            \                     /
             v                   v
              kanban backend (Go)
                |
                +-- llamadas internas a las
                    mismas funciones del backend
                    (no HTTP loopback)

• No HTTP loopback: el endpoint /api/chat ejecuta los tools llamando directamente a db.* (mismas funciones que usan los handlers HTTP). Cero overhead, cero auth-loop.
• SSE streaming: respuestas + tool_use deltas streamed al frontend para UX viva.
• State sharing: el chat ve y modifica el mismo operations.db que la UI. Tras una mutacion via tool, el frontend hace reload() del board para reflejar cambios.

Backend Go

Nuevo paquete apps/kanban/chat/

Archivo	Responsabilidad
chat.go	Endpoint POST /api/chat con SSE. Loop: send msgs+tools a Claude API, recibe tool_use, ejecuta, reinyecta tool_result, hasta end_turn.
tools.go	Catalogo de tools: nombre, JSON schema, dispatch a db.*.
claude.go	Cliente Claude API (HTTP directo, sin SDK Go porque no hay oficial). Usa infra.HttpPostJSON + streaming manual.

Tool catalog (mapeo 1:1 con la API REST + extras)

Tool name	Input	Output	DB call
list_board	{}	{columns,cards} con time_in_column_ms	ListColumns + ListCardsWithTime
create_column	{name:string}	Column	CreateColumn
rename_column	{id:string, name:string}	{}	UpdateColumn
delete_column	{id:string}	{}	DeleteColumn
reorder_columns	{ids:string[]}	{}	ReorderColumns
create_card	{column_id, requester?, title, description?}	Card	CreateCard
update_card	{id, requester?, title?, description?}	{}	UpdateCard
delete_card	{id}	{}	DeleteCard
move_card	{id, column_id, position?}	{}	MoveCard (calcula ordered_ids si solo position)
card_history	{id}	[{column_name,duration_ms,...}]	CardHistory
find_cards	{query?:string, column_id?:string, requester?:string}	Card[]	filtro en memoria sobre ListCardsWithTime
column_stats	{column_id}	{count, total_time_ms, avg_time_ms, oldest_card_id}	derivado
bulk_create_cards	{column_id, cards:[{requester?,title,description?}]}	Card[]	loop CreateCard

Tools puros (sin escritura) marcados read_only en metadata para mostrar badge "solo lectura" en UI.

Configuracion

• Env vars: ANTHROPIC_API_KEY (obligatoria), KANBAN_CHAT_MODEL (default: claude-sonnet-4-6), KANBAN_CHAT_SYSTEM (opcional, override del system prompt).
• Sistema prompt incluido en el binario:

  Eres asistente del tablero kanban. Antes de modificar, llama list_board para ver el estado. Cuando el usuario nombre tarjetas o columnas, resuelve el id con find_cards/list_board. Confirma cambios destructivos antes de borrar.

• Coste: prompt-caching del system + tools schema (5 min TTL) → llamadas siguientes baratas.

SSE protocol al frontend

event: text
data: "Voy a mover la tarjeta..."

event: tool_use
data: {"id":"toolu_01","name":"move_card","input":{...}}

event: tool_result
data: {"tool_use_id":"toolu_01","ok":true,"result":{...}}

event: text
data: "Hecho. Ahora esta en Doing."

event: done
data: {"stop_reason":"end_turn","usage":{"input_tokens":1234,"output_tokens":56}}

Frontend

Layout

AppShell con aside={{ width: 360, breakpoint: "md" }}. Toggle con icon en header (IconMessageChatbot) — colapsable para no robar espacio en monitores chicos.

Componentes nuevos

Componente	Funcion
ChatPanel.tsx	Lista de mensajes + input. Usa EventSource para SSE.
ChatMessage.tsx	Renderiza turn: texto markdown, tool_use cards (nombre+input pretty-printed), tool_result chips.
useKanbanChat.ts	Hook: estado de turnos, persistencia en localStorage, trigger de onBoardChange (reload) tras cada tool_result exitoso.

Markdown

react-markdown + remark-gfm para tablas/listas en respuestas del LLM.

Botones rapidos en cada tarjeta/columna

ActionIcon "Preguntar al chat sobre esto" inyecta contexto:

Sobre la tarjeta {title} (id {id}): ...

Persistencia chat

Conversaciones por sesion en localStorage (clave kanban_chat_v1). NO se persiste en SQLite por ahora — es state efimero. Si en el futuro se quiere historico → tabla chat_messages en operations.db.

Seguridad

• Tools de borrado (delete_column, delete_card) requieren confirmacion explicita en el system prompt. Si el LLM las invoca sin confirmar, el frontend abre modal de confirmacion antes de pasar el resultado al loop.
• ANTHROPIC_API_KEY solo en backend, NUNCA expuesta al frontend.

Hitos (orden de ejecucion sugerido)

1. Tools.go + tests: catalogo + dispatch puro Go, sin LLM. Probar con curl manual.
2. Endpoint /api/chat no streaming: request → response sincrono. Validar Claude API + tool loop.
3. Streaming SSE.
4. ChatPanel UI + useKanbanChat.
5. Toggle aside + layout responsive.
6. Confirmacion de tools destructivos.
7. Botones contextuales en cards/columns.

Funciones del registry a delegar a fn-constructor (registry-first)

Antes de codear el chat, crear estas primitivas reutilizables:

ID	Lenguaje	Proposito
claude_messages_call_go_infra	Go	Wrapper sobre POST https://api.anthropic.com/v1/messages con tools, system, prompt-caching. Impure, error_type.
claude_messages_stream_go_infra	Go	Idem pero con SSE streaming, retorna canal de eventos. Impure.
sse_writer_go_infra	Go	Helper para escribir SSE eventos en http.ResponseWriter (set headers, flusher, format event:/data:). Pure factory.

Estas tres son utiles en cualquier app que necesite chat o LLM tools — no se quedan en el kanban.

Decisiones pendientes (preguntar al usuario antes de codear)

1. Modelo: claude-opus-4-7 (mas capaz, mas caro) vs claude-sonnet-4-6 (default razonable) vs claude-haiku-4-5 (rapido, barato).
2. Streaming: empezar simple (request/response sincrono) o ir directo a SSE.
3. Persistencia chat: solo localStorage o tambien tabla en operations.db para historico cross-session.
4. Confirmaciones destructivas: bloqueo en frontend o solo via prompt? Si bloqueo, ¿qué define "destructivo"?
5. Limite de turnos por sesion: para evitar tool-loops infinitos, cap (ej. 20 iteraciones por mensaje del usuario).