Macro Pipeline Skill

intent

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.

inputs

Files & Paths:

• Project directory: ~/Documents/proyectos/<project>/ (must exist, git-initialized)
• PIPELINE.md location: <project-repo>/PIPELINE.md (created/updated by skill)
• HEARTBEAT.md location: ~/.openclaw/workspace-<agent>/HEARTBEAT.md (created/locked by skill)
• Agent workspace must exist: ~/.openclaw/workspace-<agent>/

Agent & Cron Setup:

• Agent ID (from openclaw agent list)
• Cron interval (e.g., 30m, 15m, 1h). stagger across teams to avoid collisions (group A at :00/:30, group B at :15/:45)
• Discord webhook URL or channel ID (optional, for step completion notifications)

External Connections:

• Git (local repo at project path). agents will commit with tags pipeline/<project>/step-<N>: <title>
• OpenClaw CLI (v2+) for openclaw cron add and openclaw agent list
• Discord API (optional): set env var DISCORD_WEBHOOK_URL or pass channel:<id> in task prompt

Context from User:

• Pipeline name and objective (one-liner)
• List of steps with titles, engines (claude-code | human | deploy), descriptions, verification commands
• Dependencies (which steps block which others)
• Parallel-execution groups (if any)
• Artifacts passed between steps

procedure

1. validate project repo exists and is git-initialized

   • input: project path ~/Documents/proyectos/<project>/
   • run: cd <project> && git status (exits 0 if valid repo)
   • output: confirmed repo path; error if git init fails
   • edge case: if repo does not exist, create with git init or prompt user to init manually

2. create PIPELINE.md in project repo with step definitions

   • input: step list (titles, engines, descriptions, verify commands, dependencies, artifacts)
   • create file at <project>/PIPELINE.md with header: # PIPELINE , <Project Name>: <Pipeline Title> + metadata (Proyecto, Objetivo, Creado date)
   • for each step, write markdown block with fields: engine, description, files, verify, artifacts, depends_on/parallel
   • set all steps to [PENDING] initially
   • output: PIPELINE.md written to disk; git status shows untracked file
   • edge case: if PIPELINE.md exists, prompt to overwrite or merge

3. lock and create HEARTBEAT.md in agent workspace

   • input: agent ID, agent workspace path, active pipeline path (absolute)
   • create file at ~/.openclaw/workspace-<agent>/HEARTBEAT.md
   • write header: # 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)
   • add zombie detection rule: if step in [RUNNING] > 2 hours, reset to [PENDING] and report
   • run: chflags uchg ~/.openclaw/workspace-<agent>/HEARTBEAT.md (macOS/BSD) or chmod 444 (linux) to lock file
   • output: HEARTBEAT.md created and immutable; confirm lock status in logs
   • edge case: if chflags/chmod fails (permissions, OS), log warning but continue

4. register cron job via openclaw CLI

   • input: project name, agent ID, heartbeat interval (e.g., 30m)
   • run: openclaw cron add --name "<Project> Pipeline" --agent <agent-id> --every <interval> --message "Heartbeat: lee HEARTBEAT.md y ejecuta siguiente step"
   • output: cron job registered; confirm job ID and next run time
   • do NOT edit openclaw.json directly
   • edge case: if cron add fails (invalid agent ID, CLI version mismatch), log error and suggest manual cron setup via crontab -e

5. seed first step execution (optional, for immediate start)

   • input: PIPELINE.md path, first [PENDING] step without dependencies
   • run: openclaw spawn-session --agent <agent-id> --task "execute step 1 of PIPELINE.md, update status, commit with tag" (or wait for next cron beat)
   • output: session spawned or queued; log session ID
   • edge case: if user skips this, pipeline starts at next scheduled heartbeat

6. configure subagent task template and Discord notifications

   • input: absolute PIPELINE.md path, Discord channel ID (or webhook)
   • embed in each task prompt or subagent instructions: "al terminar, actualiza , cambia Step X de [RUNNING] a [COMPLETED], send Discord notification with summary"
   • output: task template documented; ready for agents to use
   • edge case: if Discord config missing, skip notification step (non-blocking)

