ClawHub

Macro Pipeline

Workflows

Create and manage macro-task pipelines (QA, roadmaps, feature rollouts) using PIPELINE.md + HEARTBEAT.md pattern. Use when building multi-step project plans that agents execute autonomously via cron.

Install

openclaw skills install macro-pipeline

Macro Pipeline Skill v3

Architecture

Two files, two locations:

FileLocationPurposeMutable?
PIPELINE.mdProject repo (~/Documents/proyectos/<project>/)State + progress✅ Yes (subagents update directly)
HEARTBEAT.mdAgent workspace (~/.openclaw/workspace-<agent>/)Instructions (read-only)❌ No (locked with chflags uchg)

Why PIPELINE in the repo?

  • Subagents work in the repo → can update status without cross-path issues
  • Git-trackable (commits show when steps completed)
  • Eliminates zombie steps from path access failures

Why HEARTBEAT in workspace?

  • Operational instructions for the OpenClaw agent
  • Should not contaminate project code
  • Locked to prevent agents from overwriting their own instructions

PIPELINE.md Format

# PIPELINE — <Project Name>: <Pipeline Title>
# Proyecto: ~/Documents/proyectos/<project>
# Objetivo: <one-line goal>
# Creado: YYYY-MM-DD

## Step 1: <Title> [PENDING]
- engine: claude-code
- description: <what to do>
- files: <key files to touch>
- verify: <command that proves step is done>
- artifacts: <outputs for next steps>

## Step 2: <Title> [PENDING]
- engine: claude-code
- depends_on: [1]
- description: <what to do>
- verify: <verification command>

Status values:

  • [PENDING] — not started
  • [RUNNING YYYY-MM-DDTHH:MM] — in progress (with timestamp)
  • [✅ COMPLETED] — done
  • [FAILED] — failed (include error reason)
  • [BLOCKED] — waiting on human or external dependency

Step fields:

  • engine: — claude-code | human | deploy
  • depends_on: — list of step numbers that must be ✅ first
  • parallel: — list of steps that can run simultaneously
  • verify: — shell command to validate completion
  • artifacts: — outputs passed to dependent steps
  • files: — key files modified

HEARTBEAT.md Format

# HEARTBEAT — <Agent Name>

> ⚠️ NUNCA modifiques este archivo (HEARTBEAT.md). Es read-only.

## Pipeline activo: ~/Documents/proyectos/<project>/PIPELINE.md

## Protocolo cada heartbeat:
1. Lee el pipeline activo (ruta absoluta arriba)
2. Si hay step [PENDING] sin dependencias bloqueadas → ejecútalo
3. Marca [RUNNING YYYY-MM-DDTHH:MM] con timestamp actual
4. Ejecuta: sessions_spawn(task=..., thread=true)
5. Un step por heartbeat máximo

## Zombie Detection
Si un step lleva >2h en [RUNNING], resetear a [PENDING] y reportar.

## En sesión activa con usuario
Priorizar responder. HEARTBEAT_OK.

Cron Setup

Always use CLI, never edit openclaw.json:

openclaw cron add --name "<Project> Pipeline" --agent <agent-id> --every 30m --message "Heartbeat: lee HEARTBEAT.md y ejecuta siguiente step"

Stagger schedules to avoid collisions:

  • :00/:30 → Group A
  • :15/:45 → Group B

Subagent Task Template

Include in the task prompt:

Al terminar:
1. Actualiza <absolute-path-to-PIPELINE.md>: cambia Step X de [RUNNING] a [✅ COMPLETED] con output y artifacts
2. Si fallas, marca [FAILED] con el error
3. Notifica a Discord (action=send, channel=discord, target="channel:<id>") con resumen

Multiple Pipelines Per Project

An agent can have multiple pipeline files. HEARTBEAT specifies priority order:

Lee PIPELINE_ACTIVE.md (prioritario). Si todos completados, lee PIPELINE.md como fallback.

Parallel Execution

Steps sin dependencias cruzadas pueden ejecutarse en paralelo:

## Step 1: Task A [PENDING]
- parallel: [2, 3]

## Step 2: Task B [PENDING]
- parallel: [1, 3]

## Step 3: Task C [PENDING]
- parallel: [1, 2]

## Step 4: Task D [PENDING]
- depends_on: [1, 2, 3]

El heartbeat puede lanzar múltiples steps paralelos en un mismo ciclo si no hay dependencias.

Git Tagging

Cada step completado debe crear un commit taggeado:

git add . && git commit -m "pipeline/<project>/step-<N>: <step title>"

Esto da trazabilidad completa del progreso en git log.

Key Rules

  1. PIPELINE.md siempre en el repo — nunca en workspace
  2. HEARTBEAT.md siempre en workspace — nunca en repo
  3. HEARTBEAT es immutable — locked con chflags uchg
  4. Crons vía CLI — openclaw cron add, nunca editar openclaw.json
  5. Un step por heartbeat — evita saturación (salvo paralelos explícitos)
  6. verify: obligatorio — cada step debe tener comando de verificación
  7. Rutas absolutas — siempre usar ~/Documents/proyectos/... en HEARTBEAT
  8. Git tag por step — commit con pipeline/<project>/step-<N>: <title>
  9. Parallel explícito — steps sin dependencias pueden correr en paralelo si tienen parallel:
More in Workflows