swarm-executor

Coordinate multi-agent swarm execution with a lightweight Pub/Sub protocol, standardized SwarmCommand messages, token-budget control, agent status tracking,...

Security Scan

The package implements a coherent multi-agent coordination library (protocol, pub/sub, negotiation, token budget) that matches its description; nothing in the files demands unrelated credentials or hidden endpoints, but review runtime dependency & Redis usage before deploying to production.

Purpose & Capability

Name/description (swarm coordination, Pub/Sub, token budgeting, negotiation) align with the included modules (swarm_protocol, pubsub, token_budget, agent_manager, negotiation). The code implements the advertised features and default agent IDs/roles that the SKILL.md references.

Instruction Scope

SKILL.md stays on-topic (create/validate/publish SwarmCommand, track state, enforce budgets). Minor inconsistency: SKILL.md example uses PubSubCoordinator(use_redis=True) while the code's PubSubCoordinator constructor expects a backend enum and optional redis_url; the README-driven example won't work without adjusting parameters. The runtime instructions do not tell the agent to read arbitrary host files or to exfiltrate secrets, but published messages can go to a user-supplied Redis instance (see guidance).

Install Mechanism

No install spec in registry (instruction-only), but the repo includes requirements.txt listing redis, pydantic, fastapi, uvicorn, python-dotenv, etc. Because there's no automatic installer, these dependencies will not be installed by the platform — a manual install may be needed. The listed packages are plausible for optional Redis and an HTTP API, but they are heavier than the core library needs if you only use the in-memory backend.

Credentials

The skill declares no required environment variables or primary credentials. The code supports connecting to Redis via a redis_url parameter (not an env var), which is proportional to the described Redis-backed Pub/Sub feature. No unrelated cloud credentials or secrets are requested by the package.

Persistence & Privilege

always is false and the package does not request elevated platform privileges. It defines module-level singletons (a global coordinator) but does not attempt to modify other skills or global agent configuration. Autonomous invocation is allowed by default (normal) but no extra permanent presence is requested.

Assessment

This skill appears to do what it claims: a library for coordinating multi-agent workflows with in-memory or Redis Pub/Sub, token budgeting, negotiation, and agent tracking. Before installing or running it: - If you plan to use Redis, provide a trusted redis_url only (do not point to unknown/public Redis servers). Messages published to Redis can contain task payloads and could be read by whoever controls that Redis instance. - The registry package includes requirements.txt (fastapi, uvicorn, python-dotenv, etc.). Because there is no install spec, those dependencies won't be auto-installed — install only the packages you need. The full stack (FastAPI/uvicorn) may pull in a webserver surface you should review. - SKILL.md examples contain a minor API mismatch (use_redis=True vs the actual PubSubCoordinator signature). Double-check examples against the code before copying. - The code sets up default agent IDs and includes logic where agent "001" (CEO) can cancel negotiations; if you map external agents to those IDs, ensure authentication/authorization is enforced by your deployment to prevent unauthorized cancellations. - Review docker-compose.yml and any omitted files before running to ensure they don't start unexpected network services. If you need a second opinion, provide the docker-compose.yml and any omitted runtime files and I can check them for external endpoints or secret handling.

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:

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:

{
  "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:

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:

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:

{
  "decision": "assign_to_developer_then_review_by_auditor",
  "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:

## 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.