juanca202/sdd-devkit

Auditar el cumplimiento de los estándares de arquitectura (docs/standards/) y de las reglas de AGENTS.md contra el estado real del repositorio (Architecture Compliance Checking), citando el ADR de origen de cada estándar, y generar un informe priorizado en docs/audits/arch-audit-YYYY-MM-DD.md. Audita una raíz de arquitectura por corrida (repo principal o submódulo), con sus estándares, fitness functions e informe. Activar siempre que el usuario quiera verificar, auditar o comprobar si el código respeta los estándares, decisiones arquitectónicas o reglas del proyecto, aunque no diga "estándar", "ADR" o "auditoría". Frases: "audita el cumplimiento", "¿el código respeta los estándares/ADR?", "verifica que seguimos las reglas de AGENTS.md", "compliance de arquitectura", "arch-audit", "/arch-audit". Usar también ante sospecha de desvío de lo documentado, para un informe de brechas con acciones.

Inspeccionar un proyecto existente para descubrir decisiones arquitectónicas implícitas y las reglas/convenciones vivas que están en vigor, y proponer los ADR y estándares candidatos que las documentarían. Usar cuando el usuario quiera auditar un repositorio en busca de decisiones o normas no documentadas, pida "descubrir ADRs", "descubrir estándares", "qué decisiones arquitectónicas tiene este proyecto", "qué convenciones sigue el código", "analiza la arquitectura del proyecto" o cualquier variante que implique explorar el código/estructura para inferir arquitectura relevante que merezca documentarse. Activar también cuando el usuario llegue a un proyecto nuevo y quiera entender qué decisiones y reglas ya existen, aunque no mencione explícitamente "ADR" o "estándar". Descubre una raíz de arquitectura por corrida —el repo principal o un submódulo—, y crea los documentos aprobados en esa misma raíz.

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/.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 el siguiente paso (requirement-refine, work-define, work-plan o test-define). Activar al pedir inicializar o preparar uno o varios repos para agentes, configurar su harness, crear AGENTS.md/MEMORY.md desde cero, o mencionar "arch-init", "/arch-init", "inicializa el harness".

Crear o actualizar la arquitectura documentada del proyecto: Architecture Decision Records (ADR, en docs/adr/) y estándares de arquitectura por dominio (en docs/standards/), en la raíz del repositorio al que pertenece el código (repo principal o submódulo). Un ADR registra el "por qué" de una decisión (histórico, inmutable); un estándar agrupa los requisitos verificables de un dominio — el "qué hay que cumplir hoy". Cada decisión que fija una regla actualiza el estándar de su dominio, no crea uno nuevo. Activar para documentar, registrar o cambiar el estado de una decisión arquitectónica o norma del proyecto, aunque no use las palabras "ADR" o "estándar". Frases: "registrar decisión", "documentar por qué usamos X", "decision record", "cambiar ADR a Accepted", "marcar como Superseded", "crear/actualizar ADR", "ADR-XXX", "definir un estándar", "añadir un requisito". Usar también ante una tensión arquitectónica que deba quedar documentada.

Revisión cualitativa de código, estilo ingeniero senior, sobre el diff de una rama contra su base (incluye lo no commiteado): intención, arquitectura y diseño (SOLID, Clean Architecture, ISO/IEC 25010: acoplamiento, fiabilidad, seguridad, desempeño) y feedback accionable que explica el porqué y propone cambios. Devuelve hallazgos con severidad, veredicto y próximas acciones. No exige artefactos de este plugin: la intención puede venir de una US-XXX/WI-XXX/FT-XXX, un ticket o spec externo, o la rama y sus commits. Activar cuando el usuario pida "revisa este código", "code review", "¿está bien resuelto esto?", "revisa el diseño antes del PR/merge", o cuando lo invoque otro skill (work-integrate, pr-create). Proceso de cierre, no proactivo. NO ejecuta pruebas, linter ni build — eso es de quality-check. Por defecto pide confirmación antes de corregir un hallazgo bloqueante; .sdd-devkit/settings.json (verification.codeReview.confirmFix: "never") permite corregir directo sin preguntar.

