Arch Init

Skill: Inicialización del harness de agentes (arch-init)

Inicializa, en un proyecto en cualquier punto de partida, las primeras instrucciones persistentes y compatibles con múltiples agentes: repositorio git, los archivos base del harness (AGENTS.md, CLAUDE.md, .agents/MEMORY.md, .sdd-devkit/settings.json, docs/adr/README.md, docs/standards/README.md, README.md de la raíz), un stack tecnológico definido, una compuerta de calidad mínima y las decisiones relevantes documentadas como ADR/estándares.

Completa siempre lo que falta. El punto de partida que identifica el Paso 1 — sin código, con código base, o con implementación — solo decide cómo se llega a cada pieza (p. ej. un stack ya detectado salta el Paso 2). El resultado al cerrar es siempre el mismo checklist completo, sin importar de dónde partió. Excepción: "Solo specs". Un repositorio sin código de aplicación (nunca lo va a tener) no es un punto de partida más de esa escala, sino un tipo de repositorio distinto: su checklist de cierre es deliberadamente más corto — sin stack, sin candidatos de arquitectura ni compuerta de calidad, sin docs/adr//docs/standards/ propios — porque nada de eso aplica a un repositorio que solo contiene documentación.

Alcance: este skill bootstrapea el harness — es el primer paso de SDD Devkit, antes de que exista nada que arch-discover, arch-manage, arch-audit o quality-check puedan leer, auditar o revisar. No reemplaza a work-define / work-plan / work-implement (historias y tareas) ni reimplementa la lógica de esos skills — los invoca cuando corresponde. Se ejecuta normalmente una vez por proyecto; volver a ejecutarlo sobre uno ya inicializado solo completa lo que falte (ver Idempotencia).

Orden con compuertas: no se avanza de paso mientras el anterior no esté resuelto. La sección # Stack tecnológico de AGENTS.md se deja con su comentario de plantilla hasta el cierre (Paso 5) — no se rellena antes, aunque el stack ya se conozca desde el Paso 1 o el Paso 2.

Relación con el resto de SDD Devkit

arch-init es el único punto de entrada que crea AGENTS.md, .agents/MEMORY.md, .sdd-devkit/settings.json, docs/adr/README.md, docs/standards/README.md y el README.md de la raíz desde cero — el resto de skills de arquitectura los dan por existentes (o toleran que estén vacíos):

Cómo preguntar al usuario

Mecanismo, ritmo y fallback compartidos: ${PLUGIN_ROOT}/reference/asking.md.

Cada vez que este skill o sus referencias digan preguntar, pedir, confirmar, validar o sugerir algo al usuario, asume ese mecanismo; no se repite allí.

Ritmo propio: una tanda por paso, no una sola al inicio. Este flujo tiene cinco pasos con preguntas en cada uno; agrupar las de un mismo paso en un solo bloque, sin tope fijo de preguntas por bloque. En modo multi-repo, "un paso" se entiende por submódulo cuando el paso se repite por submódulo (Pasos 1.2, 1.3, 2, 4): agrupar en una tanda las preguntas de varios submódulos que compartan el mismo paso, no una tanda por submódulo.

Selección múltiple donde el paso lo indique explícitamente: capas de testing y candidatos de ADR.

Rutas de las referencias compartidas

${PLUGIN_ROOT} es la raíz del plugin instalado (la carpeta que contiene skills/, agents/ y reference/), y toda referencia compartida de este skill se escribe como ${PLUGIN_ROOT}/reference/<archivo>.md. Resolverla así, en este orden: (1) en Claude Code, ${PLUGIN_ROOT} es ${CLAUDE_PLUGIN_ROOT} — comprobar con echo "$CLAUDE_PLUGIN_ROOT" y usar ese valor; (2) en cualquier otro cliente, o si la variable está vacía, la carpeta desde la que se cargó este archivo, dos niveles arriba. El destino de cada enlace markdown (../../reference/…) existe solo para navegar el repositorio en GitHub o en un editor: no resolverlo desde el directorio de trabajo. Nunca buscar reference/ en el proyecto: un <proyecto>/reference/language.md que no existe no es un archivo que falte, es una ruta mal resuelta — corregir la raíz y volver a leer, sin preguntar al usuario ni saltarse la lectura.

Resolución de idioma

