From 131b71aea95466e2d62716d4ca45fcdee591e703 Mon Sep 17 00:00:00 2001 From: Bryan Helmkamp Date: Sat, 7 Mar 2026 10:01:53 -0500 Subject: [PATCH] Update docs tutorials, examples, and add sub-workflow tutorial Co-Authored-By: Claude Opus 4.6 --- demo/05-branch-loop.dot | 2 +- docs/docs.json | 14 +- docs/examples/solitaire.mdx | 6 +- docs/images/tutorial-sub-workflow-child.svg | 90 +++++++++++ docs/images/tutorial-sub-workflow.svg | 82 ++++++++++ docs/reference/cli-configuration.mdx | 69 +++++++++ docs/tutorials/branch-loop.mdx | 4 +- docs/tutorials/ensemble.mdx | 19 +-- docs/tutorials/sub-workflow.mdx | 145 ++++++++++++++++++ .../examples/solitaire/build-solitaire.dot | 6 +- .../tutorials/branch-loop/branch-loop.dot | 2 +- 11 files changed, 409 insertions(+), 30 deletions(-) create mode 100644 docs/images/tutorial-sub-workflow-child.svg create mode 100644 docs/images/tutorial-sub-workflow.svg create mode 100644 docs/reference/cli-configuration.mdx create mode 100644 docs/tutorials/sub-workflow.mdx diff --git a/demo/05-branch-loop.dot b/demo/05-branch-loop.dot index ab9a77ebe..b50eb1a8c 100644 --- a/demo/05-branch-loop.dot +++ b/demo/05-branch-loop.dot @@ -7,7 +7,7 @@ digraph BranchLoop { plan [label="Plan", prompt="Plan a small Python script (fizzbuzz.py) and a test file (test_fizzbuzz.py) using pytest. Describe what you will create.", shape=tab, reasoning_effort="low"] implement [label="Implement", prompt="Create fizzbuzz.py and test_fizzbuzz.py as planned. Write the files to disk."] - validate [label="Validate", shape=parallelogram, script="python -m pytest test_fizzbuzz.py -v 2>&1 || true"] + validate [label="Validate", shape=parallelogram, script="python3 -m pytest test_fizzbuzz.py -v 2>&1 || true"] gate [shape=diamond, label="Tests passing?"] start -> plan -> implement -> validate -> gate diff --git a/docs/docs.json b/docs/docs.json index dc8a80d32..805d7b7f5 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -78,6 +78,7 @@ "pages": [ "reference/dot-language", "reference/cli", + "reference/cli-configuration", "reference/architecture", "administration/advanced-setup", "administration/security" @@ -98,7 +99,8 @@ "tutorials/branch-loop", "tutorials/parallel-review", "tutorials/multi-model", - "tutorials/ensemble" + "tutorials/ensemble", + "tutorials/sub-workflow" ] }, { @@ -167,7 +169,7 @@ "pages": [ "GET /runs/{id}/compare", "GET /runs/{id}/usage", - "GET /runs/{id}/verifications", + "GET /runs/{id}/verification", { "group": "Run Internals", "icon": "microchip", @@ -192,11 +194,13 @@ ] }, { - "group": "Verifications", + "group": "Verification", "icon": "shield-check", "pages": [ - "GET /verifications", - "GET /verifications/{slug}" + "GET /verification/criteria", + "GET /verification/criteria/{id}", + "GET /verification/controls", + "GET /verification/controls/{id}" ] }, { diff --git a/docs/examples/solitaire.mdx b/docs/examples/solitaire.mdx index e034fc758..ce357aa6f 100644 --- a/docs/examples/solitaire.mdx +++ b/docs/examples/solitaire.mdx @@ -22,9 +22,9 @@ digraph BuildSolitaire { retry_target="impl_setup", fallback_retry_target="impl_game_logic", model_stylesheet=" - * { llm_model: claude-sonnet-4-5; llm_provider: anthropic; } - .hard { llm_model: claude-opus-4-6; llm_provider: anthropic; } - .verify { llm_model: claude-haiku-4-5; llm_provider: anthropic; } + * { llm_model: claude-sonnet; llm_provider: anthropic; } + .hard { llm_model: claude-opus; llm_provider: anthropic; } + .verify { llm_model: claude-haiku; llm_provider: anthropic; } " ] diff --git a/docs/images/tutorial-sub-workflow-child.svg b/docs/images/tutorial-sub-workflow-child.svg new file mode 100644 index 000000000..6f8f02788 --- /dev/null +++ b/docs/images/tutorial-sub-workflow-child.svg @@ -0,0 +1,90 @@ + + + + + + + +ImplementAndTest + + +start + + + + + +Start + + + +implement + +Implement + + + +start->implement + + + + + +exit + + + + + +Exit + + + +validate + +Validate + + + +implement->validate + + + + + +gate + +Tests passing? + + + +validate->gate + + + + + +gate->exit + + +Pass + + + +gate->implement + + +Fix + + + diff --git a/docs/images/tutorial-sub-workflow.svg b/docs/images/tutorial-sub-workflow.svg new file mode 100644 index 000000000..8a625182a --- /dev/null +++ b/docs/images/tutorial-sub-workflow.svg @@ -0,0 +1,82 @@ + + + + + + + +SubWorkflow + + +start + + + + + +Start + + + +plan + +Plan + + + +start->plan + + + + + +exit + + + + + +Exit + + + +impl + +Implement & Test + + + +plan->impl + + + + + +review + +Review + + + +impl->review + + + + + +review->exit + + + + + diff --git a/docs/reference/cli-configuration.mdx b/docs/reference/cli-configuration.mdx new file mode 100644 index 000000000..f0f33b947 --- /dev/null +++ b/docs/reference/cli-configuration.mdx @@ -0,0 +1,69 @@ +--- +title: "CLI Configuration" +description: "Configure default settings for the Arc CLI with cli.toml" +--- + +Arc loads CLI defaults from `~/.arc/cli.toml` so you don't have to pass common flags every time. The file is optional — if it doesn't exist, built-in defaults are used. + +## File location + +The default path is `~/.arc/cli.toml`. Arc silently skips loading if the file is missing. + +## Precedence + +CLI flags always take the highest priority: + +1. **CLI flags** — always win +2. **`cli.toml`** — used when no flag is provided +3. **Built-in defaults** — used when neither flag nor config is set + +## Full example + +```toml +[agent] +provider = "anthropic" +model = "claude-opus-4-6" +permissions = "read-write" +output_format = "text" + +[llm] +model = "claude-sonnet-4-5" +``` + +All fields are optional. You can include just the sections and keys you want to override. + +## `[agent]` section + +Defaults for `arc agent` sessions. + +| Key | Description | Values | Default | +|---|---|---|---| +| `provider` | LLM provider | `"anthropic"`, `"openai"`, `"gemini"`, etc. | `"anthropic"` | +| `model` | Model name | Any model ID from `arc models list` | Per provider | +| `permissions` | Tool permission level | `"read-only"`, `"read-write"`, `"full"` | `"read-write"` | +| `output_format` | Output format | `"text"`, `"json"` | `"text"` | + +### Permission levels + +- **`read-only`** — auto-approves read tools (`read_file`, `grep`, `glob`, `list_dir`) and subagent tools +- **`read-write`** — adds write tools (`write_file`, `edit_file`, `apply_patch`) +- **`full`** — allows all tools including shell commands + +Tools outside the permission level are interactively prompted (if a TTY is present) or denied (with `--auto-approve`). + +### Output formats + +- **`text`** — human-readable terminal output +- **`json`** — NDJSON event stream + +## `[llm]` section + +Defaults for `arc llm prompt` and `arc llm chat`. + +| Key | Description | Values | Default | +|---|---|---|---| +| `model` | Model name | Any model ID from `arc models list` | Per provider | + + +The `[llm]` section only sets the default model. Use `[agent]` to configure provider, permissions, and output format for `arc agent`. + diff --git a/docs/tutorials/branch-loop.mdx b/docs/tutorials/branch-loop.mdx index 25526bec1..df001fd7e 100644 --- a/docs/tutorials/branch-loop.mdx +++ b/docs/tutorials/branch-loop.mdx @@ -21,7 +21,7 @@ digraph BranchLoop { plan [label="Plan", prompt="Plan a small Python script (fizzbuzz.py) and a test file (test_fizzbuzz.py) using pytest. Describe what you will create.", shape=tab, reasoning_effort="low"] implement [label="Implement", prompt="Create fizzbuzz.py and test_fizzbuzz.py as planned. Write the files to disk."] - validate [label="Validate", shape=parallelogram, script="python -m pytest test_fizzbuzz.py -v 2>&1 || true"] + validate [label="Validate", shape=parallelogram, script="python3 -m pytest test_fizzbuzz.py -v 2>&1 || true"] gate [shape=diamond, label="Tests passing?"] start -> plan -> implement -> validate -> gate @@ -39,7 +39,7 @@ arc run start demo/05-branch-loop.dot The `validate` node has `shape=parallelogram`, making it a **command node**. It runs a shell script and captures the output: ```dot -validate [label="Validate", shape=parallelogram, script="python -m pytest test_fizzbuzz.py -v 2>&1 || true"] +validate [label="Validate", shape=parallelogram, script="python3 -m pytest test_fizzbuzz.py -v 2>&1 || true"] ``` The `|| true` ensures the command always exits successfully — this way the node itself doesn't fail even when tests fail. The test output is captured as `command.output` in the [run context](/execution/context) for downstream nodes to use. diff --git a/docs/tutorials/ensemble.mdx b/docs/tutorials/ensemble.mdx index 464336b9e..4fca63670 100644 --- a/docs/tutorials/ensemble.mdx +++ b/docs/tutorials/ensemble.mdx @@ -111,19 +111,8 @@ The tradeoff is cost and latency — you're making 4x the LLM calls. Use single- - A **synthesis node** compares perspectives and produces a unified result - Combine parallel execution and model routing for diverse, independent analysis -## Further reading +## Next - - - Available models, providers, and fallback configuration. - - - Full stylesheet syntax and specificity rules. - - - Complete reference for all node types. - - - Edge conditions, routing directives, and tiebreaking. - - + + Delegate to reusable child workflows with the supervisor pattern. + diff --git a/docs/tutorials/sub-workflow.mdx b/docs/tutorials/sub-workflow.mdx new file mode 100644 index 000000000..259a8832c --- /dev/null +++ b/docs/tutorials/sub-workflow.mdx @@ -0,0 +1,145 @@ +--- +title: "Sub-Workflows" +description: "Reusable child workflows, context flow, and the supervisor pattern" +--- + +This tutorial uses a **sub-workflow node** to delegate part of a parent workflow to a separate, reusable child workflow. The parent plans a feature, hands off implementation to a child workflow that runs its own implement-test loop, then reviews the result. + +## Prerequisites + +Complete the [Branch & Loop](/tutorials/branch-loop) tutorial — the child workflow in this tutorial reuses that pattern. + +## The child workflow + +First, create a standalone implement-and-test workflow. This is a normal workflow that can run on its own or be invoked as a sub-workflow by a parent. + + + Child workflow: Start → Implement → Validate → Tests passing? → Pass to Exit or Fix back to Implement + + +```dot title="implement-and-test.dot" +digraph ImplementAndTest { + graph [goal="Implement the plan and make tests pass"] + rankdir=LR + + start [shape=Mdiamond, label="Start"] + exit [shape=Msquare, label="Exit"] + + implement [label="Implement", prompt="Read plan.md and implement every step. Write the code and tests to disk."] + validate [label="Validate", shape=parallelogram, script="python3 -m pytest -v 2>&1 || true"] + gate [shape=diamond, label="Tests passing?"] + + start -> implement -> validate -> gate + gate -> exit [label="Pass", condition="outcome=success"] + gate -> implement [label="Fix", max_visits=5] +} +``` + +This is the same implement-test-fix loop from the [Branch & Loop](/tutorials/branch-loop) tutorial, packaged as its own file. + +## The parent workflow + +Now create a parent workflow that delegates to the child: + + + Sub-Workflow: Start → Plan (agent) → Implement & Test (house) → Review (agent) → Exit + + +```dot title="sub-workflow.dot" +digraph SubWorkflow { + graph [goal="Create a Python module (tempconv.py) that converts between Celsius, Fahrenheit, and Kelvin, with pytest tests"] + rankdir=LR + + start [shape=Mdiamond, label="Start"] + exit [shape=Msquare, label="Exit"] + + plan [label="Plan", prompt="Analyze the goal. List the functions needed, their signatures, and edge cases. Write the plan to plan.md."] + impl [label="Implement & Test", shape=house, stack.child_dotfile="implement-and-test.dot", manager.max_cycles=50] + review [label="Review", prompt="Read every file the child workflow created. Run the tests yourself with 'python3 -m pytest -v'. Verify the implementation matches plan.md and all tests pass. Write a short verdict to review.md."] + + start -> plan -> impl -> review -> exit +} +``` + +```bash +arc run start demo/12-sub-workflow.dot +``` + +## The house node + +The `impl` node has `shape=house`, which makes it a **sub-workflow node**. Instead of running an LLM or a script, it launches an entirely separate workflow engine to execute the child DOT file: + +```dot +impl [label="Implement & Test", shape=house, stack.child_dotfile="implement-and-test.dot", manager.max_cycles=50] +``` + +The child workflow runs through its own start → implement → validate → gate → exit sequence. When it finishes, execution returns to the parent and continues to the `review` node. + +### Sub-workflow attributes + +| Attribute | Description | +|---|---| +| `stack.child_dotfile` | Path to the child DOT file (resolved relative to the parent) | +| `stack.child_dot_source` | Inline child DOT source (alternative to `child_dotfile`) | +| `manager.max_cycles` | Safety limit on poll cycles before the child is cancelled (default: 1000) | +| `manager.poll_interval` | How often to check for completion or stop conditions (default: `45s`) | +| `manager.stop_condition` | Condition expression that, when true, cancels the child early | + +Use `stack.child_dotfile` when you want to reuse the child workflow across multiple parents. Use `stack.child_dot_source` for one-off child workflows that are specific to the parent. + +## Context flow + +Context flows bidirectionally between parent and child: + +1. **Parent → child:** The child receives a clone of the parent's context. In this example, the `plan` node writes `plan.md` to disk and the child's `implement` node reads it. +2. **Child → parent:** When the child finishes, any context values it added or changed are merged back into the parent. The `review` node sees the results of the child's work. + +Only the _diff_ is merged — values the child didn't touch remain unchanged in the parent. + +## Stop conditions + +For long-running child workflows, you can set a stop condition that cancels the child early based on the parent's context: + +```dot +impl [shape=house, + stack.child_dotfile="implement-and-test.dot", + manager.stop_condition="context.deploy_ready=true", + manager.max_cycles=100] +``` + +The parent polls at `manager.poll_interval` (default 45 seconds). On each poll, it evaluates the stop condition against the current context. If the condition is true, the child is cancelled and the parent continues. This is useful when an external process (another branch, a webhook, a human gate) signals that the child's work is no longer needed. + +## When to use sub-workflows + +Sub-workflows are most valuable when: + +- **Reusability** — the same child workflow is used by multiple parents (e.g., a standard test-and-fix loop, a deploy pipeline, a review checklist) +- **Encapsulation** — the child runs its own engine with isolated logs and checkpoints, keeping the parent's execution trace clean +- **Supervisor patterns** — the parent needs to monitor or cancel a complex child process based on external conditions + +For simpler cases, just add more nodes to a single workflow. Sub-workflows add a layer of indirection — use them when the benefits of reuse or encapsulation justify it. + +## What you've learned + +- **Sub-workflow nodes** (`shape=house`) run a child workflow inside a parent +- **`stack.child_dotfile`** references an external DOT file for reuse +- **Context flows** from parent to child and back via diff merging +- **`manager.max_cycles`** prevents runaway child workflows +- **`manager.stop_condition`** cancels the child when an external signal arrives + +## Further reading + + + + Complete reference for all node types. + + + Full syntax reference including sub-workflow attributes. + + + How context flows between nodes and across workflow boundaries. + + + The implement-test-fix pattern used in the child workflow. + + diff --git a/test/docs/examples/solitaire/build-solitaire.dot b/test/docs/examples/solitaire/build-solitaire.dot index d774f7a3a..d39b11300 100644 --- a/test/docs/examples/solitaire/build-solitaire.dot +++ b/test/docs/examples/solitaire/build-solitaire.dot @@ -6,9 +6,9 @@ digraph BuildSolitaire { retry_target="impl_setup", fallback_retry_target="impl_game_logic", model_stylesheet=" - * { llm_model: claude-sonnet-4-5; llm_provider: anthropic; } - .hard { llm_model: claude-opus-4-6; llm_provider: anthropic; } - .verify { llm_model: claude-haiku-4-5; llm_provider: anthropic; } + * { llm_model: claude-sonnet; llm_provider: anthropic; } + .hard { llm_model: claude-opus; llm_provider: anthropic; } + .verify { llm_model: claude-haiku; llm_provider: anthropic; } " ] diff --git a/test/docs/tutorials/branch-loop/branch-loop.dot b/test/docs/tutorials/branch-loop/branch-loop.dot index ab9a77ebe..b50eb1a8c 100644 --- a/test/docs/tutorials/branch-loop/branch-loop.dot +++ b/test/docs/tutorials/branch-loop/branch-loop.dot @@ -7,7 +7,7 @@ digraph BranchLoop { plan [label="Plan", prompt="Plan a small Python script (fizzbuzz.py) and a test file (test_fizzbuzz.py) using pytest. Describe what you will create.", shape=tab, reasoning_effort="low"] implement [label="Implement", prompt="Create fizzbuzz.py and test_fizzbuzz.py as planned. Write the files to disk."] - validate [label="Validate", shape=parallelogram, script="python -m pytest test_fizzbuzz.py -v 2>&1 || true"] + validate [label="Validate", shape=parallelogram, script="python3 -m pytest test_fizzbuzz.py -v 2>&1 || true"] gate [shape=diamond, label="Tests passing?"] start -> plan -> implement -> validate -> gate