Interactive agent fleet designer - configure your multi-agent workspace.

Fleet Protocol (The Workspace Architect)

Interactive agent fleet designer. Helps users configure their multi-agent workspace based on their workflow, not generic categories.

Core Concepts

Workgroups

High-level themes that organize your work. Not everyone has all of these:

Subprojects

Actual features/areas you work on — discovered through interview, not picked from a menu.

• Bad: "Frontend: Components" (generic)
• Good: "Viewer", "Layout", "Extraction UI" (your actual work)

Placeholders

Slots for areas you don't know yet. Create "Future" agents to reserve space.

Subcommands

0. Setup Phase

1. Auto-detect identity (per ¶INVINFERUSERFROMGDRIVE):

``bash USERNAME=$(engine user-info username) EMAIL=$(engine user-info email) `` Announce: "Detected identity: {USERNAME} ({EMAIL})"

1. Check for existing config: Use engine fleet to detect existing configs:

``bash engine fleet status `` This outputs the fleet directory path and any running sessions.

Then check for yml files: ``bash engine fleet list ``

- If configs found: "Found existing fleet config. Update it, or start fresh?" - If no configs: "No existing fleet configuration found — let's design one from scratch!"

1. Detect pane context (if running inside a fleet pane):

``bash # Check if we're in a fleet tmux session TMUXSOCKET=$(echo "$TMUX" | cut -d, -f1 | xargs basename 2>/dev/null || echo "") if [ "$TMUXSOCKET" = "fleet" ]; then CURRENTPANEID="${TMUXPANETITLE:-}" CURRENTLABEL=$(tmux -L fleet display-message -p '#{@panelabel}' 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 {CURRENTLABEL} ({CURRENTPANE_ID}). Update this pane, or configure the whole fleet?"

Phase 0 always proceeds to Phase 1 — no transition question needed.

1. Interview Phase (Discovery-Based)

The goal is to discover what the user actually works on, not force them into categories.

Round 1: Workgroups

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

Round 2: Subproject Discovery (per workgroup)

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.

Round 3: Hardware & Layout

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

Round 4: Organization

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 an Intakes tab for per-project inbox grooming (/intake)?"
- "Yes — one pane per project" — An Intakes tab with one agent pane per Linear project (you name them); invoke /intake in a pane to groom that project's feedback inbox
- "Yes — projects + a spare" — Same, plus one Future placeholder pane to activate for a new project later
- "No" — No Intakes tab

2. Generate Layout Phase

Workgroup → Tab Mapping

Based on organization preference:

• Separate: One tab per workgroup, subprojects as agents within
• Combined: Merge related workgroups (e.g., Project + Meta)
• Separate sessions: Generate multiple tmuxinator configs

YAML String Safety

[!!!] QUOTE ALL STRING VALUES IN YML. YAML silently converts unquoted values into non-string types. This causes runtime bugs that are invisible until the config is parsed.

Dangerous unquoted values (YAML interprets these as non-strings):

Rule: Always double-quote ALL string values in generated yml — descriptions, labels, env var values, command arguments. The only safe unquoted values are simple single-word identifiers with no special characters.

Examples:

# BAD — "Deep research: web and docs" is parsed as nested mapping
- export AGENT_DESCRIPTION=Deep research: web and docs

# BAD — "no" becomes boolean false
- export AGENT_FOCUS=no specific focus

# GOOD — always quote
- export AGENT_DESCRIPTION="Deep research: web and docs"
- export AGENT_FOCUS="no specific focus"
- tmux set-option -p -t $TMUX_PANE @pane_label "Research"

Agent Generation

For each subproject discovered, gather three things during the interview:

1. Agent type — the persona from ~/.claude/agents/
2. Description — 1-3 sentence topic description (what this agent works on)
3. Delegation tags — which #needs-* tags this agent handles

Generate 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:

