Caution
This project is at v0 stage.
It is for research and discussion only.
Do not use it in production.
v0 does not follow Semantic Versioning. Breaking changes can happen at any commit. If you are not a developer of this project, expect things to break often.
The first stable release will be v1.
WORKFLOWASLIST is a language to describe agent task workflows. Its syntax is SYNTAX.ebnf.
The syntax is independent of programming language and execution layer. Any language can implement a WORKFLOWASLIST parser and runtime. This repository is a Python prototype. The workflow files can also run on CLI Code Agents such as:
- Opencode
- Claude Code
- GitHub Copilot CLI
- Codex
Agent interactions are non-deterministic. A natural language instruction can produce different message sequences, different shell commands, and different costs across runs. This makes debugging, maintenance, and caching difficult.
WORKFLOWASLIST extracts the deterministic part of an agent interaction. This part includes the message structure, the shell sequences, and the dependency graph. It puts them into a parseable, shareable, cacheable form. A workflow written in WORKFLOWASLIST always produces the same message list, even though agent responses vary.
The result is an interaction that can be:
- debugged by replay and step inspection
- maintained through version control
- scheduled as a periodic task
- cached at the provider level for cost savings
Think of it as a script for agent message lists, the same way bash is a script for shell commands.
Note
This document is written with LLM assistance. There may be language gaps or inaccuracies. If something is unclear, please ask on Discussions.
This repository is a Python prototype for WORKFLOWASLIST. It contains three packages:
The runtime in packages/wal-runtime can work with Code Agent adapters such as opencode codex as its execution layer.
One line. One step. One job.
- Keep each step small and atomic.
- Do only one thing in each step.
- For LLM steps. Use short text. If more explanation is needed, write a document and reference it.
- For shell steps. Do not use pipe,
&&or||. Write a script file instead and call it. - Split any step that does more than one job. Reference documents and scripts when needed.
This approach creates clear, maintainable and debuggable workflows.