Flujo de Trabajo

1. Propósito y alcance

Esta sección define cómo fluye una tarjeta desde que se plantea una necesidad hasta que el trabajo llega a producción y se cierra. Documenta los dos pipelines, la tipología de columnas, el punto de inserción de cada agente y los tres modos de arranque (app nueva, feature en app existente, customización de app adoptada).

Delimitación: el detalle de cada agente está en la sección 04; la doctrina humano–agente en la 03; los campos y automatizaciones de las columnas en la 07; las capas de conocimiento y el status.md en la 06.

Lo que no cambia. El flujo conserva las reglas críticas del modelo vigente: ningún deploy manual; ningún cambio directo en producción; todo desarrollo vía tarjeta; ningún PR llega a producción sin la autorización del Lead; nada llega a producción sin pasar por Staging. Los agentes se insertan dentro de estas reglas; ninguna decisión de aprobación se transfiere a un agente.

2. El flujo en dos pipelines

La secuencia lógica de trabajo es una sola. Se implementa como dos tablas de SeaTable —dos pipelines— porque separa territorios de responsabilidad y acota las columnas que cada tarjeta necesita: una secuencia única, recorrida por una sola persona, no necesita esta división; con más fases y más personas, sí.

• Pipeline A · Definición — territorio del Director y el Lead. Aquí se decide qué se construye y cómo a nivel técnico. Termina con el Plan cerrado.
• Pipeline B · Ejecución — territorio del Lead y los Developers. Aquí se construye, revisa, prueba y publica. El Developer no ve el churn de planeación; solo trabajo accionable.

Las dos tablas se unen por el campo Plan URL: la tarjeta de definición (Pipeline A) y la tarjeta de ejecución (Pipeline B) son dos tarjetas distintas —los rows de SeaTable no cruzan de una tabla a otra— vinculadas por ese campo. Esto no es una limitación sino una ventaja: cada tabla lleva solo las columnas de su tramo, y la tarjeta deja de ser inmanejablemente larga.

La frontera A→B es el Ready gate: una tarjeta cruza a Ejecución cuando sus criterios de aceptación (Capa 1) están congelados y el Plan está completo. ③ Spec Writer crea la tarjeta de ejecución en Queue al cerrar el Tech Spec.

3. La tipología de columnas

No todas las columnas hacen lo mismo. Cada una es de uno de tres tipos, y el tipo determina qué la mueve:

Tipo	Qué hace	Columnas
Trigger	Al entrar una tarjeta, dispara trabajo (una sesión de agente o de dev)	Product Architect, Design, Build
Intake	Recibe tarjetas y espera triage humano; nada las mueve automáticamente	Backlog, Queue, Ops Health
Waiting / terminal	No dispara nada; espera una acción humana o es un estado final	Tech Specs, In Review, Staging Validation, Published, Done, Discarded

Regla dura — una columna sin lector automático no es un estado, es una nota. Si una columna existe, algo (un agente, un job, una automatización) debe consumirla; si solo un humano la nota, no merece ser columna y su información vive en un campo o en el status.md. Esta regla gobierna qué columnas existen y evita que el board se llene de estados decorativos.

Consecuencia de diseño: los agentes de las columnas trigger no avanzan su propia tarjeta. El Product Architect escribe el Requirement pero no se autopromueve; la aprobación es el humano moviendo la tarjeta. Los agentes preparan; el humano decide (doctrina, 03 §3).

4. Pipeline A · Definición

Backlog (intake)

La tarjeta entra aquí. ① Idea Enricher la crea a partir de una solicitud planteada en el chat del sitio de documentación: hace preguntas base, redacta el problema y el pain point (marcando Pain point (inferido) si lo dedujo), y asigna un primer puntaje de impacto/facilidad. El Director valida la necesidad estratégica y prioriza — nada mueve una tarjeta fuera del Backlog salvo su juicio.

Product Architect (trigger)

Al mover la tarjeta aquí, ② Product Architect escribe el Requirement: qué se construye, por qué, y los criterios de experiencia verificables. ④ Independent Reviewer lo revisa. El Director aprueba el Requirement y decide el siguiente paso: a Design si la tarjeta necesita trabajo visual, o directo a Tech Specs si no.

Design (trigger · atendida · opcional)

No todas las tarjetas la cruzan. Es una fase atendida: el humano usa una herramienta de IA (conector claude.ai/design) de forma interactiva —ve el trabajo en tiempo real, da feedback, afina y completa—, no un agente que entrega un borrador para revisar después. Produce el diseño con su sistema de tokens, anclado en el design system existente, sincronizado a docs/internal/design/<módulo>/ (indexado, sin archivos sueltos). ④ lo revisa. El humano aprueba moviendo la tarjeta; Design no se autopromueve.

Tech Specs (waiting)

