Tus proyectos y sus documentos

Dónde viven los documentos

Los documentos que tus asistentes guardan para un repositorio — los planes, los análisis de negocio, la visión y los hallazgos pendientes — viven en el toolkit, no en tu repositorio. Escribir un plan o cambiar su estado nunca se vuelve un commit, dos personas planeando al mismo tiempo nunca reciben el mismo número, y cualquier computadora que use tu token ve los mismos documentos.

Cada repositorio es un proyecto, con el nombre de la carpeta del repositorio. No lo creas tú: aparece la primera vez que se usa su nombre — un comando, aunque solo sea para listar sus documentos, o una revisión de código que lo nombra. Una revisión sin proyecto no crea ninguno. Solo tú ves tus proyectos.

Tu documentación para desarrolladores y tus guías de usuario no cambian. Siguen en el repositorio, en su rama, como antes.

Si el toolkit no está conectado, planear, correr la cola y escribir la visión se detienen y te avisan, porque su trabajo son estos documentos. Construir también se detiene, haya o no un plan guardado, porque la revisión del código corre en el mismo servidor. Un comando que sigue trabajando sin él, como una revisión o una limpieza, continúa y nombra en su reporte los hallazgos pendientes que no pudo escribir. Ninguno los escribe en tu repositorio en su lugar.

Recorrer un proyecto

Abre Proyectos en el menú lateral y elige uno. Ves sus carpetas y archivos como los muestra un explorador de repositorios, con la ruta arriba para volver hacia atrás:

• analysis/ guarda los planes y los análisis de negocio, numerados.
• vision.md y todos.md están en la raíz del proyecto.
• Cualquier carpeta que creaste, con los archivos que subiste a ella.

Cada carpeta por debajo de la raíz del proyecto empieza su lista con una fila ..: te lleva a la carpeta de arriba y conserva la rama que elegiste.

Abre un documento para leerlo renderizado, con su estado, su rama, cuándo cambió por última vez y su tamaño junto al nombre, y sus botones Editar y Eliminar. La lista de su carpeta se queda a la izquierda, en una columna angosta con el documento marcado y los nombres largos partidos en varias líneas, y el contenido ocupa el resto del ancho, así que puedes pasar al siguiente archivo sin volver atrás. En un teléfono la lista queda encima del contenido.

Una carpeta con un index.md, o si no un README.md, abre ese índice de la misma forma, a la derecha de su lista, así que la carpeta se explica sola en cuanto la abres. El nombre se reconoce sin importar mayúsculas, solo cuentan los archivos Markdown, y el que se muestra es el de la rama que elegiste. Una carpeta sin ninguno de los dos muestra su lista a todo lo ancho. analysis/ muestra a la derecha su índice generado, sin Editar ni Eliminar, salvo que le hayas dado un index.md propio.

Un enlace dentro de un documento a otro archivo Markdown, como ../vision.md o designs/login.md, abre ese archivo aquí. Se lee desde la carpeta donde está el documento, también cuando el documento se muestra como índice de su carpeta, y conserva la rama que elegiste.

Una imagen de la lista se abre en un visor sobre la misma pantalla, junto con las demás imágenes de su carpeta: recórrelas con las flechas o las miniaturas, y cierra el visor para volver a la lista. Los PDF y los demás archivos se abren en otra pestaña.

Puedes subir archivos, crear carpetas y borrar lo que ya no necesites. Borrar siempre pregunta antes. Para subir, suelta uno o varios archivos en la caja de subida, debajo de la barra de herramientas, o haz clic en ella para elegirlos: cada archivo se guarda en la carpeta que estás viendo en cuanto termina de subir, sin ningún botón que pulsar. Cada archivo puede pesar hasta 100 MB; uno más grande se rechaza con un mensaje que dice cuánto pesa y cuál es el máximo.

Editar un documento

La mayoría de los documentos los escriben los comandos, pero aquí puedes cambiar cualquiera: un plan, la visión, los hallazgos pendientes, un comando interno o uno que subiste. Ábrelo y pulsa Editar: su Markdown se abre en un campo de texto. Guardar conserva el cambio y vuelve a mostrar el documento; Cancelar lo deja como estaba. Su rama y su estado no cambian.

• Si un comando cambió el documento mientras lo editabas, al guardar se te avisa y no se sobrescribe nada. Copia tu texto, recarga la página y vuelve a aplicarlo.
• No se puede guardar un documento vacío.
• Tampoco se guarda un cambio que hace el documento más grande que el espacio que le queda a tu cuenta: el mensaje dice Te has quedado sin espacio. Libera algo eliminando archivos que ya no necesites, o compra más espacio, y vuelve a guardar.
• El índice de analysis/ se calcula a partir de los planes, así que no tiene botón Editar.

