Arnés agéntico

En esta página

Estados de interacción
1. Estado inactivo
2. Estado de flujo de trabajo
Ciclo de vida de la sesión
Clasificación de solicitudes
1. La regla de detección de solicitudes de funcionalidad
Flujos de trabajo de contenido
Procesamiento determinista y agéntico
Ejecución de BPMN: una habilidad, dos motores
Flujo de trabajo de solicitudes de funcionalidad (CRDM)
Contenido y fuentes proporcionados por el usuario
1. Para CRDM específicamente
Disciplina de issues y beans
1. Issues frente a beans
2. Reglas para los agentes
Referencias consolidadas de habilidades
Lo que aún no está construido

Esta página se genera a partir de content/docs/agentic-harness/ — cada sección a continuación enlaza a su propia fuente.

✎ Edit TR

El arnés agéntico es el modelo de interacción sobre el que se ejecuta folio-assistant: las reglas, estados y flujos de trabajo que rigen cómo colaboran un agente y un usuario dentro de esta plataforma. Gran parte de este comportamiento ya se describe a lo largo de habilidades individuales y documentos de orientación; esta página lo consolida en una sola referencia para que un agente que entra en una sesión pueda consultar el comportamiento esperado en lugar de reconstruirlo a partir de reglas dispersas.

Esto no trata sobre la arquitectura interna del agente. Trata sobre el contrato observable entre el agente y el usuario: en qué estados puede estar la interacción, cómo se clasifican las solicitudes, a qué flujo de trabajo ingresa el agente para cada clase y qué debe esperar el usuario en cada etapa.

Estados de interacción

✎ Edit TR

Una interacción usuario–agente se encuentra siempre exactamente en uno de dos estados:

Estado inactivo

El agente no tiene ningún flujo de trabajo activo. Está esperando una solicitud del usuario. Al recibir una, clasifica la solicitud (consulta Clasificación de solicitudes) y realiza una transición al estado de flujo de trabajo correspondiente.

Estado de flujo de trabajo

El agente está ejecutando un flujo de trabajo con nombre; cada uno representado por un diagrama de procesos BPMN con el agente y el usuario en carriles (swim lanes) independientes. El flujo de trabajo activo determina qué hace el agente a continuación y qué espera del usuario.

Flujos de trabajo activos en esta plataforma:

Flujo de trabajo	Origen BPMN	Se inicia cuando
Autoría (paper)	`authoring-a-paper.bpmn`	El usuario solicita autoría de contenido en un folio de paper
Autoría (document)	`authoring-a-document.bpmn`	El usuario solicita autoría de contenido en un folio de documento
Ciclo de vida de contenido	`content-lifecycle.bpmn`	El contenido avanza a través de validar → renderizar → publicar
Ingesta de documentos	`document-ingestion.bpmn`	El usuario deposita un archivo en `uploads/`
De borrador a publicación	`draft-to-publication.bpmn`	El contenido pasa de borrador a publicado
Requisitos CRDM	`crdm-requirements.bpmn`	El agente detecta una solicitud de funcionalidad (feature request)
Recuperación de evidencias	`evidence-retrieval.bpmn`	El agente busca evidencias para respaldar una afirmación

Transiciones de estado: un flujo de trabajo puede suspenderse cuando el usuario solicita cambiar de contexto. El agente registra dónde se encontraba (la actividad BPMN actual) y puede reanudarlo más tarde. Solo hay un flujo de trabajo activo a la vez, pero los flujos de trabajo suspendidos forman una pila: el más reciente se reanuda primero.

La regla clave: el agente siempre sabe en qué flujo de trabajo se encuentra. Si no lo sabe, está en estado inactivo, y la siguiente solicitud inicia un nuevo flujo de trabajo.

Ciclo de vida de la sesión

✎ Edit TR

Cada sesión de agente sigue el mismo ciclo de vida:

Inicio (Start) — ejecutar el barrido de inicio de sesión (beans prime, beans list, scripts/session-start-coord-sweep.sh). Esto saca a la luz el plan de trabajo actual, cuánto ha avanzado la rama por defecto y la actividad reciente en ramas hermanas. Consulta AGENTS.md § At session start.
Clasificación (Classify) — cada solicitud del usuario se clasifica (consulta la siguiente sección) y se enruta al flujo de trabajo correspondiente.
Ejecución (Execute) — el agente trabaja dentro del flujo de trabajo activo, siguiendo su proceso BPMN. En cada turno se informa del bean en el que se está trabajando y de qué viene a continuación.
Commit — cada unidad de trabajo significativa recibe su propio commit y push. Los PR se abren en el primer commit, no al final. Consulta AGENTS.md § Commit early, commit often, always PR.
Traspaso (Handoff) — cuando la sesión finaliza (el usuario se marcha, límite de contexto, agotamiento de tokens), el estado duradero del agente consiste en:
- Código con commit y push realizados
- Beans actualizados con estado y notas
- Comentarios en issues con resúmenes de lo que se ha logrado
- El chat es efímero; todo lo demás sobrevive

Clasificación de solicitudes

✎ Edit TR

Cada solicitud del usuario se clasifica en una de estas categorías. La clasificación determina a qué flujo de trabajo ingresa el agente.

Categoría	Descripción	Flujo de trabajo iniciado
Autoría de contenido	Escribir, editar, ampliar contenido del folio (capítulos, bloques, secciones)	Flujo de trabajo de autoría (paper o document)
Revisión de contenido	Revisar, validar, proporcionar comentarios sobre contenido existente	Ciclo de vida de contenido / flujo de trabajo de HCI de edición
Ingesta de contenido	Ingerir un documento fuente en el folio	Flujo de trabajo de ingesta de documentos
*Solicitud de funcionalidad (feature request)*	Solicitar una nueva capacidad de la plataforma (ver crdm-detect)	Flujo de trabajo de requisitos CRDM
Solicitud de información	Preguntar sobre la plataforma, el contenido o el proceso	Sin flujo de trabajo — responder directamente
Invocación de herramientas	Ejecutar una herramienta específica (`content_validate`, `qa_sweep`, etc.)	Sin flujo de trabajo — ejecutar e informar
Gestión del plan de trabajo	Crear, actualizar o consultar beans	Sin flujo de trabajo — ejecutar e informar
*Informe de error (bug report)*	Reportar un comportamiento anómalo en funcionalidades existentes	Triaje: corregir directamente si es pequeño, CRDM si requiere rediseño

La regla de detección de solicitudes de funcionalidad

El límite de clasificación crítico se sitúa entre la autoría de contenido y la solicitud de funcionalidad (feature request). La habilidad crdm-detect (skills/sdlc/crdm/crdm-detect.md) proporciona las señales detalladas de detección. La regla resumida:

Si implementar la solicitud requeriría cambios en folio-assistant (el repositorio de la plataforma) en lugar de en un repositorio de folio, la solicitud es una funcionalidad (feature), y el agente debe ingresar al flujo de trabajo CRDM.

En caso de duda, el agente pregunta: “Esto parece requerir un cambio en la plataforma; ¿es correcto, o es algo que puedo hacer dentro del modelo de contenido actual?”

Flujos de trabajo de contenido

✎ Edit TR

Cuando una solicitud se clasifica como trabajo de contenido (autoría, revisión, ingesta), el agente sigue el flujo de trabajo BPMN correspondiente. Las páginas de documentación existentes los describen en detalle:

Flujo de trabajo de publicación — el ciclo de vida del contenido desde el borrador hasta la validación, renderizado y publicación. Cubre los roles (autor, revisor, editor), los procesos base, las actividades y las habilidades.
Ingesta de documentos — cómo un archivo depositado se convierte en una fuente L1: extraer estructura, derivar contenido, construir el grafo de conocimiento L1, control de completitud (completeness gate).
Guías de redacción:

El arnés no redefine estos flujos de trabajo. Proporciona el punto de entrada — clasificar la solicitud y enrutar a la adecuada — y el punto de salida — regresar al estado inactivo cuando el flujo de trabajo se completa, o suspenderlo si el usuario cambia de contexto.

Procesamiento determinista y agéntico

✎ Edit QA TR

El procesamiento de flujos de trabajo aquí es un espectro, no un interruptor, y el arnés ya se encuentra en cuatro puntos diferentes de él sin haber nombrado nunca el eje: cat-harness.processes:policy enforcement decide si un paso que no está habilitado se rechaza o simplemente se anota; relaxable="false" decide si un paquete puede negociar la eliminación de un paso base; cat-harness.processes:decision decide si una bifurcación se calcula a partir de una tabla en lugar de elegirse; y el control de límite de commit (commit-boundary gate) rechaza la escritura realizada por algo que no sea el agente.

