Handbook

Agents and workcells

This section is the canonical handbook for Forge Agent sessions, workcells, forge runners, campaigns, workflows, and the private forge-workcells repo. Platform schemas live in schemas/; execution code lives in product…

Updated

Reading order

  1. Terminology — names, aliases, anti-patterns
  2. Forge Agent — pattern, AgentRun, governance modes
  3. Workcell model — roles and request/result envelope
  4. Forge runner — executable vs record vs workcell id
  5. Workflows and runs — ForgeRun, Fleet, harness, campaign
  6. Governed workflows and rules — approval gates, DecisionPack, campaign phases
  7. Workcell catalog — maintained id → host matrix
  8. Contracts — schema pointers and samples
  9. Documentation hydration and rehydration design — seed Markdown, routing, promotion, rehydration
  10. Documentation hydration agent — Markdown seed → reviewable docs drafts
  11. Forge micro-agent — local_llm_worker pilot
  12. Forge Campaign — multi-repo automation under one ForgeRun
  13. Self-Host local runner — local_runner alpha
  14. forge-workcells repo — private runners

Terminology (short)

Term What it is
Forge Control-plane envelope (not an agent)
ForgeRun Governed run container (frun_*)
Forge Agent Pattern for a bounded agent session
AgentRun Record of one session (arun_*)
Workcell Bounded role: WorkcellRequest → WorkcellResult
Workcell id Stable string (hermes, local_llm_worker, …)
Forge runner Code that executes a workcell
forge-workcells Private repo for shared runner implementations
Micro-agent Single local-LLM judgment (local_llm_worker)
Forge Campaign Multi-repo effort under one ForgeRun
Fleet job Container execution (not the run SoR)
Harness run KS ruleset test (ForgeRun optional)
Governed workflow LCDL DAG or operators (not platform BPM)
DecisionPack Versioned graph spec in forge-lcdl
Approval gate Human/policy record before execution

Workcells reference architecture

How a ForgeRun anchors agent sessions, executable runners, and Lenses evidence on one governed spine.

  1. ForgeRun (frun_*)The governed run container records the overall agents-and-workcells effort.
  2. AgentRun (arun_*) + workcell idEach bounded session binds one workcell identity under the parent ForgeRun.
  3. Forge runner (executable)Runnable code receives WorkcellRequest and returns WorkcellResult.
  4. platformforge-platform hosts the Self-Host local_runner executable path.
  5. workcellsforge-workcells implements shared private runners such as local_llm_worker.
  6. fleet containerFleet executes containerized workcells including fleet_ux_worker jobs.
  7. selfhostSelf-Host runner executes on the operator machine without a Fleet container.
  8. local_llmMicro-agent path issues one governed LCDL judgment per workcell invocation.
  9. fleet_ux_workerIn-container UX audit and remediation worker with optional headless agent steps.
  10. EvidencePacket / Approval (Lenses)Structured proof and human approval gates attach for reviewable execution.

Workcells terminology map

Platform context