toyin-software-factory/develop

Estilo de salida (palabras simples, sin guiones ni rayas)

Escribe todo lo que esta skill produce, archivos y mensajes por igual, en lenguaje sencillo y simple. Habla 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 como una orden. Mantén los términos técnicos que tienen significado real; explica cada uno en palabras sencillas. Nunca uses una raya o un guion como signo de puntuación: sin raya larga (em dash), sin raya corta (en dash) y sin compuestos con guion. Escribe read only, no read-only. Dilo en palabras simples o reformula la oración. El código, las rutas de archivo, las banderas de comandos y los valores con los que otras skills hacen coincidencia mantienen sus guiones. Usa oraciones cortas, comas o paréntesis. La claridad vence a la astucia.

Qué hace esta skill

El constructor: convierte una especificación más las convenciones del proyecto en código funcional. Rastrea: IU (componentes, páginas, diseños; ui-guide.md), Lógico (APIs, servicios, capas de datos, lógica de negocio, integraciones; logical-guide.md), o ambos (por ejemplo, "auth" = páginas de inicio de sesión más lógica de sesión → ejecuta ambos). El Paso 0 actúa como compuerta sobre la especificación para que las decisiones importantes (un enfoque de autenticación, un proveedor de pagos) se decidan en /architect, no se inventen silenciosamente durante la construcción.

Pregunta vs actúa

Actúa como compuerta, luego actúa: sin rondas de preguntas iniciales como /architect. Lee la decisión, construye, pregunta solo por lo que el diseño dejó abierto (la dirección visual cuando no se dio ninguna referencia; una regla de negocio que la especificación no resolvió). Infiere a partir de la especificación, AGENTS.md y el código base; recomienda elecciones de implementación local.

Propiedad de artefactos

• Escribe código de la aplicación (más CSS/tokens para IU).
• Alcance (docs/scope/): solo el Paso 4 toca (estado de característica → in-progress, subcajas de hito, casilla "Constrúyelo", puntero de código). Marca una característica como done solo en el nivel de flujo de trabajo Prototype (construcción más su propia autoverificación; el ingeniero optó por no hacer una verificación separada); una especificación Assumed no bloquea esto, permanece marcada como pendiente de ratificación. En Alpha/Beta/GA deja la característica in-progress para que /check verify y /test la cierren, y nunca marca Verifícalo o Pruébalo. Nunca crea archivos en docs/scope/ (solo alcances; el análisis/investigación es de /architect, en el rationale.md de la especificación).
• Nunca escribe contenido de especificaciones ni delibera una decisión (marca la necesidad, lo delega a /architect); nunca reestructura el AGENTS.md raíz (eso es de /audit); las nuevas convenciones de área van a través de /sync después. Una excepción estrecha: en "Construir ahora, registrarlo como una especificación asumida" (Paso 0), /develop puede crear una especificación, pero solo en Estado: Assumed, y solo los campos de registro de suposición (decisión pendiente, suposición sobre la que se construye, autorizada por, área de código, semillas de requisitos). Nunca escribe la justificación y nunca avanza una especificación Assumed más allá de ese estado; /architect es responsable de limpiarla. Esta es la única especificación que /develop crea.
• Un toque de especificación en una especificación existente: la línea **Estado**: (decisión general → la del index.md, nunca la de un hijo), más completar la línea del puntero de especificación de la característica. Inicio de construcción: Propuesta → En Progreso; construcción finalizada (característica → done): En Progreso → Aceptada (una especificación no está Aceptada hasta que su característica se haya enviado). Nunca edites el contenido de la especificación, solo esa línea, quirúrgicamente: léela de nuevo justo antes de escribir; estado inesperado (ya Aceptada, Supercedida) → señálalo, no sobrescribas. Nunca muevas una especificación fuera de Assumed (eso es ratificación, trabajo de /architect): una especificación Assumed permanece Assumed durante toda la construcción, incluso mientras la característica está in-progress, por lo que nunca puede llegar a Aceptada hasta que /architect la ratifique. La característica en sí aún se puede marcar como done (decisión del ingeniero); la especificación Assumed permanece marcada como pendiente de ratificación, no bloquea done.
• Base de artefactos: docs/ por defecto, .workflow/ si docs/ es un sitio de documentación publicado. Lee de la que exista (las rutas aquí asumen docs/).
• Alcance compartido: léelo de nuevo justo antes de marcar, edita solo la casilla de verificación específica, el estado o la línea del puntero (nunca reescribas el archivo); característica no como se esperaba (ya done, rehecho) → señálalo, no sobrescribas.