7. monitor and maintain pipeline during execution

   • input: cron running, agents active, PIPELINE.md mutable in repo
   • monitor via: git log --oneline | grep pipeline/ (see step commits), cat PIPELINE.md | grep RUNNING|FAILED (see stuck steps)
   • if step stuck in [RUNNING] > 2h, manually reset to [PENDING] or [BLOCKED] with reason
   • if step [FAILED], inspect error in PIPELINE.md, fix root cause, reset to [PENDING]
   • output: pipeline progression visible in git history and PIPELINE.md status
   • edge case: handle network timeouts (agents retry on next beat), rate limits (insert delay step), auth expiry (rotate credentials, restart cron)

decision points

• if PIPELINE.md already exists in repo: prompt user to merge changes or overwrite; do not silently clobber
• if agent workspace does not exist: create ~/.openclaw/workspace-<agent>/ before writing HEARTBEAT.md
• if chflags/chmod fails (file lock): log warning; HEARTBEAT.md remains writable but agents must respect read-only discipline via protocol
• if step depends_on other steps: heartbeat skips this step until all dependencies are [✅ COMPLETED]; mark as [BLOCKED] if a dependency is [FAILED]
• if step has parallel list: heartbeat can spawn multiple steps in same beat if no cross-dependencies exist; otherwise, execute one at a time
• if step in [RUNNING] > 2 hours: zombie detection triggers; reset to [PENDING], log incident, optionally notify via Discord
• if cron add fails (invalid agent, CLI error): fall back to manual crontab -e or ask user to check agent ID via openclaw agent list
• if Discord webhook missing: skip notification; continue pipeline without blocking
• if git commit fails (dirty working tree, no perms): log error; agent must resolve before next step
• if multiple pipelines active per agent: HEARTBEAT reads PIPELINE_ACTIVE.md (priority) first; if all steps [✅ COMPLETED], reads PIPELINE.md as fallback

output contract

PIPELINE.md (in project repo at ~/Documents/proyectos/<project>/PIPELINE.md):

• markdown file with header # PIPELINE , <Project>: <Title> + metadata
• each step is a level-2 heading with status marker: ## Step N: <Title> [PENDING|RUNNING|✅ COMPLETED|FAILED|BLOCKED]
• fields per step: engine, description, files, verify, artifacts, depends_on (list), parallel (list)
• all steps start as [PENDING]
• agents mutate status in-place as they execute
• file is git-tracked; commits tagged as pipeline/<project>/step-<N>: <title>

HEARTBEAT.md (in agent workspace at ~/.openclaw/workspace-<agent>/HEARTBEAT.md):

• markdown file with header # HEARTBEAT , <Agent Name>
• contains absolute path to active PIPELINE.md
• contains heartbeat protocol (read pipeline, execute next unblocked [PENDING] step, mark [RUNNING] with timestamp, spawn session, max one step per beat)
• locked immutable via chflags/chmod
• agents read-only; do not mutate

Cron Registration:

• cron job registered in OpenClaw with name, agent ID, interval
• cron fires message "Heartbeat: lee HEARTBEAT.md y ejecuta siguiente step"
• next run time confirmed in CLI output

Git History:

• one commit per completed step with tag pipeline/<project>/step-<N>: <title>
• git log --oneline shows pipeline progression
• PIPELINE.md changes (status updates) are tracked in commits

outcome signal

• cron job fires on schedule: check openclaw cron list shows job active; verify via agent logs that heartbeat message is processed
• PIPELINE.md status updates in real time: git diff PIPELINE.md shows step status changing [PENDING] -> [RUNNING] -> [✅ COMPLETED]
• git commits appear with pipeline tags: git log | grep pipeline/ shows commits like "pipeline/myproject/step-1: setup database"
• agents execute steps autonomously: no manual intervention needed per step; agents spawn sessions, run tasks, update PIPELINE.md, commit
• Discord notifications (if configured) arrive when steps complete: check channel for summaries with step title, artifacts, completion time
• zombie detection works: if step stuck in [RUNNING] > 2h, HEARTBEAT resets it to [