Elegir una rama

Cada plan recuerda la rama en la que se planeó. El selector de arriba del proyecto elige qué rama estás viendo:

• master es donde empiezas.
• Cada rama que tiene planes aparece en la lista.
• Todas las ramas muestra todo.

Los documentos sin rama — análisis de negocio, la visión, los hallazgos pendientes y lo que subiste — se muestran en todas las ramas. Si la rama que elegiste no tiene planes propios, la pantalla te lo dice.

/next sigue la misma regla: solo corre los planes de la rama en la que estás. Un plan no cambia de rama por sí solo, ni siquiera cuando su rama se fusiona; cambia solo cuando le pides a tu asistente que lo mueva.

El índice de la carpeta de análisis

Dentro de analysis/ siempre hay un README.md. Nadie lo escribe: se calcula a partir de los documentos cada vez que lo abres, y se muestra a la derecha de la lista de la carpeta. Es una tabla con el número, la funcionalidad, el estado, la rama, la fecha del último cambio y un enlace a cada documento, para la rama que elegiste y los documentos sin rama.

Borrar finalizados

También dentro de analysis/, Borrar finalizados limpia los planes que ya terminaron:

1. Elige la rama que quieres limpiar, o Todas las ramas para todo el proyecto.
2. Presiona Borrar finalizados.
3. Lee la confirmación. Dice cuántos documentos se van a borrar y cuántos planes, de otras ramas incluidos, van a cambiar de número.
4. Confirma.

Cuando la rama que elegiste no tiene ningún plan marcado como implementado o descartado, el botón solo dice Nada que borrar, y nada cambia.

Borra los planes marcados como implementados o descartados. Nunca borra un análisis de negocio, ni un plan del que depende otro plan que se queda. Lo que queda del proyecto se numera otra vez desde 001, en su orden actual, y cada referencia a un número que cambió — los nombres de archivo y las líneas que dicen de qué documento depende un plan — se reescribe en el mismo paso.

Úsalo solo cuando ningún asistente esté construyendo un plan del proyecto: una construcción en curso lleva el número de su plan, y renumerar debajo de ella la apunta a otro documento. Si un plan sigue apareciendo en desarrollo porque una ejecución se interrumpió, el botón no puede distinguirlo de una construcción en curso: pide a tu asistente que mueva su estado primero y después borra. /next nunca lo hace por ti; si se lo pides durante una ejecución, te manda aquí.

/finish reconoce los commits de un plan por su número, y renumerar no cambia los commits. Un plan renumerado cuyos propios commits llevan su número anterior, y cuyo número nuevo no aparece en ningún commit de tu rama principal, lo conserva /finish: tú lo borras a mano cuando su código ya está en tu rama principal. Y un plan renumerado con un número cuyo dueño anterior tiene commits en tu rama principal, hechos después de que se creó el plan, puede borrarlo /finish en cuanto esté implementado, antes de que su propio código se integre.

Agregar un documento propio

Sube un archivo Markdown, como un manual de identidad, a cualquier carpeta — brand/, por ejemplo. Luego nómbralo en el comando que lo necesita: "usa brand/manual-identidad.md como semilla de marca". El comando lo lee por ese nombre dentro del proyecto.

Si subes un .md con un nombre que ya existe en esa carpeta, se te pregunta si quieres reemplazar el documento. Reemplazar cambia solo su contenido y conserva su rama, su estado y su número; Cancelar no sube nada. Un nombre que no está permitido, o que repite el número de otro plan de analysis/, se rechaza con un mensaje que dice por qué.

Las imágenes, los PDF y los demás archivos funcionan igual: si subes uno con un nombre que ya existe en esa carpeta, se te pregunta si quieres reemplazarlo. Reemplazar deja el archivo que acabas de subir en lugar del anterior; Cancelar no sube nada y deja el archivo anterior como estaba.

Tu asistente también puede subir estos archivos — un manual de identidad en PDF o un logo para /design-catalog, por ejemplo — y aparecen en la lista como cualquier otro. No pregunta antes de reemplazar: un archivo con el mismo nombre en esa carpeta se reemplaza, y a tu asistente se le avisa. Una imagen grande se reduce al subirla, la suba tu asistente o la subas aquí, salvo en la carpeta identity/ y las carpetas que tiene dentro, donde cada archivo se guarda tal como llegó. Un archivo de más de 20 MB no puede pasar por tu asistente: súbelo en esta página.

Los documentos y archivos que subes cuentan contra el espacio de tu cuenta, igual que los archivos de tu biblioteca de medios.

Sigue por aquí

• Planear antes de construir — de dónde salen los planes.
• Correr la cola con /next — cómo se trabajan los planes listos de tu rama.
• Hallazgos pendientes — qué guarda todos.md.