Macro Pipeline
by @santacruzg282-cyber
Create and manage macro-task pipelines (QA, roadmaps, feature rollouts) using PIPELINE.md + HEARTBEAT.md pattern. Use when building multi-step project plans...
clawhub install macro-pipeline📖 About This Skill
name: macro-pipeline description: 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. metadata: { "openclaw": { "emoji": "🔧" } }
Macro Pipeline Skill v3
Architecture
Two files, two locations:
| File | Location | Purpose | Mutable? |
|------|----------|---------|----------|
| PIPELINE.md | Project repo (~/Documents/proyectos/) | State + progress | ✅ Yes (subagents update directly) |
| HEARTBEAT.md | Agent workspace (~/.openclaw/workspace-) | Instructions (read-only) | ❌ No (locked with chflags uchg) |
Why PIPELINE in the repo?
Why HEARTBEAT in workspace?
PIPELINE.md Format
# PIPELINE — :
Proyecto: ~/Documents/proyectos/
Objetivo:
Creado: YYYY-MM-DD
Step 1: [PENDING]
engine: claude-code
description:
files:
verify:
artifacts: Step 2: [PENDING]
engine: claude-code
depends_on: [1]
description:
verify:
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 dependencyStep fields:
engine: — claude-code | human | deploydepends_on: — list of step numbers that must be ✅ firstparallel: — list of steps that can run simultaneouslyverify: — shell command to validate completionartifacts: — outputs passed to dependent stepsfiles: — key files modifiedHEARTBEAT.md Format
# HEARTBEAT — > ⚠️ NUNCA modifiques este archivo (HEARTBEAT.md). Es read-only.
Pipeline activo: ~/Documents/proyectos//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áximoZombie 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 " Pipeline" --agent --every 30m --message "Heartbeat: lee HEARTBEAT.md y ejecuta siguiente step"
Stagger schedules to avoid collisions:
:00/:30 → Group A:15/:45 → Group BSubagent Task Template
Include in the task prompt:
Al terminar:
1. Actualiza : 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:") 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//step-: "
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 conchflags 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//step-:
9. Parallel explícito — steps sin dependencias pueden correr en paralelo si tienen parallel: