Skill: xb19960921/swarm-executor (version 1.1.0)

--- name: swarm-coordinator description: Coordinate multi-agent swarm execution with a lightweight Pub/Sub protocol, standardized SwarmCommand messages, token-budget control, agent status tracking, negotiation, fallback, and completion gates. Use when building or reviewing multi-agent coordination, swarm execution, task delegation, agent handoff, token quota governance, Redis/in-memory PubSub orchestration, role-based agent teams, or safe parallel AI workflows. version: "1.1.0" last_updated: "2026-04-25" changelog: "ClawHub-ready release: generalized public wording, added execution workflow, safety boundaries, gates, failure handling, validation checklist, and test prompts." --- # Swarm Coordinator Swarm Coordinator is a lightweight coordination skill for multi-agent execution. It helps an agent design, validate, and operate a swarm workflow using: - standardized `SwarmCommand` messages - Redis or in-memory Pub/Sub coordination - token-budget governance and downgrade rules - agent status tracking - negotiation and conflict resolution - assignment, completion, and failure notifications Use it when the task is not “one agent answers once”, but **multiple agents must coordinate without losing control of cost, state, ownership, or completion criteria**. This skill is intentionally control-oriented: a swarm is only valuable when parallelism improves throughput or quality without causing duplicated work, hidden queue drift, or uncontrolled token spend. --- ## When to Use Use this skill for: - multi-agent task delegation or swarm execution - role-based AI teams, agent crews, or collaborative agent workflows - Pub/Sub task coordination with Redis or memory queues - designing a standard command protocol between agents - assigning roles, budgets, deadlines, and dependencies - tracking task state across multiple agents - negotiating conflicts between agents - enforcing token quota and fallback behavior - reviewing whether a swarm workflow can converge safely Do not use it for simple single-agent tasks. If one agent can complete the job directly, avoid swarm overhead. --- ## Core Principle A swarm is useful only if it improves throughput or quality **without causing coordination chaos**. Always protect four invariants: 1. **Single task owner** — every task has one accountable owner at a time. 2. **Explicit state** — each command has status, deadline, budget, dependencies, and result. 3. **Bounded cost** — token budget and downgrade rules are part of the protocol. 4. **Verifiable completion** — completion requires artifacts, tests, review, or an explicit result field. If any invariant is missing, the swarm can drift, duplicate work, or burn tokens. --- ## Default Workflow ### Step 1: Decide whether swarm is justified Use swarm only when at least one is true: - task can be split into independent subtasks - different agents have clearly different roles - review/verification must be separated from implementation - latency can be reduced through parallel work - negotiation is needed because constraints conflict If not, keep it single-agent. ### Step 2: Define roles and ownership Specify: ```text commander / coordinator executor(s) reviewer / auditor monitor / verifier fallback owner ``` Each task should have one current `assigned_to`. Multiple reviewers are allowed, but multiple executors writing the same artifact are not unless explicitly coordinated. ### Step 3: Create a SwarmCommand A command must include: ```json { "command_id": "cmd_12345678", "timestamp": "2026-04-25T12:00:00Z", "sender": {"type": "coordinator", "id": "001"}, "target": {"type": "developer", "id": "003"}, "command": { "action": "develop", "module": "login", "requirements": ["JWT auth", "tests"], "output_format": "python_code" }, "metadata": { "priority": "high", "token_budget": 1500, "deadline": "2026-04-25T13:00:00Z", "dependencies": [] }, "negotiation": { "allowed": true, "timeout": 300 } } ``` Prefer using `coordinator/swarm_protocol.py` for deterministic command creation and validation. If your project has its own agent taxonomy, map local role names to the protocol roles instead of hard-coding private labels in prompts. ### Step 4: Validate before publish Before publishing to Redis or memory queue, validate: - schema format - known sender / target role - priority is one of `low | medium | high | critical` - token budget is positive and within tier quota - dependencies exist or are intentionally empty - deadline is realistic - completion gate is clear If validation fails, do not publish. Return validation errors and ask for correction or auto-fix safe fields. ### Step 5: Publish, subscribe, and track state Use: ```python from coordinator.pubsub import PubSubCoordinator from coordinator.swarm_protocol import SwarmProtocol protocol = SwarmProtocol() coordinator = PubSubCoordinator(use_redis=True) command = protocol.create_command( agent_type="developer", command={"action": "analyze", "module": "performance"}, priority="high", token_budget=2000, ) valid, errors = protocol.validate_command(command) if valid: coordinator.publish("tasks", command.to_dict()) else: print(errors) ``` Track state transitions: ```text pending → assigned → in_progress → completed / failed / cancelled ``` No command should remain `in_progress` forever. Use deadline or heartbeat timeout to trigger fallback. ### Step 6: Collect result and close the loop Completion should include: - `success: true/false` - output or artifact path - tests/review/verification result when applicable - token usage - failure reason if failed - next action recommendation If result is missing required artifacts, mark as incomplete instead of completed. --- ## Token Budget and Downgrade Rules Use token budget as a control mechanism, not just metadata. Recommended rules: | Condition | Action | |---|---| | budget remaining > 40% | continue normal execution | | budget remaining 20-40% | compress context and reduce parallel agents | | budget remaining < 20% | downgrade model/tier or require coordinator approval | | budget exceeded | stop publishing new subtasks and request confirmation | | repeated failure | lower concurrency and route to reviewer/monitor | For local implementation, use `coordinator/token_budget.py` if available. --- ## Negotiation Rules Allow negotiation when: - two agents propose conflicting plans - deadline and token budget cannot both be satisfied - a dependency is blocked - an agent lacks capability or context Negotiation output should be a decision, not endless discussion: ```json { "decision": [REDACTED_SECRET], "reason": "developer owns implementation; auditor reviews risk", "budget_adjustment": 500, "deadline_adjustment": null, "blocked": false } ``` If negotiation exceeds timeout, coordinator decides or escalates to human. --- ## Failure Handling Handle these failures explicitly: | Failure | Response | |---|---| | invalid command | reject before publish; return schema errors | | target unavailable | reroute to fallback owner | | dependency blocked | keep pending; notify coordinator | | budget exceeded | pause or downgrade; do not silently continue | | deadline missed | mark failed or escalate | | duplicate owner | choose one owner; cancel duplicate assignment | | incomplete result | reopen task with missing artifact list | | repeated failure | reduce concurrency; route to reviewer/monitor | Never let failures become silent queue drift. --- ## Safety Boundaries Ask for human confirmation before swarm actions that are: - destructive: delete data, remove files, reset state - public: publish, message external users, send email - costly: paid API calls, high-token parallel execution, cloud deployment - irreversible: production migrations, permission changes, credential rotation - ambiguous: unclear task owner, conflicting requirements, missing acceptance criteria Swarm coordination amplifies mistakes. High-risk actions need stronger gates than single-agent execution. --- ## Output Format When using this skill, return: ```markdown ## Swarm Plan - Goal: - Swarm justified? yes/no + reason - Agents and roles: - Ownership model: ## Commands | command_id | target | action | budget | dependencies | gate | |---|---|---|---:|---|---| ## Coordination Flow pending → assigned → in_progress → completed/failed ## Budget / Downgrade - Total budget: - Per-agent budget: - Downgrade trigger: ## Failure / Fallback - Main risks: - Fallback owner: - Escalation condition: ## Verification - Required artifacts: - Tests / review: - Done criteria: ``` For code-facing tasks, also mention which files or APIs to use. --- ## Bundled Resources Use these resources when needed: - `coordinator/swarm_protocol.py` — deterministic SwarmCommand creation, validation, assignment, completion, negotiation helpers. - `schemas/swarm_command.json` — JSON Schema for command validation. - `tests/test_swarm_protocol.py` — regression tests for protocol behavior. - `test-prompts.json` — Darwin-style prompts for future skill regression evaluation. Read or run them when modifying the protocol implementation. --- ## Validation Checklist Before calling a swarm workflow ready, check: - [ ] Every task has exactly one current owner. - [ ] Every command validates against schema. - [ ] Budget and deadline are explicit. - [ ] Dependencies are declared. - [ ] Completion gate is explicit. - [ ] Failure fallback is defined. - [ ] High-risk actions require confirmation. - [ ] Tests or review exist for important outputs. - [ ] No open-ended negotiation loop remains. --- ## Quality Bar A good swarm plan should reduce confusion, not add bureaucracy. It succeeds when: - agents know exactly what they own - coordinator can see state and budget - failures route to a clear fallback - completion is verifiable - token use stays bounded - parallelism improves throughput without oscillation If the swarm adds agents without improving control, do not use swarm.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)