From 4d62c784ee9e04b82711d620fe57613eac93103f Mon Sep 17 00:00:00 2001 From: Bryan Helmkamp Date: Sun, 29 Mar 2026 15:02:48 -0400 Subject: [PATCH] Update docs for new CLI commands, fast mode, and subagent defaults Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/skills/docs/watermark | 2 +- docs/agents/subagents.mdx | 8 ++-- docs/reference/cli.mdx | 68 +++++++++++++++++++++++++++++++++ docs/reference/dot-language.mdx | 3 +- docs/workflows/stylesheets.mdx | 1 + 5 files changed, 77 insertions(+), 5 deletions(-) diff --git a/.claude/skills/docs/watermark b/.claude/skills/docs/watermark index 6d7216bae..54c7dee68 100644 --- a/.claude/skills/docs/watermark +++ b/.claude/skills/docs/watermark @@ -1 +1 @@ -45ff3da4e05c7c67c909d7b860c7764b34e6a342 +1afa8419b53670f95c5d6a041cfd373c4a8c9371 diff --git a/docs/agents/subagents.mdx b/docs/agents/subagents.mdx index 69551a8e0..2d669184c 100644 --- a/docs/agents/subagents.mdx +++ b/docs/agents/subagents.mdx @@ -31,7 +31,7 @@ Creates a new sub-agent session and starts it working on the given task. | `task` | string | yes | The task description for the sub-agent | | `working_dir` | string | no | Working directory for the sub-agent | | `model` | string | no | Model to use for the sub-agent | -| `max_turns` | integer | no | Maximum number of turns (default: 50) | +| `max_turns` | integer | no | Maximum number of turns (default: unlimited) | Returns the `agent_id` string used to reference this sub-agent in subsequent calls. @@ -104,7 +104,7 @@ When a sub-agent fails, the error is captured and returned to the parent via the Specific failure modes: -- **Sub-agent hits `max_turns`** — The sub-agent stops naturally and returns its last output as a successful result. The parent sees a normal completion with the final assistant message. +- **Sub-agent hits `max_turns`** — The sub-agent stops naturally and returns its last output as a successful result. The parent sees a normal completion with the final assistant message. By default, there is no turn limit — sub-agents run until they complete their task or hit the context window. - **Sub-agent panics or errors** — The error is captured and returned through `wait` as a failure result. The parent can inspect the error and decide what to do. - **`spawn_agent` fails** (e.g. depth limit exceeded) — The error is returned immediately as a tool result. The parent can adjust its approach without waiting. @@ -133,5 +133,7 @@ Sub-agents are most useful when: - **Context management** -- offload work to a sub-agent when the parent's context window is getting full -Sub-agents have a default turn limit of 50. For larger tasks, pass a higher `max_turns` when spawning. The parent agent is blocked during a `wait` call, so spawn sub-agents before starting the wait to maximize concurrency. +Sub-agents run with no turn limit by default — they continue until the task is complete or the context window is exhausted. Pass `max_turns` when spawning to cap execution for predictable cost control. The parent agent is blocked during a `wait` call, so spawn sub-agents before starting the wait to maximize concurrency. + +All active sub-agents are automatically cleaned up when the parent session closes — you don't need to explicitly `close_agent` on every sub-agent. diff --git a/docs/reference/cli.mdx b/docs/reference/cli.mdx index de36c829f..cbace6df0 100644 --- a/docs/reference/cli.mdx +++ b/docs/reference/cli.mdx @@ -117,6 +117,57 @@ fabro resume --detach | `` | Run ID or unambiguous prefix | | `-d, --detach` | Run in the background and print the run ID | +## `fabro wait` + +Block until a workflow run reaches a terminal state and exit with a code reflecting the outcome — analogous to `docker wait`. Exits 0 on success, 1 on failure or dead. + +```bash +fabro wait +fabro wait abc123 --timeout 300 +fabro wait my-workflow --json +``` + +| Argument / Flag | Description | +|---|---| +| `` | Run ID prefix or workflow name (most recent run) | +| `--timeout ` | Maximum time to wait in seconds | +| `--interval ` | Poll interval in milliseconds (default: 1000) | +| `--json` | Output the conclusion as JSON | + +## `fabro create` + +Allocate a run directory and persist a run spec without starting execution. Pair with `fabro start` and `fabro attach` for composable automation. + +```bash +fabro create --goal "Implement feature X" +``` + +Accepts the same arguments and flags as [`fabro run`](#fabro-run). + +## `fabro start` + +Start a previously created run by spawning the detached engine process. + +```bash +fabro start +``` + +| Argument | Description | +|---|---| +| `` | Run ID prefix or workflow name | + +## `fabro attach` + +Attach to a running or finished workflow run. Tails progress with live rendering and handles human-in-the-loop interactions (interviews, steering). + +```bash +fabro attach +``` + +| Argument | Description | +|---|---| +| `` | Run ID prefix or workflow name | + ## `fabro ps` List workflow runs. By default, shows only active (running) runs — similar to `docker ps`. Use `-a` to include completed runs. @@ -275,6 +326,7 @@ fabro model test -m claude-sonnet-4-5 |---|---| | `-p, --provider ` | Filter by provider | | `-m, --model ` | Test a specific model | +| `--deep` | Run a multi-turn tool-use test that validates the full agent loop (tool calls, reasoning round-trips) instead of a single-turn completion | --- @@ -819,6 +871,22 @@ fabro secret rm ANTHROPIC_API_KEY --- +## `fabro store dump` + +Export the contents of a run's store-backed state to a directory for debugging and inspection. + +```bash +fabro store dump +fabro store dump abc123 -o ./debug-output +``` + +| Argument / Flag | Description | +|---|---| +| `` | Run ID prefix or workflow name | +| `-o, --output ` | Output directory (must not exist or be empty) | + +--- + ## `fabro docs` Open the Fabro documentation website in your default browser. diff --git a/docs/reference/dot-language.mdx b/docs/reference/dot-language.mdx index 617d4313c..bfdcfdfdf 100644 --- a/docs/reference/dot-language.mdx +++ b/docs/reference/dot-language.mdx @@ -76,7 +76,7 @@ rankdir=LR | `goal` | String | Workflow objective — guides agent behavior and retrospectives | | `rankdir` | Identifier | Layout direction: `LR` (left-to-right) or `TB` (top-to-bottom) | | `model_stylesheet` | String | CSS-like rules for model assignment (see [Model Stylesheets](/workflows/stylesheets)) | -| `default_max_retries` | Integer | Default retry count for all nodes (default: 3) | +| `default_max_retries` | Integer | Default retry count for all nodes (default: 0) | | `retry_target` | String | Default node ID to jump to on retry | | `fallback_retry_target` | String | Fallback retry target if primary target fails | | `default_fidelity` | String | Default [fidelity level](/execution/context) for all nodes | @@ -262,6 +262,7 @@ OrExpr ::= AndExpr ('||' AndExpr)* AndExpr ::= UnaryExpr ('&&' UnaryExpr)* UnaryExpr ::= '!' UnaryExpr | Clause Clause ::= Key Op Value | Key (bare key = truthy check) +Value ::= BareWord | '"' QuotedString '"' Op ::= '=' | '!=' | '>' | '<' | '>=' | '<=' | 'contains' | 'matches' ``` diff --git a/docs/workflows/stylesheets.mdx b/docs/workflows/stylesheets.mdx index c77f223db..6f171f92e 100644 --- a/docs/workflows/stylesheets.mdx +++ b/docs/workflows/stylesheets.mdx @@ -67,6 +67,7 @@ Stylesheets support four properties: | `model` | Model ID or alias | `claude-sonnet-4-5`, `opus`, `gemini-pro` | | `provider` | Provider name (optional — auto-inferred from the model catalog when omitted) | `anthropic`, `openai`, `gemini` | | `reasoning_effort` | Reasoning effort level | `low`, `medium`, `high` | +| `speed` | Output speed mode. `fast` enables Anthropic's fast mode for up to 2.5x faster output at higher cost. | `fast` | | `backend` | Agent execution backend — `api` (default) runs Fabro's own tool loop, `cli` delegates to an external CLI tool. See [Backends](/core-concepts/agents#backends). | `cli`, `api` | See [Models](/core-concepts/models) for the full list of model IDs and aliases.