Handbook

Workflows and runs

How ForgeRun, AgentRuns, Fleet jobs, campaigns, and harness runs relate. For conditional rules (approval, DecisionPack, campaign phases) see Governed workflows and rules.

Updated 2026-07-26

ForgeRun spine (production)

Production ForgeRun spine

How human intent becomes a governed workcell run with traceable evidence and a reviewable decision.

Human intentThe operator states what they want the run to accomplish.
Lenses opens ForgeRun (frun_*)Lenses creates a ForgeRun record with a stable frun_* identifier.
BlueprintContextPack (optional)Optional blueprint context enriches the run with governed methodology references.
WorkcellRequest -> Forge runner -> WorkcellResultA WorkcellRequest invokes the Forge runner and returns a structured WorkcellResult.
LCDLTraceSummary / FleetJobSummary (optional)Optional summaries attach LCDL graph traces or Fleet job outcomes to the run.
EvidencePacketRun artifacts are assembled into a reviewable EvidencePacket.
Lenses review / ForgeRun decisionThe operator reviews evidence and records the ForgeRun decision in Lenses.

  Human intent
    -> Lenses opens ForgeRun (frun_*)
    -> BlueprintContextPack (optional)
    -> WorkcellRequest -> Forge runner -> WorkcellResult
    -> LCDLTraceSummary / FleetJobSummary (optional)
    -> EvidencePacket
    -> Lenses review / ForgeRun decision

On-disk alpha layout: Self-Host run store.

Parallel paths under one ForgeRun

Parallel paths under ForgeRun

One ForgeRun may branch through campaign orchestration, governed LCDL graphs, or a single workcell before converging on evidence.

ForgeRun (frun_*)The frun_* record is the shared parent for every execution path below.
[B] Campaign orchestrator + Fleet jobManifest-driven campaign phases coordinate branches and POST Fleet jobs.
[C] LCDL graph DecisionPack + trace summaryA governed LCDL DAG runs with DecisionPack rules and emits a trace summary.
single workcell (one AgentRun)One runner invocation handles the intent without campaign or LCDL orchestration.
EvidencePacket + decisionEvery path converges on a reviewable evidence bundle and a Lenses decision.

                      ForgeRun (frun_*)
                             |
           +-----------------+------------------+
           |                 |                  |
           v                 v                  v
     [B] Campaign      [C] LCDL graph      single workcell
     orchestrator      DecisionPack        (one AgentRun)
     + Fleet job        + trace summary     e.g. local_runner
           |                 |                  |
           +-----------------+------------------+
                             v
                    EvidencePacket + decision

[B] — Forge Campaign: manifest-driven phases, not DecisionPack.
[C] — Governed workflows and rules: LCDL DAG attached via trace/evidence (R3 visibility on Lenses).
Single workcell — one runner invocation per AgentRun (typical Self-Host Alpha).

Forge Campaign flow

Forge Campaign execution flow

How an operator launches a manifest-driven campaign that runs Fleet workers and lands on evidence plus a Lenses decision.

Operator -> frun_* + campaign.yamlThe operator opens a ForgeRun and supplies the campaign manifest.
campaign_orchestrator: branches, pack, POST FleetThe orchestrator evaluates branches, assembles context, and submits Fleet jobs.
fleet_ux_worker (container): audit/remediateA Fleet container runs audit and remediation steps inside bounded job boundaries.
orchestrator: integrate, PR stack, verifyThe orchestrator integrates outputs, manages the PR stack, and runs verification gates.
EvidencePacket + Lenses decisionCampaign artifacts become an EvidencePacket for operator review and decision in Lenses.

  Operator -> frun_* + campaign.yaml
           -> campaign_orchestrator: branches, pack, POST Fleet
           -> fleet_ux_worker (container): audit/remediate
           -> orchestrator: integrate, PR stack, verify
           -> EvidencePacket + Lenses decision

See Forge Campaign for manifest and lifecycle states.

Fleet-only execution

Fleet-only job execution

How a single approved Fleet template runs to completion without a campaign orchestrator.

Approved FleetTemplateA pre-reviewed template defines the containerized job the operator may launch.
POST /v1/jobs (+ workspace upload)The client submits the job and uploads the workspace Fleet needs.
poll terminal stateThe caller polls until the job reaches a terminal success or failure state.
FleetJobSummary -> EvidencePacket path -> LensesJob outcomes feed the evidence path and surface for review in Lenses.

  Approved FleetTemplate
    -> POST /v1/jobs (+ workspace upload)
    -> poll terminal state
    -> FleetJobSummary -> EvidencePacket path -> Lenses

No campaign required when a single template job satisfies the intent.

Harness / auditor (development)

Harness and auditor pipeline

How Kitchen Sink fixtures and rules drive analysis, optional LLM review, and a bounded detection gate in development.

KS fixture + rulesetA Kitchen Sink fixture and ruleset define what the harness will inspect.
analyze / assemble contextThe harness analyzes the target and assembles context for downstream checks.
optional --llm -> local_llm_worker OR Cursor CLIAn optional LLM pass routes through local_llm_worker or the Cursor CLI agent.
parse findings -> detection gateParsed findings pass through a detection gate before the harness reports results.

  KS fixture + ruleset
    -> analyze / assemble context
    -> optional --llm -> local_llm_worker OR Cursor CLI
    -> parse findings -> detection gate

ForgeRun is optional in harness mode; contracts still align when recording an AgentRun for integration tests.

Separate agents as workcell ids

Hermes, Factory Droid, OpenClaw, Cursor CLI, and future agents appear as workcell ids on AgentRuns — not as alternate run models. See Workcell catalog.

Forge Platform