Verificar que el código cubre —alcanza— los criterios de aceptación del artefacto implementado: una historia de usuario (US-XXX), una tarea de mantenimiento (WI-XXX), un feature (FT-XXX) o cualquier documento cuyos criterios tengan identificador codificado (AC-001, 1.1, R-3…). La evidencia son las pruebas automatizadas del repositorio, los casos de prueba (TC-XXX), o ambos. Por cada criterio indica qué lo cubre, su estado (COVERED / PARTIAL / UNCOVERED) y el resultado de su ejecución, y genera un reporte (criteria-coverage.md) con veredicto. No corre la suite: delega en quality-check. Activar cuando el usuario pida verificar que el código cumple o cubre los criterios de aceptación, validar cobertura, generar una matriz o reporte de trazabilidad, comprobar si un trabajo o feature está cubierto por pruebas, o mencione "trazabilidad" o "matriz de cobertura". Cubre también trabajo archivado en <archivedPath>/, dejando el reporte junto al artefacto.

Crear o actualizar documentación técnica (modelos de datos, grupos de APIs/endpoints, flujos/procesos, diagramas de clases/C4) en docs/architecture/, organizada por capability, como referencia de implementación de US-XXX, TK-XXX y WI-XXX; y generar y revisar con el usuario los wireframes de pantalla (WF-XXX: .md + SVG en escala de grises) que viven en wireframes/ del SRS, US o WI que los origina. Activar cuando el usuario pida documentar o especificar un modelo, entidad, DTO, contrato de API, endpoint, flujo, proceso técnico o diagrama; cuando pida un wireframe, mockup o boceto de una pantalla; cuando pida «más detalle» sobre un elemento técnico sin especificación citado en una US, TK o WI; o cuando otro skill (requirement-refine, work-define, work-plan) delegue la especificación técnica o los wireframes. También con «/design-define», «documento técnico», «technical doc», «especificación técnica», «diseño técnico» o «wireframe», aunque no se nombre la capability.

Preparar y ejecutar git commit con mensajes Conventional Commits inferidos del diff (tipo, scope, descripción, staging). El push es opcional y lo gobierna .sdd-devkit/settings.json (git.push: ask/always/never; nunca por defecto), y solo aplica en invocación directa del usuario, no cuando lo invocan otros skills. No mergea, no toca la configuración global de git ni aplica operaciones destructivas. Activar cuando el usuario pida hacer commit, generar el mensaje, separar cambios en varios commits, o use invocaciones tipo /commit; también lo invocan automáticamente work-integrate y pr-create ante un working tree sucio.

Normalizar contenido producido con versiones anteriores del plugin SDD Devkit a la estructura vigente: archivos del harness fuera del formato de su plantilla (AGENTS.md, .agents/MEMORY.md, índices de ADR/estándares), CLAUDE.md heredado, settings.json con claves obsoletas (basePath/archivePath → changesPath/currentPath/archivedPath), el layout anterior de docs/specs/ (que pasa a changes/, current/ y archived/), glosario y documentación técnica en rutas antiguas, cabeceras de US sin sus líneas vigentes y estándares con la columna Verificación en yes/no. Detecta por estructura, propone un plan, aplica con confirmación conservando ids y redacción del usuario, actualiza referencias internas y reporta el mapeo viejo → nuevo. Activar cuando el usuario pida migrar, normalizar o actualizar el contenido del proyecto tras actualizar el plugin, mencione «plugin-migrate», o cuando otro skill detecte estructura de una versión anterior — los demás skills no migran: derivan aquí.

Crear Pull Request (PR) o Merge Request (MR) desde la rama actual hacia una rama destino preguntada al usuario, en dos modos: implementación (feature/fix/chore/refactor/test hacia su rama de integración) y promoción (develop hacia master/main/release, consolidando trabajos ya integrados). Puertas obligatorias y bloqueantes: en implementación, quality-check, code-review y coverage-verify; en promoción solo quality-check. En ambos se verifica docs/policies/definition-of-done.md si existe. No archiva el artefacto: el archivado se pide, tras la revisión humana, al skill que lo produjo (work-define / work-plan con el modificador archive). Funciona sobre cualquier repositorio git con remoto: auto-detecta la plataforma (GitHub, GitLab, Bitbucket, Gitea, Azure Repos) y su CLI, y genera título y descripción. Usar siempre que el usuario pida crear, abrir o subir un PR, MR, pull request o merge request, o promover develop a master, incluso si solo dice "crea el PR" o "súbelo a develop".

