diff --git a/AGENTS.md b/AGENTS.md index 62420d208..a6d66bef3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,11 +45,11 @@ The OpenAPI spec at `docs/api-reference/fabro-api.yaml` is the source of truth f ## Architecture -Fabro is an AI-powered workflow orchestration platform. Workflows are defined as DOT graphs, where each node is a stage (agent, prompt, command, conditional, human, parallel, etc.) executed by the workflow engine. +Fabro is an AI-powered workflow orchestration platform. Workflows are defined as Graphviz graphs, where each node is a stage (agent, prompt, command, conditional, human, parallel, etc.) executed by the workflow engine. ### Rust crates (`lib/crates/`) - **fabro-cli** — CLI entry point. Commands: `run`, `exec`, `serve`, `validate`, `parse`, `cp`, `model`, `doctor`, `init`, `install`, `ps`, `system prune`, `llm` -- **fabro-workflows** — Core workflow engine. Parses DOT graphs, runs stages, manages checkpoints/resume, hooks, retros, and human-in-the-loop interactions +- **fabro-workflows** — Core workflow engine. Parses Graphviz graphs, runs stages, manages checkpoints/resume, hooks, retros, and human-in-the-loop interactions - **fabro-agent** — AI coding agent with tool use (Bash, Read, Write, Edit, Glob, Grep, WebFetch). `Sandbox` trait abstracts execution environments - **fabro-api** — Axum HTTP server. Routes for runs, sessions, models, completions, usage. SSE event streaming. Demo mode via header - **fabro-exe** — SSH-based sandbox implementation (`ExeSandbox`) @@ -70,7 +70,7 @@ Fabro is an AI-powered workflow orchestration platform. Workflows are defined as ### Key design patterns - **Sandbox trait** — Uniform interface for local, Docker, SSH (ExeSandbox), Sprites, and Daytona execution environments -- **DOT graph workflows** — Stages and transitions defined as DOT graph attributes +- **Graphviz graph workflows** — Stages and transitions defined as Graphviz graph attributes - **OpenAPI-first** — `fabro-api.yaml` drives both Rust type generation (typify) and TypeScript client generation (openapi-generator) - **Checkpoint/resume** — Workflows can be paused, checkpointed, and resumed diff --git a/README.md b/README.md index c5e48e576..a39f2623e 100644 --- a/README.md +++ b/README.md @@ -87,7 +87,7 @@ digraph PlanImplement { } ``` -Agents run as multi-turn LLM sessions with tool access. Human gates (`hexagon`) pause for approval. The stylesheet routes planning to a cheap model and coding to a frontier model. See the [DOT language reference](https://docs.fabro.sh/reference/dot-language) for the full syntax. +Agents run as multi-turn LLM sessions with tool access. Human gates (`hexagon`) pause for approval. The stylesheet routes planning to a cheap model and coding to a frontier model. See the [Graphviz DOT language reference](https://docs.fabro.sh/reference/dot-language) for the full syntax. --- diff --git a/apps/marketing/public/install.md b/apps/marketing/public/install.md index 3cc4b4d90..a1ce33f89 100644 --- a/apps/marketing/public/install.md +++ b/apps/marketing/public/install.md @@ -1,6 +1,6 @@ # fabro -> AI-powered workflow orchestration platform. Workflows are defined as DOT graphs and executed by the Fabro engine. +> AI-powered workflow orchestration platform. Workflows are defined as Graphviz graphs and executed by the Fabro engine. I want you to install Fabro for me. Execute all the steps below autonomously. diff --git a/apps/marketing/public/llms.txt b/apps/marketing/public/llms.txt index f525c1df2..d775edc0d 100644 --- a/apps/marketing/public/llms.txt +++ b/apps/marketing/public/llms.txt @@ -2,10 +2,10 @@ > Fabro is the open source dark software factory for expert engineers. Define your process as a workflow graph, let AI agents execute it, and intervene only where it matters. -Fabro replaces the prompt-wait-review loop with version-controlled workflow graphs that orchestrate AI agents, shell commands, and human decisions into repeatable, long-horizon coding processes. Workflows are defined as DOT graphs where each node is a stage (agent, prompt, command, conditional, human, parallel, etc.) executed by the workflow engine. +Fabro replaces the prompt-wait-review loop with version-controlled workflow graphs that orchestrate AI agents, shell commands, and human decisions into repeatable, long-horizon coding processes. Workflows are defined as Graphviz graphs where each node is a stage (agent, prompt, command, conditional, human, parallel, etc.) executed by the workflow engine. - Open source, MIT-licensed -- Workflows defined as DOT graphs with CSS-like model stylesheets +- Workflows defined as Graphviz graphs with CSS-like model stylesheets - Sandboxed execution via local Docker, Daytona, SSH, or Sprites - Checkpoint/resume for long-running workflows - Human-in-the-loop via CLI, web UI, or Slack @@ -71,7 +71,7 @@ Fabro replaces the prompt-wait-review loop with version-controlled workflow grap - [API Overview](https://docs.fabro.sh/api-reference/overview): Introduction to the Fabro REST API - [CLI Reference](https://docs.fabro.sh/reference/cli): Command-line interface reference - [Architecture](https://docs.fabro.sh/reference/architecture): How CLI and API modes work under the hood -- [DOT Language](https://docs.fabro.sh/reference/dot-language): Complete reference for Fabro's workflow language +- [Graphviz DOT Language](https://docs.fabro.sh/reference/dot-language): Complete reference for Fabro's workflow language ## Optional diff --git a/apps/marketing/src/content.config.ts b/apps/marketing/src/content.config.ts index cb921de69..449b142ae 100644 --- a/apps/marketing/src/content.config.ts +++ b/apps/marketing/src/content.config.ts @@ -7,8 +7,7 @@ const roadmap = defineCollection({ title: z.string(), description: z.string(), status: z.enum(["shipped", "building", "next"]), - date: z.string().optional(), // e.g. "Mar 2026", required for shipped - sortOrder: z.number(), // lower = shown first within status group + date: z.coerce.date(), }), }); diff --git a/apps/marketing/src/content/blog/introducing-fabro.md b/apps/marketing/src/content/blog/introducing-fabro.md index 819f118fc..2dc94465a 100644 --- a/apps/marketing/src/content/blog/introducing-fabro.md +++ b/apps/marketing/src/content/blog/introducing-fabro.md @@ -11,7 +11,7 @@ Most AI coding tools give you a chat window and hope for the best. Fabro takes a A chat-based agent is a single loop: prompt, act, repeat. That works for small tasks, but it falls apart when you need structure — when the plan should be approved before implementation begins, when tests must pass before the PR is opened, when a second model should cross-review the first. -Fabro workflows are DOT graphs. Each node is a stage with a specific role: planning, coding, reviewing, testing. Edges define the flow. Human-in-the-loop gates let you intervene where it matters and step back where it doesn't. +Fabro workflows are Graphviz graphs. Each node is a stage with a specific role: planning, coding, reviewing, testing. Edges define the flow. Human-in-the-loop gates let you intervene where it matters and step back where it doesn't. ## Multi-model by design diff --git a/apps/marketing/src/content/roadmap/analytics.yaml b/apps/marketing/src/content/roadmap/analytics.yaml new file mode 100644 index 000000000..5919b9d22 --- /dev/null +++ b/apps/marketing/src/content/roadmap/analytics.yaml @@ -0,0 +1,4 @@ +title: Analytics +description: Cost tracking, success rates, and performance trends across runs. Budgets, alerts, and optimization insights. +status: next +date: 2026-06-01 diff --git a/apps/marketing/src/content/roadmap/api-server-web-ui.yaml b/apps/marketing/src/content/roadmap/api-server-web-ui.yaml index 992c61098..5b8b91157 100644 --- a/apps/marketing/src/content/roadmap/api-server-web-ui.yaml +++ b/apps/marketing/src/content/roadmap/api-server-web-ui.yaml @@ -1,5 +1,4 @@ -title: API server & web UI -description: REST API with SSE event streaming and a React dashboard for managing workflows at scale. -status: shipped -date: Feb 2026 -sortOrder: 2 +title: REST API server mode +description: REST API with SSE event streaming for queuing runs, tracking progress, and managing workflows programmatically. +status: building +date: 2026-04-02 diff --git a/apps/marketing/src/content/roadmap/automatic-retrospectives.yaml b/apps/marketing/src/content/roadmap/automatic-retrospectives.yaml index 7876efa74..387eb697c 100644 --- a/apps/marketing/src/content/roadmap/automatic-retrospectives.yaml +++ b/apps/marketing/src/content/roadmap/automatic-retrospectives.yaml @@ -1,5 +1,4 @@ title: Automatic retrospectives -description: Each run generates a retro with cost, duration, files touched, and an LLM-written narrative. -status: shipped -date: Mar 2026 -sortOrder: 1 +description: Structured post-run analysis with cost, duration, smoothness ratings, friction points, and LLM-generated narratives. +status: building +date: 2026-04-03 diff --git a/apps/marketing/src/content/roadmap/cloud-sandboxes.yaml b/apps/marketing/src/content/roadmap/cloud-sandboxes.yaml index b1a947dcd..4b15222fe 100644 --- a/apps/marketing/src/content/roadmap/cloud-sandboxes.yaml +++ b/apps/marketing/src/content/roadmap/cloud-sandboxes.yaml @@ -1,5 +1,4 @@ title: Cloud sandboxes -description: Isolated VM execution environments with snapshot-based setup, network controls, and SSH access. +description: Isolated cloud VMs with snapshot-based setup, network controls, SSH access, and preview URLs. status: shipped -date: Jan 2026 -sortOrder: 3 +date: 2026-03-15 diff --git a/apps/marketing/src/content/roadmap/core-workflow-engine.yaml b/apps/marketing/src/content/roadmap/core-workflow-engine.yaml index cd144d724..d05f5e96f 100644 --- a/apps/marketing/src/content/roadmap/core-workflow-engine.yaml +++ b/apps/marketing/src/content/roadmap/core-workflow-engine.yaml @@ -1,5 +1,4 @@ -title: Core workflow engine -description: DOT graph parsing with branching, loops, parallel execution, and conditional routing. +title: Workflow engine +description: Graphviz graph parsing with agent, command, and human nodes. Dynamic edge selection with conditions and loops. status: shipped -date: May 2025 -sortOrder: 7 +date: 2026-02-15 diff --git a/apps/marketing/src/content/roadmap/custom-tool-plugins.yaml b/apps/marketing/src/content/roadmap/custom-tool-plugins.yaml deleted file mode 100644 index 3c8c2208a..000000000 --- a/apps/marketing/src/content/roadmap/custom-tool-plugins.yaml +++ /dev/null @@ -1,4 +0,0 @@ -title: Custom tool plugins -description: Extend agent capabilities with your own tool definitions. Package, share, and version tools independently of workflows. -status: next -sortOrder: 2 diff --git a/apps/marketing/src/content/roadmap/git-checkpointing.yaml b/apps/marketing/src/content/roadmap/git-checkpointing.yaml index 3d0e8e604..eebc2518d 100644 --- a/apps/marketing/src/content/roadmap/git-checkpointing.yaml +++ b/apps/marketing/src/content/roadmap/git-checkpointing.yaml @@ -1,5 +1,4 @@ -title: Git checkpointing & resume -description: Every stage commits to a Git branch with full metadata. Revert or resume from any checkpoint. +title: Git checkpoints +description: Every stage commits code and execution metadata to Git branches. Resume or fork from any checkpoint. status: shipped -date: Nov 2025 -sortOrder: 4 +date: 2026-03-01 diff --git a/apps/marketing/src/content/roadmap/human-in-the-loop.yaml b/apps/marketing/src/content/roadmap/human-in-the-loop.yaml index 336c0dfa3..9fdba8480 100644 --- a/apps/marketing/src/content/roadmap/human-in-the-loop.yaml +++ b/apps/marketing/src/content/roadmap/human-in-the-loop.yaml @@ -1,5 +1,4 @@ -title: Human-in-the-loop -description: Approval gates pause for human decisions. Steer running agents mid-turn. Interview steps collect input. +title: Interview-based steering +description: Approval gates, multiple choice, and freeform questions. Steer running agents via CLI, web, or Slack. status: shipped -date: Sep 2025 -sortOrder: 5 +date: 2026-02-15 diff --git a/apps/marketing/src/content/roadmap/metrics-cost-dashboards.yaml b/apps/marketing/src/content/roadmap/metrics-cost-dashboards.yaml deleted file mode 100644 index cdc5fab69..000000000 --- a/apps/marketing/src/content/roadmap/metrics-cost-dashboards.yaml +++ /dev/null @@ -1,4 +0,0 @@ -title: Metrics & cost dashboards -description: Real-time cost tracking, success rates, and performance trends across all runs. Set budgets, alerts, and optimization targets. -status: next -sortOrder: 3 diff --git a/apps/marketing/src/content/roadmap/multi-model-routing.yaml b/apps/marketing/src/content/roadmap/multi-model-routing.yaml index b19f13a9b..dc11f1f05 100644 --- a/apps/marketing/src/content/roadmap/multi-model-routing.yaml +++ b/apps/marketing/src/content/roadmap/multi-model-routing.yaml @@ -1,5 +1,4 @@ -title: Multi-model routing -description: CSS-like model stylesheets assign providers per stage. Automatic fallback chains across providers. +title: Multi-model agent +description: Multi-turn LLM sessions with bash, file editing, sub-agents, skills, and lifecycle hooks. status: shipped -date: Jul 2025 -sortOrder: 6 +date: 2026-02-15 diff --git a/apps/marketing/src/content/roadmap/parallel-execution-scaling.yaml b/apps/marketing/src/content/roadmap/parallel-execution-scaling.yaml deleted file mode 100644 index 7961b7cd4..000000000 --- a/apps/marketing/src/content/roadmap/parallel-execution-scaling.yaml +++ /dev/null @@ -1,4 +0,0 @@ -title: Parallel execution scaling -description: Dynamic fan-out with resource-aware scheduling. Run dozens of sandboxes concurrently with automatic load balancing and cost caps. -status: building -sortOrder: 2 diff --git a/apps/marketing/src/content/roadmap/self-hosted-cloud.yaml b/apps/marketing/src/content/roadmap/self-hosted-cloud.yaml deleted file mode 100644 index 23f0e2d63..000000000 --- a/apps/marketing/src/content/roadmap/self-hosted-cloud.yaml +++ /dev/null @@ -1,4 +0,0 @@ -title: Self-hosted cloud -description: Deploy Fabro as a managed service in your own infrastructure. Kubernetes-native with horizontal scaling and multi-tenant isolation. -status: next -sortOrder: 4 diff --git a/apps/marketing/src/content/roadmap/slack-integration.yaml b/apps/marketing/src/content/roadmap/slack-integration.yaml new file mode 100644 index 000000000..ae6627eca --- /dev/null +++ b/apps/marketing/src/content/roadmap/slack-integration.yaml @@ -0,0 +1,4 @@ +title: Slack integration +description: Receive notifications, approve human gates, and monitor runs directly from Slack channels. +status: next +date: 2026-06-02 diff --git a/apps/marketing/src/content/roadmap/team-collaboration.yaml b/apps/marketing/src/content/roadmap/team-collaboration.yaml deleted file mode 100644 index 9a4fdf35a..000000000 --- a/apps/marketing/src/content/roadmap/team-collaboration.yaml +++ /dev/null @@ -1,4 +0,0 @@ -title: Team collaboration -description: Shared workflow runs with role-based access. Assign reviewers, track ownership, and coordinate across teams. -status: next -sortOrder: 1 diff --git a/apps/marketing/src/content/roadmap/verifications.yaml b/apps/marketing/src/content/roadmap/verifications.yaml new file mode 100644 index 000000000..fcf30c4d7 --- /dev/null +++ b/apps/marketing/src/content/roadmap/verifications.yaml @@ -0,0 +1,4 @@ +title: Verifications +description: Deterministic quality gates — test suites, linters, type checkers, and LLM-as-judge — wired into the workflow graph. +status: building +date: 2026-04-01 diff --git a/apps/marketing/src/content/roadmap/web-app.yaml b/apps/marketing/src/content/roadmap/web-app.yaml new file mode 100644 index 000000000..e3e7f7814 --- /dev/null +++ b/apps/marketing/src/content/roadmap/web-app.yaml @@ -0,0 +1,4 @@ +title: Web app +description: React dashboard for managing workflows, viewing runs, approving human gates, and browsing retrospectives. +status: next +date: 2026-06-03 diff --git a/apps/marketing/src/content/roadmap/workflow-marketplace.yaml b/apps/marketing/src/content/roadmap/workflow-marketplace.yaml deleted file mode 100644 index 6299ff062..000000000 --- a/apps/marketing/src/content/roadmap/workflow-marketplace.yaml +++ /dev/null @@ -1,4 +0,0 @@ -title: Workflow marketplace -description: Browse, fork, and publish community workflows. One-command install with dependency resolution and version pinning. -status: building -sortOrder: 1 diff --git a/apps/marketing/src/pages/index.astro b/apps/marketing/src/pages/index.astro index bd7f447da..2218ad069 100644 --- a/apps/marketing/src/pages/index.astro +++ b/apps/marketing/src/pages/index.astro @@ -430,7 +430,7 @@ const cssExample = `/* All nodes default to fast + ch - +
diff --git a/apps/marketing/src/pages/roadmap.astro b/apps/marketing/src/pages/roadmap.astro index 499f4d2a3..7bd49ce80 100644 --- a/apps/marketing/src/pages/roadmap.astro +++ b/apps/marketing/src/pages/roadmap.astro @@ -6,18 +6,21 @@ import PageScripts from "../components/PageScripts.astro"; import { getCollection } from "astro:content"; const allItems = await getCollection("roadmap"); -const byStatus = (status: string) => +const byDate = (status: string) => allItems .filter((item) => item.data.status === status) - .sort((a, b) => a.data.sortOrder - b.data.sortOrder); + .sort((a, b) => b.data.date.getTime() - a.data.date.getTime()); -const shipped = byStatus("shipped"); +const formatDate = (date: Date) => + date.toLocaleDateString("en-US", { month: "short", year: "numeric", timeZone: "UTC" }); + +const shipped = byDate("shipped"); const SHIPPED_VISIBLE = 3; const shippedVisible = shipped.slice(0, SHIPPED_VISIBLE); const shippedHidden = shipped.slice(SHIPPED_VISIBLE); -const building = byStatus("building"); -const next = byStatus("next"); +const building = byDate("building"); +const next = byDate("next"); const statusConfig = { building: { @@ -74,7 +77,7 @@ const statusConfig = {
{shippedVisible.map((item, i) => (
- {item.data.date} + {item.data.date && formatDate(item.data.date)} {item.data.title} @@ -118,7 +121,7 @@ const statusConfig = {
{shippedHidden.map((item) => (
- {item.data.date} + {item.data.date && formatDate(item.data.date)} {item.data.title} diff --git a/apps/marketing/src/pages/showcase/[slug].astro b/apps/marketing/src/pages/showcase/[slug].astro index 5b04bcb64..00f2b4163 100644 --- a/apps/marketing/src/pages/showcase/[slug].astro +++ b/apps/marketing/src/pages/showcase/[slug].astro @@ -200,7 +200,7 @@ const langIcons: Record = { Fabro web UI Workflows list showing Fix Build, Implement Feature, Sync Drift, and Expand Product workflows - - Fabro web UI workflow detail showing the DOT source for Fix Build + + Fabro web UI workflow detail showing the Graphviz source for Fix Build diff --git a/docs/execution/checkpoints.mdx b/docs/execution/checkpoints.mdx index 1a5568b8a..1923f9f75 100644 --- a/docs/execution/checkpoints.mdx +++ b/docs/execution/checkpoints.mdx @@ -44,7 +44,7 @@ The `Fabro-Checkpoint` trailer links each run branch commit to its metadata bran The metadata branch (`fabro/meta/{run_id}`) is an orphan branch that stores structured run data using Git's object storage directly (via `git2`). It is initialized at run start with: - **`manifest.json`** — Run metadata: run ID, graph name, node/edge counts, base SHA, and branch name -- **`graph.fabro`** — The workflow DOT source as it was parsed +- **`graph.fabro`** — The workflow Graphviz source as it was parsed After each node, the metadata branch is updated with: @@ -111,7 +111,7 @@ Resume from the Git branches created during a previous run: fabro run --run-branch fabro/run/01JKXYZ... ``` -This reads the checkpoint, manifest, and graph DOT from the metadata branch (`fabro/meta/01JKXYZ...`), re-attaches a worktree to the existing run branch, and resumes execution. No workflow file argument is needed — everything is recovered from Git. +This reads the checkpoint, manifest, and Graphviz graph from the metadata branch (`fabro/meta/01JKXYZ...`), re-attaches a worktree to the existing run branch, and resumes execution. No workflow file argument is needed — everything is recovered from Git. 1. Fabro reads `checkpoint.json` from the metadata branch diff --git a/docs/execution/run-configuration.mdx b/docs/execution/run-configuration.mdx index 4b8d25305..e95a464e5 100644 --- a/docs/execution/run-configuration.mdx +++ b/docs/execution/run-configuration.mdx @@ -22,10 +22,10 @@ goal = "Implement the login feature" | Field | Required | Description | |---|---|---| | `version` | Yes | Config format version. Must be `1`. | -| `graph` | Yes | Path to the DOT workflow file, resolved relative to the TOML file's directory. | -| `goal` | No | What the workflow should accomplish. Passed to agents and used in retrospectives. Can also be provided via `--goal` CLI flag or DOT graph `goal` attribute. | +| `graph` | Yes | Path to the Graphviz workflow file, resolved relative to the TOML file's directory. | +| `goal` | No | What the workflow should accomplish. Passed to agents and used in retrospectives. Can also be provided via `--goal` CLI flag or Graphviz graph `goal` attribute. | -Goal precedence: CLI `--goal` > TOML `goal` > DOT graph attribute. +Goal precedence: CLI `--goal` > TOML `goal` > Graphviz graph attribute. ## Full example @@ -275,7 +275,7 @@ Exclude globs from `server.toml` defaults and the run config are merged (union, ### `[vars]` -Define variables that are expanded into the DOT source before the graph is parsed. See [Variables](/workflows/variables) for the full reference. +Define variables that are expanded into the Graphviz source before the graph is parsed. See [Variables](/workflows/variables) for the full reference. ```toml title="run.toml" [vars] @@ -284,7 +284,7 @@ repo_url = "https://github.com/fabro-sh/fabro" language = "rust" ``` -Variables can be used anywhere in the DOT file with `$name` syntax: +Variables can be used anywhere in the Graphviz file with `$name` syntax: ```dot title="c-i.fabro" digraph CI { @@ -294,7 +294,7 @@ digraph CI { } ``` -If a `$variable` in the DOT file has no matching entry in `[vars]`, Fabro raises an error immediately. A bare `$` not followed by an identifier (e.g. `costs $5`) is left as-is. +If a `$variable` in the Graphviz file has no matching entry in `[vars]`, Fabro raises an error immediately. A bare `$` not followed by an identifier (e.g. `costs $5`) is left as-is. ### `[assets]` @@ -430,11 +430,11 @@ Settings can come from multiple sources. Fabro resolves them in this order (firs | CLI flags (`--model`, `--provider`, `--sandbox`) | | | Project defaults (`fabro.toml`) | | | Server defaults (`~/.fabro/server.toml`) | | -| DOT graph attributes (`default_model`, `default_provider`) | | +| Graphviz graph attributes (`default_model`, `default_provider`) | | | Built-in defaults | Lowest | -For model and provider specifically, the precedence is: CLI flags > TOML config > project defaults > server defaults > DOT graph attributes > built-in defaults. Stylesheet rules on individual nodes always take priority over all of these. +For model and provider specifically, the precedence is: CLI flags > TOML config > project defaults > server defaults > Graphviz graph attributes > built-in defaults. Stylesheet rules on individual nodes always take priority over all of these. ### Project defaults (`fabro.toml`) @@ -484,9 +484,9 @@ The same merge behavior applies to Daytona labels. All other fields use simple " Fabro validates the run config when it loads: - **Version check** — Only `version = 1` is accepted. Other versions are rejected immediately. -- **Required fields** — `version` and `graph` are required. `goal` is optional (can be provided via `--goal` or DOT graph attribute). +- **Required fields** — `version` and `graph` are required. `goal` is optional (can be provided via `--goal` or Graphviz graph attribute). - **Unknown fields** — Extra fields not listed above are rejected (`deny_unknown_fields`). -- **Variable check** — Any `$variable` in the DOT file without a matching `[vars]` entry produces an error. +- **Variable check** — Any `$variable` in the Graphviz file without a matching `[vars]` entry produces an error. Use `--preflight` to validate a run config without executing it: diff --git a/docs/getting-started/quick-start.mdx b/docs/getting-started/quick-start.mdx index 1ba81803d..e9eed957e 100644 --- a/docs/getting-started/quick-start.mdx +++ b/docs/getting-started/quick-start.mdx @@ -66,6 +66,6 @@ fabro run hello Understand the problems Fabro solves. - Learn how to define workflow graphs in DOT. + Learn how to define workflow graphs in Graphviz. diff --git a/docs/getting-started/why-fabro.mdx b/docs/getting-started/why-fabro.mdx index d62b6d69b..e77605872 100644 --- a/docs/getting-started/why-fabro.mdx +++ b/docs/getting-started/why-fabro.mdx @@ -19,11 +19,11 @@ AI coding agents have transformed software engineering productivity, but the sur ## How Fabro solves this -Fabro gives you a deterministic harness around non-deterministic AI. You define **workflow graphs** in DOT files that specify exactly what happens, in what order, with which models, and where humans weigh in. Fabro handles orchestration, parallelism, model routing, verification, and observability. +Fabro gives you a deterministic harness around non-deterministic AI. You define **workflow graphs** in Graphviz files that specify exactly what happens, in what order, with which models, and where humans weigh in. Fabro handles orchestration, parallelism, model routing, verification, and observability. - Define workflows as code in Graphviz DOT. Nodes are agents, shell commands, or human input gates. Fan out, loop, branch, and resume — all traceable and repeatable. + Define workflows as code in Graphviz. Nodes are agents, shell commands, or human input gates. Fan out, loop, branch, and resume — all traceable and repeatable. Route tasks to the right model using CSS-like stylesheets. Cross-critique with fresh eyes, delegate simple tasks to fast models, and fail over automatically when providers go down. @@ -46,7 +46,7 @@ Fabro gives you a deterministic harness around non-deterministic AI. You define ## What a workflow looks like -Workflows are defined in Graphviz DOT, a simple graph description language. Here's a plan-approve-implement workflow and its DOT source: +Workflows are defined in Graphviz, a simple graph description language. Here's a plan-approve-implement workflow and its Graphviz source: Plan-Implement workflow graph diff --git a/docs/reference/architecture.mdx b/docs/reference/architecture.mdx index e0d290b53..0cb644785 100644 --- a/docs/reference/architecture.mdx +++ b/docs/reference/architecture.mdx @@ -7,7 +7,7 @@ Fabro provides two interfaces — a CLI for local development and an HTTP API fo ## Shared engine -At the core of both modes is the `WorkflowRunEngine`. It parses the DOT graph, walks nodes, dispatches to handlers (agent, command, human, etc.), selects edges, and checkpoints after each stage. The engine is parameterized by an `Interviewer` trait that controls how human-in-the-loop questions are presented — terminal prompts in CLI mode, HTTP request/response in API mode. +At the core of both modes is the `WorkflowRunEngine`. It parses the Graphviz graph, walks nodes, dispatches to handlers (agent, command, human, etc.), selects edges, and checkpoints after each stage. The engine is parameterized by an `Interviewer` trait that controls how human-in-the-loop questions are presented — terminal prompts in CLI mode, HTTP request/response in API mode. ## CLI mode @@ -46,7 +46,7 @@ Key server config options: ### Run lifecycle -1. **Submit** — `POST /runs` with a DOT workflow source. The run is created with status `Queued` and the response returns immediately with the run ID. +1. **Submit** — `POST /runs` with a Graphviz workflow source. The run is created with status `Queued` and the response returns immediately with the run ID. 2. **Schedule** — A background scheduler promotes queued runs to `Running` in FIFO order, up to the concurrency limit. 3. **Execute** — The engine walks the graph, streaming events to all subscribers. 4. **Complete** — The run transitions to `Completed`, `Failed`, or `Cancelled`. @@ -82,7 +82,7 @@ cd apps/fabro-web && bun run dev # Web UI on port 5173 The UI provides: - **Run board** — List and monitor all runs - **Run detail** — Real-time stage progress, event stream, diffs, usage stats -- **Start new run** — Submit a DOT workflow from the browser +- **Start new run** — Submit a Graphviz workflow from the browser - **Human-in-the-loop** — Answer agent questions through the web interface - **Sessions** — Interactive chat interface (coming soon) - **Insights** — SQL-based analysis across runs via DuckDB diff --git a/docs/reference/cli.mdx b/docs/reference/cli.mdx index 4b5595644..d8c775720 100644 --- a/docs/reference/cli.mdx +++ b/docs/reference/cli.mdx @@ -361,7 +361,7 @@ fabro system df -v ## `fabro graph` -Render a workflow DOT graph as SVG or PNG. Requires [Graphviz](https://graphviz.org) (`dot`) to be installed. +Render a workflow graph as SVG or PNG. Requires [Graphviz](https://graphviz.org) (`dot`) to be installed. ```bash fabro graph workflow.fabro @@ -374,11 +374,11 @@ fabro graph run.toml --format svg | `` | Path to a `.fabro` workflow file or `.toml` run config (required) | | `--format ` | Output format: `svg` (default) or `png` | | `-o, --output ` | Output file path. Defaults to stdout. | -| `-d, --direction ` | Graph direction: `lr` or `tb`. If omitted, uses the DOT file's own `rankdir`. | +| `-d, --direction ` | Graph direction: `lr` or `tb`. If omitted, uses the Graphviz file's own `rankdir`. | ## `fabro skill install` -Install the built-in `fabro-create-workflow` skill for AI assistants (Claude Code, Codex). The skill teaches AI assistants Fabro's DOT syntax, node types, and run configuration format. +Install the built-in `fabro-create-workflow` skill for AI assistants (Claude Code, Codex). The skill teaches AI assistants Fabro's Graphviz syntax, node types, and run configuration format. ```bash # Install into the current project (.claude/skills/ or .agents/skills/) @@ -522,7 +522,7 @@ fabro validate run.toml ## `fabro parse` -Parse a DOT file and print its AST as JSON. Useful for debugging workflow definitions. +Parse a Graphviz file and print its AST as JSON. Useful for debugging workflow definitions. ```bash fabro parse workflow.fabro diff --git a/docs/reference/dot-language.mdx b/docs/reference/dot-language.mdx index e5c08ee66..899ab3def 100644 --- a/docs/reference/dot-language.mdx +++ b/docs/reference/dot-language.mdx @@ -1,6 +1,6 @@ --- title: "Fabro Language" -description: "Complete reference for Fabro's DOT workflow language" +description: "Complete reference for Fabro's Graphviz workflow language" --- Fabro workflows are written in a subset of the [Graphviz DOT language](https://graphviz.org/doc/info/lang.html) with extensions for agent orchestration. This page is the complete syntax reference. For conceptual introductions, see [Workflows](/core-concepts/workflows) and [Nodes & Stages](/workflows/stages-and-nodes). @@ -323,7 +323,7 @@ shared [prompt="@~/shared-prompts/review.md"] parent [prompt="@../common/plan.md"] ``` -Untracked `@file` references (files not committed to git) are inlined into the DOT source at prepare time, so they work even inside sandboxes that only see the git tree. +Untracked `@file` references (files not committed to git) are inlined into the Graphviz source at prepare time, so they work even inside sandboxes that only see the git tree. Fabro validates `@file` references at parse time — if the referenced file does not exist, validation fails with a clear error pointing to the bad reference. diff --git a/docs/reference/run-directory.mdx b/docs/reference/run-directory.mdx index dc4828f8c..157b147c2 100644 --- a/docs/reference/run-directory.mdx +++ b/docs/reference/run-directory.mdx @@ -20,7 +20,7 @@ The naming format is `YYYYMMDD-{run_id}`, where `run_id` is the ULID assigned to | File | Format | When written | Description | |---|---|---|---| | `manifest.json` | JSON | Run start | Run metadata — `run_id`, `workflow_name`, `goal`, `start_time`, `node_count`, `edge_count`, `run_branch`, `base_sha`, `labels` | -| `graph.fabro` | DOT | Run start | Copy of the workflow graph | +| `graph.fabro` | Graphviz | Run start | Copy of the workflow graph | | `run.pid` | Text | Run start | Process ID of the running CLI process. Presence indicates the run is active; an orphaned file indicates a crash. | | `run.toml` | TOML | Run start | Copy of the original workflow file (only when the workflow is defined in TOML) | | `progress.jsonl` | JSONL | Continuous | Event stream — one JSON object per line for every significant event (stage starts, completions, tool calls, retries, etc.). See [Observability](/execution/observability) for the full event catalog. | diff --git a/docs/tutorials/plan-implement.mdx b/docs/tutorials/plan-implement.mdx index da683ceab..8cd499919 100644 --- a/docs/tutorials/plan-implement.mdx +++ b/docs/tutorials/plan-implement.mdx @@ -83,7 +83,7 @@ The `simplify` node uses `@files-internal/prompts/simplify.md` instead of an inl simplify [label="Simplify", prompt="@files-internal/prompts/simplify.md"] ``` -The `@` prefix tells Fabro to load the prompt from a Markdown file, resolved relative to the DOT file's location. This keeps DOT files concise and lets you version prompts as standalone files. See [Prompts](/agents/prompts) for details. +The `@` prefix tells Fabro to load the prompt from a Markdown file, resolved relative to the Graphviz file's location. This keeps Graphviz files concise and lets you version prompts as standalone files. See [Prompts](/agents/prompts) for details. ## Context flow between nodes @@ -100,7 +100,7 @@ The agent reads `plan.md` (as instructed by its prompt), but the preamble gives - **Human gates** (`shape=hexagon`) pause for human input with edge labels as options - **Revision loops** are just edges that point back to earlier nodes -- **Prompt file references** (`@path/to/file.md`) keep DOT files clean +- **Prompt file references** (`@path/to/file.md`) keep Graphviz files clean - **`reasoning_effort`** controls how hard the model thinks - Nodes receive preambles summarizing prior stages diff --git a/docs/tutorials/sub-workflow.mdx b/docs/tutorials/sub-workflow.mdx index eb9faa3c7..2ab90752b 100644 --- a/docs/tutorials/sub-workflow.mdx +++ b/docs/tutorials/sub-workflow.mdx @@ -81,7 +81,7 @@ The child workflow runs through its own start → implement → validate → gat |---|---| | `stack.child_workflow` | Path to the child workflow file (resolved relative to the parent). Preferred. | | `stack.child_dotfile` | Backward-compatible alias for `stack.child_workflow`. | -| `stack.child_dot_source` | Inline child DOT source (alternative to `child_workflow`) | +| `stack.child_dot_source` | Inline child Graphviz source (alternative to `child_workflow`) | | `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 | @@ -134,7 +134,7 @@ For simpler cases, just add more nodes to a single workflow. Sub-workflows add a Complete reference for all node types. - + Full syntax reference including sub-workflow attributes. diff --git a/docs/workflows/stages-and-nodes.mdx b/docs/workflows/stages-and-nodes.mdx index cb7a93ded..dcf74345c 100644 --- a/docs/workflows/stages-and-nodes.mdx +++ b/docs/workflows/stages-and-nodes.mdx @@ -5,7 +5,7 @@ description: "All node types and how they become stages at runtime" ## Nodes vs. stages -A **node** is a step defined in the DOT file at author time. A **stage** is the runtime execution of a node. In a simple linear workflow, each node runs once and produces one stage. But when a workflow loops — for example, an implement-test-fix cycle — the same node can produce multiple stages within a single run. +A **node** is a step defined in the Graphviz file at author time. A **stage** is the runtime execution of a node. In a simple linear workflow, each node runs once and produces one stage. But when a workflow loops — for example, an implement-test-fix cycle — the same node can produce multiple stages within a single run. This distinction matters for observability and debugging: the workflow graph shows nodes, but the run timeline shows stages. Each stage records its own inputs, outputs, duration, and token usage. diff --git a/docs/workflows/variables.mdx b/docs/workflows/variables.mdx index 3184e6497..345375ec3 100644 --- a/docs/workflows/variables.mdx +++ b/docs/workflows/variables.mdx @@ -3,7 +3,7 @@ title: "Variables" description: "Using variables in workflows" --- -Fabro supports `$variable` placeholders that let you parameterize workflows without editing the DOT file. +Fabro supports `$variable` placeholders that let you parameterize workflows without editing the Graphviz file. ## Run config variables @@ -20,7 +20,7 @@ repo_url = "https://github.com/fabro-sh/fabro" language = "rust" ``` -These variables are expanded into the DOT source **before** the graph is parsed. You can use `$variable` anywhere in the DOT file — goals, prompts, labels, scripts, or any other attribute: +These variables are expanded into the Graphviz source **before** the graph is parsed. You can use `$variable` anywhere in the Graphviz file — goals, prompts, labels, scripts, or any other attribute: ```dot title="check.fabro" digraph Check { @@ -40,7 +40,7 @@ When launched with `fabro run run.toml`, Fabro replaces `$repo_name`, `$repo_url ### Undefined variables -If a `$variable` in the DOT file has no matching entry in `[vars]`, Fabro raises an error. This catches typos early — a misspelled `$langauge` fails immediately rather than passing a literal `$langauge` to the LLM. +If a `$variable` in the Graphviz file has no matching entry in `[vars]`, Fabro raises an error. This catches typos early — a misspelled `$langauge` fails immediately rather than passing a literal `$langauge` to the LLM. ### Escaping `$`