cibseven-devflows

Ejecuta tus flujos de trabajo de desarrollo como procesos BPMN en un motor CIB seven local, y condúcelos desde agentes de codificación de IA como Claude Code a través de un servidor MCP.

La versión 0.1.0 incluye un flujo de trabajo: el ritual de release de un repositorio. Ejecuta los controles de calidad, pregunta a un humano, crea la etiqueta, publica. Este repositorio produjo su propio v0.1.0 ejecutando ese proceso sobre sí mismo.

Por qué

Hacer un release es un proceso con una decisión humana en medio. Normalmente ese proceso vive en la cabeza de alguien y en el scrollback de una terminal. Nada registra que los controles se ejecutaron, que una persona lo aprobó o qué se publicó.

Un motor de procesos es exactamente la herramienta adecuada para ese tipo de problemas. CIB seven conserva el estado, conserva el historial y sabe esperar a un humano. Tu máquina sigue haciendo el trabajo, y un agente de IA puede iniciar una ejecución y observarla, pero no puede saltarse la aprobación, porque la aprobación es un paso del proceso, no una promesa en un prompt.

Related MCP server: jt-mcp-server

Arquitectura

flowchart LR
    agent["Claude Code<br/>(any MCP client)"] -- stdio --> mcpserver["devflows-mcp"]
    mcpserver -- REST --> engine["CIB seven engine<br/>Docker, H2, localhost:8080"]
    human["You, in the web UI"] -- approve --> engine
    engine -- fetchAndLock --> worker["devflows-worker"]
    worker -- shell --> repo["your repository<br/>pytest, ruff, git, gh"]

El motor nunca ejecuta un comando de shell y nunca toca tu repositorio. Reparte trabajo; el worker de tu máquina lo consulta y lo hace. Ese es el patrón estándar de Camunda 7 external task, y es lo que hace seguro dejar que un proceso maneje una máquina de desarrollo.

El proceso de release

flowchart LR
    start((start)) --> gates["Run gates<br/><i>devflows.gates</i>"]
    gates --> q1{Gates passed?}
    q1 -- no --> failed((Gates failed))
    q1 -- yes --> approve["Approve release<br/><i>user task</i>"]
    approve --> q2{Approved?}
    q2 -- stop --> rejected((Release rejected))
    q2 -- ship --> tag["Tag<br/><i>devflows.tag</i>"]
    tag --> publish["Publish<br/><i>devflows.publish</i>"]
    publish --> released((Released))

Los tres rectángulos con un nombre son external tasks. «Approve release» es una user task de BPMN, por lo que espera, sobrevive a un reinicio del motor y puede responderse en la interfaz web o mediante el approve_gate MCP tool.

dry_run=true ejecuta los controles de verdad y no cambia nada más: ni etiqueta, ni push, ni release.

Inicio rápido

docker compose -f engine/docker-compose.yml up -d

uv sync

uv run pytest -m "not integration" && uv run ruff check .

Despliega el proceso (una vez por motor):

curl -s -X POST http://localhost:8080/engine-rest/deployment/create -F "deployment-name=cibseven-devflows" -F "release.bpmn=@processes/release.bpmn"

Inicia el worker y déjalo corriendo en su propia terminal:

uv run devflows-worker

Inicia un release en seco de este repositorio. Sustituye repo_path por la ruta absoluta de este repositorio. Usa barras normales incluso en Windows (C:/Users/tu/repos/cibseven-devflows): funcionan y te evitan luchar contra tu shell por el escapado de las contrabarras.

curl -s -X POST http://localhost:8080/engine-rest/process-definition/key/devflows-release/start -H "Content-Type: application/json" -d '{"variables":{"repo_path":{"value":"ABSOLUTE/PATH/TO/cibseven-devflows","type":"String"},"version":{"value":"0.2.0","type":"String"},"dry_run":{"value":true,"type":"Boolean"}}}'

Después afrobaríntalo en http://localhost:8080/webapp/#/seven/auth/tasks con demo / demo: filtra por My Group Tasks, toma Approve release, marca approve y envía.

En la práctica inicias las ejecuciones a través del servidor MCP en lugar de con curl. Consulta docs/DEMO.md para ver el recorrido completo.

devflows.yaml

Cada repositorio describe su propio release en un devflows.yaml en su raíz:

gates:
  - name: tests
    run: uv run pytest -q
  - name: lint
    run: uv run ruff check .

tag:
  format: "v{version}"

publish:
  run: gh release create v{version} --generate-notes

Las claves de nivel superior desconocidas se ignoran, así que una versión más reciente de devflows puede agregar pasos sin romper un archivo antiguo.

Las herramientas MCP

devflows-mcp habla MCP sobre stdio y funciona desde cualquier cliente MCP.

Cada herramienta devuelve un diccionario con una bandera ok, y una cadena error cuando ok es false. Ninguna herramienta lanza excepciones, porque el llamador es un modelo de lenguaje que debe explicar el fallo a una persona.

Usarlo desde Claude Code

El directorio plugin/ es un plugin de Claude Code alrededor del mismo servidor:

• plugin/.mcp.json inicia devflows-mcp con uv run.

• plugin/skills/release-with-devflows/SKILL.md le dice al agente cuándo usar el motor y en qué orden llamar a las herramientas, incluye la regla de que debe detenerse y preguntar antes de aprobar.

• plugin/commands/release.md proporciona el comando /devflows:release <version> [--real].

Para conectar el servidor a cualquier otro cliente de MCP directamente:

{
  "mcpServers": {
    "cibseven-devflows": {
      "command": "uv",
      "args": ["run", "devflows-mcp"]
    }
  }
}

Configuración

Seguridad

Dos cosas sobre este proyecto son deliberadas, y ambas asumen que se ejecuta en tu propia máquina:

• El motor no tiene autenticación. La API REST en localhost:8080 acepta cualquier cosa que pueda alcanzarla. No expongas ese puerto a una red que no controles.

• El worker ejecuta comandos de shell. Provienen del devflows.yaml del repositorio del que le pides un release, se ejecutan como tú, en ese repositorio, y son los mismos comandos que escribirías tú. Apunta solo a repositorios de confianza.

No hay servicio en la nube, ni telemetría, ni ninguna cuenta más allá de las credenciales de GitHub que gh ya posee.

Estructura del repositorio

Requisitos

• Docker Desktop para el motor.

• Python 3.12 y uv.

• git y gh autentificado, para los pasos de tag y push.

• Camunda Modeler 5. (opcional, si quieres editar el diagrama BPMN). Abre processes/release.bpmn como diagrama de Camunda 7.

Licencia

Apache License 2.0. Consulta LICENSE.