toyin-software-factory/audit

Estilo de salida (palabras llanas, sin guiones, sin guiones ortográficos)

Escribe todo lo que esta habilidad produce, archivos y mensajes por igual, en lenguaje llano y simple. Háblale al lector como tú, cálido y directo como un colega, y presenta cada paso como una recomendación que pueden ejecutar o saltarse, nunca una orden. Mantén los términos técnicos que tengan un significado real; explica cada uno en palabras llanas. Nunca uses un guion largo ni un guion ortográfico como signo de puntuación: no uses guion largo, guion medio ni compuestos con guion ortográfico. Escribe de solo lectura, no de-solo-lectura. Dilo en palabras simples o reformula la oración. El código, las rutas de archivo, las banderas de comandos y los valores que otras habilidades usan para coincidir conservan sus guiones. Usa oraciones cortas, comas o paréntesis. La claridad vence a la astucia.

Qué hace esta habilidad

El iniciador de contexto: escribe los archivos AGENTS.md que toda habilidad posterior y herramienta de IA leen.

• Proyecto greenfield (aún sin código): pregunta por estándares de codificación, siembra el AGENTS.md raíz a partir de las respuestas más el enfoque de construcción (nombre y principio de una línea) del encabezado de alcance si /scope lo estableció. Se ejecuta después de que el proyecto se haya armado con su stack elegido (/scope → /architect decide el stack → armado → /audit); hacerlo antes es prematuro.
• Proyecto brownfield, sin documentar (código, sin AGENTS.md): escanea todo el proyecto, escribe AGENTS.md raíz y archivos <area>/AGENTS.md anidados, juzgando qué es global (raíz) vs específico del área (anidado).
• Proyecto brownfield, parcialmente documentado: verifica los documentos raíz y anidados existentes contra todo el código base; añade solo lo que falta (nuevos hechos globales, documentos anidados para áreas no documentadas); nunca sobrescribe contenido curado.

No crea especificaciones (/architect es dueño de esas), no mantiene archivos después de cambios (/sync es dueño de eso), ni escribe el alcance de la característica (/scope es dueño de docs/scope/).

Convención de archivos de contexto (AGENTS.md es canónico)

El contexto duradero vive en AGENTS.md (raíz y anidado), que es agnóstico a la herramienta; cada agente (Codex, Cursor, Claude Code y otros) lo lee. CLAUDE.md es solo un puntero de una línea cuyo cuerpo completo importa el AGENTS.md hermano mediante la importación @ de Claude Code (cuerpo del puntero exacto en agent-prompt.md); el contenido nunca se duplica entre los dos.

• Escribe el conocimiento en AGENTS.md. Créalo cuando falte. Nunca sobrescribas un AGENTS.md existente (puede haber sido creado por el usuario o una herramienta); rellena los vacíos con prudencia y con permiso.
• Migra contenido heredado: un CLAUDE.md con contenido pero sin AGENTS.md → pide permiso, mueve su contenido a un nuevo AGENTS.md, reemplaza CLAUDE.md con el puntero. Nunca descartes en silencio contenido curado.
• La raíz se mantiene corta y global; AGENTS.md anidado solo para áreas significativas con convenciones reales (mismas reglas raíz/anidado que se aplicaban antes a CLAUDE.md).

Alcance

Un argumento de ruta de área (ej. auth, src/payments) desencadena la Fase 3. Sin argumento, las señales de Pre-vuelo a continuación enrutan a la Fase 0 (ambiguo: preguntar nuevo vs existente), Fase 1 (greenfield: preguntar estándares, sembrar raíz), Fase 2 (establecido, sin AGENTS.md raíz: escaneo de todo el repositorio) o Fase 4 (existe AGENTS.md raíz: relleno de vacíos). Un CLAUDE.md heredado con contenido pero sin AGENTS.md se migra y luego se trata como Fase 4.

Actúa vs pregunta

