> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Synthesis

> How Forge creates a missing skill, agent or procedure for the Workflow Architect: reuse first, Builders, the Coherence Gate, provisional use, the budget and the Curator.

**Synthesis** is what happens when the [Workflow Architect](https://docs.gloo.com/forge/build/use-workflow-architect.md)
needs a primitive (a skill, an agent or a procedure) that does not yet exist in the workspace
catalog. Instead of failing the design, the Architect asks a **Builder** to create it. Judges check
the plan and the result, the primitive lands as provisional, and a person reviews it.

Synthesis is scoped to the workspace. A synthesized primitive belongs to the workspace that asked
for it and never appears in another workspace's catalog. Each synthesis reaches a person as a
[human task](https://docs.gloo.com/forge/run/approvals-and-hitl.md#human-tasks) in **My Work**, and every stage is recorded,
so you can reconstruct why a primitive landed or did not.

The price of cheap synthesis is operating discipline: a workspace synthesis budget, a Curator that
sweeps the catalog, and review queues for the primitives that land. In Forge Console, all of
it lives under **Platform → Synthesis**, with **Templates**, **Settings** and **Curator** tabs.

## When synthesis fires

Synthesis is the last resort, not the first move. The Architect searches first:

1. **Search the catalog.** The Architect searches the workspace's existing skills, agents and
   procedures for the intent.
2. **Score relevance.** The `judge-primitive-relevance` judge grades each candidate against the
   requested intent. Scores are cached per intent, so repeated sessions on the same intent reuse
   them.
3. **Reuse a good candidate.** If a candidate scores above the workspace's reuse threshold, the
   Architect plans with it and no synthesis fires.
4. **Otherwise, synthesize.** The Architect asks the matching Builder.

Each workspace sets a default synthesis mode on the **Settings** tab: **Off**, **Ask** or **On**. It
controls whether new Architect sessions start with synthesis enabled; a person can change it for one
session from the Architect drawer. The budget cap applies in every mode.

## The three Builders

| Builder | Creates |
| - | - |
| `skill-builder` | A skill: its instructions and, optionally, the tools it allows |
| `agent-builder` | An agent definition: prompt, skills, tool sets and model |
| `procedure-builder` | A procedure: its manifest and bundled code, as a draft version |

Each Builder is an ordinary agent, governed by Trust Fabric like any other.

## How a synthesized primitive is admitted

Synthesis runs in the same order for every kind of primitive:

1. The Workflow Architect proposes what to build, and a person confirms the plan (a
   `synthesis_confirmation` human task). When the plan builds two or more primitives, the
   [Coherence Gate](#the-coherence-gate) checks them as a set before the person can accept it.
2. A Builder parses the request (intent, expected input and output, constraints) and generates a
   draft.
3. The draft lands as **provisional** once it passes its structural checks. A procedure, for
   example, needs passing sandbox tests and a clean spec lint; one whose sandbox validation fails
   goes to review. A quality judge scores every draft. By default a non-passing verdict is logged
   but does not block promotion; when an operator sets that kind's judge gate to `enforce`, a
   non-passing draft goes back for a re-spec and reaches review only if that fails.
4. An [admission panel](#the-admission-panel) of judges scores the provisional primitive, and a
   person reviews it (a `synthesis_review` human task).

### The Coherence Gate

The Coherence Gate checks a planned set of primitives for consistency before any Builder runs. It
runs on the proposed plan, before the person accepts it, and only when the plan builds two or more
primitives; a single primitive skips it, because there is nothing to be consistent with.

The gate calls one judge, `judge-synthesis-coherence`, with the whole set. It scores whether the
skills, agents and procedures agree on capabilities, on what each agent uses each skill for, on the
inputs and outputs passed between agents and procedures, and on each item's purpose. A confident
`fail` keeps the plan's **Accept** button disabled; `needs_work` or a low score on one criterion
shows as a warning and does not block.

### The admission panel

After a Builder lands a draft, an admission panel judges that one primitive:

* The **quality judge** for its kind (skill, agent or procedure), using the verdict the Builder
  already recorded.
* **`judge-primitive-feasibility`**, which checks that the capabilities the primitive needs resolve
  in your organization.

The panel's verdict is recorded with the primitive and shown to the reviewer. Duplicate detection
(`judge-curator-duplicate`) compares two primitives, so it belongs to the [Curator](#the-curator),
not to this panel.

## Provisional-first use

A synthesized primitive does not need approval before the workflow that triggered it uses it. The
Architect uses the provisional primitive immediately, and an operator reviews it on their schedule.
The workflow that needed the primitive is also the one that proves it works: if the run succeeds,
the primitive earns evidence; if it fails, the primitive is demoted automatically and the demotion
shows in the review queue.

## Duplicate requests share one build

Two concurrent Architect sessions can ask for the same synthesis at the same moment. Forge
recognizes identical requests by their intent and expected input and output, so both sessions wait
on the same Builder run and consume one budget reservation instead of two. The second session's plan
records that it reused the existing request.

## Improving an existing primitive

Sometimes the Architect finds a primitive that nearly fits but fails on a real case. Instead of
synthesizing a near-duplicate, it requests an improvement with the target, the evidence (what failed
and the case that must pass) and the requested change. This works for procedures, skills and agents.

The Builder never edits the version that is serving live traffic:

* **Procedures** clone the active version forward into a new draft version of the same procedure.
* **Skills and agents** get a **shadow**: a separate copy of the target with its own id. An agent's
  shadow does not copy the agent's skill and tool-set grants; those stay on the agent, and the
  shadow is checked against them.

When the Builder finalizes, the improved copy must pass two checks:

1. **Its judge**, as for any synthesized primitive.
2. **The regression gate.** The exemplars the target had when the improvement was requested are
   frozen on the request. The improved copy runs against every one of them, against the acceptance
   case from the evidence when there is one, and against any exemplar the Builder added. The Builder
   cannot remove a frozen exemplar or the acceptance case. In the default `enforce` mode, a failing
   improvement goes back to the Builder with the failing exemplars named; only an explicit `warn`
   setting logs the regression and promotes anyway.

An improvement that passes becomes a new **provisional** version of the target. The live version
stays live until an operator approves the new one, under the same approval policy as any other
version. An improvement whose content matches the live version, or another improvement still
awaiting approval, goes to operator review instead of creating a version. If a later improvement
replaces an earlier one's provisional version, the earlier request can no longer be approved;
demoting it closes it. A second improvement of the same primitive is refused while one is in
progress.

### Improvements proposed from proven cases

The Architect is not the only source of skill improvements. Once a week, Forge looks for
[knowledge](https://docs.gloo.com/forge/knowledge.md) cases that were resolved the same way and turns a shared pattern into
a skill improvement.

* **Eligible cases.** Only `proven` cases in the scope types that `knowledge.distillationScopes`
  names. The default is company and global, the only scopes already readable across the workspace,
  as every skill is. The setting can narrow that set but never widen it.
* **Clusters.** Two proven cases in the same namespace belong together when a knowledge search for
  one returns the other with a cosine similarity of at least `knowledge.distillationMinScore`. A
  group needs at least `knowledge.distillationMinClusterSize` cases (default 5). A cluster that
  produced a request is never proposed again; one that was skipped or failed is reconsidered the
  next week.
* **Target skill.** The target is the skill recorded for at least 60% of the cluster's cases. A
  cluster without one is skipped.
* **Case exemplars.** One bounded model call per cluster picks one to three short verbatim phrases
  from each case. Case text is redacted before it is read, and a cluster left with fewer than two
  exemplars is skipped.
* **Request.** The case exemplars are frozen into the regression gate, which always blocks for a
  request distilled from cases. The exemplars gate the improvement but are not copied into the
  skill, so no case text ships in the approved skill.
* **Approval.** The result is a provisional version that replaces nothing until an operator approves
  it under `synthesis:approve`.

At most three requests are made per weekly run. A skill that is already being improved, or a
workspace whose synthesis budget is spent, skips the cluster without failing the sweep.

## The workspace synthesis budget

Synthesis is metered. Each workspace has one synthesis budget, configured on the **Settings** tab:

| Setting | Default | What it controls |
| - | - | - |
| Monthly cap | None until you set one | Synthesis spend ceiling per evaluation window. Until a workspace configures a budget, synthesis runs with no cap. Zero disables synthesis. |
| Rolling window | 30 days | The evaluation window for the cap. |
| Alert threshold | 80% | The share of the cap at which the synthesis-budget alert fires. |

To turn synthesis off, set the cap to zero. Existing provisional primitives keep working; new
synthesis requests fail with `SYNTHESIS_BUDGET_EXCEEDED`, and the Architect shows a budget-blocked plan card.
There is no soft off.

### Reservation and reconciliation

1. **Reserve at dispatch.** Each Builder run reserves its estimated cost against the budget. A burst
   of concurrent runs cannot exceed the cap by more than one estimate's worth.
2. **Reconcile at the end.** When the Builder finishes, is deduplicated, bails out or is demoted,
   Forge applies the difference between actual and estimated cost: under-spend is refunded and
   overshoot is charged. Work that consumed no compute is refunded in full.
3. **Hourly sweep.** An hourly sweep reconciles requests that ended without the normal finish step,
   such as a force-kill. Reservations also expire, so a Builder that hangs does not hold its slot
   forever.

### Alerts

When spend first crosses the alert threshold in a window, Forge sends one `synthesis.budget_warning`
notification. Then decide whether to:

* **Raise the cap** to give synthesis more room.
* **Disable synthesis** by setting the cap to zero.
* **Audit recent synthesis** to see, by actual cost, what is spending the budget.

If you hit the threshold often, check the reuse rate first. When `judge-primitive-relevance` rejects
candidates that operators would have accepted, the reuse threshold is too high and the budget is
spent synthesizing things the Architect should have reused.

## The Curator

The **Curator** keeps the synthesized catalog from sprawling. It runs scheduled sweeps, and its
findings land on the **Curator** tab. Synthesis is cheap to add because the Curator makes it cheap
to subtract.

> [!NOTE]
>
> Each pending Curator recommendation is a group human task that asks everyone who holds
> `synthesis:approve` at the platform scope. It is listed in their [My Work](https://docs.gloo.com/forge/console/my-work.md#review-queues),
> can be claimed and taken over on the queue page, and is reported by a daily digest after 7 days. It
> stays open until someone decides it.

### Pending review

A synthesized primitive that landed provisional and is waiting for operator confirmation. Each item
shows the judge panel verdict, the originating Architect session, and the first runs that used the
primitive. **Confirm** promotes it to non-provisional status. **Edit** opens the matching builder
pre-filled. **Reject** deletes it and records the reason.

### Auto-deprecate candidates

A daily sweep deprecates a provisional primitive that nothing has referenced or dispatched for 60
days (a primitive that was never used counts from its creation). A primitive that is in a pending
Curator recommendation, or a procedure that a workflow draft or active version still references, is
held back. Each deprecation is also recorded so that an identical synthesis request is answered as
abandoned instead of being rebuilt.

### Duplicate suggestions

`judge-curator-duplicate` flags pairs of primitives that look like near-duplicates. The item shows
both side by side with a **Merge** action: pick a winner, deprecate the other, and redirect
references. The Curator also flags two primitives that share a parent but have drifted apart.

## Synthesis templates

Templates narrow what a workspace accepts from synthesis. Use one when:

* the workspace bans a capability domain, such as external email, and synthesized agents must not
  declare it;
* synthesized skills must always carry a constraint, such as using the company name or the metric
  system; or
* synthesized procedures must not declare direct egress.

Add a template on the **Templates** tab. Each template declares what it applies to (`skill`, `agent`
or `procedure`), its rules, and a status (`active`, `disabled` or `draft`). The template rule format
is still stabilizing. The spec linter checks each procedure and agent synthesis spec against the
active templates before a Builder generates anything, and reports every violated constraint (a
pattern, a length bound or an allowed-values list) as a lint issue on the spec.

## Drift alerts

A daily check compares each Builder's latest metrics with the week before and raises a drift alert
when a signal trips its threshold:

* **Review pass rate:** below 80% is a warning; below 70% is critical.
* **Review score regression:** a drop of more than 10% week over week.
* **Archetype selection accuracy** (agent builder only): below 90%.
* **Cost regression:** an increase of more than 50% week over week.

An alert resolves itself once its signal no longer trips the threshold.

To resolve one, work out whether the rubric, the model or the
shape of the requests moved, and fix the one that did.

## What healthy synthesis looks like

* Monthly spend is well under the cap, and the cap is high enough that you rarely think about it.
* The Curator queue stays short. A growing queue means people are ignoring it; one that is always
  empty means synthesis is not happening.
* The reuse rate is high: most Architect requests find an existing primitive.
* The auto-deprecate rate is low: primitives that land actually get used.

## Related

* [Use the Workflow Architect](https://docs.gloo.com/forge/build/use-workflow-architect.md): how plans and synthesis reach you.
* [Judges](https://docs.gloo.com/forge/concepts/trust-fabric.md#judges): the judges synthesis uses.
* [Synthesis queue](https://docs.gloo.com/forge/console/platform/synthesis-queue): the Console guide for review decisions.
* [Procedures](https://docs.gloo.com/forge/concepts/procedures.md): the primitive synthesis prefers when the work allows it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.