Esos no son un solo eje, y tratarlos como tal es el primer error que se comete. Se están combinando al menos tres preguntas: quién decide la bifurcación, qué sucede si la decisión es incorrecta y quién la hace cumplir. Un paso puede ser totalmente agéntico en la primera y totalmente determinista en la tercera: el límite de commit es exactamente eso, un agente que decide libremente y un hook que rechaza la escritura independientemente.

Una compuerta (gateway) ahora indica cuál es. <cat-harness.processes:decision> significa que una tabla lo calcula y se rechaza un resultado proporcionado manualmente; <cat-harness.processes:judgement reason="…"> significa el criterio de alguien, exigiéndose el motivo. Antes de ese marcador, “no hay tabla porque esto es un juicio subjetivo” y “no hay tabla porque nadie escribió una” eran indistinguibles; y bun run cat check:workflow-refs ahora imprime la división tripartita, de modo que la pregunta ¿cuánto de esto lo decide un modelo? tiene una respuesta que se cuenta en lugar de meramente afirmarse.

El propósito de ese recuento es la investigación, y está abierto. Qué puntos de criterio son riesgos de seguridad, cuánto debe ser determinista y cómo se comparan los modelos a lo largo de subflujos de trabajo bajo una superposición controlada de contexto y recuerdos son tres preguntas que este repositorio ahora puede plantear y aún no ha respondido. La agenda, con cada afirmación marcada como medida, decidida o hipótesis, es deterministic-and-agentic. Léela como una agenda: contiene más hipótesis que mediciones, y así lo declara.

Ejecución de BPMN: una habilidad, dos motores

✎ Edit QA TR

El responsable (owner), 2026-09-23, nombrando la habilidad sobre la que trata este espectro:

Habilidad de ejecución de BPMN: dados un Proceso, Contexto, Estado y Rol, utilizar una o más Habilidades para ejecutar una Tarea.

Una habilidad, dos tipos de Herramienta. La habilidad es la misma en ambos extremos: tomar el proceso, el contexto, el estado actual y el rol, elegir las habilidades y realizar la tarea. Lo que cambia es la Herramienta (Tool) que la ejecuta, y una Herramienta es intercambiable detrás de una habilidad del mismo modo que cualquier otra Herramienta aquí.

	extremo determinista	extremo agéntico
Herramienta	cualquier motor BPMN 2.0 de código abierto	un enjambre agéntico
Alcance de un agente	una tarea a la vez, asignada por el motor	la mayoría o todas las tareas
Estado	mantenido por el motor, estrictamente	no gobernado: el enjambre lo mantiene
*Carriles (swimlanes)*	aplicados: solo el rol del carril puede ejecutar su tarea	relajados: un agente puede actuar a través de carriles
Qué garantiza la honestidad	el motor rechaza un paso antes de que ocurra	informes de QA/QC mecánicos + agénticos lo detectan después de que haya ocurrido

Los dos extremos difieren en cuándo se comprueba una regla, no en cuál regla. El mismo proceso, los mismos roles y los mismos permisos rigen ambos. El motor los comprueba antes de que comience una tarea y la rechaza; el enjambre actúa y un informe de QA/QC los comprueba después, a partir del registro de lo realizado. Eso solo funciona si las reglas y el registro son datos legibles por un informe, lo cual se cumple en W3C ODRL 2.2 como lenguaje de permisos y W3C PROV-O como registro de ejecución (responsable, 2026-09-23; el esquema que esto implica es la propuesta de actores, ODRL y PROV-O).

La mayoría de las ejecuciones reales se sitúan entre ambos extremos, y por tarea más que por proceso: la sección anterior ya contabiliza qué compuertas se calculan y cuáles son decisiones de criterio. Un paso de firma puede ser aplicado por el motor dentro de una ejecución por lo demás agéntica, y esa es una propiedad de la tarea, no de todo el diagrama.