• operator — General-purpose work (API, schema, engine, etc.)
• refiner — Extraction, parsing, prompt iteration
• reviewer — Visual QA, review workflows
• researcher — Domain research, deep dives
• analyzer — Code/doc analysis, pattern identification
• writer — Documentation, reports
• tester — Test fixtures, coverage
• builder — TDD implementation
• debugger — Bug investigation
• critiquer — Design critique, code review

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:

• Viewer → #needs-viewer, #needs-frontend
• Layout → #needs-layout, #needs-frontend
• Parsing → #needs-parsing, #needs-extraction
• Insurance → #needs-insurance, #needs-domain
• Sessions → #needs-sessions, #needs-meta

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

Placeholder Agents

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

Intake Panes

Intake panes are ordinary interactive agent panes — one per Linear project — where the user invokes /intake to run an inbox-grooming wave for that project. They use run.sh --agent operator (the operator runs the /intake protocol); no daemon, no --monitor-tags.

- intakes-{project-slug}:
    - export TMUX_PANE_TITLE="intakes-{project-slug}"
    - export AGENT_DESCRIPTION="Intake grooming for the '{Project}' Linear project. Drain the inbox, organize + consolidate feedback, triage each signal toward an outcome, graduate ripe items to tickets. Run /intake to start a wave."
    - tmux set-option -p -t $TMUX_PANE @pane_label "{Short Label}"
    - clear && ~/.claude/scripts/run.sh --agent operator --description "$AGENT_DESCRIPTION"

Generate one such pane per project the user names, and (if they chose "projects + a spare") a trailing intakes-future-1 placeholder that runs ~/.claude/scripts/fleet.sh wait. See /intake for what a grooming wave does.

Legacy — Delegation Pool: earlier fleets had a pool tab of worker.sh --accepts daemon workers that auto-picked up #delegated-* work. That feature is deprecated; new fleets use the Intakes tab instead. If a user explicitly wants background daemon workers, the old worker.sh --pane-id … --accepts "#needs-delegation,#needs-implementation" --agent operator form still works.

Activating or Updating a Pane

This flow handles both:

• Placeholder activation: Converting a "Future" slot to a real agent
• Self-update: Modifying an existing pane's configuration

When /fleet activate is invoked (or user presses 'a' in a placeholder):

Step 1: Gather Context

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

Step 2: Ask Configuration Questions

Use AskUserQuestion to gather:

1. Name/Label: "What should this agent be called?"

- Suggest based on workgroup (e.g., domain → research-related names)

1. Agent Type: "What type of agent?"

- Options: researcher, builder, operator, analyzer, reviewer, writer, tester, prompter

1. Description: "Describe what this agent does (1-2 sentences)"

- Example: "Deep research agent for web, docs, and codebase exploration"

1. Focus Areas: "What topics does this agent specialize in? (comma-separated)"

- Example: "Insurance claims, Xactimate codes, PDF extraction"

Step 3: Apply Immediately

# Update pane label (visible immediately)
tmux -L fleet set-option -p @pane_label "{NEW_LABEL}"

Step 4: Prompt for Permanent Update

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)

Step 5: Update Yml (if user said Yes)

1. Get yml path (use engine fleet config-path for dynamic resolution):

``bash # Default fleet config: YMLPATH=$(engine fleet config-path) # Workgroup-specific config: YMLPATH=$(engine fleet config-path project) ``

1. Read the yml and find the pane entry by TMUXPANETITLE:

- Search for line containing export TMUXPANETITLE="{CURRENTPANEID}" - This identifies the pane block to update

1. Update the pane block:

- Change the pane key (e.g., domain-future-2 → domain-research) - Update @pane_label value - Replace engine fleet wait with engine run --agent {TYPE} --description "{DESC}" --focus "{FOCUS}" - Add env var exports for description/focus

Before (placeholder): ``yaml - domain-future-2: - export TMUXPANETITLE="domain-future-2" - tmux set-option -p -t $TMUXPANE @panelabel "Future" - engine fleet wait ``

