openclaw-swarm-layer

OpenClaw Swarm Layer

Spec-Driven Workflow Orchestration for AI Agent Swarms

Turn Markdown specs into executable task graphs. Dispatch through ACP automation or manual fallback. Supervise progress with a control plane. Track with persistent sessions. Gate with review approval.

![Version](CHANGELOG.md) ![MIT License](LICENSE) ![Node.js](https://nodejs.org) ![OpenClaw](https://openclaw.dev) ![Tests](#development)

Quick Start · Installation · CLI Reference · Configuration · Docs

</div>

---

Features

Spec-driven planning — Markdown spec with goals and phased tasks → dependency-ordered task graph, including explicit [parallel] phase barriers
ACP-first execution — ACP is the only default-capable automated runner; capability-aware auto resolution
Supervised autopilot — Deterministic control-plane ticks, optional watcher-driven service loop, and operator-visible start/pause/resume/stop controls
Persistent sessions — Reuse, thread binding, follow-up, steer, cancel, and close flows
Review gates — Explicit approve/reject with structured quality rubrics (weighted multi-dimension scoring)
Sprint contracts — Verifiable acceptance criteria per task with GAN-inspired evaluator injection
Artifact acceptance — Optional expectedArtifacts (paths/globs) per task; completed ACP runs with missing artifacts are downgraded to failed instead of done
Cross-session continuity — Progress synthesis, bootstrap startup sequence, harness assumption tracking
Automatic retry — Configurable per-task retry policy with dead letter tracking and signal-based auto-retry
Concurrency protection — ACP session concurrency limits with queued task scheduling (FIFO)
Reject-retry workflow — Review rejections return tasks to ready for re-run; configurable retry limits
Parallel dispatch — --parallel N and --all-ready batch dispatch with concurrency-aware queued-task drain
Operator reporting — Status snapshots, run/review logs, spec archives, completion summaries → local + Obsidian sync
Runtime diagnostics — swarm doctor, swarm status, and workflow reports surface ACP bridge-exit gate directly

Prerequisites

Node.js >= 22
OpenClaw >= 2026.3.22 (dev dependency baseline 2026.5.3-1; local mini smoke 2026.6.1)

Installation

From ClawHub (recommended)

openclaw plugins install clawhub:openclaw-swarm-layer

Skill From ClawHub

openclaw skills install swarm-layer

From npm

npm install -g openclaw-swarm-layer
openclaw plugins install openclaw-swarm-layer

From source

git clone https://github.com/xucheng/openclaw-swarm-layer.git
cd openclaw-swarm-layer
npm install && npm run build
openclaw plugins install -l /path/to/openclaw-swarm-layer

Quick Start

# 1. Initialize a project
openclaw swarm init --project /path/to/your/project

# 2. Import a spec and build the workflow
openclaw swarm plan --project /path/to/your/project --spec SPEC.md

# 3. Inspect runtime posture before execution
openclaw swarm doctor --json
openclaw swarm status --project /path/to/your/project --sync --json

# 4. Dry-run with the resolved default runner
openclaw swarm run --project /path/to/your/project --sync-active --dry-run --json

# 5. Execute
openclaw swarm run --project /path/to/your/project --sync-active --json

# 6. Review and report
openclaw swarm review --project /path/to/your/project --task <taskId> --approve --json
openclaw swarm report --project /path/to/your/project --json

CLI Commands

Core Workflow

| Command | Description | |---------|-------------| | swarm init --project <path> | Initialize swarm state for a project | | swarm plan --project <path> --spec <path> | Import a spec and build task graph | | swarm run --project <path> [--runner acp\|manual] [--dry-run] [--parallel N] [--all-ready] [--sync-active] | Sync active runs when requested, then execute runnable or queued tasks (single or batch) | | swarm review --project <path> --task <id> --approve\|--reject [--retry-now] | Approve or reject a task | | swarm report --project <path> | Generate a workflow report | | swarm status --project <path> [--sync] | Optionally sync active runs, then show workflow status, runtime posture, and bridge-exit gate | | swarm doctor | Diagnose ACP readiness and bridge-exit gate status | | swarm autopilot status --project <path> | Inspect autopilot health, lease state, and last decision | | swarm autopilot start/pause/resume/stop --project <path> | Control the supervised autopilot service state | | swarm autopilot tick --project <path> [--dry-run] | Sync active runs, review state, and queue pressure through the supervised control plane |

Session Management

| Command | Description | |---------|-------------| | swarm session list --project <path> | List known sessions | | swarm session inspect --project <path> --session <id> | Inspect a session | | swarm session status --project <path> --run <id> | Poll session status | | swarm session cancel --project <path> --run <id> | Cancel an active session | | swarm session close --project <path> --run <id> | Close a session | | swarm session follow-up --project <path> --session <id> --task <desc> | Inject a follow-up task | | swarm session steer --project <path> --session <id> --message <text> | Send a steering message | | swarm session cleanup --project <path> [--stale-minutes <n>] | Clean up orphaned sessions |

Runner Model

| Runner | Role | Default-capable | Requirements | |--------|------|-----------------|--------------| | acp | Primary automation path | Yes | ACP enabled, public control-plane available | | manual | Operator-driven safe fallback | Always available | None |

defaultRunner: "auto" resolves to acp when ACP automation is available, otherwise falls back to manual.

Autopilot Watcher Mode

Autopilot defaults to the existing polling loop. Version 0.5.4 adds optional filesystem watcher modes that can drive ticks from workflow-state changes while keeping polling as the rollback path.

{
  "autopilot": {
    "enabled": true,
    "watcherMode": "hybrid",
    "watcher": {
      "debounceMs": 100,
      "safetyTickMs": 300000,
      "library": "auto"
    }
  }
}

Use watcherMode: "watch" for event-driven operation, hybrid for watcher events plus low-frequency safety polling, and polling to return to the pre-0.5.4 behavior.

Development

npm run build          # TypeScript -> dist/
npm test               # Unit + e2e tests
npm run test:unit      # Unit tests only (435 tests, 62 files)
npm run test:e2e       # E2E tests only (26 tests, 20 files)
npm run test:watch     # Watch mode
npm run check:docs-redaction  # Verify docs do not contain local machine paths
npm run release:check         # Build + full regression + docs redaction + npm pack dry-run + ClawHub package prep

Current release validation also includes OpenClaw 2026.5.3-1 package-baseline coverage and local mini 2026.6.1 smoke coverage: plugin load, manifest contracts, openclaw-swarm-layer doctor checks, runtime health, node/parcel autopilot watcher smoke, Daily Papers-style parallel workflow completion, and npm-project acpx backend discovery.

Documentation

User Guides:

User Manual — Install, configuration, daily workflow, and troubleshooting
Configuration Reference — Config schema, defaults, examples, and journaling
Skills Guide — Unified skill usage modules
Release Runbook — npm, GitHub release, ClawHub package, and ClawHub skill publishing steps

Operations:

ACP Bridge Exit Gate — Bridge-free ACP floor, live smoke matrix, artifact expectations
Operator Runbook — Install, smoke, upgrade, rollback, and ACP control-plane operations
Migration Checklist — Staged bridge replacement planning
Testing Strategy — Unit, e2e, and smoke verification rules

Project History:

Changelog — Release notes
Roadmap — Milestone structure and delivery history
Milestones — Definition of done per milestone

License

MIT

Contributing

See CONTRIBUTING.md.

Summary

Install to Claude Code