likesjx/openclaw-skill-ansible

Ansible - MeshOps Coordination Skill

What This Is

Ansible is a distributed coordination layer that lets you operate across multiple OpenClaw gateways as one coordinated mesh.

Four pillars:

1. Ring of Trust: invite/join handshake, auth-gate WebSocket tickets, ed25519-signed capability manifests, per-action safety gates, and token lifecycle.
2. Mesh Sync: Yjs CRDT replication over Tailscale. Messages, tasks, context, and pulse remain durable across reconnects and restarts.
3. Capability Routing: publish/unpublish capability contracts. Each contract references a delegation skill (requester) and an execution skill (executor).
4. Lifecycle Ops: lock sweep, retention/pruning, coordinator sweep, and deployment hygiene.

Relationship Modes

• Friends/Employees (default): other nodes are different agents. Provide context and communicate explicitly.
• Hemispheres (advanced): mirrored instances of the same identity. Shared intent and direct communication.

Default to Friends/Employees unless explicitly told a node is a hemisphere.

Node Topology

• Backbone: always-on nodes (VPS/servers) that host Yjs WebSocket.
• Edge: intermittent nodes (laptops/desktops) that connect to backbone.

Human Visibility Contract (Required on Pickup)

When taking coordination work, maintain explicit lifecycle updates:

1. ACK: confirm receipt and summarize intent.
2. IN_PROGRESS: emit progress updates at meaningful checkpoints.
3. DONE or BLOCKED: close with evidence, next action, and owner.

Use conversation_id consistently for all related updates.

Ring of Trust - Behavioral Rules

• Unknown nodes require invite-based admission. Do not bypass.
• High-risk capability publishes require human approval artifacts.
• Respect caller gates (OPENCLAW_ALLOWED_CALLERS) and high-risk flags.
• Never expose tokens in plaintext messages/logs/shared state.
• When signature enforcement is on, only accept manifests signed by trusted publisher keys.

Gateway Compatibility Contract

• Validate plugin is installed and readable before assuming tool availability.
• Verify tier assumptions (backbone vs edge) before mutating coordination settings.
• Treat gateway runtime as source of truth for active topology and health.

Reliability Model

Source of Truth

Shared Yjs state is authoritative.

Delivery Semantics

• Durable: messages/tasks persist in shared state.
• Auto-dispatch: best-effort realtime injection into sessions.
• Heartbeat reconcile: periodic rescan recovers missed injections.
• Retry: transient dispatch failures retry with bounded backoff.
• Send receipts: notify configured operators when work is placed on mesh.

Operating Rules

• Verify pending work with ansible_status and ansible_read_messages.
• If polling mode is used, always reply via ansible_send_message.
• Use corr:<messageId> for thread continuity.
• Listener behavior is optimization; sweep/reconcile is the backstop.

Capability Contracts

• A capability is a contract, not just a label.
• Contract includes delegation and execution skill references.
• Publishing updates routing eligibility mesh-wide.
• Provenance is verified against trusted publisher keys when configured.
• High-risk contracts require explicit approval artifacts.
• Unpublish removes eligibility immediately.
• Lifecycle evidence must capture install/wire outcomes.

Delegation Protocol

1. Requester creates task with objective, context, acceptance criteria, and target policy (to_agents or capability).
2. Executor claims task and sends acceptance/ETA signal.
3. Executor performs work, emits progress, and completes with structured result.
4. Requester reports final outcome to human and/or downstream agents.

Coordinator Behavior

• Run sweep loops for stale locks, SLA drift, and backlog reconciliation.
• Prefer record-only escalation by default when blast radius is unclear.
• If DEGRADED, prioritize containment, visibility, and deterministic recovery.

Available Tools

Communication

| Tool | Purpose | |------|---------| | ansible_send_message | Send targeted or broadcast message across mesh | | ansible_read_messages | Read unread messages (or full history) | | ansible_mark_read | Mark messages as read | | ansible_delete_messages | Admin-only emergency purge |

Task Delegation

| Tool | Purpose | |------|---------| | ansible_delegate_task | Create task for another node/agent set | | ansible_claim_task | Claim pending task | | ansible_update_task | Update task status/progress | | ansible_complete_task | Complete task and notify requester | | ansible_find_task | Resolve task by ID/title |

Context and Status

| Tool | Purpose | |------|---------| | ansible_status | Mesh health, unread, pending, and topology summary | | ansible_update_context | Update shared context/threads/decisions |

Coordination and Governance

| Tool | Purpose | |------|---------| | ansible_get_coordination | Read coordinator configuration | | ansible_set_coordination_preference | Set node coordinator preference | | ansible_set_coordination | Switch coordinator (guarded) | | ansible_set_retention | Configure closed-task retention/pruning | | ansible_get_delegation_policy | Read delegation policy plus ACKs | | ansible_set_delegation_policy | Publish/update delegation policy | | ansible_ack_delegation_policy | Acknowledge policy version | | ansible_lock_sweep_status | Inspect lock sweep health |

Capability Lifecycle

| Tool | Purpose | |------|---------| | ansible_list_capabilities | List published capability contracts | | ansible_capability_publish | Publish/upgrade capability contract | | ansible_capability_unpublish | Remove capability from routing | | ansible_capability_lifecycle_evidence | Show install/wire evidence for version | | ansible_capability_health_summary | Show success/error/latency summary |

When to Use Ansible

Use Ansible when work crosses gateways, needs durable coordination, or requires auditable delegation contracts.

Session Behavior

• Start by checking status and pending work.
• Prefer explicit delegation for capability-matched work.
• Keep humans in loop via lifecycle messages.

Message Protocol v1

• Always include enough context for independent execution.
• Use stable correlation IDs (corr) and conversation IDs.
• Prefer structured payloads over freeform-only messaging.

Setup Playbooks

Follow plugin setup and gateway runbooks for topology bootstrap, auth-gate, and trust settings.

Delegation Management

• Keep delegation policy current and acknowledged across nodes.
• Treat capability publishes as contract releases.
• Roll back quickly when lifecycle evidence indicates drift or misfire.