Workflow definitions

A workflow is a named set of agents with role-specific prompts. Feed one to lokustd via POST /sessions/workflow (or lokust session workflow <file>) and it becomes a session with those agents ready to run in order.

The default 5-agent workflow (architect, security, integration, testing, documentation) is built into the daemon. Custom workflows let you define different agent mixes for different projects — e.g. the ipad-streaming-portal workflow at session-vm/workflows/ipad-streaming-portal.json.

Schema

{
  "name": "string — display name",
  "description": "string — optional one-liner",
  "agents": [
    {
      "id":            "architect",
      "name":          "Platform Architect",
      "system_prompt": "You are a senior platform architect...",
      "task_prompt":   "Design the end-to-end architecture..."
    }
  ]
}

Fields

Field	Type	Required	Notes
name	string	yes	Shown in lokust session ls and in exported .lok files
description	string	no	Free-form
agents	array	yes, ≥1	Executed in array order
agents[].id	string	yes	Stable identifier — used in phase.agent_id
agents[].name	string	yes	Display name — used in phase.name
agents[].system_prompt	string	yes	Claude system parameter
agents[].task_prompt	string	yes	User message for this agent's turn

Execution contract

When /run fires the next phase:

1. The agent's system_prompt becomes the Claude system message.
2. The outputs of all previously completed phases are concatenated (with === <agent name> === headers) and appended after the task_prompt as prior context.
3. The combined user message + system prompt is sent to Claude.
4. The response text becomes phase.output; token counts go into metrics.

Agents later in the array see everything earlier agents produced. Design prompts accordingly — earlier agents are effectively setting up the working state for later ones.

Example — the iPad streaming portal workflow

See session-vm/workflows/ipad-streaming-portal.json for a 5-agent workflow that produces technical specs for:

• Platform Architect — overall architecture + Selkies port analysis
• Cloud Infrastructure Engineer — Terraform modules, GPU droplet specs
• Streaming Engine Developer — Rust pipeline with NVENC
• Input Protocol Engineer — WebRTC data channel protocol
• iPad App Developer — SwiftUI + WebRTC client

Run it:

lokust workflow session-vm/workflows/ipad-streaming-portal.json
lokust session run

Each agent consumes the outputs of the previous ones, producing a self-consistent blueprint.

Best practices

• Keep agent count ≤ 7 — coordination overhead grows with the number of prior-context handoffs. The 5-agent default is a proven sweet spot.
• Order agents by dependency — planners before implementers, implementers before validators, validators before writers.
• Cap prompts at ~500 words — longer prompts drive up cost per token without improving quality. Specificity beats length.
• Don't embed secrets in prompts — workflow files are often committed to git. Pass credentials via the agent-runtime host implementation, not the prompt.
• Output format expectations — ask each agent to produce structured sections (numbered lists, headings). Makes prior-context easier for later agents to consume.

Versioning

The workflow format has no explicit version field today. Additive changes (new optional fields) will not break existing clients. Breaking changes will introduce a version field with a monotonic integer — readers should default to v1 when absent.