EvolveHQ/docflow

bootstrap

Estás instalando (o readaptando) un conjunto de convenciones basadas en documentación en el repositorio actual. El estado final es un repositorio que puede ser manejado tanto por humanos como por agentes de codificación a partir de un pequeño conjunto de archivos canónicos. Transfiere el mecanismo descrito aquí — nada de ningún otro proyecto.

Paso 1 — Detectar la situación

Inspecciona el repositorio antes de preguntar nada. Reutiliza las respuestas explícitas y la aprobación ya proporcionadas en esta sesión; nunca las reemplaces con valores predeterminados del perfil ni preguntes por ellas nuevamente. Antes de escribir, resume la raíz del artefacto resuelta, la profundidad, la cola, la puerta de verificación y los modos de coordinación/integración en función de esas respuestas. Si un host refleja una carpeta seleccionada en un entorno aislado, identifica la ruta de destino real y cómo los resultados verificados llegan a la carpeta seleccionada; nunca llames completo a un destino no tocado simplemente porque un reflejo de prueba pasó.

• Repositorio nuevo (sin fuente, sin documentación): estás andamiando desde cero.

• Repositorio existente: estás readaptando.

  • Lee cualquier README.md, CONTRIBUTING.md, AGENTS.md, CLAUDE.md, docs/, adr/, .github/ actuales antes de proponer cambios.
  • Conserva el contenido existente. Fusiona, no sobrescribas. Si las convenciones existentes entran en conflicto con las siguientes, expón el conflicto en tu resumen de evaluación.
  • Si los ADRs ya existen en otro formato, propón un plan de migración (renumerar, conservar, traducir) en lugar de crear un árbol paralelo.

• Ya es un repositorio docflow (incluye AGENTS.md + CONVENTIONS.md + un catálogo de ADR): estás agregando a una configuración existente, no andamiando. No vuelvas a andamiar el núcleo ni vuelvas a preguntar preguntas ya resueltas — lee las elecciones registradas de CONVENTIONS.md/AGENTS.md (forma de ADR, ciclo de vida de estado, raíz del artefacto, modo multiagente y qué capas opcionales ya existen). Luego ofrece habilitar cualquier capa opcional no elegida que aún falte — plan/, _agent/, GLOSSARY.md, domains/, o la segunda forma de ADR (la plantilla de tecnología) — y escribe solo las elegidas, mediante fusión, bajo la raíz del artefacto registrada, dejando todo lo demás intacto. Haz solo las preguntas que necesiten las nuevas capas (por ejemplo, la pregunta de coordinación al habilitar _agent/ — donde un escritor único sin una puerta de verificación registrada y una cola de planificación termina correctamente sin _agent/ en absoluto, y la capa simplemente no es necesaria). Este es el punto de entrada para agregar una capa que diferiste en la primera inicialización. Un repositorio que aún contenga archivos de coordinación que un andamiaje anterior escribió los conserva: déjalos en su lugar y permite que la habilidad de auditoría informe el diseño.

  Habilitar GLOSSARY.md escribe el esqueleto canónico, nunca una reescritura. Cuando se elige la capa y el archivo está ausente, escríbelo desde templates/GLOSSARY.md — el encabezado y prosa opcionales, luego la tabla Término | Definición registrada en el CONVENTIONS.md generado §Glosario. Si el archivo ya existe, déjalo intacto: habilitar la capa no agrega nada, y add-convention extiende el archivo existente en la forma canónica o audit ofrece una migración consentida.

  Habilitar la segunda forma de ADR es un cambio de esquema, no una copia de archivo. Es la única capa diferida que cambia una elección ya registrada, así que escríbela toda de una vez o ninguna: reemplaza §Formas de ADR en CONVENTIONS.md con el texto de dos formas, agrega el orden de secciones de tecnología y las viñetas de forma a AGENTS.md, escribe adr/0000-template-technology.md, y regenera INDEX.md con la columna Forma. Los ADRs existentes conservan sus números y siguen siendo de capacidad — un campo shape: ausente ya significa capacidad, por lo que ningún ADR se reescribe y nada se renombra. La mitad del cambio deja al repositorio en el estado que la verificación cruzada del Paso 4.5 llama una contradicción: una plantilla de tecnología que un esquema de una sola forma nunca seleccionará.

  Un repositorio ya en la codificación de rango heredada recibe la oferta de migración en su lugar. Algunos repositorios de dos formas fueron andamiados antes de que la forma se convirtiera en un campo declarado y la codifican en el número: §Formas de ADR registra un límite (capacidad por debajo de él, tecnología en él o por encima), y adr/ contiene una plantilla numerada distinta de 0000 (por ejemplo, adr/0100-template.md). Cualquiera de las señales lo identifica. Tal repositorio no carece de una capa — ya tiene ambas formas — así que no ofrezcas el cambio de esquema anterior, ya que lo dejaría con dos codificaciones rivales. Ofrece la migración al campo declarado, en los mismos términos que usa la habilidad de auditoría:

  • Muestra primero el mapa de números de antiguo a nuevo, como una simulación: los ADRs de capacidad conservan sus números; los ADRs de tecnología toman los números siguientes al ADR de capacidad más alto, en su orden relativo original. Junto a él, enumera las referencias que siguen (depends-on, supersedes / superseded-by, enlaces relativos adr/NNNN-*.md, INDEX.md, listados de README.md de dominio, líneas de ADR propietario en plan/todo/) y lo que queda como historial (pies de página de plan/done/, mensajes de commit, etiquetas).
  • No escribas nada sin una confirmación explícita de ese mapa. Rechazar es un resultado válido: el repositorio conserva la codificación de rango y sigue cumpliendo sus propias reglas.
  • Tras la confirmación, aplica la migración exactamente como lo especifica el paso de migración de la habilidad de auditoría — renumerar, poner el sello shape: en cada ADR, reescribir cada referencia en el catálogo, reemplazar la plantilla de límite con adr/0000-template-technology.md, reescribir §Formas de ADR al campo declarado y eliminar cualquier cláusula de excepción de ADR semilla, regenerar INDEX.md con la columna Forma — y conviértelo en un commit cuyo mensaje enumere cada par antiguo a nuevo. Ese procedimiento es la única fuente de verdad; no parafrasees una segunda variante del mismo aquí.
  • Luego continúa la re-ejecución normalmente para las capas que realmente están ausentes (plan/, _agent/, GLOSSARY.md, domains/).

Indica qué situación se aplica en una línea antes de hacer las preguntas de evaluación.

Paso 2 — Dispositivo objetivo

<repo>/
  AGENTS.md              # reglas estrictas para agentes de codificación — punto de entrada
  CLAUDE.md              # línea única: @AGENTS.md
  README.md              # resumen del proyecto para humanos (conservar si existe)
  CONVENTIONS.md         # reglas de autoría: ADRs, nomenclatura, estado, auditoría, git
  INDEX.md               # tabla generada de todos los ADRs
  GLOSSARY.md            # términos compartidos (opcional — ver P7)
  adr/
    0000-template.md     # plantilla de ADR de capacidad (siempre)
    0000-template-technology.md  # plantilla de ADR de tecnología (solo si dos formas — ver P2)
    NNNN-<kebab-slug>.md # un ADR por decisión, numeración contigua
  domains/<slug>/README.md   # opcional (ver P7)
  plan/
    README.md
    todo/NNNN-<slug>.md
    done/<YYYY-MM-DD>-<slug>.md
  _agent/                # el contrato operativo del agente (ver P5) — opcional
    ROLES.md             # quién escribe qué (varios escritores solamente)
    LOCKS.md             # el mutex de reclamo de archivos (solo checkout compartido)
    prompts/autonomous.md  # cómo se comporta una ejecución desatendida (solo con una
                         #   puerta de verificación — P8 — Y una cola de planificación — P4a)
  federation.md          # solo multirepositorio (P11): puntero de retroceso de este repositorio
  federation-index.md    # solo multirepositorio (P11): índice de miembros — solo repositorio principal

