swarm-coordination
Coordinate multi-agent swarm workflows. Use when working in parallel with other agents, managing shared resources, or orchestrating distributed tasks. Covers conflict prevention, handoffs, and two-tier task tracking (native task list + artifacts).
How do I install this agent skill?
npx skills add https://github.com/dralgorhythm/claude-agentic-framework --skill swarm-coordinationIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides protocols for multi-agent coordination, including task tracking and file locking. It is functional but introduces an indirect prompt injection surface by requiring the agent to ingest and synthesize content from external sources like GitHub Issues and worker-provided scratchpad files.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
- Runlayerpass
1 file scanned · No issues
What does this agent skill do?
Swarm Coordination
Protocols and patterns for consistent, conflict-free multi-agent development. Follow these guidelines when working alongside other Claude Code agents in the same codebase.
Core Principles
- Two-Tier Task Tracking: Durable work items live in GitHub Issues (or a committed
ISSUES.md); in-flight work lives in the orchestrator's native task list (TaskCreate/TaskUpdate/TaskList) - File Locking: Hooks automatically manage file locks - respect them
- Session Isolation: Each agent has a unique session ID for tracking
- Clean Handoffs: Always leave state — and an artifact reference — that another agent can continue from
Two-Tier Task Tracking
- Tier 1 — Durable record: GitHub Issues (or
ISSUES.mdfor repos without a tracker) hold the permanent history of work items: what was requested, why, and its final disposition. - Tier 2 — In-flight work: The orchestrator owns a native task list (TaskCreate/TaskUpdate/TaskList). One task per work item, each with explicit acceptance criteria. Workers do not maintain their own task lists (see
.claude/rules/agent-constraints.mdfor the no-shared-state rule). - Handoffs: see Core Directives §7 "Follow Command Protocols" — every handoff needs a verifiable artifact reference.
File-Based Output
Workers write results to scratchpad/<task-id>.md, not direct context. Only durable artifacts (ADRs, plans, PRDs) go to artifacts/. Orchestrator creates output targets before launching workers; workers write to assigned files; orchestrator reads and synthesizes.
Workflows
Starting Work
- Check the Task List: Orchestrator reviews TaskList for unblocked, unclaimed items
- Create Tasks: One task per work item, each with explicit acceptance criteria
- Check Conflicts: Review
.claude/hooks/.file-tracker.logfor recent edits - Dispatch: Send workers a focused, self-contained prompt (see
agent-constraints.md)
During Work
- Atomic Changes: Make small, complete changes that don't leave broken state
- Frequent Commits: Commit often to reduce merge conflicts
- Update Task Status: Orchestrator updates TaskUpdate as workers report back
- Respect Locks: If a file is locked, wait or work on something else
Completing Work
- Run Tests: Verify changes don't break existing functionality
- Mark Task Done: Orchestrator closes the task in the native task list with the result
- Update Durable Record: Reflect completion in the GitHub Issue /
ISSUES.md - Clean State: Commit all changes, leave no uncommitted work
Conflict Prevention
File Lock Protocol
Hooks automatically acquire/release locks. If you encounter a lock:
# Check who holds the lock
cat .claude/hooks/.locks/<filename>.lock
# Lock automatically expires after 60 seconds
# If urgent, wait or pick a different task from the task list
Merge Conflict Strategy
- Pull frequently: Keep your branch up to date
- Small PRs: Easier to merge than large changes
- Coordinate: Claim a task (and its files) in the orchestrator's task list before editing
- Resolve quickly: Address conflicts immediately when detected
Communication Patterns
Handoff Message
When ending a session with incomplete work, leave a handoff pointing at a concrete artifact:
echo '{"message": "Continue implementing auth middleware. Tests passing but needs error handling in src/auth.ts:45", "artifact": "artifacts/plan_auth_middleware.md"}' > .claude/hooks/.state/handoff.json
Multi-Agent Patterns
Orchestrator-Worker Pattern
For complex tasks, one agent orchestrates while others execute:
- Orchestrator: Plans, decomposes work into tasks on the native task list, dispatches workers
- Workers: Receive a focused prompt, implement, return results (no worker-to-worker state sharing — see
agent-constraints.md) - Sync Point: Orchestrator collects all worker results and reconciles before final integration
Parallel Streams
For independent features:
- Create a separate task (with acceptance criteria) for each stream
- Each worker claims one stream via its assigned task
- Avoid editing same files across streams
- Merge streams at defined integration points
Budget & Waves
Cost circuit-breaker only: this bounds runaway spend after the fact. It does not detect step-repetition or looping — that is a different failure mode, out of scope here.
- Orchestrators declare a token/wave ceiling when dispatching a batch of workers — set the ceiling before launch, not after
- On hitting the ceiling: stop dispatching, report spend so far and the remaining work, and ask the user before continuing
- Dispatched task titles carry a
[Wave N/M]prefix (e.g.,[Wave 1/3] Explore auth patterns) so spend and progress can be attributed to a wave at a glance
State Files
| File | Purpose |
|---|---|
.claude/hooks/.state/session_*.json | Active agent sessions |
.claude/hooks/.state/handoff.json | Handoff messages between sessions |
.claude/hooks/.locks/*.lock | File edit locks |
.claude/hooks/.file-tracker.log | Recent file modifications |
Best Practices
- Check Before Edit: Always verify no active locks on target files
- Complete Units: Finish logical units of work before switching
- Document Intent: Use the task list to declare what you're working on and its acceptance criteria
- Test Locally: Run tests before pushing to catch issues early
- Sync Often: Keep the task list, durable issues, and git in sync with other agents
Emergency Procedures
Deadlock Detection
If agents are waiting on each other:
# Check active sessions
ls -la .claude/hooks/.state/session_*.json
# Check active locks
ls -la .claude/hooks/.locks/
# Force release stale locks (use with caution)
find .claude/hooks/.locks -mmin +5 -delete
Recovery from Conflict
- Save current work to a new branch
- Sync with main:
git fetch && git rebase origin/main - Resolve conflicts file by file
- Update the native task list and durable issue record to reflect current state
- Continue work
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/dralgorhythm/claude-agentic-framework/swarm-coordination">View swarm-coordination on skillZs</a>