hellices/flow-atlas

¿Qué hace flow-atlas?

El AGENTS.md propio del repositorio, los documentos de diseño y las pruebas de gobierno tienen prioridad sobre esta habilidad.

Tres partes

atlas genera lo que el código establece. Tú escribes lo que necesita intención, y atlas lo verifica. Entre ambos, interpretas qué trabajo pertenece a qué componente, con los criterios en references/boundaries.md. Todo lo que decides va a un archivo que atlas lee (archivos de flujo, el archivo de excepciones, la configuración, retroalimentación), así que la siguiente ejecución y el siguiente agente lo ven.

atlas genera: nunca escribas esto a mano

Hecho	Comando
superficies, llamadas, aristas, operationIds, registros, versiones de contrato	scan
superficies y llamadas por ruta, método o componente	query
los llamantes de una superficie aguas arriba y los servicios que alcanza aguas abajo	trace
un borrador de Flow: nombre, pasos a lo largo de la ruta del código, entrada cuando un componente lo llama, candidatos donde se ramifica	draft flow
si un Flow se mantiene en el código y si sus campos de autor están escritos	flows (condiciones)
hallazgos con ubicaciones y rutas cercanas	check, explain
qué cambió entre revisiones	diff
candidatos de configuración y cuánto cubre la configuración	inventory, scan
las descripciones OpenAPI de cada componente, hasta qué punto las confirmadas concuerdan con el código, y cuál es la del componente cuando el código lo decide	scan, inventory

No hagas grep de graph.json, no adivines llamantes mediante búsqueda de texto ni escribas ids de superficies de memoria: cópialos de la salida de atlas.

Tú escribes: atlas lo verifica

Qué	Verificado por
el title de un Flow y el role de cada paso	Documented
owner, labels, sources, lifecycle (planned cuando un paso no está construido)	esquema; Resolved cuenta los pasos planificados aparte
generated: { by: <herramienta>/<modelo>, at } una vez que has escrito la intención de un flujo; stale_after cuando debe revisarse (OKF)	esquema; Fresh
el componente de entrada cuando varios llaman al primer paso; el siguiente paso donde el manejador se ramifica	EntryCalled, Connected
produces	ProducesListed
excepciones: razón, decidedBy, reviewBy	el vencimiento trae de vuelta el hallazgo
falsos positivos, con el motivo	stats
la configuración	cobertura de scan
el documento OpenAPI que el framework genera, para un componente que atlas no puede analizar (routes[].openapi, references/openapi.md)	cobertura de scan y líneas limit:
origins: la URL base en la que cada componente se ejecuta en un entorno, desde los archivos de despliegue	export arazzo nota uno faltante
openapi.<componente> cuando atlas informa que su descripción es ambiguous	export arazzo se niega hasta que esté definido

No delegues tu parte a la herramienta: no hay publicSurfaces, excepción o actualización de línea base sin una razón que una persona aceptaría. Nunca escribas una entrada verified con un actor human:: eso registra una revisión de una persona, y el nivel de confianza del flujo (unverified, machine-confirmed, human-reviewed) depende de ello.

Tú interpretas: límites

Si un salto pertenece al componente en el que se encuentra, si una superficie similar ya hace el trabajo, si una brecha es un defecto, un plan o un falso positivo, hasta dónde confiar en una arista, y dónde comienza y termina un flujo. Sigue references/boundaries.md; ordena las fuentes (reglas del repositorio, luego roles de flujo, luego código) y da los criterios.

Configuración

• Ejecuta atlas --help. Si atlas no está instalado, ejecútalo a través de npx (npx github:hellices/flow-atlas --help) o pide al usuario que lo instale; no reimplementes sus lecturas a mano.
• La configuración es <raíz>/atlas.config.yaml, <salida>/atlas.config.yaml, o --config <archivo>. Si no hay ninguna, sigue "Configuración inicial" a continuación.
• Si no se debe escribir en el repositorio, pasa --out <directorio fuera de él>. Cada escritura va allí.

Diseñando un cambio

