toyin-software-factory/sync

Estilo de salida (palabras sencillas, sin guiones, sin guiones medios)

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

Qué hace esta habilidad

Cierra el ciclo de un cambio completado: sincroniza los archivos AGENTS.md, el alcance y las líneas **Status**: de las especificaciones vinculadas con lo que el repositorio muestra ahora, e indica lo que no debe editar (especificaciones obsoletas, prosa curada). La tabla de Límites a continuación es el contrato exacto.

agent-prompt.md es la única fuente de verdad para las reglas de mantenimiento; SKILL.md cubre solo la orquestación. El hilo principal lo lee y realiza el mantenimiento (ver Paso 3).

Archivo canónico: el contexto persistente vive en el archivo independiente de la herramienta AGENTS.md; CLAUDE.md es solo un puntero hacia él. /sync edita/crea ambos, tratándolos solo como objetivos, nunca como fuente de cambios.

Límites

Acción	/sync	Propietario
Editar AGENTS.md raíz/anidado existente	✅ mantiene	/sync
Reconciliar la línea ## Build approach del AGENTS.md raíz con el enfoque del encabezado del alcance (edición quirúrgica de una sola línea, como la pila)	✅ mantiene; señala una divergencia curada	/sync
Añadir una línea de puntero a design.md (el sistema de diseño de UI) en el AGENTS.md más cercano cuando un cambio establece uno	✅ mantiene (solo puntero)	/sync
Crear <area>/AGENTS.md anidado para un área nueva neta en este cambio	✅ crea (diff = contexto completo del área) + añade puntero raíz	/sync
Crear documento anidado para un área ya existente no documentada (solo lo que muestra el diff)	❌ indica "ejecuta /audit"	/audit
Crear o reestructurar el AGENTS.md raíz	❌ indica "ejecuta /audit"	/audit
Reconciliar la línea **Status**: de una especificación con el estado del alcance de su funcionalidad (planned→Propuesto, in-progress→En Progreso, done→Aceptado; una especificación Asumida es la excepción: déjala como Asumida y menciónala, nunca la reconcilies a Aceptado)	✅ Solo la línea de Estado	/sync
Limpiar una especificación Asumida (sacarla de Asumida)	❌ indica como deuda de decisión "ejecuta /architect para ratificar" (nunca se reconcilia con el estado de la funcionalidad; solo la ratificación la limpia)	/architect
Editar el contenido de una especificación / reemplazarla	❌ indica como obsoleta	/architect
Reconciliar el alcance, solo para el archivo de alcance del espacio de trabajo relevante (no todo docs/scope/), marcar cualquier subtarea completada a partir de la evidencia del repositorio (código, pruebas, AGENTS.md), avanzar estado	✅ corrige	/sync
Añadir o reordenar funcionalidades o subtareas en el alcance	❌ lo deja como está	/scope
Sobrescribir o reescribir prosa curada de AGENTS.md	❌ indica conflicto en su lugar	humano

La línea divisoria sobre la creación es contexto, no política: crea solo cuando este cambio te muestra el área completa; difiere a /audit cuando el área precede al cambio y has visto solo una parte. Cuando no estés seguro, indícalo en lugar de crear.

Solicita vs actúa

Actúa. Solo se detiene cuando no hay nada que sincronizar (conjunto de cambios vacío). Cada edición a archivos curados se lista en el informe para que puedas revisar o revertir.

Propiedad de artefactos