La Fase 1 hace preguntas sobre estándares de codificación mediante MCQ antes de crear el AGENTS.md raíz. La Fase 2 actúa de inmediato, sin preguntas; escribe la raíz y los documentos anidados que considere justificados. Las Fases 3 y 4 actúan para explorar pero piden permiso antes de modificar un AGENTS.md raíz existente o migrar un CLAUDE.md heredado; la Fase 4 informa primero sobre la creación de documentos anidados para áreas no documentadas y luego aplica tras la confirmación.

Propiedad de los artefactos

Los archivos AGENTS.md contienen el contenido: crear raíz si falta (Fase 1, 2) y <area>/AGENTS.md si falta y está justificado, según el criterio (Fase 2, 3, 4); cuando existe uno, rellenar vacíos o proponer adiciones con permiso; nunca sobrescribir. Los archivos CLAUDE.md son solo punteros (raíz y área), creados si faltan; uno heredado con contenido se migra a AGENTS.md con permiso. Al crear un AGENTS.md anidado, añade exactamente una línea de puntero al AGENTS.md raíz debajo de ## Archivos de contexto: - [<area>/AGENTS.md](<area>/AGENTS.md) (<descripción de una línea>). Nunca uno por subcarpeta, solo donde existan convenciones distintas.

Portabilidad (cualquier SO, cualquier agente)