1. atlas query --path <ruta o fragmento> y atlas query --component <nombre> para ver qué existe ya.
2. atlas trace <superficie más cercana> para ver la cadena: llamada de cliente, ruta BFF, los métodos de puerto que alcanza su manejador, la ruta del servicio que coincide con cada uno.
3. Decide: reutilizar, extender o agregar. Anota las claves de superficie que agregarás o cambiarás y qué componente posee cada salto. Si dos componentes terminarían haciendo el mismo paso, resuelve eso antes de escribir código.
4. Si el repositorio mantiene flujos (flows/*.flow.yaml), actualiza el Flow, o comienza uno nuevo con atlas draft flow <surface> (ver "Escribiendo un flujo"). Marca los pasos que aún no existen con lifecycle: planned.

Mientras implementas

Después de agregar una ruta o una llamada de cliente, ejecuta atlas trace <superficie>. Aguas arriba debería mostrar el llamante que pretendías y aguas abajo las llamadas que pretendías. Un lado vacío significa que no está cableado aún, o está cableado de una manera que la herramienta no puede leer (una ruta construida lejos de la llamada, un manejador en otro idioma); abre el código y dilo.

Cuando agregues, elimines o cambies una ruta de un componente cuyas rutas provienen de un documento OpenAPI generado, regenera el documento en el mismo cambio. Una llamada de cliente por sí sola no lo cambia.

Escribiendo un flujo

1. atlas draft flow <primera superficie> imprime un Flow con todo lo que el código establece; añade --to <superficie> para seguir el código hasta un final dado. Guárdalo bajo flows/<nombre>.flow.yaml (o <salida>/flows/ para un repositorio que no debas modificar).
2. Llena cada comentario agent:: title, role de cada paso (qué hace el componente y deja a otros), owner, lifecycle, produces; elige la entrada y los siguientes pasos donde el borrador lista candidatos. Mantén los valores sin marcador; provienen del código.
3. atlas flows hasta que el flujo tenga Ready=True. Un Resolved, Connected o EntryCalled falso significa que el código o el flujo está mal: decide cuál con references/boundaries.md. Un Documented falso significa que un campo de autor está vacío.

Un archivo puede contener varios flujos separados por ---. Los ids de superficie escriben parámetros de ruta como plantillas OpenAPI ({id}). No copies ubicaciones, aristas o condiciones en el archivo; atlas las calcula en cada ejecución. El formato es schema/flow.schema.json en el paquete flow-atlas, cuyos docs/schema.md y docs/responsibilities.md lo explican.

Antes de finalizar

1. atlas check --since <revisión desde la que empezaste>. Solo aparecen los hallazgos que introdujo tu cambio.
2. Para cada uno: atlas explain <clave> muestra las ubicaciones y rutas similares. Luego arréglalo, o registra una excepción, o registra un falso positivo. Ver "Manejo de un hallazgo".
3. Pon atlas diff <base>..WORKTREE --format markdown (o <base>..HEAD) y el trace de cada nueva superficie en la descripción del PR o nota de entrega.

Cuando la configuración se ha quedado atrás

Señales: líneas limit: en stderr (los archivos configurados no coinciden con nada, una fuente produce menos de la mitad de su línea base), o FA001 en rutas que sabes que son llamadas. Ejecuta atlas inventory, compara con la configuración, corrígela (references/config.md), y verifica la cobertura de atlas scan nuevamente. Pregunta a una persona antes de atlas baseline update.

Configuración inicial

atlas inventory lista candidatos sin decidir nada. Escribe la configuración a partir de eso (references/config.md); para un framework de servidor que atlas no analiza (Spring, Django, Flask y otros), genera su documento OpenAPI y apunta las rutas hacia él (references/openapi.md), ejecuta atlas scan hasta que cada fuente produzca lo que esperas, ejecuta atlas check, y repasa una muestra de hallazgos con una persona. Solo entonces registra la línea base.

Manejo de un hallazgo

Decide primero si es un defecto, un plan o un falso positivo (references/boundaries.md), luego:

• Arréglalo cuando el hallazgo sea el error: cablea el llamante faltante, elimina la ruta muerta, agrega el productor, apunta la llamada a la ruta servida. references/rules.md lista las causas habituales por regla.

• Cuando el código es correcto a propósito, agrega una excepción que nombre la decisión:

  # flows/atlas-exceptions.yaml (o <salida>/exceptions.yaml)
  - rule: FA001
    key: FA001|orders|GET /orders/{id}/history
    reason: El servicio se envía primero; la pantalla de la aplicación sigue en la próxima versión.
    decidedBy: docs/orders.md#history
    reviewBy: 2026-12-31
  

  Las superficies servidas a clientes fuera del repositorio van en publicSurfaces en la configuración.

• Cuando el hallazgo es incorrecto: atlas feedback <clave> false-positive --note "<motivo>". Si el extractor leyó mal un archivo, di qué archivo y cómo.

Nunca ejecutes atlas baseline update a menos que una persona lo solicite. Nunca edites código generado para satisfacer un hallazgo.

Salida legible por máquina

--format json o --format yaml imprime documentos que siguen el esquema schema/*.schema.json del paquete flow-atlas, cada uno con apiVersion, kind y provenance (la confirmación y los archivos leídos, con resúmenes). Lee estos en lugar de analizar la salida de texto; ramifica según el reason de una condición, no su message. atlas check --format sarif da los hallazgos como SARIF 2.1.0 para escaneo de código y visores de IDE; atlas export arazzo da los flujos como Arazzo 1.0 para flujos de trabajo de API y herramientas e2e, que aún necesitan parámetros, cuerpos de solicitud y criterios de éxito completados.

Leyendo la salida

• Estado del hallazgo: new es tuyo; baseline es deuda aceptada; excepted está cubierto; expired-exception necesita a una persona.
• En un trace, = une una llamada a una superficie por método y ruta; ~ une una ruta a una llamada saliente que ejecuta su manejador: escrito en el propio código del manejador o en las funciones que llama (evidencia static), o contenido en un método de un nombre que el manejador llama (evidencia name), o, para una página Spring, realizado por la plantilla que renderiza su nombre de vista (via view <nombre>). Un ~ por nombre a través de un nombre genérico (get, send) necesita una revisión del código.
• La llamada in <nombre> es la función que contiene la cadena. Una cadena en una etiqueta de error o un mensaje de registro no es una solicitud aunque parezca una ruta; el ámbito generalmente lo muestra.
• Solo se leen los archivos configurados, y en ellos solo lo que está escrito con certeza: rutas literales, con el significado que un estándar o el framework les da. Una URL proveniente de una variable, otro motor de plantillas, o atributos htmx y Vue no se lee ni se adivina. Por lo tanto, "sin llamante" significa ninguno que atlas pueda leer; verifica el código antes de eliminar cualquier cosa, y declara las superficies servidas fuera del repositorio en publicSurfaces. Ningún hallazgo no prueba que un flujo esté completo.

Referencias

• Interpretación de límites, decidir defecto, plan o falso positivo: references/boundaries.md
• Reglas, causas, resoluciones, cuándo encaja una excepción: references/rules.md
• Escribir o corregir la configuración: references/config.md
• Leer rutas desde el documento OpenAPI generado de un framework, y cómo generarlo: references/openapi.md