After (activated): ``yaml - domain-research: - export TMUXPANETITLE="domain-research" - export AGENTDESCRIPTION="Deep research agent for web, docs, and codebase exploration" - export AGENTFOCUS="Insurance claims, Xactimate codes, PDF extraction" - tmux set-option -p -t $TMUXPANE @panelabel "Research" - clear && engine run --agent researcher --description "$AGENTDESCRIPTION" --focus "$AGENTFOCUS" ``

1. Write the updated yml using the Edit tool.

1. Confirm: "Updated {YML_PATH}. Changes will persist on fleet restart."

3. Present & Confirm Phase

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      │
└─────────────┴─────────────┘

### Intakes
**Tab: Intakes** (2x3 grid) — one pane per Linear project, invoke `/intake` per pane
┌─────────────┬─────────────┬─────────────┐
│ Intake Sys  │ Differ      │ Email Class │
├─────────────┼─────────────┼─────────────┤
│ Doc Extract │ Claims & Pol│ Future      │
└─────────────┴─────────────┴─────────────┘

Adjust anything? (Add/remove/rename/reorder)

4. Save & Generate Phase

1. Create directories:

``bash mkdir -p ~/.claude/fleet/workers ``

1. Generate tmuxinator config:

- Location: Resolve via engine fleet config-path [workgroup] - Default fleet: tmuxcommand: tmux -L fleet -f ~/.claude/engine/skills/fleet/assets/tmux.conf - Workgroup fleet: tmuxcommand: tmux -L fleet-{workgroup} -f ~/.claude/engine/skills/fleet/assets/tmux.conf - Each active pane exports AGENTDESCRIPTION and calls run.sh --agent {type} --description "$AGENTDESCRIPTION" - Placeholder panes call engine fleet wait (no agent, no description) - Intake panes use run.sh --agent operator — one per Linear project, invoke /intake to groom that project's inbox

1. Report:

``` Fleet configured!

To start default: engine fleet start To start workgroup: engine fleet start {workgroup} To update: /fleet update To rearrange: /fleet rearrange ```

5. Update Mode

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

6. Rearrange Mode

For easy reordering:

1. Show current layout as numbered list:

`` 1. [Project] Viewer 2. [Project] Layout 3. [Project] Extraction 4. [Domain] Insurance 5. [Meta] Sessions ``

1. Ask: "Enter new order (e.g., '3,1,2,5,4') or move commands ('move 5 to Project')"

1. Apply changes, regenerate config

The Intakes Tab

The Intakes tab holds one interactive agent pane per Linear project. Each pane runs an operator agent; the user invokes /intake in it to run an inbox-grooming wave for that project (drain new feedback → organize + consolidate → triage each signal → graduate ripe items to tickets → debrief). Panes are ordinary run.sh --agent operator panes — no daemon, no tag monitoring. Add a trailing intakes-future-1 placeholder (fleet.sh wait) as a cheap slot for a new project.

Legacy — Daemon Mode: earlier fleets ran a pool tab of daemon workers (worker.sh --accepts / run.sh --monitor-tags) that scanned sessions/ for #delegated-* tags and auto-spawned the resolving skill per §TAG_DISPATCH. Deprecated in favor of the Intakes tab. Still available on request for background delegation workloads.

Invariants

• ¶INVYMLISSOURCEOF_TRUTH: The fleet yml config is the single source of truth. No separate metadata files.
• ¶INVINTAKESTAB_LAST: The Intakes tab (formerly the pool tab) is always last.
• ¶INVUNIQUEAGENT_IDS: Agent IDs must be unique across all tabs.
• ¶INVDISCOVERDONT_PRESCRIBE: Interview discovers subprojects; don't force generic categories.
• ¶INVPLACEHOLDERSARE_CHEAP: Encourage "Future" slots — easy to convert later.
• ¶INVINTAKEPANEPERPROJECT: An Intakes tab has one interactive /intake pane per Linear project (plus an optional spare) — not daemon workers.