Antes de ejecutar este skill, DEBES leer ${PLUGIN_ROOT}/reference/language.md.

Las reglas de language.md son obligatorias y tienen prioridad para determinar el idioma de todos los artefactos y mensajes generados por este skill.

No continúes hasta haber leído y aplicado language.md.

Excepción deliberada: este skill crea el archivo donde language.md lee el idioma. El idioma resuelto se persiste en la clave language de .sdd-devkit/settings.json al crearlo (Paso 3); a partir de ahí lo lee todo el catálogo.

Mapa del harness

Los archivos del harness que ya existan en el proyecto se revisan en el Paso 3. AGENTS.md, CLAUDE.md, .agents/MEMORY.md, .sdd-devkit/settings.json, docs/adr/README.md y docs/standards/README.md se llevan al formato de su plantilla (ver 3.1 Migración de formato) — no admiten variantes de formato, porque el resto del catálogo lee sus secciones por título; en multi-repo, esto aplica una vez por cada copia de AGENTS.md/CLAUDE.md (raíz principal y cada submódulo), cada una comparada contra la plantilla que le corresponde. README.md es distinto: no tiene una plantilla de secciones fija: es un artefacto libre del proyecto, y su única regla de conformidad es tener, cerca del inicio, la descripción de qué hace el proyecto (o ese repositorio, en un submódulo) en 1-2 párrafos, sin que arch-init toque el resto de su contenido — ver 3.4 README.md raíz — descripción del proyecto.

Raíz de los índices de arquitectura. Los dos índices (docs/adr/README.md, docs/standards/README.md) son artefactos de arquitectura: pertenecen a la raíz del repositorio cuyo código documentan (ver ${PLUGIN_ROOT}/reference/artifacts.md). La raíz principal los recibe (AGENTS.md los referencia) salvo que esté clasificada "Solo specs" (Paso 1.2) — un repositorio sin código de aplicación nunca los recibe, sin excepción y sin preguntarlo; el repositorio de especificaciones en multi-repo es siempre "Solo specs", así que nunca tiene los suyos propios. Si el proyecto tiene submódulos o repositorios anidados que no sean "Solo specs", preguntar en el Paso 3 para cuáles de ellos crear además los suyos — cada raíz lleva su propia serie ADR-XXX. No crearlos en un submódulo sin preguntar (ni en uno "Solo specs" bajo ninguna circunstancia), ni asumir que un submódulo comparte los del padre.

Único vs. por repositorio. .agents/MEMORY.md y .sdd-devkit/settings.json son artefactos únicos de la solución: viven solo en la raíz principal, nunca en un submódulo. AGENTS.md, CLAUDE.md y README.md no son únicos: cada repositorio —la raíz principal y cada submódulo— tiene el suyo propio, porque un agente puede trabajar directamente dentro de un submódulo sin pasar por la raíz principal y necesita encontrar ahí sus propias instrucciones. docs/adr/README.md/docs/standards/README.md siguen la lógica de la raíz de arquitectura de arriba, independiente de esta distinción.

Proyecto de un solo repo vs. multi-repo. "Repositorio principal" arriba no es siempre el directorio desde el que se invocó el skill: si la solución abarca más de un repositorio, el Paso 1.0 crea un repositorio de especificaciones que pasa a ser el principal y agrega el resto de repos como submódulos en su raíz — ver references/multi-repo.md, en particular su § 4 para el contenido exacto del AGENTS.md de un submódulo. Con un solo repo, nada de esto aplica y el comportamiento es el descrito arriba sin cambios.

Paso 1 — Identificar el punto de partida

Leer references/stack-detection.md completo antes de este paso.

1.0 Topología del proyecto (repo único vs. multi-repo)

Leer references/multi-repo.md completo antes de continuar. Antes de resolver el repositorio git, decidir si la solución abarca uno o más de un repositorio: preguntar al usuario — no hay señal de código que lo infiera con confianza, a diferencia de la clasificación del 1.2.

• Uno solo → sin cambios de comportamiento. Continuar en el 1.1 sobre el directorio de invocación.
• Más de uno → crear (o usar, si ya existe) un repositorio de especificaciones que pasa a ser la raíz principal para todo el resto del flujo, y agregar cada repositorio adicional como submódulo en su raíz. El detalle completo — cómo preguntar nombre/ubicación, cómo distinguir repos existentes de nuevos, los comandos de git submodule, y cómo se repiten los Pasos 1.2, 1.3, 2, 4 y 5.2 por cada submódulo — vive en references/multi-repo.md. El 1.1 de abajo queda resuelto por este mismo paso; no se repite.

