Create and manage macro-task pipelines (QA, roadmaps, feature rollouts) using PIPELINE.md + HEARTBEAT.md pattern. Use when building multi-step project plans...
---
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/<project>/`) | State + progress | ✅ Yes (subagents update directly) |
| `HEARTBEAT.md` | **Agent 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
```markdown
# 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
```markdown
# 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:
```bash
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:
```markdown
## 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:
```bash
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:`
don't have the plugin yet? install it then click "run inline in claude" again.
build multi-step autonomous project pipelines by splitting state (PIPELINE.md in your repo) from agent instructions (HEARTBEAT.md in agent workspace). use this when you need agents to execute sequential or parallel tasks (QA cycles, roadmap rollouts, feature launches) on a schedule without human intervention per step. the pattern keeps git history clean, prevents zombie tasks, and lets subagents update progress directly in your project repo.
Files & Paths:
~/Documents/proyectos/<project>/ (must exist, git-initialized)<project-repo>/PIPELINE.md (created/updated by skill)~/.openclaw/workspace-<agent>/HEARTBEAT.md (created/locked by skill)~/.openclaw/workspace-<agent>/Agent & Cron Setup:
openclaw agent list)External Connections:
pipeline/<project>/step-<N>: <title>openclaw cron add and openclaw agent listDISCORD_WEBHOOK_URL or pass channel:<id> in task promptContext from User:
validate project repo exists and is git-initialized
~/Documents/proyectos/<project>/cd <project> && git status (exits 0 if valid repo)git init or prompt user to init manuallycreate PIPELINE.md in project repo with step definitions
<project>/PIPELINE.md with header: # PIPELINE , <Project Name>: <Pipeline Title> + metadata (Proyecto, Objetivo, Creado date)[PENDING] initiallylock and create HEARTBEAT.md in agent workspace
~/.openclaw/workspace-<agent>/HEARTBEAT.md# HEARTBEAT , <Agent Name>, pipeline path reference, heartbeat protocol (read PIPELINE, execute next [PENDING] step without blocked deps, mark [RUNNING] with timestamp, spawn session, one step per beat max)chflags uchg ~/.openclaw/workspace-<agent>/HEARTBEAT.md (macOS/BSD) or chmod 444 (linux) to lock fileregister cron job via openclaw CLI
openclaw cron add --name "<Project> Pipeline" --agent <agent-id> --every <interval> --message "Heartbeat: lee HEARTBEAT.md y ejecuta siguiente step"crontab -eseed first step execution (optional, for immediate start)
openclaw spawn-session --agent <agent-id> --task "execute step 1 of PIPELINE.md, update status, commit with tag" (or wait for next cron beat)configure subagent task template and Discord notifications
monitor and maintain pipeline during execution
git log --oneline | grep pipeline/ (see step commits), cat PIPELINE.md | grep RUNNING|FAILED (see stuck steps)~/.openclaw/workspace-<agent>/ before writing HEARTBEAT.mdcrontab -e or ask user to check agent ID via openclaw agent listPIPELINE.md (in project repo at ~/Documents/proyectos/<project>/PIPELINE.md):
# PIPELINE , <Project>: <Title> + metadata## Step N: <Title> [PENDING|RUNNING|✅ COMPLETED|FAILED|BLOCKED]pipeline/<project>/step-<N>: <title>HEARTBEAT.md (in agent workspace at ~/.openclaw/workspace-<agent>/HEARTBEAT.md):
# HEARTBEAT , <Agent Name>Cron Registration:
Git History:
pipeline/<project>/step-<N>: <title>git log --oneline shows pipeline progressionopenclaw cron list shows job active; verify via agent logs that heartbeat message is processedgit diff PIPELINE.md shows step status changing [PENDING] -> [RUNNING] -> [✅ COMPLETED]git log | grep pipeline/ shows commits like "pipeline/myproject/step-1: setup database"