Recorre un árbol de carpetas, encuentra tus proyectos, detecta su stack y actividad, y los indexa en el cerebro global para que BMAD+ conozca todo tu portafolio.
scan responde a la pregunta «¿qué proyectos tengo y cuáles ya usan BMAD+?». Recorre una carpeta, reconoce las raíces de proyecto, adivina el stack, clasifica cada proyecto como activo, en pausa o archivado, y guarda una ficha pequeña por proyecto en el cerebro global, la carpeta de memoria personal compartida por todos tus proyectos (~/.bmad-plus/brain). Es para quien guarda muchos repositorios y quiere que un agente, normalmente Zecher, los conozca todos.
Una carpeta es raíz de proyecto si contiene uno de estos archivos, comprobados en este orden: package.json, Cargo.toml, pyproject.toml, requirements.txt, go.mod, composer.json, Gemfile, pom.xml, build.gradle. El recorrido no desciende dentro de un proyecto cuya raíz ya encontró.
Una carpeta por debajo del punto de partida que tiene un directorio .git pero ninguno de esos archivos también es un proyecto, con el stack «Unknown». La carpeta de partida solo cuenta por los archivos marcadores.
El stack sale del marcador: Rust, Python, Go, PHP, Ruby, Java o Java/Kotlin, y para package.json uno de Next.js, Nuxt, React, Vue.js, Svelte, Express, Fastify, Electron, Tauri (comprobados en ese orden sobre dependencies y devDependencies), si no Node.js.
Estas carpetas se omiten: node_modules, .git, vendor, __pycache__, dist, build, .next, .nuxt, .svelte-kit, target, .venv, venv, .cache, .output, coverage, .turbo, .angular, y las carpetas de sistema de Windows $RECYCLE.BIN, System Volume Information, Windows, Program Files, Program Files (x86), ProgramData, AppData, Recovery, PerfLogs. También se omite cualquier otra carpeta cuyo nombre empiece por un punto. Las carpetas ilegibles se omiten en silencio.
La actividad es la fecha de modificación de la propia carpeta del proyecto. Cambia cuando se añaden o quitan entradas directamente dentro, no cuando editas un archivo más abajo, así que un proyecto muy activo aún puede salir como «paused». Ajusta --active-days y --paused-days si las etiquetas no encajan con tu forma de trabajar.
La columna BMAD+ muestra una marca cuando el proyecto tiene una carpeta .agents o _bmad.
Una ficha por proyecto indexado: path, name, hash, stack, status, bmad_installed, has_git, last_scanned (una fecha). El hash de 8 caracteres sale de la ruta del proyecto, así que escanear dos veces el mismo proyecto actualiza su ficha en vez de añadir otra.
.bmad-plus/brain/projects-index.md
Una tabla Markdown de todas las fichas de la carpeta projects/ (no solo las de esta pasada), reescrita tras cada scan que indexa algo.
Los proyectos recorridos solo se leen, nunca se modifican. La ubicación del cerebro es fija, ~/.bmad-plus/brain: scan no sigue la variable BMAD_PLUS_BRAIN ni una carpeta _brain de portafolio que install haya podido enlazar. No se hace ninguna petición de red.
Cualquier final normal: indexado, nada encontrado, cancelado, y también «Directory not found».
1
Se escapó un error inesperado (la CLI imprime BMAD+: <message>). scan no fija ningún otro código.
Nota· No te fíes del código de salida en scripts
Una ruta incorrecta termina igualmente con código 0 tras imprimir el error. En un script, comprueba tú la carpeta antes de llamar a scan y pasa --yes para que nada espere una respuesta.
Escaneo de una carpeta de trabajo con --yes (simulado)Simulado
$ npx bmad-plus scan ~/work --depth 3 --yesBMAD+ Project ScannerFound 3 project(s) Legend: ● active modified < 30 days ago (2 found) ◐ paused modified 30–180 days ago (1 found) ○ archived modified > 180 days ago (0 found) # Status BMAD+ Stack Name Path ────────────────────────────────────────────────────────────────────────────────────────── 1 ● active ✓ Next.js invoice-app /home/me/work/invoice-app 2 ● active · Python etl-jobs /home/me/work/etl-jobs 3 ◐ paused · Unknown notes-site /home/me/work/notes-site✅ 3 project(s) indexed in /home/me/.bmad-plus/brain/projects📋 Project index updated: /home/me/.bmad-plus/brain/projects-index.mdScan complete! 🧠
npx bmad-plus scan ~/work --depth 3 --yes
Transcripción ilustrativa, no capturada de una ejecución real. Fuente: Compuesto a partir de las plantillas de mensajes de tools/cli/commands/scan.js; colores, emojis y el marco de la biblioteca de prompts omitidos. Los nombres y las rutas son inventados.
Lee la tabla de izquierda a derecha: el número, la clase de actividad, si BMAD+ está instalado, el stack detectado, el nombre del proyecto (el de package.json si lo hay, si no el de la carpeta, cortado a 20 caracteres) y la ruta (cortada a sus últimos 37 caracteres si supera 40). Sin --yes, scan pregunta: indexarlo todo, elegir proyectos de una lista, u omitir.
Indexar una carpeta de trabajo y encontrar los proyectos sin BMAD+#
Guardas una docena de repositorios bajo una misma carpeta y quieres la lista de los activos donde BMAD+ no está instalado.
En tu asistente de IA
Ejecuta `npx bmad-plus scan ~/work --yes`. Luego lee ~/.bmad-plus/brain/projects-index.md y lista los proyectos cuyo estado es active y cuya columna BMAD+ está vacía.
Lo que deberías obtener El comando imprime la leyenda y la tabla, escribe una ficha <hash>.yaml por proyecto y reescribe projects-index.md. El asistente lee esa tabla (columnas Status, Name, Stack, BMAD+, Path; una marca significa instalado, un punto no instalado) y devuelve las filas activas con un punto. El índice abarca todas las fichas del cerebro, así que también puede citar proyectos de escaneos o instalaciones anteriores.
Dejar que Zecher escanee con tu aprobación proyecto a proyecto#
Requiere el pack memory. Es el flujo de escaneo propio del agente, que te pregunta por cada proyecto, no el comando de arriba.
En tu asistente de IA
Zecher, escanea los proyectos en ~/work.
Lo que deberías obtener Zecher recorre la carpeta, muestra una tabla (proyecto, stack, estado, BMAD+, última modificación) y pregunta por cada proyecto: confirmar, editar, omitir o instalar allí BMAD+. Solo los proyectos confirmados se escriben en ~/.bmad-plus/brain/projects/<hash>.yaml, se actualiza el índice y Zecher informa de cuántos se indexaron, nuevos y actualizados.