1.1 Repositorio git

• git rev-parse --is-inside-work-tree. Si falla, ejecutar git init e informar que se creó el repositorio (sin hacer commit todavía — el primer commit queda a criterio del usuario, p. ej. vía git-commit después del Paso 3).
• Si ya es un repo git, no tocar la configuración existente (remoto, ramas, hooks).
• Multi-repo: este paso ya se resolvió al crear/usar el repositorio de especificaciones en el 1.0; no se repite aquí.

1.2 Clasificar la situación

Aplicar las señales de references/stack-detection.md § 2 para ubicar el proyecto en una de cuatro situaciones:

Si el resultado es ambiguo, preguntar al usuario en vez de asumir — la ausencia de manifiestos por sí sola no distingue "sin código" de "solo specs" (ver stack-detection.md § 2). Esta clasificación decide si el Paso 2 hace falta (Sin código únicamente) y cómo se identifican los candidatos de arquitectura en el Paso 4 (Solo specs lo salta por completo, igual que el Paso 2 — ver la nota en cada uno).

Multi-repo: esta clasificación se aplica una vez por cada submódulo (nunca al repositorio de especificaciones, que es automáticamente Solo specs por definición — no se le pregunta, ver references/multi-repo.md § 8) — cada submódulo puede quedar en una situación distinta, Solo specs incluida. Ver references/multi-repo.md § 3.

1.3 Detectar el stack tecnológico

Buscar los manifiestos de references/stack-detection.md § 1. Con código base y Con implementación siempre tienen stack detectable — registrar internamente lenguaje(s), framework(s) y versiones (se usan en el cierre, Paso 5). Sin código no tiene nada que detectar: el Paso 2 es obligatorio.

Multi-repo: igual que el 1.2, esta detección corre una vez por cada submódulo, sobre su propia raíz.

Paso 2 — Conseguir el stack

Solo si el Paso 1.2 clasificó "Sin código". En cualquier otro caso —incluido "Solo specs", que no tiene ni va a tener stack de aplicación— saltar directo al Paso 3.

Multi-repo: este paso se ejecuta por cada submódulo que el 1.2 haya clasificado "sin código". Si son varios a la vez, agrupar sus preguntas del 2.1 en una sola tanda (una sub-pregunta por submódulo) en vez de una tanda por submódulo, y reutilizar el propósito que el usuario ya describió al identificar ese repo en el 1.0 en vez de repreguntarlo desde cero. Ver references/multi-repo.md § 3.

2.1 Preguntar qué se quiere desarrollar

No arrancar con una categoría cerrada de "tipo de proyecto" ni con una pregunta de preferencia de stack por separado. Preguntar primero, en lenguaje abierto: "¿Qué quieres desarrollar?" — pedir que describa la necesidad: qué problema resuelve, para quién, y cualquier restricción o preferencia que ya tenga en mente (integraciones con algo existente, rendimiento esperado, quién lo va a mantener, plazos). Es una respuesta de texto libre; si el cliente expone la herramienta de preguntas estructuradas, usarla igual con una opción de entrada libre en vez de forzar categorías.

De la respuesta, extraer (sin volver a preguntar por separado): el tipo de proyecto (se infiere, no se pregunta aparte), cualquier preferencia de stack ya mencionada, y las restricciones relevantes (integraciones, rendimiento, equipo, plazos, licenciamiento).

Si la respuesta es demasiado vaga para decidir nada (p. ej. "una app"), repreguntar una sola vez pidiendo más detalle — no avanzar con una necesidad ambigua.

2.2 Sugerir directo o investigar primero

Con la necesidad ya capturada, decidir cómo se llega al stack:

• El usuario ya mencionó una preferencia de stack explícita en el 2.1 → usarla directamente. Saltar a 2.3.
• No hay preferencia, pero la necesidad es común y el criterio es claro (stack bien establecido para ese tipo de proyecto, sin restricciones inusuales) → sugerir directamente 1-2 opciones con una justificación breve (1-2 líneas, atada a la necesidad descrita) y presentarlas con la herramienta de preguntas estructuradas: opciones = cada stack sugerido, más Quiero que investigues más opciones y Tengo otra preferencia (texto libre). No hace falta un subagente para este caso.
• Hay trade-offs no triviales, restricciones específicas que cambian la respuesta obvia, o el usuario pide explícitamente que se investigue → delegar en un subagente que ejecute el skill work-research (dominio Técnica, investigación independiente — no hay US/WI/MG todavía) con una pregunta construida a partir de la necesidad capturada (el problema y sus restricciones, no una categoría genérica), p. ej. "¿Qué stack tecnológico es más adecuado para <necesidad descrita, con sus restricciones>?". Pedirle explícitamente que, para cada opción, incluya los comandos exactos de instalación/scaffolding — no solo la comparación teórica. work-research guarda su informe en docs/specs/research/RS-XXX-{slug}/README.md; esperar su resultado y presentar las opciones al usuario (una por stack, más Ninguna, decido yo).

Ante la duda entre sugerir directo o investigar, preferir investigar: una sugerencia sin respaldo en un stack con opciones reñidas cuesta más corregir después que un RS-XXX de más.

Si durante 2.1 o 2.2 hace falta alguna aclaración adicional del usuario para poder decidir, preguntarla en el momento — no acumular ambigüedades para más adelante.

2.3 Instalar el stack elegido

1. Ejecutar los comandos de scaffolding/instalación de la opción elegida (de la investigación del 2.2, o indicados por el usuario si dio su propia preferencia).
2. Verificar que la instalación quedó operativa (p. ej. npm run build, un comando de arranque en modo check, o el equivalente del stack) antes de continuar.
3. Registrar internamente el stack definitivo (lenguaje, framework, versión, herramientas de build) — todavía no se escribe en AGENTS.md, eso ocurre en el Paso 5.

Paso 3 — Placeholders del harness

Antes de escribir cualquier archivo, verificar si ya existe y aplicar Idempotencia / reejecución: un archivo del harness que ya exista nunca se deja con un formato distinto al de su plantilla. Lo que sigue describe el caso en que el archivo no existe.

Multi-repo: no todo este paso opera sobre un único repositorio. AGENTS.md, CLAUDE.md y README.md (puntos 1, 2 y 8) se crean en el repositorio de especificaciones y en cada submódulo — cada uno con su propio contenido, ver references/multi-repo.md § 4. .agents/MEMORY.md, .sdd-devkit/settings.json y .gitignore (puntos 3, 6 y 7) son únicos: solo en el repositorio de especificaciones, nunca en un submódulo. Los índices de arquitectura (punto 5) siguen su propia lógica por raíz; ver la nota ahí y references/multi-repo.md § 6.