③ Spec Writer completa el Plan con el Tech Spec: arquitectura, integraciones, decisiones, y —obligatorios— los vacíos de cobertura y las preguntas abiertas. Lee la Capa B de la app. Al cerrar, tres actos: congela la Capa 1 (criterios de aceptación), crea la rama de la tarjeta (territorio del Lead, que gobierna la frontera de ejecución) y crea la tarjeta de ejecución en Queue con el Plan URL que las vincula. El Lead aprueba el Tech Spec. Cruzar de aquí a Queue es el Ready gate.

5. Pipeline B · Ejecución

Queue (intake)

La tarjeta de ejecución espera a ser tomada. Lleva solo las columnas de ejecución (branch, PRs, deploy, QA), no las de planeación — esas viven en la tarjeta de definición, enlazada por Plan URL.

Ops Health (intake · carril de prioridad)

No es un paso de la secuencia: es un carril por el que hallazgos e incidentes —archivados por ⑨ Ops-Health Monitor en su barrido nocturno, o levantados por cualquier fase— saltan la cola directo a Build, por encima del Queue ordinario. Reconcilia la columna Troubleshooting vigente. Ninguna tarjeta de Ops Health cierra sin captura retroactiva de contexto (qué falló, causa raíz, qué cambió), asistida por ⑥ (antipatrón A7).

Build (trigger)

El Developer construye. Abre la sesión con /start (⑥), que lee el status.md de la app y el Plan de la tarjeta y verifica contra el sistema vivo — el Developer recibe las dos capas de contexto: el qué construir (del Plan) y el dónde está el sistema ahora (del status.md). Construye sobre la rama de la tarjeta. Corre ⑤ QA Runner sobre su propio trabajo (QA primario). Cierra con /wrap-up (⑥), que verifica commits, hace push, abre el PR hacia staging, actualiza el status.md, emite el prompt de arranque de la siguiente tarjeta y registra la nota de sesión. El wrap-up es requisito para mover la tarjeta.

Trabajo iniciado a mano. No todo llega por el poll: una sesión puede empezar porque el Lead entrega directamente una tarjeta (“arregla estas tres”). Ese arranque reclama el carril de la tarjeta (la marca como tomada) para que un disparo automático no la trabaje en paralelo mientras una sesión ya está en ella. Build es columna trigger, así que una tarjeta ahí sin reclamar es terreno libre para el siguiente disparo.

In Review (waiting)

④ Independent Reviewer revisa el deploy preview (los enlaces por app) o el diff de la rama — sin mergear para ver o probar. El PR ya está abierto (Build lo abrió en el handoff, para que el preview y el CI corran durante la revisión). Recibe solo el artefacto, sin la intención del autor; emite veredicto BLOQUEANTE / NO-BLOQUEANTE / LIMPIO. Los arreglos son commits en la misma rama que actualizan ese mismo PR — una rama, un PR por tarjeta. El loop revisa → si bloquea, la fase autora corrige → revisa de nuevo, con tope. El Lead aprueba o pide cambios (devuelve a Build; hay loop Build↔In Review).

Staging Validation (waiting · parking lot)

Sala de espera para trabajo ya mergeado a staging, aguardando la promoción en lote a producción. El Lead valida y autoriza — no re-revisa línea por línea. La revisión detallada ya la absorbió ④ en In Review; aquí el Lead aporta el juicio que un agente no puede: coherencia arquitectónica, seguridad, ¿era esto lo pedido? La meta de diseño es que para Staging el Lead no encuentre defectos mecánicos — si los encuentra, es señal de que la revisión previa falló, y eso es un incidente del sistema, no la operación normal. El Lead autoriza la publicación (decisión humana, no inferida de una columna).

Published (waiting)

Tras la autorización, ⑦ Publisher encadena en un solo acto operado por el Lead: pre-vuelo (qué en el rango nunca se ejecutó realmente) → merge a main → cierre pesado de release (valida que cada claim de deploy sea cierto ahora, notas de versión, PRs de actualización a la Base, regeneración de la vista técnica) → la tarjeta llega a Published. Aparte, un clic en el campo User Guide dispara ⑧ User Guide & Comms (guía de usuario, guion, novedades). Nunca se conecta un disparo automático a Published — re-promovería trabajo ya enviado.

Done (terminal)

⑨ Ops-Health Monitor mueve la tarjeta a Done cuando se cumplen las dos condiciones: el first-fire (la primera ejecución real en producción) corre limpio ✚ la documentación está completa. No se llega a Done sin docs completos — la completitud de la doc es compuerta estructural, no un paso posterior. Published ≠ Done: en una promoción fuera de horario de mercado, el first-fire puede tardar días; colapsar los dos estados cerraría tarjetas sin probar o dejaría trabajo promovido leyéndose como no promovido.

Discarded (terminal)

Solo para tarjetas de feature o idea; un Bug nunca se descarta — se resuelve o permanece.

6. Los tres modos de arranque

El flujo es el mismo; cambia cómo entra el trabajo según el tipo de tarea.

