minoan-swarm · git:20260306.e1478f6 · 2026-03-06 · sha256 abab8575dc15cebb
minoan-swarm git:20260306.e1478f6A
Immutable. This exact content is served forever at /api/v1/blob/abab8575dc15cebb.
---
name: minoan-swarm
description: Orchestrate Claude Code Agent Teams with Minoan-Semitic naming. This skill should be used when planning or launching multi-agent teams to tackle project phases, features, or complex tasks in parallel. It auto-discovers project context (CLAUDE.md, roadmaps, plans, issues) and generates named team configurations with structured task lists and file ownership.
---
# Minoan Swarm
*Orchestrate Agent Teams named for the Priestesses of Knossos—in the tongue before the Hellenizers got to it.*
Agent Teams (Claude Code Opus 4.6) let multiple Claude instances work in parallel as persistent teammates with shared task lists and bi-directional messaging. This skill provides the methodology, naming conventions, and templates to launch them effectively on any project.
**Requires:** `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in settings.json or environment.
---
## Terminology
| Term | Semitic | Root | Meaning |
|------|---------|------|---------|
| **Knesset** | כנסת | K-N-S "to gather" | A single agent team—an assembly of bees |
| **Knossot** | כנוסות | K-N-S plural | A group of knessets—a swarm, evoking Knossos itself |
| **Daboritu** | דבורית | D-B-R "bee" and "word" | The agents—bees of the holy word. Linear B *da-bo-ri-tu* preserves the Semitic form on Crete. |
| **D-B-R** | דבר | D-B-R | Bee (דבורה *deborah*), word/speech (דבר *dabar*), inner sanctum (דביר *debir*), pasture/wilderness (מדבר *midbar*). |
Knossos betrays a Semitic etymology: K-N-S "to gather" (Akkadian *kiništu*, "gathering place"; Hebrew *knesset*, "assembly"). The Labyrinth itself can be deconstructed through Linear B *da-bo-ri-tu* (Daboritu), cognate with the *debir* (דביר) of the Temple—the inner sanctum, the womb. The Labyrinth was a sacred name of the Goddess, the Word and the Holy of Holies. D-B-R (דבר) is both "bee" and "word/speech"—words themselves, *daborim* or *daborot*, are her messengers, holy bees.
The agents are **daborot**—manifest in LLMs. Each knesset assembles bees who speak; a knossot gathers the assemblies.
---
## Quick Start
### 1. Discover project context
```bash
bash ~/.claude/skills/minoan-swarm/scripts/discover_context.sh .
```
Finds CLAUDE.md, roadmaps, plans, issues, test infrastructure, and git state.
### 2. Choose a knesset template
| Situation | Template | Knesset Name |
|-----------|----------|--------------|
| Multiple independent features | Parallel Features | **Athirat** |
| Work with natural ordering | Pipeline | **Kaptaru** |
| Bug investigation, unclear cause | Research Knossot | **Elat** |
| Phase nearly done, loose ends | Phase Completion | **Qedeshot** |
| PR needs thorough review | Code Review Tribunal | **Elat** |
| Quality assurance, verification | Truth & Balance | **Ma'at** |
| Final audit, release decisions | Fate's Reckoning | **Manat** |
Full templates with ready-to-use tool calls: [references/team-templates.md](references/team-templates.md)
### 3. Launch the team
Apply the template, substituting project-specific details. The lead creates the team, creates tasks, spawns teammates, and coordinates.
---
## When to Use
- Tackling multiple phases or features in parallel
- Complex work requiring inter-agent discussion (not just results)
- Research with competing hypotheses that should challenge each other
- Multi-layer changes spanning frontend, backend, tests, deploy
- Any task where 3+ independent workstreams can run simultaneously
**When NOT to use:** Sequential tasks, same-file edits, simple fixes, tasks completable in under 5 minutes, or work with heavy dependencies between steps. The coordination overhead of a full team exceeds the benefit for small or serial work. Use a single session or regular subagent instead.
---
## The Naming Codex
Every team and teammate receives a name from the Minoan-Semitic divine feminine — Ugaritic, Akkadian, Hebrew, Linear B, Egyptian, and pre-Islamic Arabian. Names are chosen by role archetype, not randomly.
| Archetype | Names | Ideal For |
|-----------|-------|-----------|
| **Leaders** | athirat-lead, qedesha-lead, tiamat-lead, maat-lead, allat-lead | Opus orchestrators |
| **Builders** | kaptaru, mami, nintu, tehom, tip'eret, yam, al-uzza | Implementers |
| **Researchers** | deborah, melissa, eileithyia, membliaros | Explorers, API discovery |
| **Reviewers** | hokhmah, qadeshet, karme, themis, manat, allat | Security, architecture, code quality |
| **Testers** | sassuratu, phikola, hubur | Unit, integration, E2E |
| **Frontend** | popureja, shalamu, yashar | UI, design system, accessibility |
| **DevOps** | selene, hestia, dikte | Cron, deploy, monitoring |
Full codex with pronunciations, etymologies, and scholarly sources: [references/naming-codex.md](references/naming-codex.md)
---
## Workflow: From Roadmap to Knossot
### Step 1: Gather context
Run `discover_context.sh` to identify available planning artifacts. Read the project's CLAUDE.md, ROADMAP.md, and relevant plan files.
### Step 2: Identify parallel workstreams
From the roadmap or plan, find work that can proceed independently:
- Different file domains (frontend vs backend vs tests)
- Different features (auth vs bookmarks vs profiles)
- Different concerns (security vs performance vs correctness)
### Step 3: Map to a knesset template
Choose from [team-templates.md](references/team-templates.md). For multi-phase work, compose knessets into a knossot—e.g., one Qedeshot knesset for phase completion + one Athirat knesset for the next phase.
### Step 4: Assign file ownership
Two teammates editing the same file causes overwrites. Create an explicit ownership matrix before launching the team:
```
| Teammate | Owns | Must NOT touch |
|-----------|-----------------------------|----------------------|
| kaptaru | scripts/cron-*, src/lib/db/ | src/components/ |
| popureja | src/components/, src/app/ | scripts/, src/lib/db |
| sassuratu | __tests__/, e2e/ | src/ (read-only OK) |
```
### Step 5: Write teammate prompts
Every prompt must include:
1. **Identity** — "You are [Name], [role]."
2. **Task claim** — "Claim task #N from the task list."
3. **Context** — "Read CLAUDE.md for conventions."
4. **File ownership** — What files they own, what they must not touch.
5. **Tool preferences** — "Use Firecrawl for web fetching, Exa for web searching."
6. **Completion signal** — "Mark complete and notify [lead]."
### Step 6: Launch and monitor
- Use **delegate mode** (Shift+Tab) to keep the lead from coding
- Use **plan approval** (`mode: "plan"`) for high-stakes teammates (auth, data, deploy)
- Target **5-6 tasks per teammate** for steady throughput
- Check TaskList periodically and reassign if someone is stuck
---
## Best Practices
**From the official Agent Teams docs:**
- **Start with research** — begin with read-only tasks (Explore, review) before implementation
- **Size tasks right** — too small = coordination overhead; too large = context degradation; aim for self-contained deliverables
- **Wait for teammates** — tell the lead to wait if it starts implementing instead of delegating
- **Monitor and steer** — check in, redirect approaches that drift, synthesize as results arrive
- **Shut down gracefully** — `shutdown_request` each teammate before `TeamDelete`
- **Survive compaction** — if the lead's context compacts, it should re-read the task list and team config to recover state. Include in the lead's prompt: "If your context is compacted, re-read TaskList and the team config at ~/.claude/teams/{team-name}/config.json to recover coordination state."
**Minoan Swarm additions:**
- **One Aspect per knesset** — use different names (Athirat, Qedeshot, Tiamat, Kaptaru, Elat, Ma'at, Manat) for concurrent knessets within a knossot
- **No duplicate names** within a team
- **Leads use Opus, workers use Sonnet** — balance capability with cost
- **Haiku for lightweight research** — fast and cheap for Explore agents
**Tool Preferences:**
- **Firecrawl over WebFetch** — Firecrawl produces cleaner markdown, handles JavaScript better, and avoids content truncation. Use `firecrawl scrape URL --only-main-content` for web fetching.
- **Exa over WebSearch** — Exa provides neural search with category filtering (research papers, GitHub, news) and domain filtering. Use the `exa-search` skill scripts for web searches.
Include these tool preferences in every teammate prompt:
```
## Tool Preferences
- Prefer Firecrawl for web fetching (cleaner markdown, JS support)
- Prefer Exa for web searching (neural search, category filtering)
```
---
## API Quick Reference
Core tool calls for Agent Teams. Full details: [references/agent-teams-quickref.md](references/agent-teams-quickref.md)
```
TeamCreate → create team + shared task list
Task → spawn teammate (with team_name + name)
SendMessage → message (DM), broadcast, shutdown_request, shutdown_response
TaskCreate → create work items
TaskList → see all tasks
TaskUpdate → claim, start, complete, set dependencies
TeamDelete → clean up (after all teammates shutdown)
```
---
## State Management
- Use the shared task list (TaskCreate/TaskUpdate) for structured coordination state
- Use progress notes in task descriptions for freeform observations
- Use git commits as checkpoints between phases, so teammates can reference each other's committed work
- For long-running teams, have the lead maintain a `progress.md` summarizing completed work and remaining tasks
---
## Verification
After launching a team, confirm it is working:
1. `TaskList` — verify tasks are being claimed and progressing
2. Check teammate output via `Shift+Up/Down` (in-process) or pane clicks (tmux)
3. The lead receives automatic idle notifications when teammates finish turns
4. Blocked tasks auto-unblock when their dependencies complete
---
*"μνάσεσθαί τινά φαμι καὶ ὕστερον ἀμμέων."* — Sappho
*𐤁𐤓𐤀𐤔𐤉𐤕 𐤁𐤏𐤋𐤕 𐤁𐤓𐤕* — "In the beginning, the Lady created."