---
name: arch-init
description: >-
  Identifica el punto de partida de un proyecto (sin código / con código base / con implementación) e inicializa lo que falte de su harness multi-agente: repo git —o, si la solución abarca varios repositorios, un repo de especificaciones que los agrega como submódulos—, placeholders `AGENTS.md`/`CLAUDE.md`/`.agents/MEMORY.md`/`.sdd-devkit/settings.json`/`docs/adr/README.md`/`docs/standards/README.md`/`README.md` (raíz, con descripción del proyecto), el stack tecnológico (investigando con `work-research` si hace falta), candidatos de ADR/estándares (vía `arch-discover` si ya hay implementación, por repositorio si es multi-repo) y la compuerta de calidad (vía `quality-check`). Cierra actualizando el stack y sugiriendo `work-define` o `work-plan`. Activar al pedir inicializar, bootstrapear o preparar uno o varios repos de una solución para agentes, configurar su harness, crear `AGENTS.md`/`CLAUDE.md`/`MEMORY.md` desde cero, o mencionar "arch-init", "/arch-init", "inicializa el harness".
license: MIT
---

# 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](#idempotencia--reejecución)).
>
> **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):

| Skill | Qué asume/hace, y cómo se relaciona con `arch-init` |
| ----- | ----------------------------------------------------- |
| `arch-manage` | Crea/actualiza ADRs y estándares de dominio. `arch-init` lo invoca en el Paso 5 con los candidatos que se aceptaron en el Paso 4 — nunca redacta un ADR/estándar por su cuenta. |
| `arch-discover` | Infiere ADR/estándares candidatos **del código ya existente** y los crea por su cuenta (su Fase 5 invoca `arch-manage`). `arch-init` lo invoca **completo** en el Paso 4.1 cuando el punto de partida es "con implementación" — no reimplementa esa inspección ni repite su creación de documentos. |
| `arch-audit` | Audita `docs/standards/` y `AGENTS.md` contra el repo — de `AGENTS.md` toma también el contexto de stack (`# Stack tecnológico`). `arch-init` es lo que le da a `arch-audit` algo que auditar la primera vez. |
| `quality-check` | Sabe qué se suele validar por stack — tipado, linter, unit tests, coverage, build, e2e, sonar (`quality-check/references/stacks.md`) — más las suites de prueba que declare el **estándar de testing** del repo, que son las únicas no fijas ([Suites de prueba](../quality-check/SKILL.md#suites-de-prueba-fijas-y-configuradas)). `arch-init` lo **consulta** en el Paso 4 para saber qué le falta a la compuerta de calidad; no ejecuta la corrida completa (esa corre sobre código ya implementado, no aplica en una inicialización). |
| `work-define` / `work-plan` | Reciben el handoff que `arch-init` ofrece al cerrar (Paso 5). |

---

## Cómo preguntar al usuario

Mecanismo, ritmo y fallback compartidos: [`${PLUGIN_ROOT}/references/asking.md`](../../references/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 `references/`), y toda referencia compartida de este skill se escribe como `${PLUGIN_ROOT}/references/<archivo>.md`. Para resolverla: la raíz es la **carpeta desde la que se cargó este archivo**, dos niveles arriba (`<raíz>/skills/<nombre>/SKILL.md`) — el cliente anuncia esa ubicación al invocar el skill (p. ej. «Base directory for this skill: …»). Si esa ubicación no está disponible, localizar la instalación buscando el manifiesto del plugin: `PLUGIN_ROOT="$(dirname "$(grep -rl '\"name\": *\"sdd-devkit\"' "$HOME/.claude/plugins" --include=plugin.json 2>/dev/null | head -1)")"`. En ambos casos, **verificar antes de usarla** que `$PLUGIN_ROOT/references/language.md` existe. El destino de cada enlace markdown (`../../references/…`) existe solo para navegar el repositorio en GitHub o en un editor: **no** resolverlo desde el directorio de trabajo. **Nunca buscar `references/` en el proyecto**: un `<proyecto>/references/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}/references/language.md`](../../references/language.md).

Las reglas de `language.md` son obligatorias y tienen prioridad para determinar el idioma de todos los artefactos, documentos 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

| Archivo | Contenido | Se crea en |
| ------- | --------- | ---------- |
| `AGENTS.md` | Fuentes de contexto + reglas generales + sección `Stack tecnológico` | Paso 3 (stub) → Paso 5 (stack definitivo). **Por repositorio**: uno en la raíz principal y uno en cada submódulo si es multi-repo — ver la nota de abajo. |
| `CLAUDE.md` | Solo `@AGENTS.md`, por compatibilidad | Paso 3. **Por repositorio**, igual que `AGENTS.md`. |
| `.agents/MEMORY.md` | Memoria persistente (preferencias y reglas operativas — **no** el stack, eso vive solo en `AGENTS.md`) | Paso 3 (stub). **Único**: solo en la raíz principal, nunca en un submódulo. |
| `.sdd-devkit/settings.json` | Configuración del plugin conforme a [`schemas/settings.schema.json`](../../schemas/settings.schema.json); **persiste el idioma** en la clave `language` | Paso 3. **Único**: solo en la raíz principal, nunca en un submódulo. |
| `README.md` (raíz) | Descripción de qué hace el proyecto, 1-2 párrafos | Paso 3 (agregada/actualizada — sin plantilla de secciones fija). **Por repositorio**, igual que `AGENTS.md`: en la raíz principal describe la solución completa; en cada submódulo, ese repositorio en particular. |
| `docs/adr/README.md` | Índice de ADRs vigentes | Paso 3 (stub) → Paso 5 (poblado por `arch-manage`) |
| `docs/standards/README.md` | Índice de estándares vigentes | Paso 3 (stub) → Paso 5 (poblado por `arch-manage`) |

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` deben estar en el formato de su plantilla — no admiten variantes, porque el resto del catálogo lee sus secciones por título; si existen con otro formato, la normalización se **delega en `/plugin-migrate`** (ver [3.1 Archivos fuera de formato](#31-archivos-fuera-de-formato)); en multi-repo, la verificación 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 documento 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](#34-readmemd-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 documentación de **arquitectura**: pertenecen a la raíz del repositorio cuyo código documentan (ver
> [`${PLUGIN_ROOT}/references/artifacts.md`](../../references/artifacts.md#raíz-de-arquitectura-adr-estándares-y-fitness-functions)).
> 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`](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).
- **Si el proyecto parte de otro proyecto** (el usuario da una URL o ruta como punto de partida), distinguir dos casos — la diferencia decide si esa URL termina como `origin` o como `upstream`:
  1. **Proyecto base** (plantilla, starter, semilla corporativa): ese repositorio **no es** el repo del proyecto, solo su punto de partida. Clonarlo y dejarlo como remote **`upstream`** del repo del proyecto: `git clone <url-base> <destino> && git -C <destino> remote rename origin upstream`. `origin` se agrega cuando exista el remoto propio del proyecto (`git remote add origin <url>`); mientras tanto, las actualizaciones del base se traen con `git fetch upstream` sin confundir ambos repos.
  2. **Proyecto existente**: la URL o ruta dada **es** el repo del proyecto. Usarlo tal cual (clonarlo si aún no está local), sin reconfigurar remotos — aplica la regla anterior de no tocar la configuración existente.

  Ante una URL sin contexto, **preguntar cuál de los dos es** en vez de asumir.