Ejecutar las verificaciones automatizadas del stack —tipado, linter, unit tests, cobertura, build, e2e, análisis estático (Sonar) y las suites que declare el estándar de testing— y emitir un veredicto con informe y próximas acciones. Produce la caché quality-check-run.json que consume coverage-verify. No exige artefactos de este plugin: corre sobre cualquier repositorio y delega las correcciones en work-implement. Activar cuando el usuario pida correr las pruebas o las verificaciones: "ejecuta los checks", "corre los tests", "quality check", "valida antes del PR/merge", "¿está verde el repo?", o cuando lo invoque otro skill (work-integrate, pr-create, coverage-verify). Proceso de cierre, no proactivo durante el desarrollo. Por defecto pide confirmación antes de corregir un fallo; .sdd-devkit/settings.json (verification.qualityCheck.confirmFix: "never") permite corregir directo sin preguntar. La revisión cualitativa de diseño es de code-review.

Punto de entrada único de requerimientos: tomar uno en bruto (idea, ticket, correo, transcripción, diseño, wireframes, documento de cliente) y formalizarlo, eligiendo el tipo al inicio, como RQ-XXX (requerimiento de un tercero que solo se certifica: AC-XXX trazados a su documento, para /test-define), PRD-XXX (problema, objetivos, actores, alcance, FR-XXX y AC-XXX de negocio, sin decisiones técnicas) o SRS-XXX (ISO/IEC/IEEE 29148: PRD + NFR-XXX, interfaces, datos, cumplimiento, stack y repositorios). Promueve un PRD a SRS conservando el número. Guarda el original en references/; wireframes vía /design-define. Activar con «refina este requerimiento», «crea un SRS/PRD/RQ», «especificación de requisitos», «documento de producto», «/requirement-refine», al describir una necesidad cruda o por handoff de /test-define. Modificadores: rq / prd / srs fijan el tipo; archive archiva con confirmación. No crea US (/work-define), TC (/test-define) ni documentación técnica (/design-define).

Crear casos de prueba (TC-XXX), según IEEE 29119-4, a partir de los criterios de aceptación de un artefacto con identificador codificado: US-XXX, WI-XXX, FT-XXX, RQ-XXX/PRD-XXX/SRS-XXX (formalizados por /requirement-refine) o cualquier documento con criterios numerados (AC-001, 1.1, R-3…). Un requerimiento en texto crudo no se formaliza aquí: handoff a /requirement-refine y se vuelve con el ID. No archiva nada. Activar cuando el usuario pida "definir test cases", "crear casos de prueba", "generar TCs", "pruebas para la US/WI/FT", o mencione "test-define" o "/test-define". Con gestor de proyectos activo, también para sincronizar Test Cases del tracker con el modificador explícito sync (código o URL de un Test Case o de su historia): crea los TC locales que falten y actualiza los existentes; sync … push sube cambios locales. Un #id o URL sin modificador NO sincroniza: se pregunta. Si el artefacto está archivado en <archivedPath>/, se detiene.

Crear o actualizar Historias de Usuario (US-XXX). Activar cuando el usuario pida una historia nueva, describa una funcionalidad o necesidad de negocio a documentar como historia, quiera crear varias relacionadas, o actualizar historias existentes. También para descomponer en historias un SRS-XXX terminado por /requirement-refine («arma las historias del SRS-003»): agrupa FR/NFR y hereda repos, wireframes y criterios; y para formalizar un spike viable en historia («historia a partir del spike WI-014»); con gestor de proyectos activo, para sincronizar una historia del tracker con el modificador explícito sync #id (crea o actualiza la US local); un #id o URL sin modificador NO sincroniza; y para archivar historias («archiva la US-042») con el modificador archive, que muestra el estado y pide confirmación. NO activar para redactar un SRS (/requirement-refine), registrar bugs o WI de mantenimiento, ni implementar o planificar TK-XXX. Una US archivada no se actualiza sin desarchivarla.