---

Portabilidad (cualquier sistema operativo, cualquier agente)

Cualquier cliente de Agent Skills, macOS/Linux/Windows. Los fragmentos de detección son referencia POSIX; usa las herramientas de archivos multiplataforma de tu propio agente. Construye en línea en el hilo principal (Paso 3); los únicos subagentes son un scout de solo lectura que explora el código (Paso 2.5) y un investigador de solo lectura para una verificación de documentación (Paso 2.6, degradándose a construir a partir del conocimiento sin capacidad web), ambos en el modelo más barato. Las guías incluidas (ui-guide.md, logical-guide.md, checklist.md) y el flujo de construcción después de la compuerta (flow/build.md) son rutas relativas a la carpeta de esta skill; el hilo principal las lee. Sin selector de preguntas interactivo → formula las preguntas como texto plano con las mismas opciones.

Ejecución

Antes de construir: el proyecto ya debe existir (excepto la tarea de andamio)

Excepción: si esta ES la subtarea de andamio de la característica de Pila y fundamentos de arquitectura (el prompt dice scaffold, o el paso inicializa el proyecto a partir de la especificación de la pila), crear el proyecto ES el trabajo. Lee la sección ## Pila propuesta de la especificación de ARQUITECTURA; ejecuta el inicializador de proyecto del propio framework para la pila que nombra la especificación; instala las dependencias base (framework, tiempo de ejecución principal, solo lo que necesita el primer slice); diseña los directorios; confirma que un servidor de desarrollo o una compilación funcione. Mantén el repositorio que el inicializador crea (nunca lo descartes al reubicar el proyecto); si no creó ninguno y la integración de git está activada, haz git init. Los pasos de andamio se derivan de la decisión de la pila (una especificación de decisión no tiene un plan de construcción). Instala justo a tiempo: NO cada biblioteca que nombra la especificación (correo electrónico, monitoreo, etcétera); cada característica posterior instala las suyas cuando se construye; solo las herramientas transversales (lint, formato, tipado estricto) llegan temprano, a través de /audit + la tarea de herramientas. Luego continúa.

De lo contrario, /develop construye dentro de un proyecto existente. Sin esqueleto (sin package.json/pyproject.toml/go.mod/manifest, sin árbol fuente) y no es la tarea de andamio → detente:

No se encontró un proyecto en el que construir. Ejecuta primero el paso de andamio (la subtarea de andamio de la característica de Pila y arquitectura, según tu especificación de arquitectura), luego ejecuta /develop de nuevo.

El proyecto existe (incluso un andamio vacío) → continúa.

Antes de construir: frescura y colaboración (no construyas sobre un estado obsoleto o sobre un compañero)

Antes de mutar cualquier cosa (salta silenciosamente si estás solo, sin conexión o no usas git): haz git fetch en silencio; base = main, si no master; número de commits por detrás (git rev-list --count HEAD..origin/<base>); trabajo sin commit (git status --short).

• Por detrás (recuento > 0) → detente y advierte: "Estás N commits por detrás de origin/$BASE. Es posible que un compañero ya haya cambiado o enviado esto. Primero haz pull, luego vuelve a ejecutar."
• Trabajo sin commit en el área que tocarás → advierte: "Tienes cambios sin confirmar aquí. Primero haz commit o stash para que esta construcción no se entremezcle con ellos." Permite que continúen si insisten.
• Característica in-progress en el alcance Y su área de código (ruta de la línea del puntero) tiene commits recientes de otro autor (git log --format='%an' -- <area>) → advierte: "<característica> parece que está a medio construir por otra persona. Coordina antes de continuarla." Confirma antes de continuar.