- **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:

| Situación | Qué implica |
| --------- | ------------ |
| **Sin código** | No hay manifiestos de ningún stack ni código fuente propio, pero va a tener código de aplicación (más adelante, vía el Paso 2). |
| **Con código base** | Hay un stack detectable (manifiestos / resultado de un scaffold) pero sin lógica de negocio propia todavía. |
| **Con implementación** | Hay características de negocio ya implementadas (módulos, rutas, componentes o tests con lógica propia; `docs/specs/` con contenido). |
| **Solo specs** | Este repositorio **nunca** va a tener código de aplicación — su único propósito es documentación o especificaciones. No es un punto de la misma escala que las otras tres. |

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](#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](#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`](../../schemas/settings.schema.json): las **6** claves de primer nivel (`language`, `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. `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` (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 pasa por la comparación de plantilla fija del Paso 3 — ver [3.4](#34-readmemd-raíz--descripción-del-proyecto). **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`.

| Estado del archivo existente | Qué hacer |
| ---------------------------- | --------- |
| **Ya conforme** — tiene todas las secciones de la plantilla, con sus títulos y en su orden | No tocar. Continuar como si ya estuviera creado. |
| **Formato divergente** — es reconociblemente el mismo archivo (mismo propósito) pero le faltan secciones, tiene otros títulos, otro orden, o perdió los comentarios-marcador | **Delegar la normalización en `/plugin-migrate`** (ver 3.1) y continuar con el resto del flujo. |
| **Contenido ajeno** — el archivo existe con un propósito distinto al del harness | No sobrescribir. Mostrar el contenido actual y preguntar si fusionar, reemplazar o dejar como está. |

`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](#34-readmemd-raíz--descripción-del-proyecto).

> **`.sdd-devkit/settings.json` se completa, no se reescribe.** 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 claves o valores que el schema rechaza (p. ej. claves de una versión anterior del plugin), no corregirlos por cuenta propia: sugerir `/plugin-migrate` e informarlo en el cierre (Paso 5.3).

### 3.1 Archivos fuera de formato

Cuando la comparación del Paso 3 encuentra archivos en **Formato divergente**, este skill **no los migra**: la normalización al formato de plantilla —con sus reglas de conservación de contenido, la excepción del stack y la confirmación por diff— es de **`/plugin-migrate`**, el único dueño de las migraciones del catálogo. Aquí solo se hace esto:

1. **Agrupar todos los hallazgos** del paso (todas las copias, en multi-repo) y presentarlos al usuario junto con las demás confirmaciones del Paso 3, en una sola mención, ofreciendo delegarlos en `/plugin-migrate`.
2. **Si el usuario acepta**, delegar (vía subagente que invoque `/plugin-migrate` con la lista de hallazgos) y esperar el resultado antes de continuar: el resto del flujo asume archivos en formato de plantilla.
3. **Si declina**, dejar los archivos intactos y registrar que quedan fuera de formato — informarlo en el cierre (Paso 5.3), porque el resto del catálogo lee estos archivos por sus títulos de sección y puede no leerlos bien.

El stack que un `AGENTS.md` existente ya describa se conserva en cualquier caso (regla de `plugin-migrate`); lo que sigue prohibido aquí es **redactar o completar** ese stack fuera del Paso 5.2.

### 3.3 Harness ya completo

Si los siete archivos existen y **todos** están conformes (los seis con plantilla fija conformes — normalizados vía `/plugin-migrate` si hizo 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 documento 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](#21-preguntar-qué-se-quiere-desarrollar) — 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, mostrando siempre antes de escribir. Si en el mismo Paso 3 hay además archivos fuera de formato detectados (3.1), agrupar esta propuesta en la **misma menció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](../quality-check/SKILL.md#suites-de-prueba-fijas-y-configuradas)); 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 definitivo en su propio `AGENTS.md` (mismo nivel de
detalle que un repo único, o `No aplica` si ese submódulo resultó "Solo specs"), en su propia pasada del
5.2. El repositorio de especificaciones es la **única** excepción a la regla de "Solo specs" → `No aplica`
de arriba: aunque él mismo es siempre "Solo specs", su `# Stack tecnológico` no queda en `No aplica` — se
reemplaza por una tabla-resumen que enlaza al de cada submódulo, porque a diferencia de un "Solo specs"
suelto, sí tiene hijos cuyo stack resumir. Formato exacto en `references/multi-repo.md § 7`.

### 5.3 Confirmar y sugerir el siguiente paso

Confirmar al usuario que el harness inicial quedó listo, resumiendo: **topología** (repo único, o repo de especificaciones + submódulos con sus rutas), punto de partida (situación del Paso 1.2 — por submódulo si es multi-repo), repositorio git (creado o ya existía), archivos del harness creados, **archivos fuera de formato** (normalizados vía `/plugin-migrate`, o dejados como estaban por decisión del usuario — Paso 3.1), **un `.sdd-devkit/settings.json` preexistente cuyos valores el schema rechaza** (Paso 3, si se detectó), stack definitivo (por submódulo si aplica), compuerta de calidad configurada (por submódulo si aplica), y — si aplica — los ADR/estándares creados con sus rutas, agrupados por raíz de arquitectura: los del Paso 5.1 y, si la situación fue "con implementación", también los que creó `arch-discover` en su propia Fase 5 (retenidos del Paso 4.1).

Después, ofrecer el siguiente paso natural con la herramienta de preguntas estructuradas — **es una sugerencia, no un paso bloqueante**: *"¿Quieres continuar con...?"* opciones: `Escribir la primera historia de usuario (work-define)` / `Planificar tareas técnicas o de mantenimiento (work-plan)` / `Nada por ahora`.

No confirmar el cierre antes de que `AGENTS.md` tenga el stack ya escrito.

---

## Mapa de referencias

| Archivo | Cuándo leerlo |
| ------- | -------------- |
| `references/multi-repo.md` | Paso 1.0 — cómo decidir repo único vs. multi-repo, crear el repositorio de especificaciones, agregar submódulos, y cómo se repiten los Pasos 1.2, 1.3, 2, 4 y 5.2 por cada uno. |
| `references/stack-detection.md` | Paso 1 — manifiestos por ecosistema y la clasificación en las cuatro situaciones (sin código / con código base / con implementación / solo specs). |
| `references/quality-gate.md` | Paso 4.2 — cómo interpretar la tabla de `quality-check` por stack, y cuándo sugerir E2E/API testing según el tipo de proyecto. |
| `references/adr-candidates.md` | Paso 4.1 y 5.1 — cómo convertir la decisión de stack (o los candidatos de `arch-discover`) y la compuerta de calidad en candidatos por dominio funcional, y cómo delegarlos en `arch-manage`. |
| `assets/agents-template.md` | Paso 3 — plantilla de `AGENTS.md` de la raíz principal (repo único, o repositorio de especificaciones en multi-repo). |
| `assets/agents-submodule-template.md` | Paso 3 — plantilla de `AGENTS.md` de un submódulo, solo multi-repo (Fuentes de contexto distinta a la de la raíz). |
| `assets/claude-template.md` | Paso 3 — plantilla de `CLAUDE.md`, igual en la raíz principal y en cada submódulo. |
| `assets/memory-template.md` | Paso 3 — plantilla de `.agents/MEMORY.md`. |
| `assets/adr-index-template.md` | Paso 3 — plantilla de `docs/adr/README.md`. |
| `assets/standards-index-template.md` | Paso 3 — plantilla de `docs/standards/README.md`. |
| `assets/settings-template.json` | Paso 3 — plantilla de `.sdd-devkit/settings.json`. |


### Referencias compartidas del plugin

Reglas transversales del catálogo; viven en la raíz del plugin, no en este skill.

- [`${PLUGIN_ROOT}/references/language.md`](../../references/language.md): **Idioma** — resolución obligatoria del idioma de artefactos, documentos y mensajes. *Lectura obligatoria antes de ejecutar el skill.*
- [`${PLUGIN_ROOT}/references/asking.md`](../../references/asking.md): **Preguntas** — mecanismo estructurado, ritmo, fallback. *Antes de la primera pregunta.*
- [`${PLUGIN_ROOT}/references/artifacts.md`](../../references/artifacts.md): **Artefactos** — rutas del harness, identificadores, archivado. *Al resolver una ruta o calcular un ID.*

---

## Anti-patterns

- **Narrar el flujo interno**: anunciar que se resuelve el idioma o la política, que se lee `settings.json`, que se carga una referencia, o ir enumerando los pasos en voz alta. Al usuario se le comunica el resultado, las preguntas que el flujo exija y lo que quede pendiente — no la maquinaria.
- Rellenar `# Stack tecnológico` en `AGENTS.md` antes del Paso 5, aunque el stack ya se conozca desde el Paso 1 o el Paso 2.
- Escribir el stack (o duplicarlo) en `.agents/MEMORY.md` — ese archivo no lleva sección de stack; `AGENTS.md` es la única fuente.
- Dar por bueno un archivo del harness que ya existía solo porque existe, sin comparar su estructura contra la plantilla de `assets/` (Paso 3).
- Normalizar por cuenta propia un archivo del harness fuera de formato en vez de delegarlo en `/plugin-migrate` — la lógica de migración vive solo en ese skill.
- Descartar contenido del archivo original porque no encaja en ninguna sección de la plantilla, en vez de conservarlo al final.
- Crear los índices de arquitectura de un submódulo sin preguntar, o dar por hecho que un submódulo comparte los del repo principal — cada raíz de arquitectura lleva los suyos y su propia serie `ADR-XXX`.
- Sacar `AGENTS.md`, `CLAUDE.md`, `.agents/MEMORY.md` o `.sdd-devkit/settings.json` de la raíz principal para meterlos en un submódulo: el harness es uno solo, solo los índices de arquitectura son por raíz.
- Inferir la topología (repo único vs. multi-repo) del contenido del directorio en vez de preguntarla en el Paso 1.0 — a diferencia de la situación del 1.2, no hay señal de código que la determine con confianza.
- Ejecutar el Paso 1.1 (`git init`) tanto sobre el directorio de invocación como sobre el repositorio de especificaciones recién creado en modo multi-repo — el 1.0 ya lo resuelve una sola vez.
- Clasificar la situación (1.2) o detectar/conseguir el stack (1.3/2) "para el proyecto" en general cuando es multi-repo, en vez de una vez por cada submódulo.
- Crear `.agents/MEMORY.md` o `.sdd-devkit/settings.json` dentro de un submódulo, o duplicarlos ahí desde el repositorio de especificaciones — son artefactos únicos de la solución, solo en la raíz principal.
- **No** crear `AGENTS.md`, `CLAUDE.md` o `README.md` en un submódulo (o copiar ahí, sin adaptar, el `AGENTS.md` de la raíz principal) — cada repositorio necesita el suyo propio, y el de un submódulo usa `assets/agents-submodule-template.md`, no `assets/agents-template.md`.
- Escribir en el `AGENTS.md` de un submódulo una sección Fuentes de contexto que apunte a un `.agents/MEMORY.md` o `README.md` locales — esos archivos no existen ahí; el include debe apuntar al repositorio de especificaciones (`../.agents/MEMORY.md`, `../README.md`).
- Consolidar los candidatos de ADR/estándares (Paso 4) o la compuerta de calidad de varios submódulos en una sola lista o una sola invocación de `arch-manage` — cada submódulo es su propia raíz de arquitectura y se documenta por separado.
- Escribir el stack completo de todos los submódulos en el `AGENTS.md` del repositorio de especificaciones en vez de en el `AGENTS.md` de cada uno — la raíz principal solo resume con una tabla que enlaza a cada uno (`references/multi-repo.md § 7`).
- Duplicar la lista de submódulos en `.sdd-devkit/settings.json` o en cualquier otro archivo del harness — `.gitmodules` ya es la fuente de verdad.
- Agregar un repositorio como submódulo sin antes preguntar si ya existe (local o remoto) o si hay que crearlo desde cero.
- Crear `docs/adr/README.md` o `docs/standards/README.md` para un repositorio clasificado "Solo specs" — nunca aplica, ni siquiera preguntándolo como opt-in; no es lo mismo que "el usuario no los pidió", es que no hay código que esos documentos puedan describir.
- Asumir "Sin código" por defecto ante un repositorio vacío sin evaluar si en realidad es "Solo specs" — la sola ausencia de manifiestos no distingue un greenfield normal de un repositorio que nunca va a tener código de aplicación.
- Preguntar la situación del repositorio de especificaciones en modo multi-repo, o correr el Paso 2 o el Paso 4 sobre él — es "Solo specs" por definición, automático, nunca se evalúa ni se pregunta.
- Ejecutar el Paso 4 (candidatos de arquitectura o compuerta de calidad) sobre un repositorio "Solo specs" — no hay código que lo justifique, se salta completo.
- Dejar en el `AGENTS.md` de un repositorio "Solo specs" las líneas de Fuentes de contexto que apuntan a `docs/adr/README.md`/`docs/standards/README.md` — quedarían apuntando a archivos que nunca se crean.
- Escribir un stack (o dejar el comentario de la plantilla sin resolver) en el `AGENTS.md` de un repositorio "Solo specs" en vez de `No aplica — repositorio de solo especificaciones`.
- Redactar el stack fuera del Paso 5.2, o borrar el que un `AGENTS.md` existente ya describía.
- Sobrescribir un `AGENTS.md`/`CLAUDE.md`/etc. existente con contenido propio del usuario sin preguntar primero.
- **Sobrescribir un `.sdd-devkit/settings.json` que ya existía** en vez de conservar sus valores y agregar solo las claves obligatorias que falten (Paso 3).
- Escribir en `.sdd-devkit/settings.json` claves que el schema no declara (`$schema` incluido) o el resto de claves de un bloque que quedó en `"enabled": false` — `additionalProperties: false` rechaza el archivo.
- Preguntar al usuario por `implementation`, `verification`, `git`, `projectManagement` o `specification` en el Paso 3: solo `language` se resuelve; el resto sale de la plantilla y el usuario lo ajusta editando el archivo.
- Ejecutar el Paso 2 (conseguir el stack) cuando el Paso 1.2 ya clasificó "con código base" o "con implementación".
- Clasificar la situación del Paso 1.2 sin evidencia clara, en vez de preguntar ante la ambigüedad.
- Preguntar "tipo de proyecto" como categoría cerrada o "¿tienes preferencia de stack?" como pregunta aparte, en vez de capturar la necesidad en el 2.1 y extraer de ahí tipo/preferencia/restricciones.
- Sugerir o investigar un stack sin haber capturado antes la necesidad real (2.1) — avanzar con una descripción vaga ("una app") sin repreguntar.
- Investigar el stack (2.2) sin pedirle al subagente los comandos de instalación de cada opción.
- Reimplementar en el Paso 4.1 la inspección de código que ya hace `arch-discover`, en vez de delegarle esa identificación cuando el punto de partida es "con implementación".
- Volver a presentar o delegar en `/arch-manage` los candidatos que `arch-discover` ya creó por su cuenta en su propia Fase 5 — es trabajo duplicado y puede generar un ADR casi-idéntico; el Paso 5.1 solo agrupa lo que **no** pasó por `arch-discover`.
- Reinventar en el Paso 4.2 un catálogo propio de qué validar por stack en vez de consultar `quality-check/references/stacks.md`.
- Ejecutar la corrida completa de `quality-check` sobre el repo — ese skill corre sobre código ya implementado, no en una inicialización sin nada que verificar.
- Sugerir E2E, API testing u otras capas que no aportan valor de validación al tipo de proyecto.
- Cerrar el Paso 4.2 sin ejecutar la suite de pruebas al menos una vez para confirmar que corre.
- Delegar en `/arch-manage` sin que el usuario haya aceptado explícitamente al menos un candidato, o sin agrupar por dominio los candidatos que comparten estándar.
- Confirmar el cierre antes de actualizar el stack definitivo en `AGENTS.md`.
- Forzar el handoff a `work-define`/`work-plan` en el 5.3 en vez de ofrecerlo como sugerencia que el usuario puede declinar.
- Hacer commit automático del harness sin que el usuario lo pida (queda para `git-commit`, fuera de este skill).
- Lanzar preguntas como prosa libre cuando el cliente expone la herramienta de preguntas estructuradas.
- Escribir más de 1-2 párrafos de descripción en el `README.md` raíz, o agregarle secciones que el usuario no pidió (instalación, features, badges, tabla de contenidos, roadmap).
- Sobrescribir, reordenar o reformular el resto del `README.md` raíz al agregar/actualizar la descripción — solo se toca ese fragmento.
- Inventar la descripción del `README.md` raíz sin evidencia (README/manifiesto previos, código, o la necesidad del Paso 2.1) en vez de preguntarle al usuario en una sola pregunta abierta.
- Tratar el `README.md` raíz como uno de los seis archivos con plantilla fija: exigirle secciones, títulos u orden que su regla de conformidad (3.4) no pide.

---

## Ejemplos

**Ejemplo 1 — Sin código, necesidad con restricciones que ameritan investigar**

Carpeta vacía salvo un `README.md` con solo el título del repo, sin descripción. Paso 1: no hay repo git → `git init`; sin manifiestos → situación "sin código". Paso 2.1: a "¿qué quieres desarrollar?" el usuario responde "una API para gestionar pedidos de un e-commerce, con picos fuertes de tráfico en fechas de descuentos" — sin preferencia de stack. Paso 2.2: la restricción de picos de tráfico no es trivial → se decide investigar; el subagente de `work-research` compara Node/Fastify, Python/FastAPI y Go con foco en throughput, con comandos de instalación para cada uno; el usuario elige Fastify + TypeScript. Paso 2.3: se ejecuta el scaffold. Paso 3: se crean los seis archivos del harness con plantilla fija (incluido `.sdd-devkit/settings.json` con `"language": "es"`); el `README.md` preexistente no tenía descripción, así que se propone agregarle el párrafo redactado a partir de la necesidad capturada en 2.1 y, confirmado, se inserta cerca del inicio sin tocar el resto del archivo. Paso 4.1: como no hay implementación todavía, el único candidato es "Fastify + TypeScript" (dominio `api`, con las alternativas del `RS-XXX`). Paso 4.2: se consulta `quality-check/references/stacks.md` para Node+TS (tipado, linter, unit, coverage y build son bloqueantes); no hay nada configurado → se sugiere Vitest (unit) y, por tratarse de una API, Supertest (API testing); el usuario acepta ambos y se configuran. Se suma "Vitest + Supertest" (dominio `testing`) a la lista. Paso 5.1: el usuario acepta documentar ambos candidatos → subagente `/arch-manage` crea los ADR y los estándares de dominio `api` y `testing`. Paso 5.2: se escribe el stack en `AGENTS.md`. Paso 5.3: se confirma el cierre y se ofrece continuar con `work-define`; el usuario acepta.

**Ejemplo 2 — Con implementación, delegando en arch-discover**

Repo git con historial de dos años, `package.json` con NestJS + Prisma, `docs/specs/user-stories/` con 40 historias. Paso 1: repo ya existe; stack detectado (NestJS/Prisma); situación "con implementación" → se salta el Paso 2. Paso 3: `AGENTS.md`, `.agents/MEMORY.md` y `.sdd-devkit/settings.json` no existían → se crean desde plantilla. Paso 4.1: se delega en un subagente que corre `arch-discover` **completo**; encuentra y presenta candidatos como "por qué Prisma" y "arquitectura en capas", el usuario acepta 3, y el propio `arch-discover` los crea invocando `arch-manage` en su Fase 5 — `arch-init` no vuelve a presentarlos ni a delegarlos. Paso 4.2: ya hay Jest configurado con buena cobertura de unit (bloqueantes cubiertos según `quality-check/references/stacks.md`); falta E2E para los flujos de checkout → se sugiere y el usuario acepta agregar Playwright, que se suma como candidato de dominio `testing`. Paso 5.1: la lista consolidada tiene solo el candidato de Playwright (los 3 de `arch-discover` ya quedaron creados) → se documenta y `/arch-manage` lo crea. Paso 5.2: stack definitivo (NestJS x.y, Prisma x.y, Jest + Playwright) se escribe en `AGENTS.md`. Paso 5.3: se confirma el cierre reportando los 3 ADR/estándares que creó `arch-discover` más el de Playwright, y se ofrece continuar con `work-plan` (hay deuda técnica pendiente); el usuario prefiere `Nada por ahora`.

**Ejemplo 3 — Con código base, sugerencia directa sin investigar**

Carpeta con un scaffold de Astro recién generado (`npm create astro@latest`), sin posts ni contenido propio. Paso 1: repo existe; `package.json` detecta Astro → situación "con código base" → se salta el Paso 2 (el stack ya está decidido por el scaffold). Paso 3: se crean los seis archivos del harness con plantilla fija; el scaffold generó un `README.md` genérico ("Astro starter") sin describir el proyecto real, así que se pregunta en una sola pregunta abierta qué hace el sitio y se actualiza la descripción cerca del inicio. Paso 4.1: el candidato es "Astro" (dominio `frontend`), sin alternativas registradas porque no hubo Paso 2. Paso 4.2: `quality-check/references/stacks.md` para Node+TS marca unit/build como bloqueantes; se sugiere Vitest; el usuario acepta. Paso 5: se documenta lo aceptado, se escribe el stack, se confirma el cierre y se ofrece `work-define`.

**Ejemplo 4 — Reejecución sobre un harness ya inicializado**

El usuario vuelve a pedir `arch-init` sobre un proyecto donde ya corrió antes. Paso 3 detecta que los siete archivos ya existen y están conformes (los seis con sus plantillas, `README.md` con su descripción) → informa que el harness ya está inicializado y pregunta si continuar para revisar/completar. El usuario confirma porque quiere agregar la compuerta E2E que no se configuró la primera vez → el skill retoma directamente en el Paso 4.2, sin tocar los archivos ya creados.

**Ejemplo 5 — Proyecto existente con documentos del harness en otro formato**

Monorepo Django con historial propio. Ya tiene un `CLAUDE.md` de 60 líneas escrito a mano (reglas de estilo, comandos de test, una nota sobre migraciones), un `docs/adr/README.md` con una tabla de tres ADRs, un `README.md` con instalación y badges pero sin ningún párrafo que diga qué hace el proyecto, y ningún `AGENTS.md`, `.agents/MEMORY.md`, `.sdd-devkit/settings.json` ni `docs/standards/README.md`. Paso 1: repo existe; stack Django detectado; situación "con implementación" → se salta el Paso 2.

Paso 3 compara cada archivo existente contra su plantilla:

- `CLAUDE.md` → **contenido ajeno** respecto a la plantilla (que es solo `@AGENTS.md`), pero su contenido sí es material de `AGENTS.md`. Se propone: crear `AGENTS.md` con la plantilla (creación de este skill) y delegar en `/plugin-migrate` la reubicación de las reglas de estilo y los comandos de test bajo `# Reglas generales` — con la nota sobre migraciones al final bajo su propio encabezado — y la reducción de `CLAUDE.md` a `@AGENTS.md`. El `# Stack tecnológico` de `AGENTS.md` queda con el comentario de la plantilla — el `CLAUDE.md` original no describía el stack, así que se rellenará en el Paso 5.2.
- `docs/adr/README.md` → **formato divergente**: falta el encabezado y el comentario-marcador, y las entradas están en tabla. Se propone delegar en `/plugin-migrate` la normalización: título y párrafo de la plantilla, marcador restaurado y las tres filas convertidas en líneas `- [ADR-XXX: Título](ADR-XXX-slug.md)` ordenadas por identificador, conservando los títulos tal como los escribió el usuario.
- `README.md` → no sigue esta comparación por plantilla (3.4): como no trae ninguna descripción del proyecto, se infiere una de lo detectado en el código Django y se propone insertarla cerca del inicio, sin tocar la instalación ni los badges existentes.
- Los cuatro archivos del harness que faltan (`AGENTS.md`, `.agents/MEMORY.md`, `.sdd-devkit/settings.json`, `docs/standards/README.md`) se crean desde plantilla, sin preguntar — `.sdd-devkit/settings.json` con el idioma resuelto en su clave `language` y el resto de valores de la plantilla.

Los dos hallazgos fuera de formato y la propuesta de descripción del `README.md` se presentan en **una sola tanda**; el usuario acepta normalizar el índice de ADRs (se delega en `/plugin-migrate`) y la descripción del `README.md`, y declina la de `CLAUDE.md` porque quiere reubicar él mismo esas reglas. `CLAUDE.md` queda intacto y `AGENTS.md` se crea igual desde plantilla (es una creación de este skill, no una normalización) — solo sin las reglas heredadas. Se registra que `CLAUDE.md` queda fuera de formato para reportarlo en el 5.3, advirtiendo que sus reglas no las verá el resto del catálogo, que lee `AGENTS.md`. El flujo continúa en el Paso 4.

**Ejemplo 6 — Multi-repo: repositorio de especificaciones nuevo con dos submódulos**

El usuario invoca `/arch-init` desde una carpeta vacía y explica que la solución tendrá un backend y un frontend en repos separados; el backend ya existe en GitHub, el frontend hay que crearlo desde cero. Paso 1.0: a "¿cuántos repositorios de código componen esta solución?" el usuario confirma "más de uno". Se propone `pedidos-specs` como nombre del repo de especificaciones en la carpeta actual (ya estaba vacía y pensada para agrupar todo); el usuario acepta. Se ejecuta `git init` ahí. Para el backend, ya existe → se pide la URL y se agrega con `git submodule add https://github.com/…/pedidos-api backend`; para el frontend, hay que crearlo → se inicializa un repo vacío en `frontend/` y se agrega con `git submodule add ./frontend frontend`, advirtiendo que no tiene remoto todavía. `git submodule status` confirma ambos registrados.

Paso 1.1 ya quedó resuelto por el 1.0. Paso 1.2/1.3 corren por submódulo: `backend` tiene `package.json` con NestJS y varias rutas de negocio → "con implementación"; `frontend` está vacío → "sin código". Paso 2 (solo para `frontend`, en una tanda): a "¿qué quieres desarrollar en `frontend`?" el usuario ya había dicho "una SPA que consume el backend de pedidos" al identificar el repo en el 1.0, así que solo se completa con restricciones adicionales; se sugiere React + Vite y el usuario acepta, se ejecuta el scaffold.

Paso 3: en la raíz de `pedidos-specs` se crean los tres archivos únicos del harness (`.agents/MEMORY.md`, `.sdd-devkit/settings.json`, `.gitignore`) más su `AGENTS.md`/`CLAUDE.md`/`README.md` — `pedidos-specs` es "Solo specs" por definición, así que **no** recibe `docs/adr/README.md` ni `docs/standards/README.md` propios, y su `AGENTS.md` omite esas dos líneas de Fuentes de contexto. Como `backend` y `frontend` se crearon en este mismo Paso 1.0 y ninguno es "Solo specs" (ambos van a tener código), se proponen índices de arquitectura para ambos por defecto; el usuario no excluye ninguno → `docs/adr/README.md` + `docs/standards/README.md` se crean en `backend/` y en `frontend/`, cada uno con su propia serie `ADR-XXX`. Con esa decisión ya resuelta, se crea el `AGENTS.md` de cada submódulo desde `assets/agents-submodule-template.md`: el de `backend` referencia `docs/adr/README.md`/`docs/standards/README.md` **locales** (recibió los suyos), y ambos —`backend` y `frontend`— referencian `@../.agents/MEMORY.md` y `@../README.md` del repo de especificaciones. El `CLAUDE.md` de cada uno es el mismo `@AGENTS.md` de siempre. El `README.md` de `backend` describe la API de pedidos (ya lo dijo el usuario al identificar el repo en el 1.0); el de `frontend`, la SPA.

Paso 4, una vez por submódulo: para `backend` ("con implementación") se delega en un subagente que corre `arch-discover` completo sobre `backend/` como raíz de arquitectura — encuentra y crea 2 ADR por su cuenta; su compuerta de calidad ya tenía Jest, se completa con Supertest para los endpoints. Para `frontend` ("sin código", scaffold recién instalado) el candidato es "React + Vite" (dominio `frontend`); su compuerta de calidad no tenía nada → se configura Vitest + Testing Library. `pedidos-specs` no pasa por el Paso 4 en ningún momento — es "Solo specs". Paso 5.1: dos corridas de `arch-manage`, una por raíz — la de `frontend` documenta el candidato de stack y el de testing; la de `backend` no repite lo que ya creó `arch-discover`, solo agrega el candidato de Supertest. Paso 5.2: `backend/AGENTS.md` queda con su propio stack completo (NestJS, Jest + Supertest); `frontend/AGENTS.md`, con el suyo (React + Vite, Vitest + Testing Library); el `AGENTS.md` de `pedidos-specs` no repite ese detalle — su `# Stack tecnológico` queda como una tabla de dos filas que enlaza a `backend/AGENTS.md` y `frontend/AGENTS.md`. Paso 5.3: se confirma el cierre resumiendo la topología (repo de especificaciones + 2 submódulos, cada uno con su propio `AGENTS.md`/`CLAUDE.md`/`README.md`), la situación y el stack de cada uno, y los ADR/estándares creados por raíz; se ofrece continuar con `work-define`.

**Ejemplo 7 — Repo único "Solo specs"**

El usuario invoca `/arch-init` sobre un repositorio recién creado y explica que va a usarlo solo para llevar los `SRS-XXX`, `US-XXX` y ADRs de un proyecto cuyo código vive en otro lado (fuera del alcance de `arch-init`, sin submódulos). Paso 1.0: proyecto de un solo repo, sin cambios de comportamiento. Paso 1.1: no hay repo git → `git init`. Paso 1.2: sin manifiestos ni código — antes de asumir "sin código", la descripción que el usuario ya dio ("solo para llevar specs y ADRs, el código vive en otro repo") es evidencia directa de "Solo specs"; no hace falta preguntar de nuevo. Paso 1.3: no aplica, no hay stack que detectar. Paso 2: se salta — "Solo specs" no tiene stack que conseguir, igual que "sin código" pero por una razón distinta. Paso 3: se crean los siete archivos del harness **menos** `docs/adr/README.md` y `docs/standards/README.md` — este repositorio nunca los recibe; su `AGENTS.md` omite esas dos líneas de Fuentes de contexto, y su `README.md` describe que el repositorio documenta las especificaciones del proyecto (usando lo que el usuario ya dijo). Paso 4: se salta completo, 4.1 y 4.2 — no hay código que audite ni compuerta de calidad que configurar. Paso 5.1: no hay candidatos que documentar, se salta directo al 5.2. Paso 5.2: `# Stack tecnológico` en `AGENTS.md` queda como `No aplica — repositorio de solo especificaciones`. Paso 5.3: se confirma el cierre señalando que este repositorio quedó sin índices de arquitectura porque es "Solo specs", y se ofrece continuar con `work-define` para empezar a escribir historias.

---

## Handoffs

| Después de `arch-init`... | Skill natural siguiente | Contexto que pasa |
| -------------------------- | ------------------------ | -------------------- |
| Harness inicializado, listo para escribir requisitos | `work-define` | El stack y las convenciones ya viven en `AGENTS.md`/`docs/standards/`. Ofrecido explícitamente en el Paso 5.3. |
| Harness inicializado, hay trabajo técnico que planificar | `work-plan` | Ofrecido explícitamente en el Paso 5.3. |
| Se necesita investigar algo más allá del stack inicial | `work-research` | Puede referenciar el `RS-XXX` generado en el Paso 2.2. |
| Se quieren agregar más ADR/estándares después del cierre | `arch-manage` | Los índices `docs/adr/README.md` y `docs/standards/README.md` ya existen y se amplían, no se recrean. |
| Verificar cumplimiento de lo documentado | `arch-audit` | Lee `AGENTS.md` (incluido el stack) y `docs/standards/`. |
| Primer commit del harness | `git-commit` | El working tree recién creado por este skill. |