# How the Lieutenant Communicates with the Pack Cockpit Dashboard in SwarmForge

> Discover how the Lieutenant communicates with the SwarmForge pack cockpit dashboard using the pack_dashboard_request.sh script and Babashka for seamless request management.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: how-to-guide
- Published: 2026-08-30

---

**The Lieutenant role communicates with the pack cockpit dashboard through a command-line helper script called [`pack_dashboard_request.sh`](https://github.com/unclebob/swarm-forge/blob/main/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:

```bash
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:

```bash
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`](https://github.com/unclebob/swarm-forge/blob/main/pack_dashboard_request.sh) script in [`swarmforge/scripts/pack_dashboard_request.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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.