Son advertencias, no bloqueos duros, pero hazlas visibles.

Integración de Git: si el AGENTS.md más cercano en ## Git dice integration: on, lee flow/git.md y síguelo (crea una rama antes de construir, haz commit a medida que los hitos aterrizan); ausente o off → no hagas git activo.

Paso 0: La compuerta de la especificación (siempre primero)

¿Hay una decisión pendiente y no registrada? NO juzgues esto por introspección ("¿siento que estoy inventando algo?"), el modelo de construcción racionaliza una decisión real como "solo cableado" y la deja pasar. Usa una prueba positiva de cobertura de entrada, que es mecánica y más difícil de eludir:

Enumera cada valor que esta construcción debe producir, calcular o mostrar (a partir de los criterios de aceptación y el diseño de la especificación). Para cada uno, ¿la especificación nombra de dónde viene (una entrada, una columna de BD, una derivación de un valor nombrado, una decisión previa)? Cualquier valor requerido sin una fuente nombrada es una decisión pendiente.

Si alguna fuente no está nombrada, detente y redirige a la compuerta (/architect, o registra una especificación Assumed; /develop implementa decisiones, no las toma). También hay una decisión pendiente cuando tendrías que inventar:

• Un proveedor, librería, integración, modelo de datos o patrón transversal (por ejemplo, proveedor de autenticación, DB/ORM, estrategia de caché).
• Una página o pantalla completa de IU: su sistema de diseño (¿hay un design.md allí? si no, ¿qué dirección?), secciones/composición, inventario de componentes, estrategia de activos (sin captura de pantalla, sin imágenes en el repo → por ejemplo, una fuente en línea). Pendiente a menos que un design.md Y una especificación a nivel de página los definan.
• El comportamiento de una característica (búsqueda, un asistente: "¿qué debería hacer exactamente?" está abierto; /architect hace esas preguntas). Pendiente a menos que una especificación lo defina.

Lo que realmente significa "detalle de implementación local" (la excepción estrecha): SOLO una elección entre opciones que las fuentes nombradas de la especificación ya permiten, un estilo de bucle, un nombre de variable, qué función auxiliar llamar. En el momento en que una elección determina la fuente de un valor, o un comportamiento que un criterio de aceptación restringe, es importante por definición, por pequeño que parezca. Derivar "la fecha del usuario a partir de la zona horaria de su última fila leída" no es un detalle local: elige la fuente de un valor que un CA restringe, por lo tanto está pendiente. NO está pendiente para implementación pura genuina: una pequeña corrección de errores, un componente que coincide con un design.md existente, cablear piezas cuyas fuentes la especificación ya nombra, un ajuste de copia, cualquier cosa que una especificación/design.md/AGENTS.md existente gobierne por completo.

No uses valores codificados para nombres de páginas o para un solo ejemplo (la zona horaria es una ilustración del patrón, no una regla); aplica la prueba de cobertura de entrada a lo que sea que se haya solicitado. Los falsos negativos son el modo de fallo, construir una decisión real sin notarlo: cuando la fuente de un valor requerido no está nombrada, o no estás seguro, trátalo como pendiente y pregunta (panel a continuación).

Lee solo lo que esta característica necesita, nunca todo el árbol docs/: su único archivo de alcance y su única especificación que la gobierna (archivo único, o index.md general más el archivo hijo que especifica esta subtarea). Ninguna otra fila de otras características, archivos de alcance, espacios de trabajo o especificaciones no relacionadas.

Verifica, en orden:

1. Localiza el archivo de alcance de esta característica (solo ese). Monorepo → docs/scope/<workspace>/ para el paquete de la tarea. Escoge el archivo (scope.md, o el <epic>.md que coincida en una división) solo de la tabla de un vistazo; lee solo la sección de esta característica. needs a decision sin puntero de especificación todavía → decisión pendiente y faltante. Mal formado → señálalo y pregunta, no adivines.
2. Abre la especificación que gobierna a través del puntero spec de la característica, leyendo solo sus secciones de especificación de construcción según se define en el flujo de construcción (flow/build.md), elemento 2 del Paso 2. Encontrada → es la especificación; continúa. Sin puntero y sin especificación vinculada → búsqueda dirigida en docs/specs/<workspace>/ para una que coincida con el alcance de esta característica, nunca una lectura general.
3. El más cercano AGENTS.md (espacio de trabajo/área) puede ya capturar la decisión, sincronizada desde una característica anterior (por ejemplo, "el proveedor de autenticación ya está elegido") → continúa sin una nueva especificación.

Decisión pendiente y no registrada → no adivines, no te detengas en silencio. Pregunta (selección única; AskUserQuestion en Claude Code):

• pregunta: "Esto parece que necesita primero una decisión de arquitectura: <nombra la elección importante específica, por ejemplo 'qué proveedor de autenticación + modelo de sesión'>. ¿Cómo quieres manejarlo?"
• encabezado: "¿especificación primero?"
• opciones:
  1. Diseñarlo primero: "Recomendado. Captura la decisión en una especificación antes de construir, para que la construcción tenga una especificación." → termina aquí con la transferencia a continuación. No construyas.
  2. No, no es necesario: "He juzgado que no hay una decisión real aquí; construye directamente." → continúa al flujo de construcción (flow/build.md).
  3. Construir ahora, registrarlo como una especificación asumida: "Constrúyelo, pero primero escribe la suposición para que la decisión viva en el repo, no solo en este chat. La especificación Assumed permanece marcada como pendiente de ratificación (/architect), pero eso nunca bloquea marcar la característica como done." → escribe una especificación Assumed (a continuación), luego continúa al flujo de construcción (flow/build.md), dejando la característica in-progress con una nota de decisión asumida (especificación NNNN) en el alcance (docs/scope/).

La herramienta añade "Otro" como una opción de texto libre automáticamente.

En "Construir ahora, registrarlo como una especificación asumida", escribe una especificación Assumed mínima antes de construir (esta es la única escritura estrecha de especificación que /develop posee; ver Propiedad de artefactos). Resuelve $SPEC_DIR de la forma en que lo hace /architect (repositorio único → docs/specs/; monorepo espacio de trabajo → docs/specs/<workspace>/), toma el siguiente NNNN libre y escribe $SPEC_DIR/NNNN-<slug>.md:

# NNNN · <característica>

**Estado**: Assumed
**Fecha**: <hoy>
**Autorizado por**: <ingeniero>, durante /develop

## Decisión pendiente
<la elección importante específica que no se tomó>

## Suposición sobre la que se construye
<la suposición concreta que usará esta construcción>

## Área de código
<las rutas que tocará esta construcción>

## Requisitos
<semillas de criterios de aceptación tomadas del "Hecho cuando" del alcance, si las hay>

## Ratificar
Esta decisión fue registrada por /develop, no deliberada. Ejecuta `/architect <característica>`
para deliberar y ratificarla. Hasta entonces permanece marcada como una decisión pendiente; no bloquea marcar la característica como `done`.

Apunta la línea spec del alcance de la característica a este archivo. La suposición ahora es duradera: sobrevive a /clear, los compañeros la leen, y un /develop posterior construye contra ella en lugar de adivinar de nuevo. La especificación Assumed permanece marcada como pendiente de ratificación; no bloquea marcar la característica como done (ver flow/build.md, Paso 4).

En "Diseñarlo primero", termina con:

Ejecuta esto a continuación, luego vuelve a /develop:

/architect <característica>: <la decisión específica a resolver>

Una vez que la especificación exista, ejecuta /develop <tarea> de nuevo y construiré según ella.

No hay decisión pendiente (implementación pura) → salta la pregunta, continúa.

Flujo de construcción (Pasos 1-4)

En construcción...