Parcialmente construido. No hay ningún motor BPMN conectado aún. El informe mecánico de QA/QC ya existe: bun run cat prov:qaqc escribe el historial de cada instancia de flujo de trabajo como un registro PROV-O y vuelve a comprobar cada paso contra las directivas ODRL, de carácter consultivo (issue #1180, paso 5; la habilidad task-authorization). El informe agéntico de QA/QC aún no existe. El resto de esta sección describe el objetivo para que la propuesta tenga algo con qué contrastarse.

Flujo de trabajo de solicitudes de funcionalidad (CRDM)

✎ Edit TR

Cuando una solicitud se clasifica como solicitud de funcionalidad (feature request), el agente ingresa al flujo de trabajo de requisitos CRDM (documentación completa, BPMN).

El flujo de trabajo de solicitudes de funcionalidad es donde este documento de arnés aporta el mayor valor, porque describe un comportamiento que antes era implícito. Los flujos de trabajo de autoría y revisión han estado documentados durante meses; el flujo de trabajo de requisitos existía únicamente como conversación ad-hoc.

Cómo ingresa el agente a CRDM

La lógica de detección se encuentra en skills/sdlc/crdm/crdm-detect.md. Tres escenarios:

Nueva sesión, la primera solicitud es una funcionalidad: → Reconocer la solicitud, explicar que primero ayudarás a definir los requisitos, ingresar a la Fase 1.

Sesión existente, ya en CRDM: → Incorporar la nueva solicitud en el documento de requisitos actual, continuar.

Sesión existente, realizando trabajo de contenido: → Sintetizar la necesidad de funcionalidad, preguntar al usuario si desea pausar el trabajo de contenido y abordarla ahora o registrarla en un bean para más adelante.

Lo que ve el usuario

El agente no dice “entrando en modo CRDM” ni utiliza jerga metodológica. En su lugar:

“Esto parece un cambio en la plataforma: algo que tendríamos que añadir al propio folio-assistant. Antes de construir nada, déjame ayudarte a definir con exactitud lo que se necesita para que lo hagamos bien. Documentaré los requisitos en el issue para que otros puedan opinar.”

Cómo sale el agente de CRDM

El flujo de trabajo CRDM finaliza cuando:

Todos los beans de los requisitos aprobados se han resuelto, O
El usuario pospone explícitamente el trabajo restante

Al salir, si se había suspendido un flujo de trabajo de contenido, el agente lo reanuda.

Contenido y fuentes proporcionados por el usuario

✎ Edit TR

Los usuarios proporcionan contenido y material fuente a través de múltiples canales. El agente debe aceptar todos ellos y enrutarlos a la canalización (pipeline) correspondiente:

Canal	Ejemplo	Enrutado a
Directorio `uploads/`	El usuario deposita un documento de Word, PDF, archivo de Excel	Canalización de ingesta de documentos
Referencias en `library/`	El usuario hace referencia a una fuente L1 ya ingerida	Citación directa en el contenido
Ediciones en `content/`	El usuario edita directamente un bloque `.md`	Flujo de trabajo de autoría de contenido
Adjuntos en issues de GitHub	El usuario adjunta un archivo a un comentario de un issue	El agente lo descarga y procesa
Subida en el chat	El usuario sube un archivo en la interfaz de chat del LLM	El agente lo guarda en `uploads/` o lo procesa en línea
Referencia por URL	El usuario pega un enlace a un documento	El agente lo descarga e ingiere si corresponde

Para CRDM específicamente

Durante la recopilación de requisitos, el contenido proporcionado por el usuario es información de entrada para los requisitos, no contenido para redactar. El agente debe:

Leer y comprender el material facilitado
Extraer información relevante para los requisitos
Sintetizarla en la declaración de necesidades o en el documento de requisitos
Hacer referencia a la fuente en el comentario del issue (con enlace o archivo adjunto)

Ejemplo: un usuario sube una hoja de cálculo de Excel con comentarios de una consulta pública. El agente no intenta ingerirla como contenido de folio; lee los elementos de retroalimentación y los sintetiza en requisitos para la herramienta de triaje de revisiones.

Disciplina de issues y beans

✎ Edit TR

El trabajo de funcionalidades debe vincularse a un issue de GitHub. El trabajo de contenido utiliza beans. Los dos están relacionados pero no son sinónimos.

Issues frente a beans

	Issue de GitHub	Bean
Alcance	Una funcionalidad, conjunto de requisitos o historia de usuario	Una única unidad de trabajo del tamaño de un PR
Audiencia	Partes interesadas (stakeholders), solicitante, BA	Agente, desarrollador
Ciclo de vida	Open → requirements → sign-off → implementation → close	Created → in-progress → resolved
Relación	Un issue tiene muchos beans	Cada bean hace referencia a su issue principal

Reglas para los agentes

Trabajo de funcionalidad → issue primero. Antes de implementar, comprueba:
- ¿Existe un issue abierto existente? Busca por palabras clave.
- Si no hay coincidencias abiertas, revisa los issues cerrados recientemente.
- Si no hay coincidencia en absoluto, pide al usuario que cree uno. No crees un issue sin el permiso del usuario.
Siempre rama de funcionalidad + PR. Sin excepciones para el trabajo de funcionalidad. El nombre de la rama debe hacer referencia al número de issue (por ejemplo, feat/197-word-import).
Preguntar siempre antes de fusionar en main. El usuario debe confirmar explícitamente. Esto es más estricto que la regla general de AGENTS.md para el trabajo de contenido, porque los cambios de funcionalidad afectan a la plataforma.
Publicar resúmenes de ronda en el issue. Tras cada ronda de implementación (uno o más beans resueltos), publica un comentario en el issue vinculado que contenga:
- Lo que se logró en esta ronda
- Lo que queda por realizar (beans abiertos)
- Enlaces al contenido actualizado para revisión (URLs de staging, páginas de documentación)
- Tabla comparativa de antes/después para las páginas modificadas
Nunca cerrar un issue sin autorización explícita. El BA o la parte interesada lo cierra. El agente lo cierra únicamente cuando el BA lo indique explícitamente. Un agente nunca debe asumir la finalización.
Los requisitos pueden abarcar múltiples issues. El agente debe enlazar a todos los issues pertinentes y señalar las relaciones.
Los beans no son issues. beans create es para elementos del plan de trabajo. Los issues son para requisitos orientados a las partes interesadas. No los confundas.

Referencias consolidadas de habilidades

✎ Edit TR

El comportamiento descrito en esta página proviene de habilidades y documentos de orientación dispersos por el repositorio. Esta sección mapea el comportamiento consolidado con sus fuentes autorizadas.

Comportamiento	Habilidad / documento de origen	Ubicación
Barrido de inicio de sesión	`AGENTS.md § At session start`	`AGENTS.md`
Protocolo de beans	`todo-manager.md`, `bean-coordination.md`	`skills/folio-core/`
Disciplina de commits y PR	`AGENTS.md § Commit early, commit often`	`AGENTS.md`
Detección de solicitudes de funcionalidad	`crdm-detect.md`	`skills/sdlc/crdm/crdm-detect.md`
Flujo de trabajo de requisitos CRDM	`crdm-requirements-workflow.md`	`skills/sdlc/crdm/crdm-requirements-workflow.md`
Autoría de contenido (paper)	habilidades authoring-math	`skill_list` → `authoring-math`
Autoría de contenido (document)	habilidades folio-document-adapter	`skill_list` → `folio-document-adapter`
Ciclo de vida de contenido	habilidades content-lifecycle	`skills/authoring/content-lifecycle/`
Ingesta de documentos	`docs-generation.md`	`skills/ui/ui-core/docs-generation.md`
Despacho y coordinación	`dispatch-agent.md`, `coordinate.md`	`skills/folio-core/`
Tipos de contenido y adaptadores	`AGENTS.md § Content types`	`AGENTS.md`
Autoría de diagramas BPMN	habilidad `bpmn-authoring`	`skills/folio-core/`

Cuando una habilidad y esta página discrepen, la habilidad prevalece. Esta página es una consolidación, no una nueva autoridad. Si encuentras una discrepancia, corrige esta página.

Lo que aún no está construido

✎ Edit TR

Persistencia del estado del flujo de trabajo — el arnés describe la suspensión y reanudación de los flujos de trabajo, pero no existe ningún mecanismo para persistir el estado del flujo de trabajo del agente entre sesiones. Hoy en día esto se apoya en beans y comentarios de issues como intermediarios (proxies).
Clasificación automatizada de solicitudes — la tabla de clasificación es una referencia para que los agentes la consulten; no existe una herramienta clasificadora que enrute automáticamente.
BPMN para el ciclo de vida de los beans — el plan de trabajo de beans tiene un ciclo de vida (create → claim → in-progress → resolve) que se analiza en AGENTS.md y en la habilidad todo-manager, pero no cuenta con un diagrama BPMN.
BPMN para el propio arnés agéntico — aún no se ha creado un diagrama BPMN de nivel superior que muestre la máquina de estados inactivo/flujo de trabajo y el enrutamiento de clasificación.
Protocolo de traspaso de sesión — las reglas sobre qué comitear antes de que termine una sesión están en AGENTS.md, pero no existe un artefacto de traspaso estructurado que una nueva sesión pueda leer para reanudar el trabajo exactamente donde lo dejó la anterior.

Seguimiento en: #203