Ubicación. El árbol anterior muestra la opción raíz. AGENTS.md y CLAUDE.md siempre se encuentran en la raíz del repositorio; adr/, plan/, _agent/, INDEX.md y CONVENTIONS.md van bajo la raíz del artefacto elegida en P12 (por defecto .docflow/, por ejemplo .docflow/adr/, .docflow/plan/).

Descubrimiento. Las herramientas localizan la raíz del artefacto sin leer primero CONVENTIONS.md: un directorio .docflow/ en la raíz del repositorio es la raíz; para cualquier otra raíz, bootstrap escribe un archivo .docflow en la raíz del repositorio — un puntero de una línea, root: <ruta> (por ejemplo root: docs/, root: .). Que no esté presente ninguno significa un repositorio precontrato (las herramientas buscan en docs/, luego en la raíz del repositorio, un CONVENTIONS.md que nombre una raíz del artefacto) o que no es un repositorio docflow.

_agent/ es el contrato operativo del agente — quién escribe qué, el único mutex real, y cómo se comporta una ejecución desatendida. No contiene nada que git ya registre: ningún registro de envío duplicado, ningún tablero de lo que está en curso, ninguna instantánea del estado actual, ninguna transferencia. Cuál de los tres archivos anteriores existe se deriva completamente de P5, P8 y P4a, y un repositorio sin ningún directorio _agent/ es un resultado válido.

Núcleo vs capas opcionales. Solo el núcleo se escribe siempre: AGENTS.md, CLAUDE.md, CONVENTIONS.md, adr/0000-template.md e INDEX.md. Un repositorio solo con estos es un repositorio docflow válido y ligero — un catálogo de ADR clásico con convenciones. Todo lo demás es una capa optativa: la cola plan/ (P4a), el contrato _agent/ (P5 + P8 + P4a — un escritor único sin una puerta de verificación y una cola de planificación no obtiene nada de ello), GLOSSARY.md y domains/ (P7). Omitir cualquier capa opcional es un estado válido, no un error; una habilidad del ciclo de vida que necesite una capa ausente se rechaza limpiamente y nombra lo que falta.

Para un producto multirepositorio (un producto repartido en varios repositorios — ver P11), aparecen dos archivos adicionales: federation.md, un pequeño puntero de retroceso que cada repositorio miembro lleva, y federation-index.md, la lista de miembros autorizada que solo vive en el repositorio principal/establecedor. Todos los artefactos de federación — federation.md, federation-index.md y el resumen derivado ROLLUP.md — se colocan bajo la raíz del artefacto configurada. Un repositorio independiente no tiene ninguno de ellos.

Paso 3 — Convenciones a instalar

1. Los ADRs son la fuente de verdad. Una decisión por ADR. Las divisiones se convierten en nuevos ADRs que reemplazan; nunca expandas el alcance dentro de uno existente.
2. Hasta dos formas de ADR, declaradas por campo. Un repositorio que distingue las dos registra la distinción en el campo de metadatos shape: de cada ADR (capability o technology; un campo ausente significa capacidad) — nunca en un rango de números. Cada ADR toma el siguiente número contiguo sea cual sea su forma, y cada forma tiene su propia plantilla, ambas numeradas 0000.
   • ADR de capacidad (lo que el sistema debe hacer). Orden de secciones: metadatos → Contexto → Declaración de capacidad → Historias de usuario / escenarios → Criterios de aceptación → Fuera del alcance → Preguntas abiertas → Referencias → Historial de revisiones → Aprobaciones.
   • ADR de tecnología (cómo se construye). Orden de secciones: metadatos → Contexto → Decisión → Justificación → Consecuencias → Criterios de aceptación → Fuera del alcance → Preguntas abiertas → Referencias → Historial de revisiones → Aprobaciones. La justificación debe nombrar las alternativas consideradas y dar razones de rechazo específicas (no "más simple" / "más idiomático").