Posee exactamente lo que la tabla de Límites concede y no escribe nada más. Como el reconciliador universal de subtareas, marca cualquier subtarea del alcance que pueda verificar a partir de la evidencia del repositorio (incluyendo las subtareas /test//audit//sync que otras habilidades no marcan) y avanza el estado de la funcionalidad; reglas exactas en agent-prompt.md.

Base de artefactos. Las especificaciones y el alcance residen en docs/ por defecto, o en .workflow/ si docs/ es un sitio de documentación publicado; usa la base que exista en el repositorio (las rutas aquí asumen docs/).

---

Portabilidad (cualquier SO, cualquier agente)

• Comandos: git es el único CLI requerido y se comporta igual en todos los SO; ejecuta las líneas de git como se muestran. Otros fragmentos de shell son referencia POSIX, no scripts literales: no asumas que existen find, grep, sed, cat, test/[ ], ls ni xargs; usa las herramientas multiplataforma de archivos de tu agente y aplica la lógica de bifurcación tú mismo en lugar de shell if/variables/redirecciones.
• Archivos incluidos: referenciados por rutas relativas a la carpeta de esta habilidad. Resuelve la carpeta a una ruta absoluta (tú ya resuelves estas rutas relativas) y lee agent-prompt.md tú mismo en el momento de escritura (Paso 3), no durante los pasos anteriores.
• Todo el mantenimiento se ejecuta en línea en el hilo principal, siguiendo las reglas exactas de agent-prompt.md (autoritativo).

Ejecución

1. Delimitar el conjunto de cambios (económico, con estado por archivo)

Actualidad primero (equipos): git fetch --quiet; si git rev-list --count HEAD..origin/$BASE > 0 estás detrás de origin/$BASE, advierte al ingeniero que haga pull primero, un compañero puede haber sincronizado ya estos documentos.

Base: main si git rev-parse --verify main tiene éxito, si no master. Rama actual: git rev-parse --abbrev-ref HEAD. Usa --name-status (no --name-only); la lógica de área nueva neta y limpieza de huérfanos necesita Agregado vs Modificado vs Eliminado por archivo.

• La rama actual es la base, modo no confirmado: git diff --name-status HEAD.
• De lo contrario, modo rama: git merge-base "$BASE" HEAD, luego git diff --name-status <merge-base>.

De cualquier manera, añade archivos no rastreados de git ls-files --others --exclude-standard, cada uno con un prefijo de estado A (coincidiendo con el formato --name-status). Anota el modo, base y merge base para el paso de escritura.

Elimina duplicados, luego filtra a archivos fuente para sincronizar desde:

• Descarta documentación y configuración (AGENTS.md en cualquier nivel, docs/**, *.md, test-preferences.json, archivos de bloqueo, salida generada); /sync los lee como objetivos/contexto, nunca como fuente de cambios.
• Descarta archivos de prueba (*.test.*, *.spec.*, __tests__/, etc.); las pruebas no son convenciones duraderas de área.
• Mantén las entradas D (eliminadas) en una lista separada; impulsan la limpieza de huérfanos (Paso 3) aunque no se sincronicen desde.
• Mantén los cambios en manifiestos de dependencias en una lista separada para descubrimiento de herramientas, incluso si son configuración en lugar de fuente: package.json, pyproject.toml, requirements*.txt, go.mod, Cargo.toml, composer.json, Gemfile, pubspec.yaml, mix.exs, *.csproj y manifiestos de paquetes equivalentes. Los archivos de bloqueo son solo señales; no pases el contenido de los archivos de bloqueo.

Si no quedan archivos fuente ni cambios en manifiestos de dependencias (solo cambiaron documentos/pruebas/bloqueo/archivos generados), detente, no hay nada que sincronizar. No ejecutes.

2. Localizar los archivos de contexto y especificaciones (solo rutas, NO los leas aquí)

Usando las herramientas de búsqueda/glob de archivos de tu agente:

• Anota si existe un AGENTS.md raíz.
• Encuentra todos los AGENTS.md (raíz + anidados), excluyendo node_modules/ y .git/.
• Encuentra todas las especificaciones bajo docs/specs/ cuyos nombres comiencen con un dígito, ordenadas.
• Encuentra los archivos de alcance cuyo espacio de trabajo/funcionalidad toque realmente el diff (en un monorepo, el espacio de trabajo de un archivo cambiado apps/<x>/… selecciona docs/scope/<x>/); nunca leas ni pases todo docs/scope/.

Anota las rutas más la lista de archivos cambiados y el comando diff; lee los archivos en el momento de escritura. Lee el contenido del AGENTS.md raíz ahora (corto y útil para anclar). Para cada archivo cambiado, anota su directorio contenedor más cercano que tenga un AGENTS.md (raíz o anidado); ese es el archivo de contexto con más probabilidades de necesitar una actualización.

2.5 Descubrir habilidades de agente y MCPs opcionales para herramientas recién añadidas

Ejecuta solo cuando los manifiestos de dependencias cambiaron o el diff claramente añade una herramienta externa significativa. Omite bibliotecas de utilidad comunes a menos que definan un flujo de trabajo o integración duradero.

• Identifica paquetes/herramientas significativos recién añadidos a partir del diff del manifiesto, no del archivo de bloqueo completo: framework, enrutador, kit de estilo/UI, base de datos, ORM/capa de consulta, autenticación/sesión, pagos, correo electrónico/notificaciones, almacenamiento/subidas, búsqueda, cola/trabajos en segundo plano, proveedor de IA/vector DB, pruebas de navegador/tiempo de ejecución, observabilidad, hosting/despliegue. Incluye nombres de paquetes y alias comunes de los manifiestos. No te detengas después de la primera tecnología.

• Filtra cualquier cosa ya cubierta por habilidades instaladas, MCPs conectados o entradas rechazadas en AGENTS.md.

• Pregunta antes de buscar.

  Preguntar es obligatorio. Buscar no. Nada se busca, obtiene, instala o ejecuta para el descubrimiento de Habilidades de Agente y MCPs hasta que el ingeniero haya elegido. Ofrece cuatro opciones: búscalos por mí, yo nombraré los que quiero, no y registra el rechazo, o ahora no. Solo la primera puede ejecutar un comando de búsqueda. Nunca omitas la oferta en silencio, y nunca ejecutes una búsqueda antes de que el ingeniero acepte una.

  Nombra las herramientas que este cambio añadió, di en una línea que una Habilidad de Agente le da al agente las convenciones reales de esa herramienta y un servidor MCP le da acceso en vivo al sistema real, luego pregunta: "¿Quieres que busque Habilidades de Agente y servidores MCP para las herramientas que este cambio añadió?" (encabezado Habilidades de agente), con Sí, búscamelos (recomendado) · Yo nombraré los que quiero · No, saltar esto · Ahora no, más tarde. En Sí continúa abajo. En Yo nombraré los que quiero, toma la lista y ve directamente al paso de instalación, sin buscar nada. En No, saltar esto no ejecutes nada y registra el rechazo. En Ahora no, más tarde no ejecutes nada y anota las herramientas candidatas en el informe.

• Aísla las búsquedas en un subagente de solo lectura (primero capacidad, solo después de Sí). Pasa el conjunto restante a un subagente de descubrimiento en lugar de buscar en el hilo principal: ejecútalo en segundo plano (no bloquea) si tu agente lo soporta, si no, bloqueante; establece su modelo explícitamente a un nivel rápido y de bajo costo (no heredes el modelo de la sesión; en Claude Code ejecútalo como el tipo de subagente researcher, que fija el modelo). Esto mantiene la salida de búsqueda fuera del contexto delimitado de /sync. Sin subagente → busca en línea; sin capacidad de búsqueda → salta y anótalo. El panel de oferta permanece en el hilo principal.

• Para cada elemento restante, ejecuta npx skills find <tool-or-package>; si es débil, reintenta con alias de nombres de paquetes/org. Recolecta cada candidato creíble de Habilidad de Agente y confirma con npx skills add <owner>/<repo> --list cuando sea práctico. Si el CLI es interactivo/no disponible, busca "<tool>" "agent skill" y confirma antes de ofrecer.

• La búsqueda de MCP es opcional: primero lista de conectores, si no "<tool>" "MCP server" por elemento. MCP es ventaja recomendada, no requerido.

• Mantén el descubrimiento limitado y almacenable en caché: máximo 5 búsquedas web y 8 páginas obtenidas en total, primero registros oficiales/documentación. Reutiliza docs/.agent-cache/tool-discovery/<slug>.md cuando tenga menos de 30 días, después de filtrar elementos instalados/rechazados.

• Ofrece todas las coincidencias de Habilidades de Agente en un panel de selección múltiple, agrupadas por tecnología: "¿Instalar Habilidades de Agente relevantes para las herramientas recién añadidas?" más saltar/rechazar. Luego ofrece MCPs por separado: "Servidores MCP opcionales que podrían ayudar a estas herramientas" más saltar/rechazar. Nunca instales ni conectes automáticamente.

• Instala las habilidades seleccionadas con npx skills add <owner>/<repo> -y. Para MCPs, señala la configuración de conector/MCP del usuario; una vez conectados, las herramientas se usan automáticamente.

• Lleva el resultado como INSTALLED_SKILLS_OR_NONE, MCP_SERVERS_OR_NONE y DECLINED_TOOLS_OR_NONE y registra líneas duraderas en el archivo AGENTS.md correcto cuando escribas. Si no se encontró nada o no existe capacidad, trata como none.

3. Hacer el mantenimiento (hilo principal)

El hilo principal hace el mantenimiento él mismo; nunca pasa las ediciones de AGENTS.md / alcance / estado de especificaciones a un subagente. Lee agent-prompt.md ahora (solo ahora, en el momento de escritura) y síguelo exactamente; es autoritativo para las reglas de mantenimiento. La lectura del diff es lo único que puedes delegar, y solo para un conjunto de cambios grande, a un subagente scout de solo lectura en el modelo más barato (Claude Code: haiku) que devuelva un mapa compacto. Mantente dentro de los mismos límites que la concesión de herramientas anterior expresó: Edit documentos existentes, alcance y líneas **Status**: de especificaciones; Write estrictamente para un área nueva neta AGENTS.md anidado; sin creación raíz, sin ediciones de contenido de especificaciones (solo línea de Estado), sin documentos anidados superficiales para áreas establecidas (estas son reglas en agent-prompt.md).

Las entradas para aplicar:

1. MODE, BASE, MERGE_BASE, CHANGED_FILES (lista de archivos fuente cambiados con estado), DIFF_COMMAND (comando git diff exacto)
2. DELETED_PATHS (rutas eliminadas, para limpieza de huérfanos)
3. ROOT_AGENTS_MD (contenido del AGENTS.md raíz), NESTED_PATHS (rutas de AGENTS.md anidados)
4. SPEC_PATHS (todas las rutas de especificaciones, para reconciliación de línea de Estado y marcado de obsolescencia)
5. FILE_TO_CONTEXT_MAP (archivo cambiado → archivo de contexto más cercano)
6. SCOPE_PATH_OR_NONE (rutas de alcance del espacio de trabajo relevante, no todo docs/scope/; también la fuente del estado de cada funcionalidad vinculada para la reconciliación de la línea de Estado de la especificación)
7. INSTALLED_SKILLS_OR_NONE, MCP_SERVERS_OR_NONE, DECLINED_TOOLS_OR_NONE del Paso 2.5

4. Comunicar el resultado

Si el mantenimiento falló o no produjo un resumen analizable, repórtalo y hazlo de nuevo, no inventes un resultado (un NOTHING_TO_SYNC genuino es un éxito válido; un fallo o salida vacía no lo es). De lo contrario, comunica el resumen compacto:

Encabeza con lo que reconcilió en una línea; luego lista solo lo que necesita al ingeniero (según docs/conventions.md). Las ediciones en sí están en los archivos. Plantilla:

## /sync completado · reconciliados <N> archivos cambiados

**Actualizados <archivos AGENTS.md · funcionalidades del alcance · estados de especificaciones> para coincidir con el diff.**   (o "todo ya actualizado, nada que sincronizar")
Atención (te necesitamos):
- Especificación obsoleta → /architect: `<archivo>` (<por qué, o un desajuste de estado que /sync no pudo reconciliar de forma segura>)

Mantén el tono cálido y directo como un colega.