1. AGENTS.md — copiar assets/agents-template.md tal cual (fuentes de contexto, el comentario de # Reglas generales y la sección # Stack tecnológico con su comentario, sin rellenar el stack). Excepción — repositorio clasificado "Solo specs": omitir, de la sección Fuentes de contexto, las líneas de docs/adr/README.md y docs/standards/README.md — este repositorio nunca los recibe (punto 4-5 de abajo), así que apuntar a ellos dejaría un enlace roto. Multi-repo: en cada submódulo, copiar en cambio assets/agents-submodule-template.md — su sección Fuentes de contexto apunta al .agents/MEMORY.md y al README.md del repositorio de especificaciones en vez de tener los suyos propios, y a los índices de arquitectura locales o del padre según si ese submódulo recibió los suyos (punto 5 de abajo, sujeto a la misma excepción de "Solo specs"); ver references/multi-repo.md § 4.2. El repositorio de especificaciones mismo es siempre "Solo specs" (§ 8 de esa referencia), así que su propio AGENTS.md siempre omite esas dos líneas — no es una excepción condicional ahí, es la regla.
2. CLAUDE.md — copiar assets/claude-template.md tal cual. Multi-repo: igual en cada submódulo — el include es relativo al propio archivo, así que la misma plantilla sirve sin cambios en cualquier repositorio.
3. .agents/MEMORY.md — copiar assets/memory-template.md tal cual. Multi-repo: solo en el repositorio de especificaciones; nunca crear este archivo dentro de un submódulo.
4. docs/adr/README.md — copiar assets/adr-index-template.md tal cual.
5. docs/standards/README.md — copiar assets/standards-index-template.md tal cual. Los puntos 4 y 5 se escriben en la raíz de arquitectura — pero nunca en un repositorio clasificado "Solo specs" (Paso 1.2): no hay código ahí que una decisión de arquitectura pueda describir, así que ni se preguntan ni se crean, sin excepción — esto no es un opt-in/opt-out, es automático. En el resto de casos, la raíz principal siempre los recibe —AGENTS.md los referencia y sin ellos el puntero queda roto—; en un repo sin submódulos ahí acaba la historia y no hay nada que preguntar. Si hay submódulos o repositorios anidados (y no son "Solo specs"), el criterio depende de su origen: si se crearon en el Paso 1.0 de esta misma corrida (proyecto multi-repo recién armado), crear los índices para todos por defecto — el Paso 4 les va a generar candidatos de todas formas —, preguntando solo si el usuario quiere excluir alguno explícitamente. Si en cambio ya existían de antes (p. ej. una reejecución sobre un repo de especificaciones con submódulos previos), mantener la pregunta de opt-in original — una sola vez, con la herramienta de preguntas estructuradas — para cuáles de ellos (de los que no sean "Solo specs") crear además sus propios índices. Cada raíz elegida recibe su propio par docs/adr/README.md + docs/standards/README.md, con su serie ADR-XXX independiente. Este bootstrap es la única excepción a la regla de «una raíz por invocación» del catálogo. Ver references/multi-repo.md § 6.
6. .sdd-devkit/settings.json — copiar assets/settings-template.json, reemplazando <código> en language por el idioma resuelto en Resolución de idioma (ISO 639-1). El resto de claves son la configuración mínima obligatoria del schema y se escriben con los valores de la plantilla; no preguntarlas aquí ni ofrecer configurarlas — el usuario las ajusta editando el archivo. Multi-repo: solo en el repositorio de especificaciones; nunca crear este archivo dentro de un submódulo.

Este archivo es JSON validado por schema, no markdown. Debe cumplir schemas/settings.schema.json: las 7 claves de primer nivel (language, trackingEnabled, specification, implementation, verification, git, projectManagement) son obligatorias — la lista viva es la de required en el schema, no esta enumeración. $schema es opcional (ruta al schema para el editor; ningún skill la resuelve). Fuera de esa, el schema no admite propiedades adicionales y language solo acepta los códigos de su enum. Cuando projectManagement queda en "enabled": false, el schema no exige el resto de sus claves: dejarlas fuera. specification es distinto: basePath, archivePath y testCases son obligatorios siempre. trackingEnabled vive en la raíz del archivo; trackingUrl (raíz) y specification.artifactRoot solo son obligatorios cuando trackingEnabled es true y se omiten con false. testCases es un objeto que exige mode (ask/always/never) y askDetails (booleano), ambos obligatorios.

7. .gitignore — asegurar que incluye .sdd-devkit/.env. Ahí vive SDD_DEVKIT_ACCESS_TOKEN (hooks y CLI); no se versiona. Si .gitignore no existe, crearlo con esa línea; si existe y no la tiene, añadirla. No crear el archivo .env. Multi-repo: solo en el repositorio de especificaciones — el .env que ignora tampoco existe en un submódulo.
8. README.md (raíz) — asegurar que incluya, cerca del inicio del archivo, una descripción de qué hace el proyecto en máximo 1-2 párrafos. Es el séptimo archivo del harness, pero no sigue la migración por plantilla completa del punto 3.1 — ver 3.4. Multi-repo: en cada submódulo se aplica la misma regla, pero describiendo ese repositorio en particular en vez de la solución completa; ver references/multi-repo.md § 4.4.

Idempotencia / reejecución

Un proyecto existente puede ya tener alguno de los archivos del harness, escrito a mano o por otra herramienta. Ninguno de ellos se deja como estaba si no cumple su propia regla de conformidad. Para los que tienen plantilla fija (AGENTS.md, CLAUDE.md, .agents/MEMORY.md, .sdd-devkit/settings.json, docs/adr/README.md, docs/standards/README.md), el harness solo funciona si tienen la estructura que el resto del catálogo espera leer (secciones, títulos y marcadores de las plantillas de assets/); comparar su estructura contra la plantilla correspondiente y aplicar una de estas tres salidas. Multi-repo: para AGENTS.md y CLAUDE.md esta comparación se repite por cada copia (raíz principal y cada submódulo), cada una contra la plantilla que le corresponde (agents-template.md en la raíz, agents-submodule-template.md en un submódulo) — ver references/multi-repo.md § 4.5.

README.md, el séptimo, no tiene plantilla de secciones ni pasa por esta tabla: su conformidad se decide solo por si ya trae, o no, una descripción vigente del proyecto — ver 3.4.

.sdd-devkit/settings.json no se migra, se completa. Si ya existe, nunca se sobrescribe: conservar los valores del usuario y limitarse a agregar las claves obligatorias que falten con los valores de la plantilla. Si le falta language, escribir ahí el idioma resuelto. Si tiene valores que el schema rechaza, no corregirlos por cuenta propia: informarlo en el cierre (Paso 5.3) y dejar el archivo como está.

3.1 Migración de formato

Migrar significa imponer la estructura de la plantilla sin perder contenido del usuario:

1. Estructura desde la plantilla: partir de la plantilla de assets/ — sus secciones, títulos exactos, orden y comentarios-marcador (los <!-- ... --> que arch-manage usa como punto de inserción en los índices). Restaurar todo marcador que falte.
2. Reubicar el contenido propio: mover cada bloque del archivo original a la sección equivalente de la plantilla. Ejemplos: reglas generales sueltas en un AGENTS.md artesanal → bajo # Reglas generales; descripción del stack encontrada en AGENTS.md → bajo # Stack tecnológico, pero ver la regla de la sección 3.2; preferencias en un MEMORY.md propio → bajo ## Preferencias; entradas de ADR/estándares ya listadas en un índice → como líneas en el formato que indica el marcador (- [ADR-XXX: Título](ADR-XXX-slug.md) / - [Nombre del estándar](<slug>.md)), ordenadas por identificador.
3. Normalizar sin reescribir: ajustar formato (nivel de encabezado, viñetas, sintaxis de enlaces e @-includes, orden de entradas), no la redacción del usuario. No resumir, reformular ni traducir su texto.
4. Contenido sin sección equivalente: conservarlo. Si no encaja en ninguna sección de la plantilla, dejarlo al final del archivo bajo un encabezado propio en lugar de descartarlo, y mencionarlo al presentar el diff.
5. Confirmar antes de escribir: mostrar el diff de la migración (o el antes/después si el diff es corto) y pedir confirmación explícita. Si el usuario declina, dejar el archivo intacto y registrar que ese archivo no está en formato del harness — informarlo en el cierre (Paso 5.3), porque el resto del catálogo puede no leerlo bien.
6. Una sola tanda: agrupar todas las migraciones detectadas en un único bloque de confirmación, no una pregunta por archivo.

3.2 Excepción del stack durante la migración

Si el AGENTS.md existente ya describía el stack, ese contenido se preserva al migrar (va bajo # Stack tecnológico, reemplazando el comentario de la plantilla) — no se borra para volver a poner el placeholder. Lo que sigue prohibido es redactar o completar ese stack aquí: si la sección queda con el comentario de la plantilla porque el archivo original no decía nada del stack, se rellena en el Paso 5.2 y en ningún otro momento.

3.3 Harness ya completo

Si los siete archivos existen y todos están conformes (los seis con plantilla fija ya migrados si hacía falta, y README.md con su descripción vigente), informar que el proyecto ya está inicializado y preguntar si se desea continuar igualmente para revisar/completar el resto (Paso 4 en adelante) o terminar aquí.

Multi-repo: esta verificación cubre el repositorio de especificaciones y cada submódulo — AGENTS.md, CLAUDE.md y README.md deben estar conformes en todos ellos (cada uno contra la plantilla que le corresponde), no solo en la raíz principal, antes de dar el harness por completo.

3.4 README.md raíz — descripción del proyecto

A diferencia de los otros seis archivos del harness, README.md no tiene una plantilla de secciones fija: es un artefacto libre del proyecto, no una plantilla del catálogo. arch-init solo garantiza que tenga, cerca del inicio, una descripción de qué hace el proyecto — no toca el resto de su contenido (instalación, badges, licencia, contribución, tabla de contenidos, etc.), ni le impone secciones.

1. De dónde sale la descripción:
   • Sin código: la necesidad capturada en el Paso 2.1 — qué problema resuelve y para quién.
   • Con código base o con implementación: inferirla del contenido existente (README previo, campo description de package.json/pyproject.toml/manifiesto equivalente, docs/specs/ si ya hay historias) o de lo observado en el código durante el Paso 1 / Paso 4.1. Si no hay evidencia suficiente para redactarla con confianza, preguntar al usuario con una sola pregunta abierta (mismo estilo que el Paso 2.1): "¿Qué hace este proyecto, en pocas palabras?".
   • Solo specs: qué documentación o especificaciones contiene este repositorio y de qué solución o repositorios trata — de lo que el usuario ya haya dicho al describirlo, o la misma pregunta abierta si hace falta.
2. Si README.md no existe: crearlo con un título (nombre del repo) y la descripción, en 1-2 párrafos.
3. Si ya existe:
   • Si ya trae una descripción vigente del propósito del proyecto (aunque no esté bajo un encabezado con ese nombre), no tocarla.
   • Si no la tiene, o quedó claramente desactualizada frente a lo detectado, proponer agregarla/actualizarla cerca del inicio del archivo — mostrando el fragmento a insertar, no un diff del archivo completo — y pedir confirmación antes de escribir, con el mismo criterio de "mostrar antes de escribir" que la migración del harness (3.1, punto 5). Si en el mismo Paso 3 hay además migraciones de formato pendientes (3.1), agrupar esta propuesta en la misma tanda de confirmación en vez de preguntar aparte.
4. Límite duro: 1-2 párrafos. No agregar instalación, lista de features, badges, tabla de contenidos ni roadmap — eso, si el proyecto lo necesita, lo agrega el usuario o queda fuera del alcance de arch-init.

Paso 4 — Candidatos de arquitectura y compuerta de calidad

Repositorio "Solo specs": saltar el Paso 4 completo (4.1 y 4.2) para cualquier repositorio así clasificado — no hay código que genere candidatos de arquitectura ni que necesite una compuerta de calidad. En multi-repo, esto incluye siempre al repositorio de especificaciones (nunca pasa por el Paso 4) y a cualquier submódulo que haya resultado "Solo specs" en su propio Paso 1.2.

4.1 Identificar candidatos de ADR/estándares

Leer references/adr-candidates.md completo antes de este paso.

Multi-repo: el 4.1 y el 4.2 se repiten completos, uno por cada submódulo, usando ese submódulo como la raíz de arquitectura de esa corrida — nunca se consolida el resultado de varios submódulos en una sola lista ni en una sola invocación de arch-manage. Ver references/multi-repo.md § 5.

Pasar la raíz de arquitectura a los subagentes. El bootstrap del Paso 3 pudo crear índices en varias raíces, pero el descubrimiento y la creación de artefactos operan sobre una. Indicar explícitamente en la instrucción del subagente qué <raíz-arq> cubre —por defecto la principal; si el usuario eligió submódulos en el Paso 3, preguntar cuál se documenta ahora— para que arch-discover/arch-manage no la vuelvan a preguntar ni acaben escribiendo en otra raíz. Cubrir otra raíz es otra corrida.

• Con implementación (Paso 1.2) → delegar en un subagente que ejecute el skill arch-discover completo sobre la raíz de arquitectura indicada — sus cinco fases, incluida la Fase 5, en la que arch-discover mismo crea los artefactos aprobados invocando /arch-manage por su cuenta. arch-discover presenta sus candidatos al usuario, los agrupa por dominio funcional y los delega en arch-manage sin intervención de arch-init — no repetir esa presentación aquí, ni volver a delegarlos en arch-manage en el Paso 5.1: arch-discover ya es dueño de esa lista de principio a fin. Lo único que se retiene de esta ejecución es un resumen (cuántos ADR/estándares creó, con sus rutas) para reportarlo en el cierre (Paso 5.3) — no se agrega nada de esto a la lista consolidada del Paso 4.1/5.1.
• Con código base o Sin código (tras el Paso 2) → no hay nada que "descubrir" en código que todavía no existe: el candidato es la decisión de stack tomada en el Paso 1.3 o el Paso 2 (con sus alternativas, si vinieron de una investigación), clasificada por dominio funcional según adr-candidates.md § 1.

La lista consolidada que llega al Paso 5.1 se arma solo con la rama "con código base"/"sin código" de arriba (cuando aplica) más lo que aporte el 4.2 — nunca con los candidatos de arch-discover, que ya quedaron resueltos por su propia Fase 5. No delegar nada en arch-manage todavía desde aquí; eso ocurre en el Paso 5.1.

4.2 Compuerta de calidad

Leer references/quality-gate.md completo antes de este paso.

1. Diagnóstico: revisar si ya existe configuración de pruebas (config, carpetas, scripts de test).
2. Qué se suele validar: consultar el skill quality-check — específicamente su references/stacks.md, tabla "Aplicabilidad por stack" — para saber qué checks son Bloqueantes (típicamente tipado si aplica, linter, unit tests, coverage, build) y cuáles Condicionales (típicamente E2E, y linter/tipado en algunos stacks) para el stack de este proyecto. Las demás clases de prueba —integración, contrato, rendimiento…— no son checks del stack: son suites configuradas, y salen del estándar de testing del repo, no de esa tabla (ver Suites de prueba); si el proyecto las necesita, lo que falta es declararlas en docs/standards/testing.md vía arch-manage. arch-init no ejecuta la corrida completa — esa corre sobre código ya implementado, no aplica en una inicialización —, solo usa esa tabla como checklist de qué falta configurar.
3. Completar lo que falte: para cada check Bloqueante ausente, y cada Condicional relevante según el tipo de proyecto (quality-gate.md § 3 — nunca sugerir una capa que no ayude a validar este proyecto en particular, p. ej. E2E a una librería sin UI ni endpoints), preguntar al usuario y, si acepta, instalar/configurar lo necesario: dependencias, config mínima, un test de ejemplo real (no un placeholder vacío), y el script de ejecución.
4. Validar: ejecutar la suite configurada y confirmar que corre sin errores de configuración antes de avanzar. Si falla por algo fuera del alcance de este skill, informar y preguntar cómo proceder.
5. El framework y las capas configuradas se suman como candidato de dominio testing a la lista del 4.1 (un requisito por capa aceptada, igual que el ejemplo canónico de arch-discover).

Paso 5 — Cierre

5.1 Documentar las decisiones aceptadas

Presentar la lista consolidada de candidatos agrupada por dominio funcional, con la herramienta de preguntas estructuradas en selección múltiple (incluir siempre Ninguno por ahora). Esta lista es la decisión de stack del 4.1 (solo si la situación fue "con código base" o "sin código" — si fue "con implementación", esos candidatos ya los gestionó arch-discover en su propia Fase 5 y no se repiten aquí) más lo añadido en el 4.2. Si la lista queda vacía (p. ej. situación "con implementación" y la compuerta de calidad ya estaba completa), saltar directo al 5.2 sin preguntar. Si el usuario acepta algo: resolver los decisores una sola vez para todo el lote (adr-candidates.md § 3) y delegar en un subagente que ejecute /arch-manage, agrupando los candidatos aceptados por dominio en la misma invocación y pasándole la raíz de arquitectura ya resuelta (ver la nota del Paso 4.1) para que no la vuelva a preguntar. arch-manage crea los ADR y, cuando corresponda, los requisitos en el estándar de dominio, actualizando ambos índices por su cuenta. Esperar su respuesta antes de continuar.

Multi-repo: una corrida de 5.1 por cada submódulo (misma raíz de arquitectura que su propio 4.1/4.2), nunca una lista ni una invocación de arch-manage consolidada entre submódulos. Un submódulo "Solo specs" no participa del 5.1: nunca pasó por el Paso 4, así que no tiene candidatos que documentar.

5.2 Actualizar el stack

Reemplazar el comentario bajo # Stack tecnológico en AGENTS.md con el stack definitivo — lenguaje(s), framework(s) y versión, gestor de paquetes/build, y las capas de testing configuradas en el 4.2. AGENTS.md es la única fuente del stack — no se repite en .agents/MEMORY.md (ese archivo no lleva sección de stack; ver plantilla). Este es el único momento del flujo en que se escribe esa sección.

Repositorio "Solo specs": no hay stack que escribir — reemplazar el comentario de la plantilla por No aplica — repositorio de solo especificaciones en vez de un stack. Sigue siendo el único momento del flujo en que se toca esa sección; no adelantarlo al Paso 3 solo porque ya se sabe desde el 1.2 que no va a haber stack.

Multi-repo: cada submódulo escribe su propio stack de

…(truncated)