Este fichero es un registro de intenciones, no una especificación redactada por el agente. Cada punto contiene la frase original del dueño del proyecto y, justo debajo, su traducción práctica.
Si algo cambia en el proyecto, se actualiza la frase o se añade una nueva, pero nunca se reescribe la intención original.
Ubicación: Vive en la raíz del repositorio para que cualquier sesión de trabajo lo lea obligatoriamente antes de modificar nada.
"Mucho texto redundante y versiones redundantes. Quiero algo funcional, no técnico."
- Cero redundancia: Un dato aparece una sola vez. Si un número está visible en tres sitios del mismo panel, sobran dos.
- Sin tripas a la vista: Ocultar rutas absolutas, nombres de fuentes internas o banderas sin traducir. El dueño decide con estados claros: está / no está, funciona / no funciona, versión, hay actualización.
- Acciones directas: Si requiere una acción, se convierte en botón. "Reinicia pi" debe ser una acción ejecutable, no una instrucción de texto.
- Eficiencia de espacio: Un panel de estado no puede ocupar media pantalla solo para decir "todo bien".
"para que quiero eso, omg"
- La interfaz comunica qué hay y qué puedes hacer (ej. Built, Stop build, Clean).
- Ocultar explicaciones sobre la maquinaria interna (dónde se guarda cada cosa o cuándo se calcula). Ese detalle va a los ficheros de tareas o a la documentación.
"Me sigue saliendo el logo de vscodium..."
- Antes de asimilar que un arreglo falló, verificar dónde se ve exactamente (pantalla, esquina, contexto). Evitar asumir que ambas partes están mirando lo mismo.
"añade siempre iconos, de marcas, de emojis etc que le de un mejor estilo visual"
- Un icono antes que texto: los encabezados, y cada fila de una lista o tabla, llevan su icono o su emoji. Un badge sin logo o una sección sin marca visual es una ocasión perdida.
- Marcas de verdad: los logos de terceros (GitHub, Node, TypeScript, Electron…) se ponen con su identificador real y comprobado antes de usarlo. Medido el 1-10:
windowsyvisualstudiocodeya no existen en simple-icons (Microsoft los retiró), así que ahí no va logo: mejor sin él que roto. - Nada que no lleve a ningún sitio: un badge que no enlaza a nada, o que promete algo que no existe, es una mentira. Si no hay a dónde ir, no se pone.
"lo de la rosa cambialo por el de picode" — 2026-10-01
- Barra de actividad: Usa la marca de PiCode (
extensions/picode/media/picode-status.svg, el icono del contenedor). - La marca vive en el conector (
picode-source/extensions/picode/media/) y lleva su pareja claro/oscuro: el icono de una fila del árbol se pinta como imagen (no como máscara), así que una sola tinta desaparece en uno de los dos temas. - Tratamiento como máscara: La barra de actividad usa el icono como máscara (solo cuenta la silueta). No incluir fondos rellenos en el lienzo para evitar cuadrados macizos.
"El logo que cambiamos en el centro de la pantalla... no uses el png usa el svg"
- Marca de agua del editor vacío: Utiliza el dibujo vectorial de trazos (
media/picode.svg), no la versión con placa de fondo.
"y ya no es SDD es ODD"
- La metodología del proyecto es ODD (Organic Driven Development). SDD es solo una rama dentro de ODD.
- En el texto visible para el dueño, «SDD» no se usa como nombre del método global. Sus comandos y artefactos específicos sí conservan su nombre.
"no quiero que la versión de picode que vive en nuestro editor sea fija, quiero poder actualizarlo desde el editor"
"El perfil de pi me gustaría que fuera interno y la configuración, etc también interna, pero poder 'importar' de la del pi del path"
"necesito que en la config de modelos también podamos conectar proveedores, y modelos y tal para cualqueir pi ya sea para el interno o el externo."
"Pi vive dentro de PiCode (Vscodium), es el HOST, el que maneja todo, agents, skills, etc. NUNCA vamos a añadir nada del path, yo tengo otro pi aquí para desarrollar esta app, que eres tú cacho cabezón."
"Mete esto en el Agents.md olvidate del pi del path"
"lo que si OLVIDATE de una extensión, todo ha de vivir en el núcleo."
"y no ha de guardar NADA en el pi externo, si no en el interno, olvidate de la carpeta /.pi/ que hay en tapla"
- Un único Pi (Host): PiCode integra su propio Pi dentro del núcleo del editor. Es el Host que maneja todo: agentes, skills, proveedores y memoria.
- Actualización interna: Pi se actualiza desde el propio editor, sin reinstalar ni editar ficheros manualmente.
- Aislamiento de escritura: Se escribe siempre en el perfil propio de PiCode. La carpeta externa (
~/.pi/) no se toca nunca para guardar o leer. - Sin extensión propia: Todo (chat, proveedores, modelos, ajustes, habilidades y agentes) vive en el núcleo del editor, usando la superficie nativa (Chat y Agente).
- El Pi del PATH: No lo ejecuta el producto; sirve solo para desarrollo.
- Conexiones y migraciones externas:
- Conectarse a un Pi externo (por RPC/WebSocket) es opcional si el usuario lo decide para usar sus datos donde están, pero nada sale de PiCode.
- Migrar datos desde el Pi del PATH al interno es una opción explícita a petición del usuario, nunca un proceso automático.
- Credenciales: Las claves de endpoints se guardan como variables de entorno o valores cifrados; nunca se muestran en pantalla.
"Esto no lo toques NUNCA, esto es mi pi que estamos corriendo ahora mismo."
"Miento, cuidado, si se puede tocar, al actualizar y tal pero via app."
"si conectamos el HOST que sea el Externo (PATH) debería poder actualizar Pi y Packages del externo"
- Nunca a mano: ni el agente ni ningún script del repo escriben, instalan ni actualizan el pi del PATH directamente. Es el pi con el que se está trabajando ahora mismo.
- Sí, vía la app (única excepción): el producto puede tocarlo solo a través de sus propios flujos de actualización (Update Pi / Packages), nunca por escritura directa. Esto matiza la regla de aislamiento de escritura: seguir prohibido guardar ni leer a mano en esa carpeta.
- Requisito de producto: cuando el HOST conectado es el externo (PATH), los botones de actualizar Pi y Packages deben actuar sobre ese externo, no sobre el interno.
"Vamos a dejar de poner como algo experimental a pi durable, quiero que esté ya en nuestro source de picode, no lo quiero a parte en "experimental", tratalo como algo ya que vive en picode." — 2026-10-09
- Residencia: el agente durable vive en el propio árbol del editor (
picode-source/durable, con su puente de chat enpicode-source/durable-bridgey su cliente de prueba ACP enpicode-source/durable-acp-client). La carpetaexperimental/no vuelve a ser su casa. - Nombre: en todo lo que ve el dueño es Durable agent, a secas. Ninguna UI, ajuste o documento vivo lo presenta como experimental.
- Build: viaja dentro de la instalación (
resources/durable), como ya hacía; solo cambia el nombre de la carpeta destino.
"Vamos a ver, necesito integrar los temas de https://vscodethemes.com para que tanto en la primera instalación como en cualquier momento puedan elegirse uno de esos temas."
- Puntos de acceso: Selección disponible en el asistente de primer arranque, en Ajustes > Aspecto, y mediante comando en la paleta/menú.
- Origen de datos: Los temas se instalan desde Open VSX.
vscodethemes.comse trata como un escaparate externo de referencia. - Vista previa nativa: Pintada por PiCode usando los colores reales del tema (sin depender de red ni imágenes externas).
- Instalación: Aplicar un tema lo instala automáticamente si no existe. Solo se pide reiniciar la ventana cuando sea estrictamente necesario.
- PiCode es 100% gratuito y completo: No hay funciones recortadas ni dependencia de la nube para su funcionamiento local.
- Valor comercial: Sincronización y respaldo en la nube de toda la configuración (PiCode y Pi) como un único bloque.
- Unidad de perfil: Toda la configuración vive en un perfil interno propio que se sube/baja como una unidad aislada.
- Seguridad de credenciales:
auth.jsony tokens requieren cifrado y consentimiento explícito del usuario antes de subir a la nube.
"No me pidas permisos ni que revise yo nada, termina TODAS las fases."
- Una vez autorizado un trabajo, se ejecuta hasta el final sin interrupciones. Las decisiones de producto no cerradas se toman, se registran y se explican al terminar.
- Transparencia total: lo que no se pueda completar se informa con la misma claridad que lo terminado.
"Generame solo la build portable luego y no el instalador, el instalador dejalo a partir de ahora si no te lo pido explicitamente." — 2026-10-14
- Toda build local produce solo el pack portable (
PICODE_SKIP_INSTALLER=yes). - El instalador se construye solo a petición explícita del dueño.
"Una vez finalices dame un reporte."
- Al terminar: informe con qué está hecho y verificado, qué falta, por qué y dónde quedó registrado.
"recuerda borrar la release anterior siempre" — 2026-10-16
- Cada canal (stable, beta, experimental) muestra una única release en GitHub: la más nueva.
- Al publicar una release nueva, el pipeline borra automáticamente la anterior del mismo canal, con su tag.
- El borrado va después de publicar la nueva: si un run falla a mitad, el canal nunca se queda sin release.
- El guard de "versión estrictamente más nueva" no depende de la lista de releases: lee la versión anterior del feed del canal en el árbol, así que sigue funcionando tras borrar.
"recuerda añadir tu siempre el texto de la release mejorado y con el changelog" — 2026-10-16
- Toda release lleva, sobre el changelog crudo, un resumen agrupado por tipo de cambio (novedades, arreglos, rendimiento, editor, seguridad, resto) con iconos — lo genera
dev/release-notes.mjsa partir de los commits del rango y el pipeline lo inserta solo. - Los commits de feed y housekeeping no aparecen: no le dicen nada a quien lee la página.
- Siempre conserva: la descripción del canal encima (
dev/release-notes/<canal>.md), el changelog generado por GitHub debajo (con el enlace de comparación apuntando al propio tag) y la tabla de archivos.
"En español."
"NOno a ver todo ha de estar en ingles, tu me hablas en español, ya costruiremos paquete sde lenguajes para todos los demás idiomas. Pero a priori en inglés."
- Producto (Interfaz): Todo lo que ve el usuario final va en inglés (ventanas, avisos, comandos, ajustes, respuestas del chat sobre herramientas).
- Comunicación interna: La interacción con el dueño, los reportes y la documentación (
docs/,AGENTS.md) se mantienen en español. - Internacionalización: Otros idiomas se añadirán mediante paquetes de lenguaje sobre la capa superior, sin mezclar cadenas en el código base.
- Excepciones técnicas: Mensajes de commit, comentarios de código e identificadores permanecen en inglés.
- Siempre se escribe en inglés: todo código nuevo, sus comentarios, las cadenas de código y los mensajes de las herramientas se redactan en inglés — nada en español en el código («añade en el agents.md que siempre se escribe en inglés» / «tradúcelo todo al inglés, nada en español», 2026-10-16).
- Si aparece español en el código (citas del dueño incluidas): se borra si el resto del comentario se entiende solo, o se traduce si hace falta para entenderlo.
- Única excepción: el texto con destino a documentación en español (
docs/,README.md,AGENTS.md).
- Datos que no son texto nuestro: las pruebas de acentos/teclados upstream, los nombres de idioma de los paquetes (
"español") y los mensajes citados de terceros se quedan como están.
"necesito que me expliques a partir de ahora todo muy sencillo, no necesito nada técnico, quiero hablarte y que me hables funcional y fácil."
- Explicaciones centradas en qué hace y qué cambia para el usuario, sin tecnicismos ni nombres de código/ficheros.
- Lenguaje directo y frases cortas.
- El detalle técnico se documenta de forma completa en
docs/. - Explicación funcional de errores: qué significa la falla (ej. "no se pudo conectar"), no la causa en el código.
- La página «Agent Customizations» del chat debe listar los elementos reales del runtime pi (perfil en fuerza), no los de las convenciones de GitHub/Copilot.
- Agents: los agentes de pi. Skills: las de pi y las del proyecto. MCP Servers: los servidores mcp de pi. Plugins: los paquetes instalados de pi.
- No existen en este producto: Instructions, Prompts y Hooks (pi no tiene hooks) → fuera de la navegación y de la rejilla de la página.
"deja avisado algo en el agents.md no? de usar esto" — 2026-10-16
- Toda carpeta nueva lleva su
README.md: una frase de qué hace esa carpeta y qué hay dentro, escrito al lado del código. Si no lo trae, CI lo avisa y el PR se detiene (dev/check-docs.mjs; las excepciones se apuntan en.docsignore). - El mapa se genera, no se escribe:
docs/MAPA.mdsale de esos README connode dev/map-docs.mjsy nunca se edita a mano. Solo se refleja lo versionado: restos locales y salidas de build no entran. - Nivel fichero solo cuando el nombre miente: si el nombre ya explica el fichero, no se documenta; si no, dos líneas de cabecera con el porqué.
- La zona upstream no se documenta fichero a fichero:
picode-source/src,cli,build,scripts,resources,remotey las extensiones built-in llevan un solo aviso de que no son nuestras (ahí está casi todo el código y detallarlo es trabajo que se pudre). - Dónde mirar primero:
docs/MAPA.md(árbol con una frase por carpeta) y, para saber quién llama a quién, el grafo de código (.codegraph/), no la documentación.
"Cuando lanzo fases de tareas no las veo… Tengo una lista con fases y no se ven." "gentle-ai siempre lo muestra ¿no deberíamos hacer lo mismo?"
- Panel de fases siempre visible: al empezar cualquier trabajo con varias fases o pasos, el agente registra la lista completa con la herramienta
set_plan(extensión pi-plan-widget de pi) y la mantiene actualizada:in_progressen la fase en marcha,doneal cerrar cada una. - El panel es estado real, no decoración: no se eliminan las fases ya hechas y cada cambio de fase se refleja en el panel en el mismo turno.
- Sin ruido: trabajos triviales de un solo paso no llevan plan.
- 2026-09-23 · Creado con las frases iniciales de la sesión de trabajo.
- 2026-09-23 · Añadido punto sobre conectar proveedores y modelos propios para la instancia elegida.
- 2026-09-23 · Añadido punto sobre selección de temas desde el catálogo e integración con Open VSX.
- 2026-09-24 · Añadida la regla de comunicación sencilla y migración del detalle técnico a
odd/tasks/. - 2026-09-24 · Clarificación de la arquitectura de Pi: Pi vive dentro de PiCode como Host. Prohibida la escritura en
~/.pi/. Opciones explícitas para conexión y migración externa. - 2026-09-24 · Confirmado que no existe extensión propia: todo el desarrollo va dentro del núcleo del editor.
- 2026-09-25 · Regla de UI: La pantalla muestra acciones y estados (Built, Stop build), no explicaciones de funcionamiento interno.
- 2026-09-25 · Definición del idioma: El producto habla inglés para el usuario; la comunicación con el dueño y la documentación interna se mantienen en español.
- 2026-09-27 · Regla de los iconos: la marca de agua cambia de hogar al borrarse la carpeta
extensions/por decisión del dueño («pues borrala»); pasa al núcleo (picode-source/.../contrib/picode/browser/media/). El dibujo de trazos del editor vacío no cambia. - 2026-09-27 · Añadida la regla de la ventana de gestión del chat: datos de pi (agents, skills, mcp, packages) y eliminadas Instructions, Prompts y Hooks.
- 2026-10-01 · Icono de la barra de actividad: es la marca de PiCode, no la rosa («lo de la rosa cambialo por el de picode»). Esa marca lleva pareja claro/oscuro, porque un icono de fila se pinta como imagen y una sola tinta desaparece en uno de los dos temas.
- 2026-10-01 · Regla de estilo visual: iconos y emoji siempre («añade siempre iconos, de marcas, de emojis etc»), con marcas reales y comprobadas; sin badge que no lleve a ningún sitio.
- 2026-10-09 · pi durable deja de ser experimental: vive en el source de PiCode («tratalo como algo ya que vive en picode»). Su casa es
picode-source/durabley en la UI se llama Durable agent, sin el "(experimental)". - 2026-10-13 · Regla de fases visibles: el trabajo por fases se muestra en el panel de pi (
set_plan, widget de pi-plan-widget) («tengo una lista con fases y no se ven»). Confirmado funcionando por el dueño. - 2026-10-14 · Builds sin instalador por defecto: solo pack portable; el instalador solo a petición explícita («Generame solo la build portable luego y no el instalador»).
- 2026-10-16 · Una sola release por canal: al publicar una release nueva, el pipeline borra la anterior del mismo canal («recuerda borrar la release anterior siempre»).
- 2026-10-16 · Página de release: resumen agrupado por tipo de cambio + changelog, siempre («recuerda añadir tu siempre el texto de la release mejorado y con el changelog»).
- 2026-10-16 ·
odd/tasks/deja de usarse: la carpeta se retira por decisión del dueño («odd ya no lo usamos») y el detalle técnico queda endocs/. - 2026-10-16 · Aclaración a «no existe extensión propia»: el conector (
picode-source/extensions/picode) es código del núcleo, viaja en el árbol y se empaqueta con el editor — no es una extensión aparte que se instala. - 2026-10-16 · Documentación por carpeta: cada carpeta lleva su
README.mdal lado del código, el mapadocs/MAPA.mdse genera condev/map-docs.mjsy CI vigila que no aparezcan carpetas sin ficha (dev/check-docs.mjs) («deja avisado algo en el agents.md no? de usar esto»). - 2026-10-16 · El pi del PATH: nunca se toca a mano («esto no lo toques NUNCA, es el pi que estamos corriendo ahora mismo»), pero sí vía la app — si el HOST conectado es el externo (PATH), el producto debe poder actualizar su Pi y sus Packages («si conectamos el HOST que sea el Externo (PATH) debería poder actualizar Pi y Packages del externo»).