Implementar en código trabajo ya especificado, de cuatro tipos: (1) tareas técnicas (TK-XXX) bajo una historia de usuario; (2) tareas de mantenimiento (WI-XXX) sin historia — bugs, refactor, deuda técnica, dependencias, operativas; (3) casos de prueba (TC-XXX) — automatizar las pruebas ya documentadas por test-define; (4) features (FT-XXX) — automatizar los TC de sus criterios. Selecciona el tipo según el artefacto referenciado. Solo implementa trabajo en Estado: Ready; acepta además un modo corrección acotado, delegado por quality-check, sobre cualquier artefacto de la rama (US-XXX, WI-XXX, FT-XXX, TC-XXX en rama test/, o un artefacto externo al plugin), para arreglar un check o una prueba en rojo. Activar siempre que el usuario pida "implementar", "desarrollar", "ejecutar tareas", "codificar", "automatizar las pruebas", "implementa los test cases", "trabaja en el TK/WI/TC/FT" o variantes que impliquen escribir código desde una especificación ya redactada.

Cerrar e integrar el trabajo de una historia de usuario (US-XXX), una tarea de mantenimiento (WI-XXX) o una automatización de pruebas (rama test/ sobre un US-XXX, WI-XXX o FT-XXX) haciendo merge de la rama hacia la rama desde la que se creó, previa verificación de que progress.md tenga todas las unidades del trabajo en Done y de que pasen las puertas de calidad de cierre (quality-check, code-review y coverage-verify). No archiva el artefacto — eso lo pide el usuario después de su revisión al skill que lo produjo (work-define / work-plan con el modificador archive). En ramas test/ no archiva. Activar cuando el usuario pida cerrar, entregar, mergear, integrar, finalizar o hacer submit del trabajo de una historia, un WI, un feature o de la rama actual.

Planifica trabajo sin generar código ni pruebas. Tipos de plan: (1) tareas técnicas (TK-XXX) bajo una historia existente; (2) tareas de mantenimiento (WI-XXX) sin historia — bug-fix, refactor, deuda técnica, dependencias, tareas operativas y spikes (experimento con timebox, entrega un informe); (3) incidentes (BUG-XXX): registro de un hallazgo con evidencia, sin plan de corrección; único documento que produce con implementation.scope: tests. Activar al pedir planificar implementación, descomponer trabajo, definir alcance técnico, planificar mantenimiento o registrar un bug o hallazgo, aunque no nombre TK, WI o BUG. Ante una sola referencia a una historia («planifica US-007»), proponer la descomposición por repositorio cubriendo los AC-XXX. Carga la definición del tipo desde references/. Con gestor activo, sync #id trae un Task como TK/WI o un Bug como BUG-XXX, creando o actualizando el documento local. Archiva WI y BUG con archive, mostrando el estado y pidiendo confirmación.

Investigar y sintetizar hallazgos en un informe estructurado (RS-XXX). Seis flujos según la entrada: investigación libre de un tema; decisiones pendientes de un US-XXX/TK-XXX/WI-XXX antes de planificar; análisis de un issue o bug (reproducción, causa raíz, diagnóstico de pruebas, entregable WI bug-fix); auditoría de un caso de prueba TC-XXX; análisis de legado (descubrir features FT-XXX y sus pruebas); y discovery de migración entre proyectos. Activar cuando el usuario pida "investiga", "research", "¿es viable?", "¿cómo funciona X?", "compara opciones", "¿qué falta por decidir?", "hay un bug", "falla en producción", "analiza el bug #1234", "revisa este caso de prueba", "analiza este código legacy", "migración entre proyectos", o mencione "RS-XXX". También para archivar investigaciones («archiva el RS-003») con el modificador archive, que informa si otro artefacto la referencia y pide confirmación.