# Arch Init > 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". - Skill: `juanca202/arch-init` (Agent Skill, multi-file: 12 files) - Install (CLI): `npx skillmds@latest add juanca202/arch-init` - Raw SKILL.md: https://api.skillmd.com/api/skills/juanca202/arch-init/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Research & Search - License: MIT - Author: juanca202 (https://skillmd.com/u/juanca202) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/juanca202/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](#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 artefactos. | | `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}/reference/asking.md`](../../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/.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 `/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`](../../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 | 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` se llevan al formato de su plantilla (ver [3.1 Migración de formato](#31-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](#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 artefactos de **arquitectura**: pertenecen a la raíz del repositorio cuyo código documentan (ver > [`${PLUGIN_ROOT}/reference/artifacts.md`](../../reference/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). - **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 ?"*. 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 `` 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 **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](#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 | **Migrar al formato de la plantilla** (ver 3.1). | | **Contenido ajeno** — el archivo existe con un propósito distinto al del harness y no hay nada que migrar | 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` 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](.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](#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, 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é `` 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 de …(truncated)