• Comandos: git es la única CLI requerida, igual en todos los SO. Otros fragmentos de shell (recuento de archivos, find, [ -f ]) son referencia POSIX, no scripts literales; usa las herramientas multiplataforma de archivos de tu agente (búsqueda/glob, lectura, escritura) para listar, contar y verificar la existencia.
• Los archivos empaquetados viven en la carpeta de esta habilidad: agent-prompt.md, los archivos de modo de fase (modes/*.md) y los preajustes de patrón (patterns/*.md). Resuelve la carpeta a una ruta absoluta. Lee el archivo de modo de fase correspondiente al enrutar, luego agent-prompt.md más el preajuste de patrón SELECCIONADO al momento de escribir. Sus marcadores de posición en MAYÚSCULAS (PHASE, AREA, ADDITIONAL_STANDARDS, MONOREPO_OR_NO, INSTALLED_SKILLS, DECLINED_TOOLS, etc.) son las entradas que recopilaste en el pre-vuelo y las rondas de preguntas; aplica cada una a medida que lees.
• ¿No hay soporte para preguntas interactivas? Haz cualquier pregunta de opción múltiple como texto plano con las mismas opciones.

Ejecución

El hilo principal realiza la escritura en cada fase; nunca delega la escritura de AGENTS.md a un subagente. El único subagente es un explorador de solo lectura (modelo más barato, Claude Code: haiku, nunca el modelo de la sesión), generado solo para un escaneo grande; devuelve un mapa compacto desde el cual el hilo principal escribe. Un armazón pequeño o un área única no necesita explorador; léelo directamente. Justo antes de escribir, lee agent-prompt.md (persona, instrucciones por fase, plantillas) más, en la Fase 1, el preajuste de patrón seleccionado; luego escribe siguiéndolo. Lee agent-prompt.md solo al momento de escribir, no durante el pre-vuelo.

Pre-vuelo (el hilo principal hace esto antes que cualquier otra cosa)

Recopila varias señales (un recuento de archivos solo engaña: un armazón lo infla, un lenguaje desconocido lo reduce a cero):

1. Archivos de contexto: AGENTS.md raíz presente → ROOT_EXISTS; un CLAUDE.md solo con contenido → ROOT_LEGACY; ninguno → ROOT_MISSING.
2. Recuento de fuentes en ecosistemas comunes (extensiones como .ts/.tsx/.js/.jsx/.py/.go/.rs/.java/.rb/.swift/.kt/.php/.cs/.dart/.ex/.exs/.scala/.c/.cpp/.h/.lua/.clj), excluyendo directorios vendidos/generados (node_modules, .git, dist, build) y archivos de configuración (*.config.*).
3. Señales establecidas: git log --oneline para profundidad del historial de commits; un manifiesto real (package.json, pyproject.toml, go.mod, Cargo.toml, composer.json, *.csproj, pubspec.yaml, mix.exs, Gemfile).
4. Señal de monorepo: marcadores de espacio de trabajo (pnpm-workspace.yaml, turbo.json, un campo "workspaces" en package.json) o cualquier apps/*/package.json / packages/*/package.json cerca de la raíz.
5. Señal de configuración del flujo de trabajo (WORKFLOW_SETUP): el AGENTS.md raíz FALTA mientras que el flujo de trabajo ya ha decidido el stack, es decir, existe una especificación de arquitectura docs/specs/ (una sección ## Stack propuesto) y/o docs/scope/ tiene una característica de "Stack y arquitectura" (o armazón fundacional similar). Este es el orden greenfield previsto (/scope → /architect decide el stack → /develop lo arma → /audit): recién armado, aún necesita capturar los estándares de codificación. Cuando se activa, el manifiesto y el código fuente del armazón que ahora existen son el armazón, no un código base existente.

Elige la fase. El orden de las comprobaciones importa: la señal de configuración del flujo de trabajo supera al recuento bruto de código, porque un armazón fresco tiene un manifiesto y archivos fuente pero sigue siendo greenfield.

Condición	Fase
Ruta de área dada como argumento	Fase 3
ROOT_EXISTS (o ROOT_LEGACY después de la migración)	Fase 4
ROOT_MISSING y WORKFLOW_SETUP (especificación de stack y/o característica de alcance del stack)	Fase 1, aunque ahora existan un manifiesto y código fuente del armazón. Pregunta por los estándares de codificación; siembra la raíz a partir del stack de la especificación. Nunca trates un proyecto de flujo de trabajo recién armado como brownfield.
ROOT_MISSING, sin WORKFLOW_SETUP, sin archivos fuente Y sin manifiesto	Fase 1
ROOT_MISSING, sin WORKFLOW_SETUP, tiene código (fuente ≥ 10 o un manifiesto), ≥ 2 commits y claramente código de característica real (no solo armazón)	Fase 2, cualquier lenguaje
ROOT_MISSING, sin WORKFLOW_SETUP, tiene código pero parece armazón intacto, o ≤ 1 commit, o no puedes diferenciar greenfield de brownfield	Fase 0, preguntar

Por qué este orden: un armazón fresco tiene un manifiesto y archivos de inicio pero sigue siendo greenfield, por lo que un recuento bruto de código solo lo malinterpretaría como brownfield y saltaría las preguntas sobre estándares; la señal de configuración del flujo de trabajo lo detecta y enruta a greenfield. Brownfield real (Fase 2) significa código de característica real, historial real y sin configuración de flujo de trabajo en curso. Cualquier ambigüedad cae en la Fase 0; nunca establezcas por defecto un proyecto tal vez greenfield como brownfield.

Monorepo (MONOREPO=yes): raíz más un stub ligero por espacio de trabajo, profundizar bajo demanda. Cada espacio de trabajo (apps/*, packages/*) es un área de primera clase; su documento principal vive en la raíz del espacio de trabajo (packages/api/AGENTS.md), nunca enterrado más profundo. Una ejecución de todo el repositorio no escanea en profundidad cada espacio de trabajo; escribe el AGENTS.md raíz del repositorio (herramientas de todo el monorepo, convenciones compartidas) más un stub ligero por espacio de trabajo desde su manifiesto, sin escaneo de código, con punteros raíz. El escaneo completo de convenciones/gotchas/archivos clave ocurre cuando el ingeniero ejecuta /audit packages/api (Fase 3) o construye allí por primera vez. Un punto dentro de un espacio de trabajo que justifique su propio documento (packages/ui/src/mdx/) recibe uno además del documento raíz del espacio de trabajo, vinculado desde él. Un documento ya enterrado en un espacio de trabajo sin documento raíz del espacio de trabajo: pregunta: "packages/ui tiene un archivo de contexto en src/mdx/ pero ninguno en su raíz. ¿Lo muevo a packages/ui/AGENTS.md, o lo mantengo como un documento anidado bajo un nuevo packages/ui/AGENTS.md?" Al moverlo: reubicarlo en la raíz del espacio de trabajo. Al mantenerlo anidado: crear el AGENTS.md raíz del espacio de trabajo Y mantener el profundo, vinculado desde la raíz. Migrar el contenido heredado de CLAUDE.md según la convención anterior. Aplica MONOREPO=yes más la lista de espacios de trabajo al escribir.

Migración heredada (cualquier fase): en ROOT_LEGACY, antes de proceder, pide permiso: "Encontré un CLAUDE.md con contexto del proyecto pero sin AGENTS.md. Moveré su contenido a un nuevo AGENTS.md (para que todas las herramientas lo lean) y reemplazaré CLAUDE.md con un puntero. ¿Procedo?" Si es sí: copia el contenido textualmente en AGENTS.md, luego reemplaza CLAUDE.md con el puntero; AGENTS.md ahora existe, así que continúa como Fase 4 (relleno de vacíos). Si es no: deja ambos intactos y continúa sin migrar. Lo mismo para cualquier <area>/CLAUDE.md anidado.

Enrutar a la fase seleccionada

La Fase 0 (ambiguo) se maneja en línea a continuación. Para las Fases 1 a 4, lee solo el archivo de modo correspondiente, luego síguelo:

• Fase 1 (configuración greenfield) → modes/greenfield.md
• Fase 2 (escaneo de todo el repositorio) → modes/whole-repo.md
• Fase 3 (escaneo de área) → modes/area.md
• Fase 4 (relleno de vacíos) → modes/gapfill.md

No leas los otros archivos de modo. Los modos greenfield y de todo el repositorio también leen modes/tool-skills.md para el barrido de Habilidades de Agente / MCP (saltarlo para ejecuciones de área y relleno de vacíos).

Fase 0: Clasificar (solo cuando el pre-vuelo es ambiguo)

No adivines. Pregunta una vez mediante el selector de opciones interactivo de tu agente (AskUserQuestion en Claude Code), o texto plano con las mismas opciones. Marca una opción (recomendada) según cuál sea la señal más fuerte (un árbol similar a un armazón con un manifiesto pero poca historia se inclina a Nuevo; código de característica real e historia profunda se inclina a Existente), y el selector añade un espacio personalizado de texto libre al final:

• pregunta: "No puedo distinguir si esto es un proyecto nuevo o un código base existente (<explica por qué: ej. 'existe un manifiesto pero no veo código fuente en un lenguaje que reconozca', o 'los archivos parecen un armazón intacto'>). ¿Qué es?"
• encabezado: "Estado del proyecto"
• opciones: 1. Proyecto nuevo, "Te preguntaré por tus estándares de codificación y sembraré el contexto." → Fase 1 (lee el manifiesto/armazón para el stack; aún pregunta por estándares). 2. Código base existente, "Escanearemos lo que hay y lo documentaremos." → Fase 2.

Después de todas las fases

Si no se escribió ningún AGENTS.md cuando debería haberse hecho (el archivo falta/está vacío), informa del fallo y hazlo de nuevo; no transmitas éxito si no lo produjo. De lo contrario, transmite el informe: qué se descubrió (2 a 4 viñetas), qué se escribió (rutas de archivo), qué se propuso o saltó (si se encontraron archivos existentes).

Preajustes de patrón

Consulta patterns/ para los cuatro preajustes de estilo de codificación utilizados en la Fase 1 (modo greenfield).

Guía de escritura

Consulta agent-prompt.md (el hilo principal lo lee al momento de escribir; sus instrucciones por fase y plantillas de AGENTS.md).