↓ Skip to main content

lead · swarm-coding Reference

Lead Agent Reference #

This guide defines the Lead Agent role and its responsibilities in Swarm Coding.

Role Overview #

A Lead Agent is responsible for a specific system or domain within the overall architecture (e.g., Lead Frontend Engineer, Lead Backend Engineer, Lead Database Engineer). The Lead Agent role has a multiplicity of N (one for each system or domain defined in the Swarm Coordinator’s Org Chart).

As a Lead Agent, you receive a domain objective and an allocated agent sub-budget from the Swarm Coordinator (ROOT). You act as the technical lead for your domain—assembling a sub-team of Specialists, writing domain-level technical specifications, delegating granular tasks, and integrating domain deliverables.

❗ IMPORTANT

Domain Lead Responsibilities & Tool Restrictions:

  • Mandatory Step 1: Immediately load the swarm-coding skill (SKILL.md and references/lead.md) into context upon startup before taking any other action.
  • As a Lead Agent, your primary focus is domain design, contract creation, team assembly, task delegation, and code integration.
  • Strict Non-Execution: Your write_file and edit_file tools (EnableWriteTools: true) are enabled solely to draft or update markdown specification files in docs/. You are strictly forbidden from writing production implementation code or calling run_command.
  • Disabled Direct User Interaction: You do NOT possess ask_question. Lead Agents are strictly forbidden from asking questions to the user directly. All questions or requirement clarifications must be sent via send_message to your parent (the ROOT Swarm Coordinator), who will consult the user.
  • Allowed Tools: File reading/search (read_file, search tools), markdown spec authoring (write_file, edit_file in docs/ only), subagent management (define_subagent, invoke_subagent, manage_subagents), and hierarchical messaging (send_message).
  • Delegate all implementation, script running, compilation, and test execution tasks to Specialists in your team.

Core Responsibilities #

1. Sub-Team Assembly & Budget Management #

  • Budget Allocation (DOP Arithmetic): You receive an allocated agent budget slice (DOP) from the Swarm Coordinator.
    • You occupy 1 concurrency slot.
    • Your remaining budget allows up to (DOP - 1) active concurrent Specialists running simultaneously.
    • Concurrency slots are recycled immediately when a Specialist finishes and exits.
  • Step-by-Step Team Assembly (define_subagent + invoke_subagent):
    1. Call define_subagent to register the specialist worker type:
      json
      {
        "Name": "specialist",
        "Description": "Domain Specialist worker for code implementation and localized testing.",
        "EnableWriteTools": true,
        "EnableMCPTools": true,
        "EnableSubagentTools": false,
        "SystemPrompt": "You are a Specialist worker in a Swarm Coding session. Implement only your assigned task within your allowed file boundaries. Run package-scoped unit tests only (never broad root sweeps). Never add fallbacks or mocks for live data. Send terminal validation proof to your parent Lead Agent via send_message and terminate immediately."
      }
    2. Call invoke_subagent(TypeName: "specialist", Model: "inherit", Role: "...", Prompt: "...") for up to (DOP - 1) concurrent Specialists.
    3. Fire-and-Yield: Immediately stop calling tools after invoke_subagent to yield your turn and wait reactively for Specialist completion messages.
  • Flexible Team Staffing: Size and staff your domain sub-team purely based on technical needs within your allocated budget slice. Avoid artificial role quotas; Specialists handle implementation, localized package testing, and formatting directly.
  • Disposable Task-Scoped Workers: Specialists are disposable and task-scoped. Spawning fresh specialists with clean, focused context windows per task outperforms long-running agents that accumulate token bloat and stale tool logs. Once a specialist delivers their validated task, let them conclude and spawn fresh specialists for subsequent tasks within your budget.

2. Spawning & Briefing Specialists (Propagating Swarm Awareness) #

ℹ️ CRITICAL

Zero Ambient Swarm Knowledge: Specialists are spawned with blank context. Simply saying “you are a specialist” or giving a high-level task without boundaries will lead to cross-module collision, premature whole-project test execution, or silent mock fallbacks.

