From d97a3ef2073af0c4b26c63ece490b7b99355e8fb Mon Sep 17 00:00:00 2001 From: Bryan Helmkamp Date: Fri, 20 Mar 2026 16:32:56 -0400 Subject: [PATCH] Add internal product docs --- docs-internal/product/business-problem.md | 25 ++++++++++++++++++ docs-internal/product/current-state.md | 26 +++++++++++++++++++ docs-internal/product/personas.md | 20 ++++++++++++++ docs-internal/product/product-description.md | 25 ++++++++++++++++++ docs-internal/product/success-metrics.md | 26 +++++++++++++++++++ .../product/technical-requirements.md | 24 +++++++++++++++++ 6 files changed, 146 insertions(+) create mode 100644 docs-internal/product/business-problem.md create mode 100644 docs-internal/product/current-state.md create mode 100644 docs-internal/product/personas.md create mode 100644 docs-internal/product/product-description.md create mode 100644 docs-internal/product/success-metrics.md create mode 100644 docs-internal/product/technical-requirements.md diff --git a/docs-internal/product/business-problem.md b/docs-internal/product/business-problem.md new file mode 100644 index 000000000..f5286f4dd --- /dev/null +++ b/docs-internal/product/business-problem.md @@ -0,0 +1,25 @@ +# The Problem Fabro Solves + +Fabro exists for teams that have outgrown the prompt-act-review loop used by most AI coding tools. + +## Why that loop breaks + +Interactive agent sessions work for small tasks, but they do not define a repeatable software process. In practice this creates four recurring problems: + +- The engineer must supervise the agent instead of defining the process once and reusing it. +- There is no reliable gate between "the agent stopped" and "the work is ready." +- Model choice is hard to control per step, so cost and quality drift. +- Sessions are hard to resume, audit, and improve over time. + +## What Fabro adds + +Fabro treats the process itself as code: + +- Workflow graphs define stages, branching, loops, parallelism, and human gates. +- Model stylesheets route different stages to different models and providers. +- Sandboxes and Git checkpoints make runs isolated, resumable, and inspectable. +- Event logs, verifications, and retros create a feedback loop after execution. + +## Product direction + +Fabro should optimize for trust in long-running workflows, not for chat UX. The product is most useful when expert engineers can design, run, inspect, and improve processes with minimal supervision. diff --git a/docs-internal/product/current-state.md b/docs-internal/product/current-state.md new file mode 100644 index 000000000..739d0f7f3 --- /dev/null +++ b/docs-internal/product/current-state.md @@ -0,0 +1,26 @@ +# Fabro Current State + +This snapshot is intentionally brief and omits volatile counts, benchmarks, and release metrics. + +## Public product shape + +Fabro currently presents as: + +- a CLI for defining and running workflows +- an API server via `fabro serve` +- a React web app for monitoring runs and inspecting workflows +- a docs site and example workflows + +## Core capabilities documented today + +- Graphviz DOT workflows with agent, prompt, command, conditional, human, and parallel stages +- CSS-like model stylesheets for per-stage model routing +- sandboxed execution across local, Docker, Daytona, SSH, and other providers +- Git checkpointing for resume, rewind, fork, and auditability +- structured run artifacts and event streams for observability +- verifications and insights in the broader product surface +- retrospectives, documented as experimental + +## Current positioning + +Fabro is positioned as an open-source, self-hosted workflow orchestration layer for expert engineers. It is not positioned as an IDE plugin, autocomplete tool, or chat-first coding assistant. diff --git a/docs-internal/product/personas.md b/docs-internal/product/personas.md new file mode 100644 index 000000000..c1ed33a76 --- /dev/null +++ b/docs-internal/product/personas.md @@ -0,0 +1,20 @@ +# Fabro Personas + +Fabro is for expert engineers who want to encode software processes as workflows. + +## Primary users + +- **Solo expert engineer**: runs workflows locally to automate planning, implementation, testing, and review loops. +- **Tech lead or platform engineer**: defines shared workflows, model routing rules, and quality gates for a team. +- **Infrastructure engineer**: deploys `fabro serve`, configures sandboxes and auth, and keeps the system reliable. + +## Good fits + +- small teams comfortable with Git, CLIs, and source-controlled workflow files +- teams that want repeatable automations such as PR review, test generation, or docs sync + +## Not a fit + +- beginners looking for guided product education +- non-technical or no-code users +- users mainly seeking IDE autocomplete or a chat-first coding assistant diff --git a/docs-internal/product/product-description.md b/docs-internal/product/product-description.md new file mode 100644 index 000000000..5eb363b65 --- /dev/null +++ b/docs-internal/product/product-description.md @@ -0,0 +1,25 @@ +# Fabro Product Description + +Fabro is an open-source workflow orchestration platform for AI coding agents. Instead of treating software work as a chat session, Fabro lets you define the process as a Graphviz workflow and run it repeatedly. + +## What a workflow can contain + +A workflow can combine: + +- agent stages +- prompt stages +- shell commands +- conditionals +- human gates +- parallel branches + +## What supports execution + +- model stylesheets choose models and providers per stage +- sandboxes isolate execution from the host +- Git checkpoints make runs resumable and auditable +- event logs, verifications, and optional retros help teams inspect outcomes + +## Interfaces + +Fabro is CLI-first, with an API server and React web app for longer-running and shared workflows. diff --git a/docs-internal/product/success-metrics.md b/docs-internal/product/success-metrics.md new file mode 100644 index 000000000..7fcba1c7f --- /dev/null +++ b/docs-internal/product/success-metrics.md @@ -0,0 +1,26 @@ +# Fabro Success Metrics + +For product work, measure trust and useful outcomes, not just command execution. + +## Signals available now + +- CLI telemetry for command success and failure +- per-run event streams in `progress.jsonl` +- run artifacts such as `checkpoint.json`, `conclusion.json`, and verification data +- `retro.json` when retros are enabled +- API and web data for runs, workflows, usage, verifications, and insights + +## Metrics that matter most + +- successful outcomes per workflow type +- cost and duration per successful outcome +- verification pass rate +- retry, loop, and human-intervention rate +- resume, rewind, and fork usage + +## Current gaps + +- command success is not the same as product success +- install, activation, and retention metrics are weak +- some aggregate usage is server-local and resets on restart +- cross-run comparison is still immature diff --git a/docs-internal/product/technical-requirements.md b/docs-internal/product/technical-requirements.md new file mode 100644 index 000000000..abbc1cd70 --- /dev/null +++ b/docs-internal/product/technical-requirements.md @@ -0,0 +1,24 @@ +# Fabro Technical Requirements + +This note captures stable constraints that product changes should respect. + +## Core constraints + +- Fabro ships primarily as a single Rust binary with CLI and server modes. +- Workflows are defined in Graphviz DOT and should remain reviewable as source files. +- The workflow engine must support loops, branching, parallel stages, commands, agent stages, and human gates. +- Model routing is per-stage and provider-agnostic through stylesheets and config. +- Execution happens through sandbox providers rather than assuming direct host access. +- Git checkpointing is central to resume, rewind, fork, and auditability. +- Runs produce structured artifacts such as `progress.jsonl`, `live.json`, `checkpoint.json`, and optional `retro.json`. +- The HTTP API is OpenAPI-based, and the web app depends on that contract. + +## Operational constraints + +- Documented targets are macOS arm64, Linux x86_64, and Linux arm64. +- Git is required for checkpointing-related workflows. +- Docker, Graphviz, and SSH are optional system dependencies depending on the features in use. + +## Design bias + +Prefer changes that improve determinism, observability, resumability, and safe unattended execution. Avoid features that only make sense as IDE autocomplete or a chat-first REPL.