Workflow Orchestration

Overview

ArmaFlow is the workflow engine for armament. .armaflow files define multi-step, multi-agent workflows with parallel execution, chaining with structured output, approval gates, and fake-context seeding. Flow files live in .arma/flows/.

New: JSON format and Visual Builder. Flows can now be stored as .armaflow.json with nodes and edges matching React Flow’s graph format. The Flow Builder (accessible via the 🔄 icon in the web UI) provides a full drag-and-drop visual editor with dagre auto-layout, per-node agent configuration (model, provider, timeout, budget), injector nodes (seed context, fake context, allow paths, complete schema), and condition nodes with true/false branching handles. Saving a JSON flow automatically regenerates the text .armaflow for TUI compatibility. See Flow Builder for full details.

For UX scripting (aliases, keybindings, macros), see Scripting.

Quick Example

/name code-review
/description Automated code review pipeline
/trigger manual
/budget 5.00

/spawn reviewer "Review the diff for bugs and style issues"
/wait reviewer complete
/chain summarizer "Summarize the findings into a report"
/log "Code review complete"

Execution Model

Commands execute sequentially top-to-bottom. Use /parallel blocks for concurrency. Use /chain to pass structured output between agents. Use /join to wait for multiple agents simultaneously.

Commands Reference

Command	Description
`/name`	Flow name
`/description`	Flow description
`/trigger`	How the flow is invoked (manual, event, cron, webhook)
`/budget`	Maximum spend for this flow execution
`/timeout`	Maximum wall-clock time for the flow
`/spawn <name> "<task>"`	Create agent channel with task
`/spawn <name>`	Create agent channel (no task, starts idle)
`/msg <target> "text"`	Send message to a running agent
`/seed <name> <role> <msg>`	Inject fake history (role: user/assistant)
`/wait <name> complete`	Pause until agent calls report_complete
`/join [a, b, ...]`	Wait for ALL named agents
`/collect [a, b] -> c`	Buffer results, forward to output agent
`/sleep <ms>`	Pause execution
`/parallel` / `/end`	Run enclosed steps concurrently
`/approve "question?"`	Pause for Yes/No confirmation
`/chain <A> -> <B>`	Pass structured output from A to B
`/complete`	Declare structured output schema for chain
`/field name type [required] "desc"`	Field within a complete block
`/pipe <script>`	Pipe agent output through external script
`/broadcast "message"`	Send to all running agents
`/set var value`	Set a flow variable
`/emit event data`	Emit a custom event
`/log "text"`	Write to flow log
`/kill <name>`	Terminate an agent

Examples

Parallel Fan-Out

/parallel
  /spawn security "Audit for vulnerabilities"
  /spawn performance "Profile for bottlenecks"
  /spawn docs "Check documentation coverage"
/end

/join security performance docs
/spawn summarizer "Combine all findings into a final report"
/wait summarizer complete

Fake Context Injection

/spawn synthesizer
/seed synthesizer assistant "I've dispatched 4 specialists to audit the codebase."
/collect specialist-a specialist-b specialist-c -> synthesizer
/msg synthesizer "All reports above. Rank by severity..."
/wait synthesizer complete

/seed injects fake assistant/user messages — the downstream agent sees them as real conversation history.

Chaining with Structured Output

/chain researcher -> writer
  /complete --purpose "Findings feed documentation writer"
    /field key_findings string[] required "Main discoveries"
    /field confidence enum(low,medium,high) required "Rating"
    /field sources string[] "Reference URLs"

The /complete block auto-generates a report_complete tool on the agent with the declared fields. Types: string, string[], number, boolean, enum(a,b,c). Fields marked required must be provided.

Approval Gates

/approve "All checks passed. Deploy to production?"

Flow pauses until the operator answers Yes/No.

Pipe (external scripts)

/pipe analyst -> ./scripts/format-results.py

Structured JSON output is piped through the script’s stdin. The script’s stdout replaces the result. Works with any language (Python, Node, bash, etc.).

Agent Completion Protocol

Agents spawned by flows complete ONLY by calling the report_complete tool:

On spawn: report_complete is registered with the declared schema (or a generic output string field if no schema)
Sticky reminder: A sticky note (position: bottom) reminds the agent on every turn to call report_complete when done
Idle nudge: If the agent is idle for 60+ seconds without calling complete, it receives a nudge message
Zombie detection: At the A2A layer, unresponsive workers are detected and reported via onWorkerError
No fallback: The flow waits (up to timeout) for the explicit call

Flow Management

/flow run deploy-pipeline       # Start a flow
/flow test deploy-pipeline      # Dry-run (validate without executing)
/flow list                       # List available flows
/flow stop                       # Stop the currently running flow

Execution Status

Each flow tracks: status (running, completed, failed, cancelled), start/completed timestamps, and duration.

Flow Channel

Every flow opens #flow-<name> as a process log channel:

Step counters and agent spawn events
Worker output previews
Nudges sent to idle agents
Final execution summary

Workers appear as children of the flow channel in the sidebar.