How the Lieutenant Communicates with the Pack Cockpit Dashboard in SwarmForge

The Lieutenant role communicates with the pack cockpit dashboard through a command-line helper script called pack_dashboard_request.sh, which forwards requests to a Babashka implementation that manipulates the dashboard's file-based request store.

In the unclebob/swarm-forge repository, the Lieutenant serves as a coordination role that does not run as a pack agent. Instead, it interacts with the cockpit-style dashboard through a lightweight CLI workflow. This architecture enables stateless, file-based communication without requiring persistent network connections or dedicated API clients.

The Communication Workflow

The Lieutenant handles two primary interaction types with the dashboard: answering pending requests and requesting clarifications. Both follow the same fundamental pattern—write content to a temporary file, then invoke the helper script with appropriate arguments.

Answering a Pending Request

When the Lieutenant receives a follow-up in the format [id] text, it constructs a response by writing the answer to a temporary file and invoking the answer command:

echo "All systems green." > ./tmp/answer.txt
pack_dashboard_request.sh answer req-20230830a1b2c3 ./tmp/answer.txt

This command pattern tells the dashboard to:

• Locate the pending request matching <id> in /.swarmforge/dashboard/requests/pending
• Move the request file to the done directory
• Attach the answer file content as the response via the complete-pending-request! function

Requesting Clarification

When the Lieutenant needs additional information from the pack, it creates a clarification request:

echo "What is the target branch for deployment?" > ./tmp/question.txt
pack_dashboard_request.sh clarify ./tmp/question.txt

The clarification workflow creates a new request file under /.swarmforge/dashboard/clarifications/pending with a generated clar-… ID through the create-clarification! function.

The Helper Script Architecture

The pack_dashboard_request.sh script in swarmforge/scripts/pack_dashboard_request.sh functions as a thin wrapper that delegates all operations to the Babashka implementation in swarmforge/scripts/pack_dashboard_request.bb.

The Babashka script performs three key operations:

• Discovers context — Identifies the SwarmForge project-root and sender-role
• Handles answers — Locates, moves, and completes pending request files
• Creates clarifications — Generates new clarification entries with unique IDs

This two-layer design separates the simple CLI interface from the complex file-manipulation logic, making the system maintainable and testable.

Source File Reference

File	Purpose
swarmforge/roles/lieutenant.prompt	Defines the Lieutenant's communication contract including answer and clarify commands
swarmforge/scripts/pack_dashboard_request.sh	Shell wrapper that forwards arguments to the Babashka implementation
swarmforge/scripts/pack_dashboard_request.bb	Full implementation of dashboard request handling including complete-pending-request! and create-clarification! functions

Summary

• The Lieutenant communicates with the pack cockpit dashboard through pack_dashboard_request.sh, not as a persistent agent
• Answer workflow: Write response to file, run pack_dashboard_request.sh answer <id> <file>
• Clarification workflow: Write question to file, run pack_dashboard_request.sh clarify <file>
• The Babashka script pack_dashboard_request.bb implements the actual file operations against the dashboard's request store
• All communication is file-based, requiring no network connection or API client

Frequently Asked Questions

Why doesn't the Lieutenant run as a pack agent?

The Lieutenant is designed as a coordination role that operates outside the pack execution environment. According to the source code in swarmforge/roles/lieutenant.prompt, it communicates through command-line helpers rather than direct agent integration, allowing it to function across different contexts without pack infrastructure dependencies.

What happens to pending requests after they're answered?

The pack_dashboard_request.bb script moves answered requests from /.swarmforge/dashboard/requests/pending to the done directory and records the response content in the request record. This archive-preserving design maintains an audit trail of all Lieutenant-dashboard interactions.

Can the Lieutenant list or create new requests, not just answer them?

Yes. The pack_dashboard_request.bb implementation includes functions for listing requests and creating new dashboard entries, though the primary Lieutenant workflow focuses on answering and clarifying existing requests as defined in its role prompt.

Is pack_dashboard_request.sh safe to run manually?

The helper script is designed for programmatic use by the Lieutenant role, but can be invoked manually with proper arguments. All operations are file-based and idempotent, though users should ensure correct file paths and IDs to avoid dashboard state inconsistencies.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}