Interactive agent fleet designer - configure your multi-agent workspace. Triggers: "configure fleet", "setup agents", "multi-agent workspace", "fleet layout".
Interactive agent fleet designer - configure your multi-agent workspace. [!!!] CRITICAL BOOT SEQUENCE:
~/.claude/directives/COMMANDS.md, ~/.claude/directives/INVARIANTS.md, and ~/.claude/directives/TAGS.md.¶INV_SKILL_PROTOCOL_MANDATORY.Output this block in chat with every blank filled:
Boot proof:
- COMMANDS.md — §CMD spotted:
________- INVARIANTS.md — ¶INV spotted:
________- TAGS.md — §FEED spotted:
________
[!!!] If ANY blank above is empty: STOP. Go back to step 1 and load the missing file. Do NOT read Phase 0 until every blank is filled.
Interactive agent fleet designer. Helps users configure their multi-agent workspace based on their workflow, not generic categories.
[!!!] DO NOT USE THE BUILT-IN PLAN MODE (EnterPlanMode tool). This protocol has its own structured phases. Use THIS protocol's phases, not the IDE's.
High-level themes that organize your work. Not everyone has all of these:
| Workgroup | Description | Examples |
|---|---|---|
| project | Active codebase work | Viewer, Layout, API, Extraction |
| company | Company-specific agents | MCP tools, internal systems |
| domain | Domain research & expertise | Insurance, Financials, Legal |
| meta | Engine & session work | Sessions analysis, reports, engine |
| personal | Personal productivity | Notes, learning, experiments |
Actual features/areas you work on — discovered through interview, not picked from a menu.
Slots for areas you don't know yet. Create "Future" agents to reserve space.
| Command | Action |
|---|---|
/fleet | Full interview (new or update) |
/fleet update | Quick changes |
/fleet rearrange | Reorder agents/tabs |
/fleet launch | Start the fleet |
/fleet launch {workgroup} | Start specific workgroup |
/fleet status | Show current state |
/fleet add {workgroup} | Add agents to workgroup |
/fleet placeholder {workgroup} | Add future slot |
Auto-detect identity (per ¶INV_INFER_USER_FROM_GDRIVE):
USERNAME=$(engine user-info username)
EMAIL=$(engine user-info email)
Announce: "Detected identity: {USERNAME} ({EMAIL})"
Check for existing config: Use engine fleet to detect existing configs:
engine fleet status
This outputs the fleet directory path and any running sessions.
Then check for yml files:
engine fleet list
Detect pane context (if running inside a fleet pane):
# Check if we're in a fleet tmux session
TMUX_SOCKET=$(echo "$TMUX" | cut -d, -f1 | xargs basename 2>/dev/null || echo "")
if [ "$TMUX_SOCKET" = "fleet" ]; then
CURRENT_PANE_ID="${TMUX_PANE_TITLE:-}"
CURRENT_LABEL=$(tmux -L fleet display-message -p '#{@pane_label}' 2>/dev/null || echo "")
CURRENT_WINDOW=$(tmux -L fleet display-message -p '#W' 2>/dev/null || echo "")
fi
If running in a fleet pane, offer: "You're in pane {CURRENT_LABEL} ({CURRENT_PANE_ID}). Update this pane, or configure the whole fleet?"
Output this block in chat with every blank filled:
Phase 0 proof:
- Identity detected:
________- Existing config:
________- Pane context:
________- Mode:
________
Phase 0 always proceeds to Phase 1 — no transition question needed.
The goal is to discover what the user actually works on, not force them into categories.
Execute AskUserQuestion (multiSelect: true):
"What levels of work do you do?"
- "Project work" — Building features in your codebase
- "Company work" — Company-specific tools, MCPs, internal systems
- "Domain research" — Industry expertise (insurance, finance, legal, etc.)
- "Meta work" — Sessions, reports, engine improvements, documentation
(Personal/experiments/learning → user types in "Other")
For each selected workgroup, execute an AskUserQuestion to discover subprojects. Use hardcoded examples as options — the user names their actual subprojects via "Other".
If Project selected:
Execute AskUserQuestion (multiSelect: true):
"What features or areas of your app do you actively work on?"
- "Viewer" — Frontend viewing/display components
- "Layout" — Page layout and structure analysis
- "API" — Backend API and services
- "Extraction" — Data extraction and parsing
Then execute AskUserQuestion (multiSelect: false):
"Any areas you might work on soon but haven't started?"
- "Yes, I'll list them" — Creates placeholder agents (type in "Other")
- "No placeholders needed" — Skip placeholder creation
If Company selected:
Execute AskUserQuestion (multiSelect: true):
"What company-specific tools or systems do you work with?"
- "MCP tools" — Model Context Protocol integrations
- "Internal dashboards" — Company-internal admin tools
- "Company docs" — Internal documentation and knowledge bases
If Domain selected:
Execute AskUserQuestion (multiSelect: true):
"What domains do you research or need expertise in?"
- "Insurance claims" — Claims processing, Xactimate, adjusting
- "Financials" — Financial analysis and reporting
- "Legal compliance" — Regulatory and legal requirements
If Meta selected:
Execute AskUserQuestion (multiSelect: true):
"What meta-level work do you do?"
- "Sessions analysis" — Reviewing and analyzing agent sessions
- "Reports" — Generating progress and status reports
- "Engine work" — Workflow engine improvements and maintenance
- "Documentation" — Docs, standards, and knowledge management
Key principle: Let the user name their subprojects via "Other". The hardcoded options are starting points, not an exhaustive list.
Execute AskUserQuestion (multiSelect: false):
"How many monitors?"
- "1" — Single monitor setup
- "2" — Dual monitor setup
- "3+" — Three or more monitors
Execute AskUserQuestion (multiSelect: false):
"Agents visible per screen?"
- "4 (2x2)" — Compact grid, 4 agents per monitor
- "6 (2x3)" — Medium grid, 6 agents per monitor
- "9 (3x3)" — Large grid, 9 agents per monitor
- "12 (3x4)" — Maximum density, 12 agents per monitor
Execute AskUserQuestion (multiSelect: false):
"How should workgroups be organized?"
- "Separate tabs per workgroup" — One tab per workgroup (Project tab, Domain tab, Meta tab)
- "Combined" — All in fewer tabs, grouped by relatedness
- "Separate tmux sessions" — Independent tmux sessions per workgroup (launch separately)
Execute AskUserQuestion (multiSelect: false):
"Add a delegation pool for background tasks?"
- "Yes (4 workers)" — Full pool with 4 background workers
- "Yes (2 workers)" — Small pool with 2 background workers
- "No" — No delegation pool
Output this block in chat with every blank filled:
Phase 1 proof:
- Workgroups selected:
________- Subprojects per workgroup:
________- Hardware/layout:
________- Organization:
________- Delegation pool:
________
Execute §CMD_TRANSITION_PHASE_WITH_OPTIONAL_WALKTHROUGH:
completedPhase: "1: Interview"
nextPhase: "2: Generate Layout"
prevPhase: "0: Setup"
Based on organization preference:
For each subproject discovered, gather three things during the interview:
~/.claude/agents/#needs-* tags this agent handlesGenerate a yml pane block with all three:
- {workgroup}-{subproject}:
- export TMUX_PANE_TITLE="{workgroup}-{subproject}"
- export AGENT_DESCRIPTION="{topic description}"
- tmux set-option -p -t $TMUX_PANE @pane_label "{Subproject}"
- clear && engine run --agent {agent_type} --description "$AGENT_DESCRIPTION"
Agent type is chosen based on the subproject's primary function:
Description is a concise topic summary that gets injected into Claude's system prompt via --description. It tells the agent what area of the codebase/domain it specializes in. Write it as if briefing a new team member.
Delegation tags map subprojects to #needs-* tags for dispatch routing. Each active agent should have 1-2 tags:
#needs-viewer, #needs-frontend#needs-layout, #needs-frontend#needs-parsing, #needs-extraction#needs-insurance, #needs-domain#needs-sessions, #needs-metaDelegation tags are used by the dispatch daemon to route work to the right agent. They are NOT passed to run.sh — they are stored in the worker registration files created at startup by persistent agents (future feature) or in pool worker --accepts flags.
For areas mentioned as "might work on soon" — no agent, no description, just engine fleet wait:
- {workgroup}-future-1:
- export TMUX_PANE_TITLE="{workgroup}-future-1"
- tmux set-option -p -t $TMUX_PANE @pane_label "Future"
- engine fleet wait
Pool workers use run.sh --monitor-tags (daemon mode). They receive --agent, --description, and --monitor-tags (delegation tags):
- pool-worker-1:
- export TMUX_PANE_TITLE="pool-worker-1"
- export AGENT_DESCRIPTION="{worker description}"
- tmux set-option -p -t $TMUX_PANE @pane_label "Worker 1"
- clear && engine run --monitor-tags "#needs-delegation,#needs-implementation" --agent operator --description "$AGENT_DESCRIPTION"
--monitor-tags takes comma-separated #needs-* tags that this worker will watch for and auto-dispatch.
This flow handles both:
When /fleet activate is invoked (or user presses 'a' in a placeholder):
CURRENT_PANE_ID="${TMUX_PANE_TITLE:-unknown}"
CURRENT_LABEL=$(tmux -L fleet display-message -p '#{@pane_label}' 2>/dev/null || echo "Future")
CURRENT_WINDOW=$(tmux -L fleet display-message -p '#W' 2>/dev/null || echo "unknown")
Use AskUserQuestion to gather:
Name/Label: "What should this agent be called?"
Agent Type: "What type of agent?"
researcher, builder, operator, analyzer, reviewer, writer, tester, prompterDescription: "Describe what this agent does (1-2 sentences)"
Focus Areas: "What topics does this agent specialize in? (comma-separated)"
# Update pane label (visible immediately)
tmux -L fleet set-option -p @pane_label "{NEW_LABEL}"
ALWAYS ask after setting the label:
Execute AskUserQuestion (multiSelect: false):
"Make this permanent in fleet.yml?"
- "Yes — persist across fleet restarts" — Update yml config so this survives
engine fleet start- "No — temporary until restart" — Keep as runtime-only change (reverts on next fleet launch)
Get yml path (use engine fleet config-path for dynamic resolution):
# Default fleet config:
YML_PATH=$(engine fleet config-path)
# Workgroup-specific config:
YML_PATH=$(engine fleet config-path project)
Read the yml and find the pane entry by TMUX_PANE_TITLE:
export TMUX_PANE_TITLE="{CURRENT_PANE_ID}"Update the pane block:
domain-future-2 → domain-research)@pane_label valueengine fleet wait with engine run --agent {TYPE} --description "{DESC}" --focus "{FOCUS}"Before (placeholder):
- domain-future-2:
- export TMUX_PANE_TITLE="domain-future-2"
- tmux set-option -p -t $TMUX_PANE @pane_label "Future"
- engine fleet wait
After (activated):
- domain-research:
- export TMUX_PANE_TITLE="domain-research"
- export AGENT_DESCRIPTION="Deep research agent for web, docs, and codebase exploration"
- export AGENT_FOCUS="Insurance claims, Xactimate codes, PDF extraction"
- tmux set-option -p -t $TMUX_PANE @pane_label "Research"
- clear && engine run --agent researcher --description "$AGENT_DESCRIPTION" --focus "$AGENT_FOCUS"
Write the updated yml using the Edit tool.
Confirm: "Updated {YML_PATH}. Changes will persist on fleet restart."
Output this block in chat with every blank filled:
Phase 2 proof:
- Layout generated:
________- Agent types assigned:
________- Descriptions written:
________- Placeholders created:
________- Pool workers configured:
________
Execute §CMD_TRANSITION_PHASE_WITH_OPTIONAL_WALKTHROUGH:
completedPhase: "2: Generate Layout"
nextPhase: "3: Present & Confirm"
prevPhase: "1: Interview"
Show the proposed layout with workgroup organization:
## Your Fleet Layout
**Person**: yarik ([email protected])
**Setup**: 2 monitors, 6 agents per view
### Workgroup: Project
**Tab: Project** (2x3 grid)
┌─────────────┬─────────────┬─────────────┐
│ Viewer │ Layout │ Extraction │
├─────────────┼─────────────┼─────────────┤
│ API │ Schema │ Future │
└─────────────┴─────────────┴─────────────┘
### Workgroup: Domain
**Tab: Domain** (2x2 grid)
┌─────────────┬─────────────┐
│ Insurance │ Financials │
├─────────────┼─────────────┤
│ Future │ Future │
└─────────────┴─────────────┘
### Workgroup: Meta
**Tab: Meta** (2x2 grid)
┌─────────────┬─────────────┐
│ Sessions │ Reports │
├─────────────┼─────────────┤
│ Engine │ Future │
└─────────────┴─────────────┘
### Delegation Pool
**Tab: Pool** (2x2 grid)
┌─────────────┬─────────────┐
│ Worker 1 │ Worker 2 │
├─────────────┼─────────────┤
│ Worker 3 │ Worker 4 │
└─────────────┴─────────────┘
Adjust anything? (Add/remove/rename/reorder)
Output this block in chat with every blank filled:
Phase 3 proof:
- Layout presented:
________- User reviewed:
________- User confirmed or adjusted:
________
Execute §CMD_TRANSITION_PHASE_WITH_OPTIONAL_WALKTHROUGH:
completedPhase: "3: Present & Confirm"
nextPhase: "4: Save & Generate"
prevPhase: "2: Generate Layout"
custom: "Go back to Phase 1 | Re-interview for different setup"
Create directories:
mkdir -p ~/.claude/fleet/workers
Generate tmuxinator config:
engine fleet config-path [workgroup]tmux_command: tmux -L fleet -f ~/.claude/engine/skills/fleet/assets/tmux.conftmux_command: tmux -L fleet-{workgroup} -f ~/.claude/engine/skills/fleet/assets/tmux.confAGENT_DESCRIPTION and calls run.sh --agent {type} --description "$AGENT_DESCRIPTION"engine fleet wait (no agent, no description)run.sh --monitor-tags with delegation tags, --agent, and --descriptionReport:
Fleet configured!
To start default: engine fleet start
To start workgroup: engine fleet start {workgroup}
To update: /fleet update
To rearrange: /fleet rearrange
Output this block in chat with every blank filled:
Phase 4 proof:
- Fleet directory created:
________- Tmuxinator config written:
________- Config validated (unique pane IDs):
________- Launch instructions displayed:
________
Execute §CMD_TRANSITION_PHASE_WITH_OPTIONAL_WALKTHROUGH:
completedPhase: "4: Save & Generate"
nextPhase: "5: Update Mode"
prevPhase: "3: Present & Confirm"
custom: "Done | Exit the fleet designer"
Quick operations without full interview.
Execute AskUserQuestion (multiSelect: false):
"What do you want to change?"
- "Add agents to a workgroup" — Create new agent panes in an existing workgroup
- "Remove agents" — Delete agent panes from the fleet config
- "Rename agents/tabs" — Change labels or tab names
- "Rearrange layout" — Reorder tabs, move agents between tabs
(Add/remove workgroups, convert placeholder → type in "Other")
Output this block in chat with every blank filled:
Phase 5 proof:
- Changes applied:
________- Config file updated:
________- User confirmed:
________
For easy reordering:
Show current layout as numbered list:
1. [Project] Viewer
2. [Project] Layout
3. [Project] Extraction
4. [Domain] Insurance
5. [Meta] Sessions
Ask: "Enter new order (e.g., '3,1,2,5,4') or move commands ('move 5 to Project')"
Apply changes, regenerate config
Output this block in chat with every blank filled:
Phase 6 proof:
- New order applied:
________- Config regenerated:
________- User confirmed:
________
If ANY blank above is empty: GO BACK and complete it before proceeding.
Pool workers run in daemon mode (run.sh --monitor-tags), which handles work distribution:
# Workers scan sessions/ for tagged files
engine run --monitor-tags "#needs-implementation,#needs-chores"
# Files with matching tags are auto-dispatched
sessions/*/REQUEST.md # with #needs-implementation tag
Tag-based routing:
--monitor-tags "#needs-implementation" in ymlsessions/ for files with matching tags#needs-* → #active-*), spawn Claude with the resolving skill per §TAG_DISPATCHrun.sh --monitor-tags) to self-schedule work.