3. Ciclo de vida de estado: Propuesto → Aceptado → Implementado → (Reemplazado | Obsoleto). Los estados terminales se pueden alcanzar desde cualquier estado anterior. El estado impulsa la ubicación en la carpeta de planificación: Aceptado → plan/todo/, Implementado → plan/done/.
4. Nombres de archivo: adr/NNNN-kebab-slug.md, acolchado con ceros a 4 dígitos, contiguo, sin espacios reservados. Las referencias cruzadas usan rutas relativas.
5. Los criterios de aceptación son comprobables y están numerados. Las pruebas se asignan a ellos cuando es práctico.
6. Disciplina de auditoría. Los cambios sustanciales de ADR agregan una fila en el Historial de revisiones. Los cambios editoriales (erratas, formato, correcciones de enlaces) se excluyen pero se marcan como editorial en el mensaje de commit. La tabla de Aprobaciones se completa cuando un ADR es Aceptado y se actualiza en cada revisión sustancial posterior.
7. INDEX.md se regenera a partir de los metadatos de ADR después de cualquier cambio de ADR. Trátalo como derivado, no editado a mano.
8. plan/ es la cola de trabajo. Cuando el trabajo se envía, git mv plan/todo/X plan/done/<fecha>-X, cualquier eliminación de estado del elemento de plan, avance de estado del ADR propietario y regeneración de INDEX.md se agrupan en el commit de finalización. Bajo integración directa a principal, ese commit se envía a la rama de integración y el pie de página del archivo movido nombra el SHA de HEAD (y el id del artefacto de despliegue si corresponde). Bajo integración por solicitud de extracción, esos cambios son el último commit en la rama de la solicitud de extracción antes de que se marque como lista, el pie de página nombra la solicitud de extracción y la fusión es el evento de finalización.
9. La coordinación es un contrato, no un registro. _agent/ contiene solo lo que git no puede decirte, y cada modo (P5) prescribe exactamente sus propios archivos — no se escribe nada más allí. En un checkout compartido, un agente agrega una fila a _agent/LOCKS.md (<id-agente> | <ruta> | <marca de tiempo ISO-8601>) antes de editar y la elimina al hacer commit; ese libro de contabilidad es el único mutex real, y un elemento de la cola se reclama sobre el propio elemento. En árboles de trabajo separados, un elemento de la cola se reclama empujando claim/<clave-elemento> — el nombre del archivo de la cola sin su extensión — más una solicitud de extracción borrador a partir de él cuando la integración se basa en solicitudes de extracción; el empuje es lo que excluye al segundo escritor y no se mantiene ningún libro de contabilidad. Bajo un escritor único no hay nada que serializar y nada que reclamar. Ningún modo mantiene estado de envío duplicado, un tablero de lo que está en curso o una instantánea del estado actual: el historial de git y plan/done/ son el registro, y las ramas activas y las solicitudes de extracción son lo que está en curso.
10. Contrato git. Commits convencionales. Pie de página obligatorio Rationale: en commits que toquen un ADR. Commits firmados a menos que el usuario opte por no hacerlo. Sin tráiler Co-Authored-By para trabajo de agente a menos que el usuario lo solicite.
11. AGENTS.md es el punto de entrada de reglas estrictas; CLAUDE.md es la línea única @AGENTS.md para agentes compatibles que lo lean.
12. Los ADRs son artefactos internos — nunca visibles para el usuario. Los números de ADR, los títulos de ADR y la existencia del catálogo de ADR NUNCA deben aparecer en rutas de código de producto que lleguen a un usuario: cadenas de UI, cuerpos de respuesta de API, mensajes de error, líneas de registro emitidas a clientes, documentación pública, notas de versión, copia de marketing o comunicaciones de soporte. Los ADRs son para constructores, no para usuarios. Las referencias SÍ están permitidas en: comentarios de código (`// ver a…

[truncado para la traducción]