Add YAML workflow language and execution

Author: sksingh2005

doc/cheatsheet/en/03-tools.md

@@ -19,11 +19,15 @@ beside the built-in ones. orangu connects; it does not launch them.
 
 | Command | What it does |
 | --- | --- |
-| `[mcp.<name>]` | A service in `orangu.conf`: its URL (usually ending in `/mcp`), `timeout`, `enabled`, `required`, `enabled_tools` / `disabled_tools`. |
-| `approval_mode = auto` | Or `prompt` (ask per call), `writes` (ask unless the tool is read-only), `deny`. Unattended and review runs deny what needs asking. |
-| `/mcp` `/mcp refresh` | What is connected, disabled or failed, and how many tools each gave; reconnect and rediscover. |
-| `/mcp add <name> <command>` | Write a profile and connect it; `/mcp remove <name>` drops it. |
-| `mcp__<server>__<tool>` | How they are named, so nothing collides; `/tools` lists them. Tools only. |
+| `[mcp.<name>]` | A configured Streamable HTTP service; URL, filters and approval are in `orangu.conf`. |
+| `/mcp` `/mcp refresh` | Show and reconnect; `/mcp add` / `remove` manage one. `/tools` lists `mcp__<server>__<tool>`. |
+
+## Workflow files
+
+| Command | What it does |
+| --- | --- |
+| `orangu --check-workflow run.yaml` / `--workflow run.yaml` | Validate every job without executing; then run the jobs in order. |
+| `orangu -w DIR loop status` `pause` `resume` `clear` | Inspect, pause, continue, or cancel a workflow loop. |
 
 ## The rest of the stack
 

doc/manual/en/40-terminal.md

@@ -22,7 +22,9 @@ The sync runs in the background so it never delays startup. Its progress and res
 | `-a`  | `--all`       | Reopen the workspace tabs that were open at the end of the last run. |
 | `-t`  | `--theme`     | Apply a theme to the terminal interface for this run. Built-in names and paths to `.theme` files are accepted. |
 | `-p`  | `--prompt`    | Run a single prompt or command and exit — no terminal UI and no session on disk. See One-shot mode below. |
-| `-q`  | `--quiet`     | Print nothing on success — the exit code is the result. Applies to the modes that print and exit (`-p`, `-l`, `-s`). |
+|       | `--workflow FILE` | Validate and execute every job in a YAML workflow. |
+|       | `--check-workflow FILE` | Validate a YAML workflow completely without executing it or loading configuration. |
+| `-q`  | `--quiet`     | Print nothing on success — the exit code is the result. Applies to the modes that print and exit, including workflows. |
 | `-l`  | `--list`      | List all stored sessions as a `SESSION WORKSPACE BRANCH DATE` table and exit. |
 | `-i`  | `--init`      | Interactively create `~/.orangu/orangu.conf` and exit (see the Configuration chapter). |
 | `-s`  | `--shell-completions` | Print the shell completion script for the detected shell (`$SHELL`; bash, zsh, or fish) and exit. |
@@ -47,6 +49,60 @@ Two groups of commands are refused rather than run, with a message saying which
 
 `/export` covers the targets that are computed at export time: `pr`, `statistics`, and `duplicates`. `console`, `review`, and `auto review` export what an interactive session accumulated, and report that there is nothing to export.
 
+### YAML workflows
+
+`--workflow FILE` is a thin, ordered YAML layer over the same commands, natural-language prompts, skills, and tools used by one-shot mode. Orangu validates and expands the complete file before the first job starts. Jobs run in declaration order and stop at the first failure; prompts within one job share a conversation.
+
+```yaml
+orangu:
+  version: 1
+  variables:
+    upstream: /home/me/Upstream
+  jobs:
+    - job: pgagroal
+      workspace: /home/me/PostgreSQL/pgagroal
+    - job: orangu
+      workspace: /home/me/Company/orangu
+      role: code
+  functions:
+    export_pr:
+      - command: /export pr
+    move_pdf:
+      - command: /shell mv ${job}-pr.pdf ${upstream}/
+  main:
+    - approved: ${upstream}
+    - call: export_pr
+    - call: move_pdf
+```
+
+`role` may be set globally or per job and defaults to `all`. `${job}` is the current job key; top-level and per-job variables use the same `${name}` form. A job's workspace is a strict path boundary. An existing absolute path supplied through a variable must have an earlier `approved` step before a command can use it outside that workspace.
+
+The boundary has the same meaning as it does elsewhere in Orangu: file and directory tools reject absolute paths and `..` paths that leave the workspace, and a tool's `cwd` must remain inside it. `approved` is an explicit workflow-language opt-in for passing a variable-derived external path to a command; it does not widen those tool roots. `/shell` explicitly invokes the user's platform shell and is therefore not an operating-system sandbox. The validator checks external paths supplied through variables, while literal shell syntax retains `/shell`'s existing semantics.
+
+A function or `main` may also contain the bounded code-and-review `loop` step described in the next chapter. Top-level and job variables are expanded in its objective, duration or goal, checks, and rubric:
+
+```yaml
+  functions:
+    improve_parser:
+      - loop:
+          objective: Fix ${job}'s parser without changing its public API.
+          stop:
+            type: goal
+            condition: All parser tests pass and review finds no regression.
+          review:
+            checks:
+              - cargo test
+            rubric:
+              - correctness
+              - backward compatibility
+  main:
+    - call: improve_parser
+```
+
+`stop.type` is `turns` with a positive `count`, `time` with a duration using `s`, `m`, `h`, or `d`, or `goal` with a reviewer-verifiable `condition`. A workflow loop uses the job's workspace and resolved role. Its saved state is the same state exposed by `orangu loop status`, `pause`, `resume`, and `clear`, so an interrupted workflow loop remains manageable from the CLI.
+
+Run `orangu --check-workflow FILE` first when editing a workflow. It checks YAML structure, variables, function calls and recursion, roles, workspaces, approvals, and every job without contacting an LLM server. Explicit slash commands are also checked before execution: the name must be a built-in command or a skill discovered in that job's workspace, required arguments must be present, and commands that need the interactive terminal are refused. Relative workspace paths are resolved from the workflow file's directory.
+
 ### Quiet mode
 
 `-q` prints nothing on success — no answer, no command output, no diagnostics — and leaves the exit code as the whole result. A failure still prints on stderr and exits non-zero, so `-q` can silence a success without ever hiding a problem:
@@ -56,7 +112,7 @@ orangu -q -p "/export pr"    # writes the PDF, says nothing
 echo $?                      # 0, or 1 with the reason on stderr
 ```
 
-That is what makes it suit a crontab or a `~/.orangu/schedule` job: silent until the day it fails. It applies to the modes that print and exit — `-p`, `-l`, and `-s`. Combining it with `-i` or with the terminal interface is an error rather than a no-op, since neither has diagnostics to separate from its output.
+That is what makes it suit a crontab or a `~/.orangu/schedule` job: silent until the day it fails. It applies to the modes that print and exit — `-p`, `-l`, `-s`, `--workflow`, and `--check-workflow`. Combining it with `-i` or with the terminal interface is an error rather than a no-op, since neither has diagnostics to separate from its output.
 
 `-t`/`--theme` is the other way round: a theme paints the interface — including the terminal's own background and foreground — so it takes effect only when there is an interface. A one-shot ignores it rather than repainting the terminal it printed into.
 

doc/manual/en/45-workflows.md

@@ -0,0 +1,230 @@
+\newpage
+
+# Workflow files
+
+A workflow file describes a set of jobs and the ordered Orangu operations to
+run in each workspace. It is a thin YAML layer over the same slash commands,
+natural-language prompts, skills, and tools available through `orangu -p`.
+
+Validate the complete file before starting it:
+
+```text
+orangu --check-workflow export-prs.yaml
+orangu --workflow export-prs.yaml
+```
+
+`--check-workflow` loads no model configuration and executes nothing. It checks
+every job, workspace, variable, function call, approval, loop definition, and
+explicit slash command. `--workflow` performs the same preflight before it
+loads configuration or starts the first job.
+
+## Complete file
+
+The following workflow runs `/export pr` in two projects and collects both
+PDFs in one explicitly approved directory:
+
+```yaml
+orangu:
+  version: 1
+  role: all
+  variables:
+    upstream: /home/me/Upstream
+  jobs:
+    - job: pgagroal
+      workspace: /home/me/PostgreSQL/pgagroal
+    - job: orangu
+      workspace: /home/me/Company/orangu
+  functions:
+    export_pr:
+      - command: /export pr
+    move_pdf:
+      - command: /shell mv ${job}-pr.pdf ${upstream}/
+  main:
+    - approved: ${upstream}
+    - call: export_pr
+    - call: move_pdf
+```
+
+The root key is `orangu`. `version` is required and is currently `1`. `jobs`
+and `main` must both be non-empty. Unknown keys are errors rather than ignored
+configuration.
+
+## Jobs, roles, and conversations
+
+Each `jobs` entry requires a unique `job` name and an existing `workspace`
+directory. Jobs run sequentially in declaration order and stop at the first
+failure. The complete `main` sequence runs once for every job, with `${job}`
+set to that job's name.
+
+`role` may be declared once under `orangu` or overridden by a job. It defaults
+to `all`; the other v1 values are `code`, `review`, `explorer`, and
+`embeddings`. When the configured endpoint is an Orangu coordinator, the role
+is sent to it for routing. Otherwise Orangu selects a configured server with
+that role, falling back to the default server.
+
+Command steps that reach the model share one conversation within their job.
+The next job starts a separate conversation in its own workspace.
+
+## Variables
+
+Top-level `variables` apply to every job. A job may add variables or override a
+top-level value:
+
+```yaml
+  variables:
+    profile: release
+  jobs:
+    - job: server
+      workspace: server
+      variables:
+        profile: debug
+```
+
+Values may be strings, integers, floating-point numbers, or booleans and are
+inserted with `${name}`. Variables may refer to other variables. `${job}` is
+reserved for the current job name and cannot be redefined. Undefined,
+recursive, malformed, or unterminated references fail validation.
+
+## Functions and execution order
+
+`functions` contains named, reusable lists of steps. A `call` expands a
+function at that exact position, so `main` is the single unambiguous execution
+order:
+
+```yaml
+  functions:
+    build:
+      - command: /build release
+    explain:
+      - command: Explain any build warnings and fix actionable ones.
+  main:
+    - call: build
+    - call: explain
+```
+
+Functions may call other functions. Unknown calls and direct or indirect
+recursion are validation errors. Function and variable names start with a
+letter or underscore and contain only letters, digits, and underscores.
+
+## Step types
+
+Version 1 has four explicit step types. A step contains exactly one of them.
+
+### `command`
+
+The value is offered to Orangu's existing dispatcher:
+
+```yaml
+  main:
+    - command: /status
+    - command: /code-review authentication
+    - command: Investigate the failing authentication test and fix it.
+```
+
+A built-in slash command runs locally, a workspace skill expands into a model
+prompt, and other text is a natural-language model prompt. Preflight rejects
+unknown slash commands, missing required arguments, and commands that require
+the interactive terminal or persistent terminal session.
+
+### `call`
+
+`call` inserts a named function's steps. Expansion happens separately for each
+job, after its variables and `${job}` have been resolved.
+
+### `approved`
+
+An external path supplied through a variable requires an earlier `approved`
+step. One path or a list of paths may be approved:
+
+```yaml
+  main:
+    - approved:
+        - ${reports}
+        - ${archives}
+    - command: /shell mv report.pdf ${reports}/
+```
+
+Approved paths must already exist. Approval is ordered: placing it after the
+command does not authorize that command. It is an explicit workflow-language
+opt-in for passing a variable-derived external path; it does not widen the
+roots of Orangu's file tools.
+
+File and directory tools reject absolute, `..`, and symlinked paths that leave
+the job workspace, and a tool's `cwd` must remain inside it. `/shell` explicitly
+invokes the user's platform shell and is not an operating-system sandbox.
+Literal shell syntax therefore retains the existing `/shell` semantics.
+
+### `loop`
+
+A loop repeats a tool-enabled work phase followed by an independent,
+tool-free review phase:
+
+```yaml
+  functions:
+    improve_parser:
+      - loop:
+          objective: Fix ${job}'s parser without changing its public API.
+          stop:
+            type: goal
+            condition: All parser tests pass and review finds no regression.
+          review:
+            checks:
+              - cargo test
+            rubric:
+              - correctness
+              - backward compatibility
+  main:
+    - call: improve_parser
+```
+
+Every iteration gives the worker the objective and the previous review. After
+the work phase, Orangu runs the configured checks in the job workspace. The
+reviewer receives the worker report, check results, and branch diff, but no
+tools. Its response becomes feedback for the next iteration.
+
+Each loop has exactly one stopping policy:
+
+| `stop.type` | Required field | Meaning |
+| --- | --- | --- |
+| `turns` | `count` | Stop after a positive number of complete iterations. |
+| `time` | `duration` | Stop at a safe boundary after active time such as `30m` or `2h`. |
+| `goal` | `condition` | Continue until the reviewer verifies the stated condition. |
+
+Durations use `s`, `m`, `h`, or `d`. Orangu never interrupts a tool call or
+review response merely because the duration has elapsed. For a goal loop, the
+reviewer must end with the exact standalone line `LOOP_COMPLETE: yes`; an
+inline mention or optimistic wording does not complete it.
+
+`review.checks` and `review.rubric` are optional lists. Variables are expanded
+in the objective, stop value, checks, and rubric. The default rubric covers
+correctness, regressions, tests, and maintainability; listed entries add
+workflow-specific criteria.
+
+## Managing a workflow loop
+
+Loop progress is stored in Orangu's workspace cache rather than in the
+repository. The same lifecycle commands inspect or control a loop started by a
+workflow:
+
+```text
+orangu --workspace /path/to/project loop status
+orangu --workspace /path/to/project loop pause
+orangu --workspace /path/to/project loop resume
+orangu --workspace /path/to/project loop clear
+```
+
+`status` reports the objective, policy, iteration count, active time, and most
+recent review. `pause` stops at the next safe phase boundary. `resume`
+continues a paused or failed loop with its saved review feedback. `clear`
+cancels the saved state so another loop may start. A per-workspace lock prevents
+two loops from running against the same checkout simultaneously.
+
+## Operational behavior
+
+- `-q` suppresses successful workflow output. Failures still write to stderr
+  and return a non-zero exit status.
+- A loop can modify its workspace but does not commit, push, or open a pull
+  request unless an explicit workflow command does so.
+- Review evidence is bounded before it is sent to the model. Truncation is
+  marked rather than silently treated as complete evidence.
+- Saved loop state is control metadata, not a persisted model conversation.