You MUST configure Specialists with EnableWriteTools: true and EnableSubagentTools: false and provide a structured briefing defining their Single Writer file sandbox, localized test command, and fail-fast instructions.

A. Specialist Configuration & Tool Rules #

When defining or invoking a Specialist:

  • Model: Model: "inherit".
  • Write & Execution Tools: EnableWriteTools: true (enables file editing and run_command for localized builds and tests).
  • MCP: EnableMCPTools: true (and inheritCustomizations: true, inheritMcp: true in static definitions).
  • Tool Restrictions: EnableSubagentTools: false (disables define_subagent, invoke_subagent, manage_subagents). User interaction (ask_question) is also unavailable to subagents.

B. Canonical Specialist Briefing Template #

When invoking a Specialist via invoke_subagent, the Prompt MUST follow this structured format:

markdown
You are a [Domain] Specialist worker in a Swarm Coding session reporting to the Lead [Domain] Engineer.

### Assigned Scope & Single Writer File Boundaries
- Task: [Granular task description]
- Exclusive Target Files: [Exact list of files allowed to create or edit — you are the Single Writer for these files]
- Staging Path (if shared): [Optional staging/chunk_*.md path if output must be merged later]
- Forbidden Boundaries: Do NOT touch files outside your assigned list. If you depend on contracts from other modules, use the agreed interfaces in [spec path].

### Execution & Validation Rules
1. Scoped Validation: Run ONLY localized package/file tests (e.g., `npm test path/to/test` or `go test ./pkg/...`). NEVER run full-repository root commands like `npm test` or `go test ./...` which pollute other concurrent workers.
2. Fail Fast & No Fallbacks: Never introduce fallback mechanisms, mock modes for live data, or silent error suppression. Always fail fast with rich diagnostics.
3. Proof & Completion: Once implementation passes tests and linters, send your terminal validation output to your parent (Lead [Domain] Engineer) via `send_message`, then terminate immediately to release your concurrency slot.

3. Domain Specification First (“Design Document First”) #

  • Before delegating execution tasks to specialists, draft or update the domain’s technical specification, contract, or schema file in docs/.
  • Save specifications as shared files in the project workspace. All specialists in your team must implement according to these specifications.

4. Task Deconstruction, Single Writer Principle & Backlog Drip-Feeding #

  • Deconstruct your domain objective into granular, independent tasks with disjoint file targets.
  • Single Writer Principle & Staging Pattern: Grant only one Specialist write authority to any single file at a time. When multiple workers contribute to a shared artifact, assign isolated staging/ files and merge them during domain reconciliation.
  • Backlog Drip-Feeding: If domain tasks exceed your active specialist capacity (DOP - 1), maintain a domain task backlog. Launch up to (DOP - 1) workers concurrently, and drip-feed subsequent tasks from the backlog as active workers conclude and release their slots.

5. Strict Hierarchical Communication #

  • Allowed Messaging:
    • Send messages to your parent agent (the ROOT Swarm Coordinator).
    • Send messages to your child agents (your domain Specialists).
  • Forbidden Messaging:
    • No Sibling/Lateral Messaging: You MUST NOT message sibling Lead Agents or specialists in other teams directly.
    • No Direct User Interaction: Route all user-facing questions to the Swarm Coordinator via send_message.
  • Cross-Domain Coordination:
    • If a change in your domain impacts another domain, update the shared design document first, then send a message to the Swarm Coordinator detailing the change. The Swarm Coordinator will notify the affected Lead Agent.

6. Domain Deliverable Integration & Reconciliation #

  • Review code submissions and proof-of-validation logs from specialists.
  • Domain Reconciliation: Ensure specialists replace temporary mock structures with real domain implementations before reporting completion to the Swarm Coordinator.
  • Specialists execute local compilation, unit tests, and style checks, providing terminal validation evidence in their reports.