6.1 Feature en app existente (el caso central)

El flujo corre completo y sin fricción, porque la app ya tiene repo, Capa B y status.md. Es el caso para el que el modelo fue diseñado: solicitud → Backlog → Definición (Requirement → ¿Design? → Tech Spec) → Ready gate → Ejecución (Build → In Review → Staging → Published → Done).

6.2 App nueva

Una app nueva no tiene repo, y el principio de lanzamiento estrecho exige que sin repo no haya documentación ni agentes. Por eso hay un paso 0 de bootstrap, previo al Pipeline A, ejecutado por el Director:

1. El Director crea el row en la tabla Applications de SeaTable (nombre, portal, etc.).
2. Pulsa el botón Create Repo de esa misma fila, que crea el repo con el andamiaje docs/{public,internal,agent} y plans/, su _meta.yml, los dos workflows, y agrega la entrada del repo al sources.yml del sitio central.
3. A partir de ahí, la definición (Requirement, luego Tech Spec) tiene dónde vivir, y el flujo continúa por el Pipeline A.

El andamiaje se dispara desde SeaTable, no desde un comando de Claude Code: registrar la app y crear su repo son un solo acto, en la superficie donde el Director ya trabaja. No es un agente del roster: es automatización de infraestructura sobre la tabla Applications.

6.3 Customización de app adoptada

Para una app que se adopta y adapta —una herramienta de terceros que se parametriza (el caso del propio piloto sobre Docusaurus/Starlight)—, el pipeline y sus compuertas son idénticos, pero la naturaleza del trabajo cambia:

• Build es configuración, no desarrollo desde cero: parametrizar, aplicar la identidad visual, cablear integraciones. El código base no es propio.
• Design suele aplicar — la customización visual es su terreno.
• La revisión (④) juzga configuración y tokens de tema, no lógica de negocio; puede requerir criterios distintos a los de una app construida.
• El verification criteria prueba lo visual y funcional (que el tema se aplica, que la navegación funciona), no lógica.
• La Capa B documenta cómo se parametrizó la app, no cómo funciona la herramienta por dentro.

7. Los tres cambios deliberados respecto al flujo vigente

1. El verification criteria (antes plan de pruebas) se adelanta a la definición. Los criterios de aceptación (Capa 1) los redacta ③ Spec Writer en el Pipeline A y se congelan en el Ready gate, antes de construir. El Lead pasa de redactor a revisor/aprobador. El mapa de ejecución (Capa 2) se completa contra lo construido en In Review (⑤). (Detalle: 04.)
2. La columna Pending Documentation se elimina. La actualización de documentación deja de ser una fase posterior y pasa a ser condición de Done, ejecutada por ⑦ y ⑧. La doc completa es compuerta, no backlog.
3. El wrap-up es requisito para mover una tarjeta de columna. Formaliza prácticas antes discrecionales (vínculo del PR, registro de variables y cambios de modelo de datos, actualización del status.md).

8. Trabajo fuera del flujo (Troubleshooting y hotfix)

El proceso de debugging vigente (rama de hotfix desde main, corrección mínima, PR acelerado, sincronización de staging, post-mortem) no se modifica. Se agrega una regla: ninguna tarjeta de Ops Health cierra sin captura retroactiva de contexto (qué falló, causa raíz, qué cambió), asistida por ⑥. Los incidentes son el conocimiento de mayor valor futuro y el que con más frecuencia se pierde (antipatrón A7).

9. Relación con el resto de la documentación

Para conocer	Sección
El detalle de cada agente insertado en el flujo	04
Quién decide qué en cada columna (doctrina de roles)	03
Los campos, automatizaciones y timestamps de cada columna	07
Las capas de conocimiento, el status.md y las convenciones de rama	06 · 09
Las reglas de decisión (enmiendas, autorizaciones, rituales)	08

---

Historial de versiones

Versión	Fecha	Cambio
v1.1	2026-09-03	Corrección de coherencia con la reunión del 2026-09-03: el paso 0 de bootstrap de una app nueva se dispara con el botón Create Repo de la tabla Applications, no con un comando de Claude Code (§6.2).
v1.0	2026-09-01	Versión inicial a nivel de consulta 1A. Reescribe el Anexo A del T0 (6 fases, 11 agentes) como dos pipelines (Definición / Ejecución) con 10 agentes. Tipología de tres tipos de columna (trigger/intake/waiting-terminal) y regla “una columna sin lector no es un estado”. Dos tarjetas unidas por Plan URL. Design como fase atendida con IA en vivo. Ops Health como carril de prioridad. Published ≠ Done con doble condición. Lead valida/autoriza en Staging sin re-revisar. Mecánica una rama/un PR, PR abierto en In Review, Staging como parking lot. Tres modos de arranque (app nueva con /new-app, feature existente, customización adoptada). Tres cambios deliberados y trabajo fuera del flujo. Front-matter YAML; destino docs/internal/.