Handbook

Workcell catalog

Registered Forge workcells and the envelopes they speak. Every workcell consumes a forge.workcell_request.v1 and produces a forge.workcell_result.v1 (schemas in schemas/); domain payloads ride inside launch_pack and…

Updated

Executive capsule

Workcells are bounded, replaceable runtimes attached to the ForgeRun spine. The catalog is the single place to see what runs where, what it may touch, and which human decision gates its output.

Who this is for

  • Architects deciding where new automation belongs.
  • Operators wiring runs through forge-workcells, Fleet, or Lenses.
  • Agents validating envelopes before acting on workcell output.

The problem this solves

Without a catalog, workcells accumulate as undocumented scripts with ad-hoc inputs: nobody can say what a runtime may touch, which envelope it speaks, or which human decision gates its output. This page makes registration the price of running.

How it works

Each workcell is registered here with its runtime home, envelope contract, and output gate. Requests and results are schema-validated (forge.workcell_request.v1 / forge.workcell_result.v1); the workcell's domain payload rides inside launch_pack and artifacts using the named domain schemas.

Ecosystem fit

forge-workcells hosts runtime code; forge-lcdl provides governed LLM tasks; forge-fleet is the template-only execution rail for batch runs; forge-lenses is the review surface; forge-platform owns the schemas, this catalog, and the promotion gates.

Registered workcells

Workcell Runtime home Purpose Output gate
local_llm_worker forge-workcells Micro-pack LLM analysis (e.g. UX audit findings) over an assembled context Findings are advisory; harness decides
doc_hydration_worker forge-workcells Hydration v2: seed → claim inventory + hydration brief review pack needs_approval; reviewer decision manifest required before promotion

doc_hydration_worker

  • Request: forge.workcell_request.v1 with workcell: doc_hydration_worker, mode: proposal, and launch_pack.seed_path (plus optional target_surface, persona, use_llm).
  • Pipeline: deterministic claim extraction by default; with use_llm: true the governed forge-lcdl tasks doc_claim_extraction and doc_risk_classification run instead (LLM classifies, never decides truth — all claims stay candidate). doc_draft_expansion is available for draft generation under the same rule.
  • Result: forge.workcell_result.v1 carrying the caller's forge_run_id (frun_*), the worker's agent_run_id (arun_*), status: needs_approval, and artifacts hydration-brief.md + claim-inventory.json (forge.claim_inventory.v1).
  • Review surface: forge-lenses GET /api/doc-hydration/review-packs (read-only) presents briefs, inventories, plans, and reviewer decision manifests.
  • Execution rail: docs build / link check / scorecard runs go through forge-fleet as template-only docker_argv jobs (forge-fleet/docs/examples/doc-hydration/).

Trust boundary

Workcell output is never canonical. Every result carrying needs_approval waits for a human reviewer decision manifest; promotion without one hard-fails (gate G3). LLM steps classify and draft only — claim truth is a human call.

Promotion gates

  1. Dry-run default — scripts/promote_hydration_pack.py --dry-run first; writes require an explicit non-dry invocation.
  2. Reviewer decision manifest required — promotion hard-fails without a valid forge.reviewer_decision_manifest.v1 in the pack.
  3. Source map required — consuming site builds must emit docs_source_map.json so promoted pages are traceable.
  4. One repo per PR/commit — promotion output lands per-repo; build logs attach to the ForgeRun evidence.

Evidence and maturity

Envelope schemas and the promotion manifest gate are demonstrated (unit tests in forge-workcells, forge-lcdl, and forge-fleet; end-to-end evidence under docs/hydration-runs/). Fleet-scheduled scorecard runs are defined, not yet demonstrated in production.

How to use this page

Find the workcell, follow its runtime-home repo for the implementation, and validate request/response payloads against the schemas named above before wiring anything new.

Related / next