# Manual de proyi-dev
Cómo se usa proyi-dev, para cualquier agente de IA o persona, en cualquier proyecto. Explica la herramienta, no la forma de trabajar de un equipo en particular: cada proyecto puede sumar sus propias reglas encima.
Para cambiar el código de proyi-dev, el punto de partida es el [mapa](mapa.md). El detalle de cada función está en el [README](../README.md).
1. [Qué es proyi-dev](#1-qué-es-proyi-dev)
2. [Conceptos](#2-conceptos)
3. [El flujo recomendado de una tarea](#3-el-flujo-recomendado-de-una-tarea)
4. [Catálogo de herramientas](#4-catálogo-de-herramientas): generado desde el código, con cada herramienta y sus parámetros
## 1. Qué es proyi-dev
proyi-dev es la memoria de un proyecto de software: sus planes, el árbol de tareas de cada plan y, por cada tarea, por qué se hizo, qué se pidió, qué se decidió, qué se aprendió, qué código tocó y con qué commits y PR llegó a main. Todo queda en una base SQLite, versionada con el repositorio.
**Para qué le sirve a un agente:**
- **Saber qué se hizo antes de tocar código.** Una búsqueda o una tarea relacionada dicen qué archivos se tocaron, qué se decidió y qué falló la última vez, sin leer el historial de git.
- **Retomar el trabajo.** El registro de acciones dice qué fue lo último que se hizo, cuándo y quién, aunque la sesión anterior se haya perdido.
- **Saber qué hacer.** La lista de prioridades dice qué sigue, y `get_ready`, qué se puede empezar ya y cuántos agentes pueden trabajar a la vez.
- **Dejar constancia.** Cada decisión, lección, criterio comprobado y archivo explicado queda en su tarea, y el cuerpo del PR sale de ahí.
- **Mostrarle cosas a la persona.** En lugar de pegar listas en el chat, el agente lleva la pestaña de la persona a la vista exacta.
**Cómo se usa:**
| Desde | Cómo |
|---|---|
| Un agente | El servidor MCP (`src/mcp.ts`). Entrega al agente las [herramientas](#4-catálogo-de-herramientas) y unas instrucciones de uso al iniciar la sesión. En Claude Code: `claude mcp add --scope local proyi-dev -- node --disable-warning=ExperimentalWarning <ruta>/proyi-dev/src/mcp.ts` |
| La terminal | Las mismas herramientas: `pnpm proyi-dev <herramienta> --parámetro valor` (`pnpm proyi-dev help` las lista) |
| Una persona | La pestaña del navegador, que se actualiza en vivo. La levanta el MCP (por defecto en `http://localhost:3200`) o `pnpm proyi-dev serve` |
Las herramientas se ejecutan en Node 24, sin dependencias. Un cambio que no cumple una regla (por ejemplo, empezar una tarea sin prepararla) se rechaza con un mensaje que dice qué falta: leerlo y completar eso.
**Este manual y las novedades**, siempre en su versión vigente, desde cualquier proyecto o máquina:
| Desde | Manual | Novedades (qué cambió, por versión) |
|---|---|---|
| Un agente, como recurso del MCP | `proyi-dev://manual` | `proyi-dev://changelog` |
| Un agente, con una herramienta | `get_manual` (con `section`, solo una sección) | `get_changelog` (con `since`, solo lo que cambió desde una versión o una fecha) |
| Cualquiera, en el navegador | `/manual` en la dirección de la pestaña (por defecto `http://localhost:3200/manual`) | `/novedades` |
Las dos páginas son públicas: no piden inicio de sesión, aunque el resto del servidor lo pida.
**Un servidor con inicio de sesión** (por ejemplo, uno publicado en internet): la persona entra con su contraseña en `/entrar`, y un agente, con su propio token en cada pedido, `Authorization: Bearer <token>`. El token lo crea la persona en el servidor (`node src/cli.ts token create "agente 4"`), se ve una sola vez y se puede revocar; ninguna herramienta del MCP lo crea. Sin token, la API responde 401. `GET /api/session` dice si el inicio de sesión está activado. En una PC sin activarlo, nada de esto hace falta.
## 2. Conceptos
### Proyecto
Un repositorio de código con sus planes. Una base puede tener varios proyectos (`list_projects` los da). Con más de uno, cada herramienta necesita `project`.
### Plan
Un objetivo grande, con un título, un ícono, un color (de la paleta de la pestaña), su contexto (de qué trata, el alcance, las decisiones que cruzan sus tareas) y su árbol de tareas. Se nombran P1, P2… Se crean con `add_plan` y se cambian con `update_plan`. Al crearlo, el agente le elige el ícono y el color que mejor lo representan, con un color distinto del de los planes vecinos, para que la persona los distinga de un vistazo en la barra lateral.
### Tarea, bloques y subtareas
Una tarea es una unidad de trabajo que se puede terminar y revisar sola, en su rama y su PR. Se nombra con el plan y su número: **P1-3.4** es la tarea 4 del bloque 3 del plan 1.
- Un **bloque** es una tarea con subtareas (P1-3). No tiene estado ni puntos propios: salen de sus subtareas. Lo que se le anota a un bloque, por ejemplo un bloqueo, aplica a todas sus tareas.
- Las **subtareas** pueden tener a su vez subtareas, a cualquier profundidad.
- Los **puntos** miden la complejidad estimada, en la escala 1, 2, 3, 5, 8, 13. Una tarea que pasaría de 13 se divide.
- El **origen** dice de dónde salió: `request` (un pedido de la persona), `bug` (algo que no funciona como debería, aunque lo reporte la persona) o `proposal` (una propuesta del agente).
- El **valor** dice cuánto aporta, relativo a las demás: un nivel del 1 al 5, en qué dimensiones (`experience`, `goal`, `technical`, `risk`, `learning`) y por qué. Lo asigna el agente al crearla y la persona lo corrige si no está de acuerdo.
Una tarea sola se crea con `add_task`; varias, o un bloque con sus subtareas, con `add_tasks` en una sola llamada.
### Planes de ideas
Un plan con el ícono `idea` no es trabajo en curso: es un conjunto de ideas para conversar. La pestaña los lista aparte, abajo de los demás. Sus tareas quedan por definir y no van a la lista de prioridades. Cuando la idea se vuelve trabajo, se le cambia el ícono con `update_plan`.
### Lista de prioridades
Lo siguiente que hay que hacer, en orden, para todos los proyectos a la vez, como una lista de reproducción. Cada tarea tiene su turno (el 1 es la que sigue).
- `next` es la que se puede tomar ya: la primera **lista para trabajar** y sin bloqueos.
- Una tarea lista se toma sin esperar a que nadie lo pida. Una por definir no se toma: se conversa con la persona.
- Lo que se termina o se borra sale solo de la lista.
- Una tarea lista que no está en la lista (por ejemplo, una que la persona sacó para pausarla) no se ofrece para tomar.
Se lee con `get_priorities` y se cambia con `add_priorities`, `move_priority` y `remove_priorities`. La persona la ve y la ordena en la pestaña.
### Ciclo de vida
```mermaid
stateDiagram-v2
direction LR
state "Por definir · todo" as todo
state "Lista · ready" as ready
state "En progreso · in_progress" as in_progress
state "Hecha · done" as done
[*] --> todo
todo --> ready: preparación completa
ready --> in_progress: se empieza, en su rama
in_progress --> done: cierre completo y PR unido
```
| Estado | Qué quiere decir |
|---|---|
| Por definir (`todo`) | Falta conversarla o prepararla |
| Lista (`ready`) | Definida, preparada y sin dudas: cualquier agente la puede tomar |
| En progreso (`in_progress`) | Desde la primera línea de código hasta que su PR se une |
| Hecha (`done`) | Su PR se unió y su cierre está completo |
En progreso, la tarea pasa por fases que la pestaña muestra (`get_task` con `estimate` dice en cuál va y qué falta para la siguiente): preparando, codificando, cerrando, PR abierto y completa. Con el PR abierto, `waitingFor` dice a quién espera: `person` si le queda un criterio «Aprobación:» sin marcar (no se une hasta que la persona apruebe), `principal` si no (el agente principal revisa el PR y lo une). Volver atrás (devolverla a por definir, reabrir una hecha) no pide nada.
### Preparación y cierre
`update_task` no deja avanzar una tarea sin lo necesario, y dice qué falta.
| | Qué pide | Para |
|---|---|---|
| **Preparación** | por qué (`why`), descripción, puntos, criterios, código que se estima tocar (`code`) y commits estimados (`commitsEstimate`) | pasar a lista o a en progreso |
| **Cierre** | qué se hizo (`what`), esfuerzo real (`effort`) y todos los criterios marcados. Si la tarea tiene rama, además: sus commits (`add_commits`), qué pasó en cada archivo (`explain_files`) y el PR unido (`link_pr`) | darla por hecha |
Sin la preparación, la tarea cuenta como bloqueada (`get_task` con `blockers` lo dice en `unprepared`). Sin el cierre, una en progreso no se puede dar por hecha (`unclosed`). Lo estimado (puntos, commits, archivos) queda frente a lo real (esfuerzo, commits y archivos de sus commits): así se ve cuánto se acertó.
### Lo que documenta una tarea
| Qué | Para qué | Cómo |
|---|---|---|
| Por qué (`why`) | Qué problema resuelve. Es la primera parte del cuerpo del PR | `update_task` |
| Descripción | Lo pedido, lo hecho y cómo se verificó, en Markdown. Se reemplaza entera: leerla antes de cambiarla | `update_task` |
| Qué (`what`) | Una lista corta de lo que se hizo, al cerrarla. Es la segunda parte del cuerpo del PR (campo `pr`) | `update_task` |
| **Criterios** de aceptación | Cosas comprobables que dicen cuándo está terminada. Uno que empieza con «Aprobación:» (con o sin Markdown alrededor, como `**Aprobación:**`) lo aprueba la persona, y el PR no se une hasta que esté marcado | `add_to_task` (`criteria`), `check_criteria` |
| **Decisiones** | Qué se decidió y por qué, una por elemento, con su fecha | `add_to_task` (`decisions`) |
| **Lecciones** | Un problema que apareció: qué pasó, por qué y cómo evitarlo. Se anotan en cuanto pasan y se leen antes de empezar una tarea relacionada | `add_to_task` (`lessons`) |
| **Preguntas** | Algo que tiene que decidir la persona. La tarea queda bloqueada hasta la respuesta, que queda como decisión | `add_to_task` (`questions`), `answer_question` |
| Bloqueos | Las tareas de las que depende. Queda bloqueada mientras alguna no esté hecha | `add_to_task` (`blockedBy`) |
| Código | Las rutas que se estima tocar (una carpeta termina en `/`). Lo real sale de los commits, y cada archivo lleva su explicación | `add_to_task` (`code`), `add_commits`, `explain_files` |
| **Notas** | Recordatorios, ideas o comentarios cortos, cada uno con su autor. Cada autor edita y borra solo las suyas | `add_note`, `edit_note`, `remove_note` |
| **Adjuntos** | Capturas (también las que la persona manda en el chat), archivos y enlaces, con una nota de qué muestran. Los archivos van a `media/` | `attach`, `remove_attachment` |
| Tokens | Lo que consumió en tokens y en dinero. Se mide solo al cerrarla y al unir su PR | `measure_tokens` |
Todo esto se lee con `get_task` (o `get_tasks`, varias a la vez), pidiendo solo los campos necesarios en `fields`. `search` busca por texto en títulos, descripciones y commits, y `get_history` da el registro de acciones de todos los proyectos (sin `project`, cada acción con el suyo), de uno, de un plan o de una tarea.
### Papelera
Lo que se borra no se pierde en el acto: va a la papelera de su proyecto y se puede restaurar durante 30 días. Después se borra para siempre, solo.
| Qué va a la papelera | Con qué se borra | Al restaurarlo |
|---|---|---|
| Una tarea, o un bloque con sus subtareas, con todo lo suyo (criterios, decisiones, lecciones, notas, adjuntos, historial y turno) | `delete_task` o la pestaña | Vuelve a su lugar con su mismo número (que nunca se le da a otra), las que la esperaban vuelven a esperarla y su turno vuelve a la lista |
| Un adjunto (su archivo se queda en `media/` hasta borrarse para siempre) | `remove_attachment` o la pestaña | Vuelve a su tarea, en su lugar, con su archivo |
| Una nota | `remove_note` o la pestaña | Vuelve a su tarea, en su lugar |
| Un elemento de una tarea: criterio (con su marca), decisión, lección, pregunta, código o bloqueo | `remove_from_task` | Vuelve a su lista, en su lugar |
| Una tarea quitada de la lista de prioridades | `remove_priorities` o la pestaña | Vuelve a la lista, en el mismo turno |
- La respuesta de cada herramienta que borra trae `trash`: el id de su entrada, hasta cuándo se guarda y cómo restaurarla.
- `get_trash` dice lo que hay en la papelera de un proyecto: qué era, de dónde, quién lo borró, cuándo y cuántos días le quedan. `restore` con su id lo devuelve.
- Si su tarea o su bloque también están en la papelera, se restaura primero eso (`get_trash` lo dice en `first`, y `restore` en su error). Si su bloque ya no existe, la tarea vuelve al final de su plan, con un número nuevo, y la respuesta lo dice.
- Borrar algo para siempre antes de tiempo, o vaciar la papelera, lo hace solo la persona, desde la página *Papelera* de la pestaña. Los agentes no pueden.
- Borrar, restaurar y borrar para siempre quedan en el historial de la tarea («borró la tarea (a la papelera)», «la restauró de la papelera») y en la actividad.
- Una tarea con commits o PR, en progreso o hecha (o un bloque con alguna así) no se borra: su historia se conserva.
### Agentes y trabajo en paralelo
El ajuste **Agentes a la vez** (`agents`, en Ajustes de la pestaña) dice cuántas tareas pueden estar en progreso al mismo tiempo, en todos los proyectos.
- `get_ready` sin `project` dice cuántos lugares quedan libres (`free`) y qué tomar ya (`take`): las listas y sin bloqueos, en el orden de la lista de prioridades. También avisa qué tareas comparten código estimado (`overlaps`, `sharesCodeWith`): es solo un aviso, los conflictos se resuelven al unir.
- Cuando quedan lugares y hay tareas para tomar, la respuesta de cualquier herramienta trae el aviso de lugares libres.
- El **agente principal** lanza un subagente por tarea, cada uno en su propio worktree de git. Cada subagente toma un lugar y se llama **agente 1**, **agente 2**…: lo pasa en `agent` en cada llamada, y su nombre queda en la actividad, el historial y *Trabajando ahora*. Sin `agent`, la acción es del principal.
- Cada subagente lleva su tarea hasta el PR abierto y lo asocia con `link_pr`, sin unirlo. El principal revisa y une los PR de a uno.
- Todos escriben en la misma base, por el mismo MCP: cada cambio va en una transacción, así dos agentes que cambian el mismo plan no se pisan.
- Dos tareas van una después de otra solo si tocan la misma parte (la misma función o pantalla, o las dos cambian el esquema de la base) o si una depende de la otra (`blockedBy`).
- Un subagente que necesita probar la interfaz levanta su propio servidor en otro puerto (`PROYI_DEV_PORT`) con una copia de la base (`PROYI_DEV_DATA`), en una carpeta que el sistema no borre sola. Nunca usa el puerto de la persona ni el de la vista previa.
`get_settings` da los ajustes y los perfiles de personas y agentes (nombre, tipo, color), para saber quién es quién.
### La pestaña
La interfaz de la persona: una página del navegador, por defecto en `http://localhost:3200`, que se actualiza sola cuando cambia la base (la cambie el MCP, la línea de comandos u otra sesión).
- Muestra los planes como árbol o tablero, el detalle de cada tarea por secciones, la lista de prioridades, *Trabajando ahora* (en qué está cada agente) y, en vivo, cada consulta que hace un agente.
- Con *Seguir* encendido, la pestaña abre sola la tarea que el agente está tocando, en la sección que cambió.
- La persona también trabaja desde ahí: responde preguntas, marca criterios (también los de aprobación), cambia el valor, escribe notas, adjunta archivos, ordena la lista de prioridades y cambia los ajustes.
- La página *Papelera* de cada proyecto (abajo en la barra de los planes, o desde Ajustes) muestra lo borrado, con *Restaurar*, *Borrar para siempre* y *Vaciar la papelera*.
- `show_to_user` lleva la pestaña a una vista exacta (un plan, una tarea con ciertas secciones, una búsqueda, la lista de prioridades, la cronología de lo terminado, con su orden y sus filtros, o la papelera) con un mensaje corto de por qué. Es la forma de mostrarle algo a la persona, en lugar de pegarlo en el chat.
- `get_user_view` dice qué está mirando la persona: sirve cuando habla de «esto».
### La vista previa
Para revisar lo visual de una tarea sin cambiar de pestaña. `preview` con una tarea arranca, en un puerto interno (por defecto el 3211, que nadie abre a mano), el servidor con el código del worktree de su rama y una copia de la base. La pestaña de la persona pasa a mostrar ese servidor, con una franja sutil arriba, en azul claro, «Vista previa de … · datos de prueba» y un botón para volver. En la franja, el código y el título de la tarea son un enlace que la abre en la pestaña. `preview main` (o unir el PR) la apaga y la pestaña vuelve a main con los datos reales. Si el servidor interno no responde, la pestaña sirve main.
### En remoto
proyi-dev también puede guardar los datos en un servidor (por ejemplo `https://proyi.dev`) en lugar de la máquina donde trabajan los agentes. Entonces el MCP se conecta con dos variables, `PROYI_DEV_URL` (la dirección del servidor) y `PROYI_DEV_TOKEN` (el token de un agente, que se crea en el servidor), y no abre ninguna base local: pide las herramientas al servidor y le reenvía cada llamada. Para el agente casi nada cambia:
- Las herramientas, sus argumentos y sus respuestas son los mismos. La persona mira la pestaña del servidor: `show_to_user`, `get_user_view` y la actividad van allá.
- Lo que solo existe en la máquina del agente lo resuelve el MCP allí y lo manda: git (`add_commits`, `set_project_repo`, con la carpeta del repo en esa máquina), `gh` (`link_pr`, `sync_prs`), el archivo o la captura de `attach` y los registros de Claude Code para los tokens (`measure_tokens`). Solo eso: nada más de la máquina sale de ella.
- `preview` no aplica en remoto: la vista previa es para construir proyi-dev en una máquina, con su MCP local.
- Cada agente sigue diciendo su nombre en `agent`; sin él, la acción queda a nombre del token.
- Lo que se escribe queda en el servidor al momento: no hay base que guardar en git.
Cómo registrar el MCP en remoto en cada editor, con la tabla de qué hace cada herramienta: la guía de instalación del repositorio.
## 3. El flujo recomendado de una tarea
Desde que nace hasta que se da por hecha. Cada paso dice con qué herramienta.
1. **Ubicarse.** Al empezar una sesión: leer la metodología del repositorio (`METODOLOGIA.md`, que el MCP entrega al final de sus instrucciones), `get_history` (lo último que se hizo; sin `project`, de todos los proyectos), `get_changelog` con `since` (qué cambió en proyi-dev desde la última sesión) y `get_priorities` o `get_ready` sin `project` (qué sigue). Antes de tocar código: `search` por tema y `get_task` de las tareas relacionadas, con `fields` como `code`, `decisions` y `lessons`.
2. **Crearla.** Cada pedido o idea nueva va como tarea: `add_task` (o `add_tasks`) con su título, por qué, origen, valor y puntos, y a la lista de prioridades con `add_priorities`, para que la persona la vea y la ordene. Si nace de una captura, se adjunta con `attach`.
3. **Definirla.** Si hace falta que la persona decida algo: `add_to_task` con `questions`, y preguntárselo también. Su respuesta va con `answer_question` y queda como decisión. Lo que la persona diga de la tarea va a su descripción (`update_task`).
4. **Prepararla.** `add_to_task` con `criteria` (comprobables) y `code` (rutas que se estima tocar), y `update_task` con `points`, `commitsEstimate` y la descripción. Si depende de otra, `blockedBy`. Con todo eso, `update_task` con `status: "ready"`.
5. **Empezarla.** `start_branch` da el nombre de la rama y el comando para crearla desde main al día. Se crea la rama y, antes de escribir la primera línea, `update_task` con `status: "in_progress"`.
6. **Trabajarla.** Mientras se programa:
- cada decisión importante, con `add_to_task` (`decisions`);
- cada problema o error, en cuanto aparece, con `add_to_task` (`lessons`);
- cada criterio, al comprobarlo, con `check_criteria`;
- lo que conviene que la persona vea, con `show_to_user`.
7. **Cerrarla.** En este orden:
1. los commits en la rama, y `add_commits` con sus hashes;
2. `explain_files`: qué cambió en cada archivo y por qué, en palabras simples;
3. `update_task` con `what`, `effort` y la descripción al día (qué se hizo, por qué y cómo se verificó), sin cambiar el estado;
4. `check_criteria` con los que falten;
5. `git push` de la rama, el PR con el cuerpo del campo `pr` (`get_task` con `fields: ["pr"]`) y `link_pr` para asociarlo.
`get_task` con `estimate` dice qué falta del cierre. Con el PR abierto, la tarea sigue en progreso.
8. **Revisarla y unirla.** Si tiene algo visual, `preview` con la tarea para que la persona lo vea. Si lleva un criterio «Aprobación:», el PR espera a que esté marcado. Al unir el PR: `link_pr` (lo deja como unido y agrega el commit de main), `update_task` con `status: "done"` (mide sus tokens solo) y `preview main` si estaba en la vista previa.
9. **Seguir.** La respuesta de `update_task` al darla por hecha trae `next`: los lugares libres y qué tomar ya. Se toma lo que diga, o se consulta `get_ready`.
**La base y los adjuntos en git.** La base (`data/proyi-dev.db`) y `media/` se versionan con el repositorio, pero git no puede unir dos versiones de una base. Por eso no se commitean en la rama de una tarea: el MCP las escribe en la copia de trabajo y se commitean desde main, en un commit propio.
**Consejos:**
- Pedir solo los campos necesarios (`fields`): una tarea completa es larga. `get_tree` con `depth: 1` y `fields: ["title", "status", "points"]` alcanza para ubicarse en un plan.
- Si una herramienta rechaza un cambio, el mensaje dice qué falta: completarlo, no buscar otro camino.
- Un campo, una sección o una herramienta que no existe da un error con el más parecido y los válidos: `get_plan` sugiere `get_tree`, y el campo `commitsEstimate`, `estimate` (que trae los commits estimados y los reales).
- Sin el MCP conectado, la línea de comandos tiene las mismas herramientas y respuestas: `node --disable-warning=ExperimentalWarning src/cli.ts <herramienta> --argumento valor` desde la raíz del repo de proyi-dev ([instalación](instalacion.md#sin-mcp-la-línea-de-comandos)).
- Las respuestas incluyen avisos (`warning`) cuando a una tarea le falta algo, por ejemplo su valor o su por qué.
## 4. Catálogo de herramientas
Se genera desde el código (`TOOLS` en `src/tools.ts`, con `src/manual.ts`): cada herramienta con su descripción y sus parámetros. Al cambiar o agregar una herramienta, `pnpm proyi-dev manual` lo pone al día; un test falla si queda desfasado.
<!-- catalogo:inicio · lo genera `pnpm proyi-dev manual` desde src/tools.ts: no editar a mano -->
42 herramientas. Las mismas por el MCP y por la línea de comandos (`pnpm proyi-dev <herramienta> --parámetro valor`). Todas aceptan además `agent` (texto): Quién hace la acción: principal (el agente principal, por defecto) o agente N (el subagente del lugar N de Agentes a la vez, que el principal le asigna al lanzarlo). Queda en el aviso de Seguir, la actividad, el historial y Trabajando ahora.
- **Ubicarse y consultar**: [`list_projects`](#list_projects), [`get_tree`](#get_tree), [`get_task`](#get_task), [`get_tasks`](#get_tasks), [`search`](#search), [`get_history`](#get_history), [`get_settings`](#get_settings), [`get_manual`](#get_manual), [`get_changelog`](#get_changelog)
- **Lista de prioridades y trabajo en paralelo**: [`get_priorities`](#get_priorities), [`add_priorities`](#add_priorities), [`move_priority`](#move_priority), [`remove_priorities`](#remove_priorities), [`get_ready`](#get_ready)
- **Crear y cambiar planes y tareas**: [`add_plan`](#add_plan), [`update_plan`](#update_plan), [`add_task`](#add_task), [`add_tasks`](#add_tasks), [`update_task`](#update_task), [`add_to_task`](#add_to_task), [`remove_from_task`](#remove_from_task), [`answer_question`](#answer_question), [`check_criteria`](#check_criteria), [`move_task`](#move_task), [`delete_task`](#delete_task)
- **Notas y adjuntos**: [`add_note`](#add_note), [`edit_note`](#edit_note), [`remove_note`](#remove_note), [`attach`](#attach), [`remove_attachment`](#remove_attachment)
- **Papelera**: [`get_trash`](#get_trash), [`restore`](#restore)
- **Git, GitHub y tokens**: [`set_project_repo`](#set_project_repo), [`start_branch`](#start_branch), [`add_commits`](#add_commits), [`explain_files`](#explain_files), [`link_pr`](#link_pr), [`sync_prs`](#sync_prs), [`measure_tokens`](#measure_tokens)
- **La pestaña de la persona**: [`show_to_user`](#show_to_user), [`get_user_view`](#get_user_view), [`preview`](#preview)
### Ubicarse y consultar
#### `list_projects`
Solo consulta. Proyectos con sus planes y el avance de cada plan (progress): tasks, las tareas hechas y totales (las que no tienen subtareas); percent, el porcentaje por tareas, que no llega a 100 mientras falte alguna; y points, los puntos hechos y totales, con unestimated, cuántas tareas no tienen puntos y no suman.
Sin parámetros (además de `agent`).
#### `get_tree`
Solo consulta. Árbol de tareas de un plan con solo los campos pedidos. Para ubicarse rápido: fields [title, status, points] y depth 1 (solo bloques); para ver todo, más campos.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `plan` | texto | sí | Plan, por ejemplo P1 |
| `fields` | lista de: `title`, `status`, `origin`, `points`, `value`, `why`, `what`, `pr`, `estimate`, `github`, `progress`, `commits`, `code`, `decisions`, `criteria`, `lessons`, `questions`, `blockers`, `turn`, `history`, `attachments`, `notes`, `tokens`, `description`, `context`, `path` | | Campos de cada tarea: title, status (todo: por definir, ready: lista para trabajar, in_progress o done), origin (request: pedido de la persona, bug o proposal: propuesta del agente), value (cuánto aporta: level de 1 a 5, dimensions y reason, o null si no lo tiene), why (el por qué), what (el qué: lo que se hizo), pr (el cuerpo del PR: por qué + qué, listo para GitHub), estimate (estimado frente a real: puntos y esfuerzo, commits, archivos, missing: lo que falta para empezar y para cerrar, y phase: en qué fase va una en progreso, preparing, coding, closing, review o complete, con lo que falta para la siguiente), github (su rama; pushed, si ya está en GitHub: se sube al crear el PR, y mientras no, branchUrl es null; y su PR: número, dirección y estado), points, progress (avance: tasks, tareas hechas y totales; percent, por tareas, nunca 100 con alguna sin hacer; points, puntos hechos y totales, con unestimated, cuántas no tienen puntos), commits, decisions (decisiones importantes, con su fecha), criteria (criterios de aceptación, con done), lessons (lecciones aprendidas, con su fecha), blockers (bloqueos: blocked, waitingFor, blockedBy con el estado de cada una, inherited de sus bloques y blocks, a quién bloquea; waitingForAnswer, cuántas preguntas esperan a la persona; unprepared, lo que le falta de la preparación para desarrollo: sin ella también está bloqueada; unclosed, en las en progreso, lo que les falta del cierre: sin él no se puede dar por hecha), questions (preguntas abiertas para la persona, con su número), turn (su turno en la lista de prioridades, o null), attachments (adjuntos: capturas, archivos y enlaces, con su nota; la ruta de un archivo es media/… desde la raíz del repositorio y se puede leer), notes (notas a mano, con su id, su autor: edwinfmesa la persona o claude el agente, y cuándo se escribieron), tokens (los tokens que consumió: respuestas, entrada, salida, caché leída y escrita, costo en USD y por modelo; se miden al cerrarla y al unir su PR; en un bloque, la suma), history (cuándo se creó, cuándo cambió por última vez y sus acciones), code (código involucrado: estimated, lo que se estimó tocar, y actual, lo que tocaron sus commits, con estado A/M/D/R; cada uno marca si coincide con el otro, y summary resume las diferencias), description (Markdown), context (contexto del plan), path (bloques que la contienen). Pedir solo los necesarios |
| `depth` | número | | Niveles a incluir (1 = solo los bloques). Por defecto, todos |
#### `get_task`
Solo consulta. Una tarea (P1-3.4) o un bloque (P1-3) con solo los campos pedidos. Por defecto: title, status, points, description y commits. Un bloque incluye sus subtareas.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `ref` | texto | sí | Tarea, por ejemplo P1-3.4 |
| `fields` | lista de: `title`, `status`, `origin`, `points`, `value`, `why`, `what`, `pr`, `estimate`, `github`, `progress`, `commits`, `code`, `decisions`, `criteria`, `lessons`, `questions`, `blockers`, `turn`, `history`, `attachments`, `notes`, `tokens`, `description`, `context`, `path` | | Campos de cada tarea: title, status (todo: por definir, ready: lista para trabajar, in_progress o done), origin (request: pedido de la persona, bug o proposal: propuesta del agente), value (cuánto aporta: level de 1 a 5, dimensions y reason, o null si no lo tiene), why (el por qué), what (el qué: lo que se hizo), pr (el cuerpo del PR: por qué + qué, listo para GitHub), estimate (estimado frente a real: puntos y esfuerzo, commits, archivos, missing: lo que falta para empezar y para cerrar, y phase: en qué fase va una en progreso, preparing, coding, closing, review o complete, con lo que falta para la siguiente), github (su rama; pushed, si ya está en GitHub: se sube al crear el PR, y mientras no, branchUrl es null; y su PR: número, dirección y estado), points, progress (avance: tasks, tareas hechas y totales; percent, por tareas, nunca 100 con alguna sin hacer; points, puntos hechos y totales, con unestimated, cuántas no tienen puntos), commits, decisions (decisiones importantes, con su fecha), criteria (criterios de aceptación, con done), lessons (lecciones aprendidas, con su fecha), blockers (bloqueos: blocked, waitingFor, blockedBy con el estado de cada una, inherited de sus bloques y blocks, a quién bloquea; waitingForAnswer, cuántas preguntas esperan a la persona; unprepared, lo que le falta de la preparación para desarrollo: sin ella también está bloqueada; unclosed, en las en progreso, lo que les falta del cierre: sin él no se puede dar por hecha), questions (preguntas abiertas para la persona, con su número), turn (su turno en la lista de prioridades, o null), attachments (adjuntos: capturas, archivos y enlaces, con su nota; la ruta de un archivo es media/… desde la raíz del repositorio y se puede leer), notes (notas a mano, con su id, su autor: edwinfmesa la persona o claude el agente, y cuándo se escribieron), tokens (los tokens que consumió: respuestas, entrada, salida, caché leída y escrita, costo en USD y por modelo; se miden al cerrarla y al unir su PR; en un bloque, la suma), history (cuándo se creó, cuándo cambió por última vez y sus acciones), code (código involucrado: estimated, lo que se estimó tocar, y actual, lo que tocaron sus commits, con estado A/M/D/R; cada uno marca si coincide con el otro, y summary resume las diferencias), description (Markdown), context (contexto del plan), path (bloques que la contienen). Pedir solo los necesarios |
#### `get_tasks`
Solo consulta. Varias tareas (P1-3.4) o bloques en una sola llamada, con los campos pedidos (los mismos de get_task). Las que no existen van en missing.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `refs` | lista de textos | sí | Tareas, por ejemplo ["P1-3.4", "P1-5"] |
| `fields` | lista de: `title`, `status`, `origin`, `points`, `value`, `why`, `what`, `pr`, `estimate`, `github`, `progress`, `commits`, `code`, `decisions`, `criteria`, `lessons`, `questions`, `blockers`, `turn`, `history`, `attachments`, `notes`, `tokens`, `description`, `context`, `path` | | Campos de cada tarea: title, status (todo: por definir, ready: lista para trabajar, in_progress o done), origin (request: pedido de la persona, bug o proposal: propuesta del agente), value (cuánto aporta: level de 1 a 5, dimensions y reason, o null si no lo tiene), why (el por qué), what (el qué: lo que se hizo), pr (el cuerpo del PR: por qué + qué, listo para GitHub), estimate (estimado frente a real: puntos y esfuerzo, commits, archivos, missing: lo que falta para empezar y para cerrar, y phase: en qué fase va una en progreso, preparing, coding, closing, review o complete, con lo que falta para la siguiente), github (su rama; pushed, si ya está en GitHub: se sube al crear el PR, y mientras no, branchUrl es null; y su PR: número, dirección y estado), points, progress (avance: tasks, tareas hechas y totales; percent, por tareas, nunca 100 con alguna sin hacer; points, puntos hechos y totales, con unestimated, cuántas no tienen puntos), commits, decisions (decisiones importantes, con su fecha), criteria (criterios de aceptación, con done), lessons (lecciones aprendidas, con su fecha), blockers (bloqueos: blocked, waitingFor, blockedBy con el estado de cada una, inherited de sus bloques y blocks, a quién bloquea; waitingForAnswer, cuántas preguntas esperan a la persona; unprepared, lo que le falta de la preparación para desarrollo: sin ella también está bloqueada; unclosed, en las en progreso, lo que les falta del cierre: sin él no se puede dar por hecha), questions (preguntas abiertas para la persona, con su número), turn (su turno en la lista de prioridades, o null), attachments (adjuntos: capturas, archivos y enlaces, con su nota; la ruta de un archivo es media/… desde la raíz del repositorio y se puede leer), notes (notas a mano, con su id, su autor: edwinfmesa la persona o claude el agente, y cuándo se escribieron), tokens (los tokens que consumió: respuestas, entrada, salida, caché leída y escrita, costo en USD y por modelo; se miden al cerrarla y al unir su PR; en un bloque, la suma), history (cuándo se creó, cuándo cambió por última vez y sus acciones), code (código involucrado: estimated, lo que se estimó tocar, y actual, lo que tocaron sus commits, con estado A/M/D/R; cada uno marca si coincide con el otro, y summary resume las diferencias), description (Markdown), context (contexto del plan), path (bloques que la contienen). Pedir solo los necesarios |
#### `search`
Solo consulta. Busca texto (sin distinguir mayúsculas ni tildes) en títulos, descripciones y commits de todas las tareas. Devuelve las coincidencias con un fragmento y los campos pedidos.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `query` | texto | sí | |
| `plan` | texto | | Limitar a un plan, por ejemplo P2 |
| `fields` | lista de: `title`, `status`, `origin`, `points`, `value`, `why`, `what`, `pr`, `estimate`, `github`, `progress`, `commits`, `code`, `decisions`, `criteria`, `lessons`, `questions`, `blockers`, `turn`, `history`, `attachments`, `notes`, `tokens`, `description`, `context`, `path` | | Campos de cada tarea: title, status (todo: por definir, ready: lista para trabajar, in_progress o done), origin (request: pedido de la persona, bug o proposal: propuesta del agente), value (cuánto aporta: level de 1 a 5, dimensions y reason, o null si no lo tiene), why (el por qué), what (el qué: lo que se hizo), pr (el cuerpo del PR: por qué + qué, listo para GitHub), estimate (estimado frente a real: puntos y esfuerzo, commits, archivos, missing: lo que falta para empezar y para cerrar, y phase: en qué fase va una en progreso, preparing, coding, closing, review o complete, con lo que falta para la siguiente), github (su rama; pushed, si ya está en GitHub: se sube al crear el PR, y mientras no, branchUrl es null; y su PR: número, dirección y estado), points, progress (avance: tasks, tareas hechas y totales; percent, por tareas, nunca 100 con alguna sin hacer; points, puntos hechos y totales, con unestimated, cuántas no tienen puntos), commits, decisions (decisiones importantes, con su fecha), criteria (criterios de aceptación, con done), lessons (lecciones aprendidas, con su fecha), blockers (bloqueos: blocked, waitingFor, blockedBy con el estado de cada una, inherited de sus bloques y blocks, a quién bloquea; waitingForAnswer, cuántas preguntas esperan a la persona; unprepared, lo que le falta de la preparación para desarrollo: sin ella también está bloqueada; unclosed, en las en progreso, lo que les falta del cierre: sin él no se puede dar por hecha), questions (preguntas abiertas para la persona, con su número), turn (su turno en la lista de prioridades, o null), attachments (adjuntos: capturas, archivos y enlaces, con su nota; la ruta de un archivo es media/… desde la raíz del repositorio y se puede leer), notes (notas a mano, con su id, su autor: edwinfmesa la persona o claude el agente, y cuándo se escribieron), tokens (los tokens que consumió: respuestas, entrada, salida, caché leída y escrita, costo en USD y por modelo; se miden al cerrarla y al unir su PR; en un bloque, la suma), history (cuándo se creó, cuándo cambió por última vez y sus acciones), code (código involucrado: estimated, lo que se estimó tocar, y actual, lo que tocaron sus commits, con estado A/M/D/R; cada uno marca si coincide con el otro, y summary resume las diferencias), description (Markdown), context (contexto del plan), path (bloques que la contienen). Pedir solo los necesarios |
#### `get_history`
Solo consulta. Lo último que se hizo según el registro de acciones (determinista: cada cambio con su hora y quién lo hizo), de lo más nuevo a lo más viejo, con una línea legible por acción. Sin project (o con all), de todos los proyectos, y cada acción dice su proyecto (project); con project, de ese proyecto. Sin ref, todo el proyecto; con ref (y su project), un plan (P1) o una tarea (P1-3.4; si es un bloque, también sus tareas). Para retomar el trabajo: qué fue lo último y cuándo.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Sin él (o con all), de todos los proyectos, cada acción con su proyecto; con ref, hace falta si hay más de uno |
| `ref` | texto | | Plan (P1) o tarea (P1-3.4). Opcional |
| `since` | texto | | Desde cuándo: AAAA-MM-DD o una hora ISO. Opcional |
| `limit` | número | | Cuántas acciones (por defecto 30, hasta 500) |
| `withDetail` | sí o no | | Incluir el detalle de cada acción (por ejemplo, la descripción anterior y la nueva). Por defecto, no |
#### `get_settings`
Solo consulta. Los ajustes de proyi-dev que elige la persona en la pestaña: agents, cuántos agentes pueden trabajar a la vez en tareas distintas (cada uno en su worktree); recording, si se anota la actividad (siempre encendido); prices, el precio de cada modelo en USD por millón de tokens (entrada, salida, caché leída y escrita de 5 min y 1 h), para el costo de los tokens; profiles, los perfiles de personas y agentes (quién es quién): id, el nombre corto que queda como quién hizo cada acción o escribió cada nota; kind, human o agent; color, de la paleta; y hasAvatar, si tiene imagen. La persona los cambia en Ajustes. preview, qué muestra la vista previa en la pestaña de la persona (http://localhost:3200; la cambia la herramienta preview): target (main o la tarea), project, branch, code (la carpeta de su código), data (la de sus datos: la real o la copia), port (el del servidor interno de la tarea), url y since; null si nunca se cambió.
Sin parámetros (además de `agent`).
#### `get_manual`
Solo consulta. El manual de proyi-dev (docs/manual.md, la versión vigente): qué es, sus conceptos, el flujo recomendado de una tarea y el catálogo de herramientas. Entero son unos 60 KB, casi todo el catálogo (las herramientas que el MCP ya da): con section, solo esa sección (por su número o parte de su título). Devuelve el texto en Markdown, las secciones (sections) y la página pública (url). También es el recurso proyi-dev://manual.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `section` | texto | | Una sección: su número (1 a 4) o parte de su título, por ejemplo flujo. Sin ella, el manual entero |
#### `get_changelog`
Solo consulta. Las novedades de proyi-dev (CHANGELOG.md, la versión vigente): qué cambió, por versión (una por jornada de trabajo), la más reciente primero. Con since, solo lo que cambió desde entonces: desde una versión (0.2.0: las más nuevas que ella) o desde una fecha (AAAA-MM-DD: las de ese día en adelante). Para saber, al empezar una sesión, qué cambió desde la última. Devuelve la última versión (latest), cuántas hay (count), cada una con su fecha y su texto en Markdown, y la página pública (url). También es el recurso proyi-dev://changelog.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `since` | texto | | Desde una versión (0.2.0) o una fecha (AAAA-MM-DD). Sin él, todas |
### Lista de prioridades y trabajo en paralelo
#### `get_priorities`
Solo consulta. La lista de prioridades (de todos los proyectos, como una playlist): las tareas que siguen, en orden por turno (el 1 es el que sigue), con su estado, sus puntos y si están bloqueadas. next es la que se puede tomar ya: la primera lista para trabajar (ready) y sin bloqueos. Lo que está en la lista es lo siguiente que hay que hacer; las que están por definir necesitan conversar con la persona.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Solo las de un proyecto (con su turno de la lista completa). Opcional |
#### `add_priorities`
Cambia los datos. Agrega tareas a la lista de prioridades, al final o desde un turno (turn 1 = la siguiente). Un bloque agrega sus tareas pendientes. Las que ya están no se repiten (con turn, se mueven ahí). Devuelve el turno de cada una.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `refs` | lista de textos | sí | Tareas o bloques, por ejemplo ["P1-3.4"] |
| `turn` | número | | Turno donde van (desde 1). Por defecto, al final |
#### `move_priority`
Cambia los datos. Cambia el turno de una tarea en la lista de prioridades (turn 1 = la siguiente).
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `ref` | texto | sí | |
| `turn` | número | sí | Turno nuevo, desde 1 |
#### `remove_priorities`
Cambia los datos. Quita tareas de la lista de prioridades (un bloque quita las suyas). Lo que se termina sale solo. Cada turno quitado va a la papelera del proyecto (trash: su id), y restore la devuelve a la lista en el mismo turno durante 30 días.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `refs` | lista de textos | sí | |
#### `get_ready`
Solo consulta. Qué se puede empezar ya: las tareas listas para trabajar y sin bloqueos (ready, con sus puntos y su código estimado), las que no esperan a otra ni a la persona pero faltan definir con ella o preparar (toDefine, con unprepared: lo que falta de la preparación para desarrollo), las que están en progreso, las bloqueadas con a quién esperan (waitingFor) qué pares comparten código estimado (overlaps: solo un aviso, los conflictos se resuelven al unir), cuántos agentes se pueden usar a la vez (agents, el ajuste), cuántos lugares quedan libres (free: agents menos las tareas en progreso de todos los proyectos) y cuáles tomar ya (take: las listas y sin bloqueos en el orden de la lista de prioridades, hasta llenar los lugares, cada una con sharesCodeWith). Para elegir la siguiente tarea y qué trabajar en paralelo: siempre se toman las de take. Sin project (o con all), de todos los proyectos: take sale de todos en el orden de la lista de prioridades y cada tarea lleva su proyecto; con project, de ese proyecto o de un plan suyo.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Sin él (o con all), de todos los proyectos: take sale de todos, en el orden de la lista de prioridades, cada una con su proyecto |
| `plan` | texto | | Limitar a un plan, por ejemplo P1 (con su project) |
### Crear y cambiar planes y tareas
#### `add_plan`
Cambia los datos. Crea el plan siguiente de un proyecto (P2, P3…), vacío, con un título que diga de qué trata (se ve en la barra lateral de la pestaña), su ícono y su color (los que mejor lo representan) y su contexto (Markdown: de qué trata, el objetivo). Después se le agregan tareas con add_task o add_tasks (parent P2).
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `title` | texto | sí | Un nombre descriptivo, por ejemplo «Imagen corporativa» |
| `icon` | `rocket`, `layers`, `wrench`, `brush`, `gamepad`, `users`, `zap`, `book`, `target`, `compass`, `flask`, `chart`, `heart`, `star`, `flag`, `box`, `idea`, `""` | | Ícono de línea del plan en la barra lateral: rocket, layers, wrench, brush, gamepad, users, zap, book, target, compass, flask, chart, heart, star, flag, box, idea. Sin él, layers. idea está reservado para los planes que son ideas (no trabajo en curso): la pestaña los lista aparte, abajo; sus tareas quedan por definir y no van a la lista de prioridades. Cuando la idea se vuelve trabajo, se le cambia el ícono |
| `color` | `blue`, `sky`, `teal`, `green`, `lime`, `amber`, `orange`, `red`, `pink`, `purple`, `indigo`, `slate`, `""` | | Color del plan, de la paleta de la pestaña (armónica con el azul de la marca): blue (azul), sky (celeste), teal (turquesa), green (verde), lime (lima), amber (ámbar), orange (naranja), red (rojo), pink (rosa), purple (morado), indigo (índigo), slate (gris). Se elige el que mejor lo representa y que no repita el de los planes vecinos. Sin él, uno según su número |
| `context` | texto | | De qué trata el plan, en Markdown |
#### `update_plan`
Cambia los datos. Cambia el título (un nombre descriptivo), el ícono, el color o el contexto (Markdown) de un plan (P2). Lo que no se mande queda como estaba; icon "" o color "" vuelven al de por defecto. Queda en el historial del plan.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `ref` | texto | sí | El plan, por ejemplo P2 |
| `title` | texto | | |
| `icon` | `rocket`, `layers`, `wrench`, `brush`, `gamepad`, `users`, `zap`, `book`, `target`, `compass`, `flask`, `chart`, `heart`, `star`, `flag`, `box`, `idea`, `""` | | Ícono de línea del plan en la barra lateral: rocket, layers, wrench, brush, gamepad, users, zap, book, target, compass, flask, chart, heart, star, flag, box, idea. Sin él, layers. idea está reservado para los planes que son ideas (no trabajo en curso): la pestaña los lista aparte, abajo; sus tareas quedan por definir y no van a la lista de prioridades. Cuando la idea se vuelve trabajo, se le cambia el ícono |
| `color` | `blue`, `sky`, `teal`, `green`, `lime`, `amber`, `orange`, `red`, `pink`, `purple`, `indigo`, `slate`, `""` | | Color del plan, de la paleta de la pestaña (armónica con el azul de la marca): blue (azul), sky (celeste), teal (turquesa), green (verde), lime (lima), amber (ámbar), orange (naranja), red (rojo), pink (rosa), purple (morado), indigo (índigo), slate (gris). Se elige el que mejor lo representa y que no repita el de los planes vecinos. Sin él, uno según su número |
| `context` | texto | | De qué trata el plan, en Markdown (reemplaza el anterior) |
#### `add_task`
Cambia los datos. Agrega una tarea al final de un plan (parent P1) o de un bloque (parent P1-3), con el número siguiente, su origen (request, bug o proposal) y su valor (value: cuánto aporta, de 1 a 5, en qué dimensiones y por qué).
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `parent` | texto | sí | Plan (P1) o bloque (P1-3) |
| `title` | texto | sí | |
| `points` | `1`, `2`, `3`, `5`, `8`, `13` | | |
| `description` | texto | | |
| `origin` | `request`, `bug`, `proposal` | | De dónde salió: request (un pedido de la persona), bug (un error que apareció) o proposal (una propuesta del agente). Siempre explícito en las tareas nuevas |
| `why` | texto | | El por qué de la tarea (Markdown, corto): qué problema resuelve o qué se busca. Se escribe al crearla; es la primera parte del cuerpo del PR |
| `commitsEstimate` | número | | Cuántos commits se estima que tomará (parte de la preparación para desarrollo: sin ella no se puede marcar lista ni empezar) |
| `value` | objeto | | Cuánto aporta la tarea al proyecto: level (1 muy bajo, 2 bajo, 3 medio, 4 alto, 5 muy alto, relativo a las demás), dimensions (en qué aporta, una o varias: experience, la experiencia de quien usa el producto; goal, el objetivo del proyecto; technical, calidad, menos deuda o desarrollo más rápido; risk, evita que algo se rompa o se pierda; learning, aclara algo que no sabíamos) y reason (la justificación, corta). Se asigna al crear cada tarea; al cambiarlo, lo que no se mande queda como estaba |
| `value.level` | `1`, `2`, `3`, `4`, `5` | | |
| `value.dimensions` | lista de: `experience`, `goal`, `technical`, `risk`, `learning` | | |
| `value.reason` | texto | | |
#### `add_tasks`
Cambia los datos. Crea varias tareas en una sola llamada, al final de un plan (parent P1) o de un bloque (parent P1-3): cada una con sus puntos, descripción, estado, valor (value) y lo que la documenta (criteria, decisions, code, lessons). Si una trae children, es un bloque con esas subtareas (a cualquier profundidad; sin puntos ni estado propios). Cada una puede traer blockedBy, las tareas que la bloquean (también otras del mismo lote, con la referencia que van a tener). Una con status ready o in_progress necesita su preparación para desarrollo completa (why, description, points, criteria, code y commitsEstimate). Una con status done necesita su cierre completo (what, effort y criterios marcados), así que una tarea nueva no se crea ya hecha. Todo o nada: si algo es inválido, no se crea ninguna. Hasta 100 tareas.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `parent` | texto | sí | Plan (P1) o bloque (P1-3) |
| `tasks` | lista de objetos | sí | |
| `tasks[].title` | texto | sí | |
| `tasks[].points` | `1`, `2`, `3`, `5`, `8`, `13` | | |
| `tasks[].description` | texto | | |
| `tasks[].status` | `todo`, `ready`, `in_progress`, `done` | | |
| `tasks[].origin` | `request`, `bug`, `proposal` | | De dónde salió: request (un pedido de la persona), bug (un error que apareció) o proposal (una propuesta del agente). Siempre explícito en las tareas nuevas |
| `tasks[].why` | texto | | El por qué de la tarea (Markdown, corto): qué problema resuelve o qué se busca. Se escribe al crearla; es la primera parte del cuerpo del PR |
| `tasks[].what` | texto | | El qué (Markdown): una lista corta de lo que realmente se hizo. Se escribe al cerrarla; es la segunda parte del cuerpo del PR |
| `tasks[].commitsEstimate` | número | | Cuántos commits se estima que tomará (parte de la preparación para desarrollo: sin ella no se puede marcar lista ni empezar) |
| `tasks[].value` | objeto | | Cuánto aporta la tarea al proyecto: level (1 muy bajo, 2 bajo, 3 medio, 4 alto, 5 muy alto, relativo a las demás), dimensions (en qué aporta, una o varias: experience, la experiencia de quien usa el producto; goal, el objetivo del proyecto; technical, calidad, menos deuda o desarrollo más rápido; risk, evita que algo se rompa o se pierda; learning, aclara algo que no sabíamos) y reason (la justificación, corta). Se asigna al crear cada tarea; al cambiarlo, lo que no se mande queda como estaba |
| `tasks[].criteria` | lista de textos | | |
| `tasks[].decisions` | lista de textos | | |
| `tasks[].code` | lista de textos | | |
| `tasks[].lessons` | lista de textos | | |
| `tasks[].blockedBy` | lista de textos | | Tareas que la bloquean (P1-6.3); pueden ser de este mismo lote |
| `tasks[].questions` | lista de textos | | Preguntas para la persona: la bloquean hasta que responde |
| `tasks[].children` | lista de objetos | | Subtareas: la tarea pasa a ser un bloque (sin puntos ni estado propios) |
#### `update_task`
Cambia los datos. Cambia una tarea: título, estado (todo: por definir; ready: lista para trabajar, definida y sin dudas; in_progress o done), origen (request, bug o proposal), por qué (why), qué (what: lista corta de lo que se hizo, al cerrarla), commits estimados (commitsEstimate), esfuerzo real (effort, al cerrarla), valor (value: cuánto aporta, de 1 a 5, en qué dimensiones y por qué; avisa si una tarea pendiente no lo tiene). Rechaza pasarla a lista para trabajar o a en progreso sin la preparación para desarrollo completa (why, description, points, criteria, code y commitsEstimate; se pueden mandar en el mismo cambio los campos de update_task) y dice qué falta; también rechaza darla por hecha sin el cierre completo (what, effort, criterios marcados y, en las tareas con rama, commits reales, explain_files y el PR unido con link_pr; con el PR abierto sigue en progreso) y dice qué falta. Puntos (1, 2, 3, 5, 8, 13); descripción (Markdown; reemplaza la anterior, así que primero leerla con get_task). El estado y los puntos de un bloque salen de sus tareas.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `ref` | texto | sí | |
| `title` | texto | | |
| `status` | `todo`, `ready`, `in_progress`, `done` | | todo (por definir), ready (lista para trabajar), in_progress (en progreso) o done (hecha) |
| `points` | `1`, `2`, `3`, `5`, `8`, `13` | | |
| `description` | texto | | |
| `origin` | `request`, `bug`, `proposal` | | De dónde salió: request (un pedido de la persona), bug (un error que apareció) o proposal (una propuesta del agente). Siempre explícito en las tareas nuevas |
| `why` | texto | | El por qué de la tarea (Markdown, corto): qué problema resuelve o qué se busca. Se escribe al crearla; es la primera parte del cuerpo del PR |
| `what` | texto | | El qué (Markdown): una lista corta de lo que realmente se hizo. Se escribe al cerrarla; es la segunda parte del cuerpo del PR |
| `commitsEstimate` | número | | Cuántos commits se estima que tomará (parte de la preparación para desarrollo: sin ella no se puede marcar lista ni empezar) |
| `effort` | `1`, `2`, `3`, `5`, `8`, `13` | | Puntos de esfuerzo reales, al cerrarla (1, 2, 3, 5, 8, 13): lo que realmente costó, frente a los puntos estimados |
| `value` | objeto | | Cuánto aporta la tarea al proyecto: level (1 muy bajo, 2 bajo, 3 medio, 4 alto, 5 muy alto, relativo a las demás), dimensions (en qué aporta, una o varias: experience, la experiencia de quien usa el producto; goal, el objetivo del proyecto; technical, calidad, menos deuda o desarrollo más rápido; risk, evita que algo se rompa o se pierda; learning, aclara algo que no sabíamos) y reason (la justificación, corta). Se asigna al crear cada tarea; al cambiarlo, lo que no se mande queda como estaba |
| `value.level` | `1`, `2`, `3`, `4`, `5` | | |
| `value.dimensions` | lista de: `experience`, `goal`, `technical`, `risk`, `learning` | | |
| `value.reason` | texto | | |
#### `add_to_task`
Cambia los datos. Agrega a una tarea lo que la documenta, al final de cada lista: code, las rutas del código que se estima tocar (relativas a la raíz del repositorio; una carpeta termina en /; lo real sale de los commits y la tarea muestra las diferencias); decisions, sus decisiones importantes (una por elemento, con el porqué); criteria, sus criterios de aceptación (cosas comprobables; se marcan con check_criteria); lessons, sus lecciones aprendidas (un problema o error que apareció: qué pasó, por qué y cómo evitarlo); blockedBy, las tareas que la bloquean (P1-6.3, de cualquier plan; queda bloqueada mientras alguna no esté hecha; se rechazan ciclos); questions, preguntas para la persona cuando hace falta que decida algo (la tarea queda bloqueada esperando su respuesta; se responden con answer_question).
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `ref` | texto | sí | |
| `code` | lista de textos | | Rutas del código que se estima tocar, por ejemplo src/server.ts o web/ |
| `decisions` | lista de textos | | Decisiones importantes, en Markdown: qué se decidió y por qué |
| `criteria` | lista de textos | | Criterios de aceptación: cada uno algo que se pueda comprobar. Uno que empieza con "Aprobación:" lo aprueba la persona (solo si ella pidió aprobar esa tarea) |
| `lessons` | lista de textos | | Lecciones aprendidas, en Markdown: qué pasó, por qué y cómo evitarlo |
| `blockedBy` | lista de textos | | Tareas que la bloquean, por ejemplo P1-6.3 |
| `questions` | lista de textos | | Preguntas para la persona, una por elemento: qué hay que decidir y, si ayuda, las opciones |
#### `remove_from_task`
Cambia los datos. Quita elementos de una lista de la tarea por su número (desde 1, en el orden en que se ven): code, decisions, criteria, lessons, blockedBy (los bloqueos; su número sale en blockers) o questions (cerrar una pregunta sin respuesta, si ya no hace falta). Cada elemento quitado va a la papelera del proyecto (trash: su id por número) y restore lo devuelve a su lugar durante 30 días.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `ref` | texto | sí | |
| `list` | `code`, `decisions`, `criteria`, `lessons`, `blockedBy`, `questions` | sí | |
| `numbers` | lista de números | sí | |
#### `answer_question`
Cambia los datos. Responde una pregunta abierta de una tarea con lo que decidió la persona (sus palabras): la pregunta se cierra y queda como decisión (pregunta y respuesta, con fecha). Si no quedan preguntas ni otros bloqueos, la tarea se desbloquea.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `ref` | texto | sí | |
| `number` | número | sí | Número de la pregunta (desde 1; sale en questions) |
| `answer` | texto | sí | La respuesta de la persona, en Markdown |
#### `check_criteria`
Cambia los datos. Marca (o con done false, desmarca) criterios de aceptación de una tarea por su número (desde 1), cuando se comprobó que se cumplen.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `ref` | texto | sí | |
| `numbers` | lista de números | sí | |
| `done` | sí o no | | true marca (por defecto), false desmarca |
#### `move_task`
Cambia los datos. Mueve una tarea, o un bloque con sus subtareas, a otro plan (to P2) o bloque (to P1-5) del mismo proyecto: va al final, con el número siguiente libre de su lugar nuevo (un bloque renumera sus subtareas: 4.2 pasa a 3.2). Se lleva todo lo suyo: criterios, decisiones, lecciones, preguntas, bloqueos, commits, código, adjuntos, notas, tokens, rama y PR, su historial y su turno en la lista de prioridades. Las tareas que la esperaban (blockedBy) pasan a esperar su referencia nueva. En el historial quedan los dos lados: «la movió a …» en la referencia vieja y «la movió de … a …» en la nueva. Los archivos adjuntos se quedan donde están en media/ (sus rutas no cambian) y la rama conserva su nombre. Un número no se vuelve a dar: la referencia vieja queda solo en el historial. Se rechaza moverla dentro de sí misma, adonde ya está o a una tarea con puntos, commits o hecha (no puede ser bloque).
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `ref` | texto | sí | La tarea o el bloque que se mueve, por ejemplo P1-3.4 |
| `to` | texto | sí | A dónde: un plan (P2) o un bloque (P1-5) |
#### `delete_task`
Cambia los datos. Borra una tarea, o un bloque con sus subtareas, que no debería existir (una copia, un error), con confirmación: confirm tiene que repetir su referencia (confirm P1-3.4); sin ella no borra nada. Va a la papelera del proyecto con todo lo suyo (subtareas, criterios, decisiones, lecciones, notas, adjuntos con sus archivos, historial y turno): la respuesta dice su id (trash) y restore la devuelve con su mismo número durante 30 días; después se borra para siempre. Solo tareas por definir o listas, sin commits ni PR (tampoco las de adentro de un bloque): se rechazan, con un mensaje que dice qué hacer, las que tienen commits o PR y las que están en progreso o hechas, porque su historia se conserva. Las tareas que la esperaban dejan de esperarla (unblocked) y sale de la lista de prioridades; al restaurarla, vuelven las dos cosas. Su historial queda en el registro, hasta «borró la tarea (a la papelera)» (get_history con su ref), y su número no se vuelve a dar.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `ref` | texto | sí | La tarea o el bloque que se borra, por ejemplo P1-3.4 |
| `confirm` | texto | sí | La misma referencia otra vez, para confirmar el borrado |
### Notas y adjuntos
#### `add_note`
Cambia los datos. Agrega una nota a mano a una tarea: un recordatorio, una idea o un comentario, corto y en Markdown (lo que no es descripción, criterio ni decisión). author dice de quién es: claude (por defecto) para las del agente, edwinfmesa para las que dicta la persona. Se leen con get_task (fields notes).
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `ref` | texto | sí | |
| `text` | texto | sí | La nota (Markdown, hasta 4000 caracteres) |
| `author` | `edwinfmesa`, `claude` | | claude: una nota del agente (por defecto); edwinfmesa: una que dicta la persona, a su nombre |
#### `edit_note`
Cambia los datos. Cambia el texto de una nota del agente (claude) por su id (get_task con fields notes los da). Cada autor edita solo las suyas: las de edwinfmesa las edita la persona en la pestaña.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `ref` | texto | sí | |
| `id` | texto | sí | |
| `text` | texto | sí | El texto nuevo (Markdown) |
#### `remove_note`
Cambia los datos. Borra una nota del agente (claude) por su id (get_task con fields notes los da). Cada autor borra solo las suyas: las de edwinfmesa las borra la persona en la pestaña. Va a la papelera del proyecto (trash: su id) y restore la devuelve durante 30 días.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `ref` | texto | sí | |
| `id` | texto | sí | |
#### `attach`
Cambia los datos. Adjunta a una tarea una captura, un archivo o un enlace, con una nota corta de qué muestra. Uno de: fromChat (una imagen que la persona mandó en el chat: 1 = la última, 2 = la anterior…; se lee del registro de la sesión de Claude Code), path (un archivo local, relativo a la raíz del repositorio o absoluto) o url (un enlace http/https). Los archivos se guardan en media/ (raíz del repositorio), hasta 25 MB. Cuando una tarea nace de una captura de la persona, se adjunta con fromChat y una nota que resume lo que se ve.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `ref` | texto | sí | |
| `fromChat` | número | | Imagen del chat: 1 = la última que mandó la persona, 2 = la anterior… |
| `path` | texto | | Archivo local para copiar a media/ |
| `url` | texto | | Enlace (http o https) |
| `name` | texto | | Nombre que se muestra. Por defecto, el del archivo, «Captura del chat» o la dirección del enlace |
| `note` | texto | | Qué muestra o para qué sirve, en una o dos frases (de una captura: lo que se ve) |
#### `remove_attachment`
Cambia los datos. Quita un adjunto de una tarea por su id (get_task con fields attachments los da). Va a la papelera del proyecto (trash: su id) y su archivo se queda en media/: restore lo devuelve durante 30 días; después se borra para siempre, con su archivo.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `ref` | texto | sí | |
| `id` | texto | sí | |
### Papelera
#### `get_trash`
Solo consulta. Lo que hay en la papelera de un proyecto, lo más nuevo primero: lo que se borró (tareas y bloques con delete_task, adjuntos, notas, elementos de una tarea y turnos de la lista de prioridades), cada uno con su id, qué era (what), su título, de dónde (ref y plan), quién lo borró y cuándo, y cuántos días le quedan (daysLeft; a los 30 se borra para siempre, solo). first dice qué restaurar antes (su tarea o su bloque, también en la papelera) y note, si su lugar ya no existe. Se restaura con restore. Borrar para siempre o vaciar la papelera lo hace solo la persona, desde la pestaña.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
#### `restore`
Cambia los datos. Restaura algo de la papelera de un proyecto por su id (get_trash los da, y las herramientas que borran lo dicen en trash): vuelve como estaba, a su lugar. Una tarea o un bloque, con su mismo número y todo lo suyo (subtareas, adjuntos con su archivo, notas, commits e historial); las que la esperaban vuelven a esperarla y sus turnos vuelven a la lista de prioridades. Un adjunto, una nota o un elemento, a su tarea, en su lugar (o al final si la lista cambió); un turno, a la lista en el mismo turno. Si su tarea o su bloque también están en la papelera, el error dice cuál restaurar primero; si su bloque ya no existe, la tarea vuelve al final del plan con un número nuevo y note lo dice. Queda en el historial como «la restauró de la papelera».
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `id` | texto | sí | El id de lo que se restaura: lo dan get_trash y la respuesta de la herramienta que lo borró (trash) |
### Git, GitHub y tokens
#### `set_project_repo`
Cambia los datos. Anota la carpeta local del repo de git de un proyecto (ruta absoluta; si es una subcarpeta, se guarda la raíz del repo). Ahí van los commits (add_commits), los PR (link_pr, sync_prs, con gh), las ramas subidas, los worktrees de Trabajando ahora, la vista previa y los archivos que se adjuntan con path de sus tareas. También anota la dirección de GitHub del proyecto (repoUrl), leída del origin de esa carpeta (https o ssh, normalizada a https://github.com/dueño/repo): la usan los enlaces de las ramas sin PR y los de los commits y PR que no guardaron su propio repo. Cada commit guarda el repo donde vive al asociarlo (add_commits) y cada PR el suyo (link_pr), así sus enlaces no cambian si el proyecto se muda; al anotar la carpeta, los commits del proyecto que existen en ella pasan a la dirección nueva (commitsMoved dice cuántos) y los que no están ahí, como los de antes de una mudanza que no trajo la historia, conservan la suya. Si la carpeta no tiene origin o no es de GitHub, la dirección queda como estaba y la respuesta lo dice (notice). Con dir vacío se quita la carpeta, y vuelve a ser el repo que contiene la carpeta de datos; la dirección de GitHub queda. list_projects dice las de cada uno (repoDir y repoUrl).
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `dir` | texto | sí | Carpeta absoluta del repo, por ejemplo /Users/ana/desarrollo/mi-juego; vacío para quitarla |
#### `start_branch`
Cambia los datos. La rama de GitHub de una tarea, nombrada como en Linear (proyi/p1-9-6-titulo-de-la-tarea): la anota en la tarea (si no tenía) y devuelve el comando para crearla. Se usa al empezar a trabajar la tarea; el agente crea la rama desde main al día.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `ref` | texto | sí | |
#### `add_commits`
Cambia los datos. Asocia commits a una tarea por su hash; el título, la fecha y los archivos que tocó cada uno se leen de git, y cada uno guarda el repo de GitHub donde vive (el del origin del repo del proyecto o, sin origin de GitHub, la dirección del proyecto): su enlace no cambia si el proyecto se muda de repo. No repite los que ya tiene (a esos solo les completa los archivos y el repo si les faltan).
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `ref` | texto | sí | |
| `hashes` | lista de textos | sí | |
#### `explain_files`
Cambia los datos. Explica qué pasó en cada archivo que tocó una tarea, en palabras simples y concretas (qué cambió y por qué), para que la persona lo entienda sin leer código. Una explicación por ruta (relativa a la raíz del repositorio, como en sus commits); si ya tenía, la reemplaza. Va en el cierre, después de add_commits: get_task con fields code muestra cuáles faltan (unexplained) y el enlace al diff de cada archivo en GitHub.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `ref` | texto | sí | |
| `files` | lista de objetos | sí | |
| `files[].path` | texto | sí | |
| `files[].note` | texto | sí | Qué cambió y por qué, en una o dos frases claras |
#### `link_pr`
Cambia los datos. Asocia el PR de GitHub de una tarea, o lo pone al día, leyéndolo con gh: por su número, o por la rama de la tarea. Guarda número, dirección y estado (open, merged o closed), y el repo de GitHub del PR (el de su dirección), de donde sale el enlace de la rama de la tarea. Si ya se unió (squash), agrega a la tarea el commit que quedó en main, con ese mismo repo. Se usa después de crear el PR (gh pr create, con el cuerpo del campo pr) y después de unirlo.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `ref` | texto | sí | |
| `number` | número | | Número del PR. Si falta, se busca por la rama de la tarea |
#### `sync_prs`
Cambia los datos. Pone al día, con gh, el estado de todos los PR abiertos de las tareas de un proyecto (para ver cuáles ya se unieron o se cerraron).
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
#### `measure_tokens`
Cambia los datos. Mide los tokens que consumieron tareas, de los registros de las sesiones de Claude Code: cada respuesta del agente se carga a la tarea que estaba en progreso y que esa sesión tocó (si hay varias, la última que se tocó). Se hace solo al cerrar una tarea y al unir su PR; esta herramienta lo hace a mano: con ref, una tarea (también en progreso, para ver cuánto lleva); sin ref, todas las del proyecto que estuvieron en progreso. Devuelve respuestas, tokens y costo en USD de cada una.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `ref` | texto | | Una tarea; sin ella, todas |
### La pestaña de la persona
#### `show_to_user`
Solo consulta. Muestra algo a quien programa en su pestaña abierta de proyi-dev, en lugar de pegarlo en el chat: un plan (target P1), una tarea (P1-3.4), la lista de prioridades (target prioridades) la cronología del proyecto (target cronologia: lo terminado, en dos pestañas, el timeline limpio por día o, con chronology.tab stats, las estadísticas con su orden y sus filtros en chronology) o la papelera del proyecto (target papelera: lo borrado que todavía se puede restaurar), con la vista, los campos del árbol, las secciones del detalle, una búsqueda, si se ocultan las tareas hechas y cómo se miden las tortas (by). Usarlo cuando algo del proyecto es importante para la persona o para ayudarla a encontrar algo (con query). Incluir un mensaje corto de por qué.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `target` | texto | sí | Plan (P1), tarea (P1-3.4), prioridades (la lista de prioridades), cronologia (lo terminado del proyecto) o papelera (lo borrado del proyecto) |
| `message` | texto | | Por qué se muestra, en una frase; aparece en la pestaña |
| `view` | `tree`, `board`, `attachments`, `agents` | | tree (árbol), board (tablero por estado), attachments (torta de las tareas del plan con y sin adjuntos, y las de cada parte) o agents (torta de las tareas hechas del plan por el agente que las hizo, el que las pasó a en progreso por última vez, y las de cada uno) |
| `fields` | lista de: `status`, `points`, `progress`, `commits`, `description` | | Qué se ve de cada tarea en el árbol o el tablero |
| `sections` | lista de: `facts`, `value`, `pr`, `prep`, `close`, `estimate`, `tokens`, `questions`, `blockers`, `description`, `attachments`, `notes`, `criteria`, `decisions`, `lessons`, `code`, `context`, `commits`, `history`, `subtasks` | | Secciones del detalle de la tarea: facts (Detalles: estado, puntos y, debajo, la descripción), value (valor: cuánto aporta, en qué dimensiones y por qué), prep (preparación para desarrollo), close (cierre: lo que falta para darla por hecha), description (lo mismo que facts: abre Detalles), context, commits, code (código estimado y real), decisions, criteria (criterios de aceptación), lessons (lecciones aprendidas), blockers (bloqueos), history (historial de acciones), subtasks |
| `query` | texto | | Búsqueda a mostrar ya aplicada |
| `hideDone` | sí o no | | Ocultar las tareas hechas |
| `by` | `points`, `tasks` | | Cómo miden las tortas (vistas attachments y agents): points, la suma de los puntos estimados de las tareas de cada parte (por defecto), o tasks, cuántas tareas |
| `chronology` | objeto | | Solo con target cronologia: la pestaña y, en stats, cómo se ordena y qué se filtra (lo que no se diga, lo de por defecto y sin filtro) |
| `chronology.tab` | `timeline`, `stats` | | timeline (por defecto: lo terminado por día, solo el ícono del plan y el título) o stats (Estadísticas: filtros, cifras, gráficos y la lista con todos sus detalles). Sin tab, con orden, gráficos o filtros, es stats |
| `chronology.sort` | `recent`, `oldest`, `points`, `plan`, `origin`, `agent` | | recent (por fecha, de la más reciente: por defecto), oldest, points, plan, origin o agent: agrupa por eso |
| `chronology.every` | `day`, `week` | | Las barras del gráfico en el tiempo, por día (por defecto) o por semana |
| `chronology.measure` | `points`, `tasks`, `cost` | | Qué miden los gráficos: points (por defecto), tasks o cost |
| `chronology.plan` | texto | | Solo las de un plan (P2) |
| `chronology.origin` | `request`, `bug`, `proposal`, `none` | | Solo las de un origen (none: sin origen) |
| `chronology.agent` | texto | | Solo las de un agente (principal, agente 1…; none: sin registro) |
| `chronology.points` | `1`, `2`, `3`, `5`, `8`, `13`, `none` | | Solo las de esos puntos estimados |
| `chronology.from` | texto | | Desde ese día, AAAA-MM-DD |
| `chronology.to` | texto | | Hasta ese día, AAAA-MM-DD |
#### `get_user_view`
Solo consulta. Qué tiene abierto quien programa en su pestaña de proyi-dev: proyecto, página (page: plan, priorities o chronology, la cronología de lo terminado, con su pestaña, timeline o stats, y su orden y sus filtros en chronology), plan, tarea abierta, vista, campos, secciones, búsqueda, si oculta las hechas y, en las vistas de torta, cómo se miden (by: points o tasks), desde cuándo y si la pestaña tiene el foco. Usarlo cuando la persona habla de "esto" o de lo que tiene abierto. Con withData, además los mismos datos que está viendo (el plan o las coincidencias de su búsqueda con sus campos, y el detalle de la tarea con sus secciones; en la cronología, sus tareas hechas filtradas y ordenadas, con sus totales); sin withData es una respuesta corta.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `withData` | sí o no | | Incluir los datos que la persona está viendo. Por defecto, no |
#### `preview`
Cambia los datos. Pone la vista previa en una tarea o en main. La persona la ve en su única pestaña, http://localhost:3200/: con una tarea (target P1-3.4), arranca el servidor de la tarea en un puerto interno (3211, que nadie abre a mano; reemplaza al que hubiera) con el código del worktree de su rama (git worktree list) y una copia de la base en data/backups/preview/, renovada en cada cambio (nunca la real: la tarea puede traer una migración), y el 3200 le reenvía la pestaña, con una franja arriba «Vista previa de la tarea · datos de prueba» y el botón Volver a main. Con main, apaga el servidor interno y el 3200 vuelve a servir main con los datos reales. La pestaña se recarga sola. Se pasa a la tarea que la persona tiene que revisar y vuelve a main al unir su PR. Devuelve qué muestra, su url en el 3200 y cuánto tardó (ms).
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `project` | texto | | Proyecto (carpeta en data/). Opcional si hay uno solo |
| `target` | texto | sí | main, o la tarea a revisar (P1-3.4) |
<!-- catalogo:fin -->
proyi-dev