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.

Quick Start

1. Discover project context

bash ~/.claude/skills/minoan-swarm/scripts/discover_context.sh .

Finds CLAUDE.md, roadmaps, plans, issues, test infrastructure, and git state.

2. Choose a team template

Full templates with ready-to-use tool calls: 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, or work with heavy dependencies between steps. Use regular subagents or a single session 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.

Full codex with pronunciations, etymologies, and scholarly sources: references/naming-codex.md

Workflow: From Roadmap to Swarm

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 template

Choose from team-templates.md. For multi-phase work, compose templates — e.g., one Qedeshot team for phase completion + one Athirat team for the next phase.

Step 4: Assign file ownership

Critical: Two teammates editing the same file causes overwrites. Create an explicit ownership matrix:

| 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

Minoan Swarm additions:

• •One Aspect per team — use different names (Athirat, Qedeshot, Tiamat, Kaptaru, Elat, Ma'at, Manat) for concurrent teams
• •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 (MANDATORY for all agents):

• •Firecrawl over WebFetch — Always use firecrawl scrape URL --only-main-content instead of WebFetch for fetching web content. Firecrawl produces cleaner markdown, handles JavaScript better, and has no token limits.
• •Exa over WebSearch — Always use the exa-search skill scripts instead of WebSearch for web searches. Exa provides neural search, category filtering (research papers, GitHub, news), and domain filtering capabilities.

Include these tool preferences in every teammate prompt:

## Tool Preferences
- Use Firecrawl skill for web fetching (not WebFetch)
- Use Exa skill for web searching (not WebSearch)

API Quick Reference

Core tool calls for Agent Teams. Full details: 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)

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