Handbook

Ecosystem reference

This page is the repo and workcell topology companion to the Product intersection map and the illustrated Platform reference architecture. The intersection map stays contract-centric; this page shows repos, visibility…

Updated

Purpose

This page is the repo and workcell topology companion to the Product intersection map and the illustrated Platform reference architecture. The intersection map stays contract-centric; this page shows repos, visibility, submodule rules, and integration flows.

For short repo and folder names used in chat and Cursor rules (bp, ks, fl, ff, fpw, …), see the workspace abbreviations glossary (canonical: docs/WORKSPACE-ABBREVIATIONS.md at the multi-repo workspace root).

Machine-readable source:

Run python3 scripts/check_foundation.py to validate the sample discriminator.

Reference architecture (start here)

For layer diagrams, per-element flows, and SVG figures, read Platform reference architecture first.

Quick topology

Forge workspace repo and submodule topology

Repo layout

Topology is grouped by role. For contract edges see Product intersection map. For operator tools without handbook shells see Operator tools.

Core spine (control plane + contracts)

id kind visibility Owns
forge-platform product org Schemas, ADRs, glossary; not runner code long-term
forge-platform-website handbook — Published handbook; only consumer that submodules platform → platform.forgesdlc.com
forge-lenses product org Control plane, run spine UI
forge-lcdl product org Governed LLM transport and contracts
forge-fleet product private Template execution
forge-workcells repo private local_llm_worker and future workcell runners
forgesdlc-kitchensink repo public Design system, UX harness, micro-packs
forge-agents repo private Channel agents (communication, cursor_bridge), packaging, Fleet orchestrator on Granite
forge-cdp-manager product org CDP surface leases, registry, control-plane HTTP (:18770)
blueprints repo public Policy; submodules into platform only
forgesdlc product org Methodology product site → forgesdlc.com

Product handbooks (deploy pairs)

Source repo Handbook shell Domain
forge-fleet forge-fleet-website fleet.forgesdlc.com
forge-lcdl forge-lcdl-website lcdl.forgesdlc.com
forge-lenses forge-lenses-website lenses.forgesdlc.com
forge-intelligence forge-intelligence-website intelligence.forgesdlc.com
forge-sti forge-sti-website sti.forgesdlc.com
forge-dark-factory forge-dark-factory-website autonomy.forgesdlc.com
blueprints blueprints-website blueprints.forgesdlc.com
forge-universe in-repo generator universe.forgesdlc.com

See product link-outs: Forge STI, Forge Universe, Dark Factory.

Operator tools (no handbook shell)

Local operator products documented on platform with in-repo docs only:

id Default port Integrates via
forge-cockpit-web 9775 (COCKPIT_PORT) forge-cdp-manager, Fleet memory (cockpit-memory)
forge-knowledge-assistant 9786 (KA_PORT) CDP SharePoint lease, LCDL atoms, ICS client
forge-certificators 11350 Fleet bank jobs, LCDL pipelines
forge-composer — (CLI) Deploy manifests to consumer repos
forge-llm 11434 gateway LCDL/Lenses LLM_* profiles — see LLM gateway
forge-a11y-checker / A11y Studio varies KS auditors — see Quality lane

Hub: Operator tools.

Granite infra (private hosts)

id kind visibility Owns
forge-intelligence-comprehend runtime private ICS HTTP API on Granite (ics.forgedc.net); FI packs + in-process LCDL; see ADR-0011
forge-matrix infra private Synapse, Element, NATS on Granite; Matrix channel for forge-agents

Deploy: ./deploy-websites.sh --only <handbook-shell> from workspace root for handbook pairs.

How repos integrate (flow)

Operator through Lenses ForgeRun to workcells, Fleet, and human review

Channel agents vs workcells

Channel agents (forge-agents) are long-lived Matrix/web services — KB bots, Cursor bridge, orchestrator registry. Workcells (forge-workcells) are batch runners under ForgeRun (WorkcellRequest → WorkcellResult). They share Fleet deploy on Granite but differ in ingress, lifecycle, and contracts. See Agents handbook and ADR-0010.

Submodule rules

Rule Detail
Platform never in products Product repos (Lenses, Fleet, KS, …) must not submodule forge-platform. Consume via docs URLs and schema copies in CI.
Handbook exception forge-platform-website/forge-platform/ submodule for build only.
Blueprints into platform forge-platform/blueprints/ → autowww/blueprints.
Workcells in consumers KS and (later) Lenses may submodule private forge-workcells via SSH.
Packs stay in KS Domain prompts under tools/forge-micro-agent/packs/; workcells does not own UX rule text.

Submodule decision flow

Submodule placement rules

Where platform and workcell repos may be submoduled versus consumed by handbook URL or schema ID.

  1. Need forge-platform content?First gate: whether the repo needs platform schemas, docs, or ADRs locally.
  2. Building handbook HTML? ----YES--> submodule in fpw onlyHandbook HTML generation is the sole submodule exception for platform content.
  3. Product repo (Lenses/Fleet/KS)? --NO--> use handbook URL + schema IDsRuntime product repos consume platform contracts without a submodule.
  4. Need to run a workcell?Second gate: whether integration requires a governed workcell runner on the host.
  5. YES --> submodule or pip install forge-workcells (private)Private workcells attach via SSH submodule or pip install on the consumer.
  6. Domain pack? --> always in KS (not in workcells repo)UX rule packs and prompt text remain in Kitchen Sink, not workcells.

Workcell → host repo

workcell id Host repo Notes
local_runner forge-platform Self-Host Alpha script (selfhost_runner.py) until extracted
local_llm_worker forge-workcells Micro-agent MVP; LCDL inference
cursor_cli harness / campaign Cursor CLI when governed under ForgeRun
fleet_ux_worker Fleet job container Playwright + optional agent in workspace
campaign_orchestrator operator host Fleet API + git

Workcell attachment to ForgeRun

Workcell attachment fan-out

How one ForgeRun fans out to AgentRuns on workcells, Fleet, and the platform alpha runner.

  1. ForgeRun (frun_*)Governed run record that orchestrates one or more AgentRuns under Lenses.
  2. AgentRun (arun_*) workcell=local_llm_worker host=forge-workcellsMicro-agent path: LCDL inference via the private workcells runner.
  3. AgentRun (arun_*) workcell=fleet_ux_worker host=forge-fleet jobContainerized UX worker path on Fleet infrastructure.
  4. AgentRun (arun_*) workcell=local_runner host=platform scriptSelf-Host Alpha path via platform selfhost_runner.py until extracted.
  5. each completes with WorkcellResult → EvidencePacket path in LensesEvery AgentRun returns traceable results into the Lenses evidence path.

Per-element integration summaries

forge-platform ↔ products

Platform consumption boundaries

How products receive platform contracts without submoduling forge-platform, except the handbook build.

  1. forge-platform --(schema IDs, docs)--> all productsSchema IDs, samples, and handbook docs reach every product as contracts.
  2. forge-platform <-X-- submodule ------ product repos (FORBIDDEN)Product repos must not embed forge-platform as a git submodule.
  3. forge-platform <--- submodule -------- forge-platform-website ONLYThe handbook repo alone submodules platform for HTML generation.

forge-lenses ↔ Fleet / LCDL / workcells

Lenses integration lanes

How Lenses orchestrates Fleet jobs, LCDL traces, and workcells while retaining the ForgeRun decision.

  1. Lenses ---- submits / displays ----> FleetJobSummaryLenses submits Fleet jobs and surfaces job summaries in the control plane.
  2. Lenses ---- displays traces ------> LCDLTraceSummaryGoverned LLM traces from LCDL appear in Lenses for review.
  3. Lenses ---- (post-MVP) invokes ---> forge-workcellsPost-MVP path for Lenses to invoke private workcell runners directly.
  4. Fleet --- never writes final -----> ForgeRun decision (Lenses does)Fleet never owns the final governed decision on a ForgeRun.

forge-workcells ↔ forge-lcdl ↔ KS

KS micro-agent local path

How the KS harness drives workcells and LCDL to produce parseable JSON findings for detection gates.

  1. KS harness --pack path + context.json--> forge-workcellsHarness supplies pack path and assembled context.json to the workcell runner.
  2. forge-workcells --LLM_* profile-------> forge-lcdlWorkcells forwards inference using the configured LLM_* environment profile.
  3. forge-lcdl --HTTP--------------------> gatewayLCDL performs governed HTTP chat/completions against the configured gateway.
  4. forge-workcells --stdout JSON--------> KS parse-ai-agent-findings.mjsRunner stdout JSON feeds the KS findings parser for rule detection.

See Platform reference architecture §7–§8.

Micro-agent data flow (local LLM path)

Micro-agent local LLM path from harness fixture through workcells to detection gate

Private forge-workcells

  • Remote: git@github.com:autowww/forge-workcells.git (visibility Private).
  • Cloners need autowww org read access.
  • CI that clones KS with --llm needs a deploy key or token with repo scope.
  • No forge-workcells-website in MVP.

Cursor path vs --llm path

Step Cursor path --llm path
Rule prompt design-rules/ai/*.md Same + pack prompt.md
Executor agent -p forge-workcells
Profile Cursor quota LLM_* env file
Output parse parse-ai-agent-findings.mjs Same

Harness rule executor choice

How the same harness rule runs via Cursor agent or the --llm workcells path before a shared parse gate.

  1. harness ruleA design-rules AI harness rule enters with the same prompt source on both paths.
  2. CursorDefault path uses the local Cursor agent as executor.
  3. agent -pCursor runs the rule via agent -p against the harness fixture context.
  4. --llmAlternate flag routes execution through governed local LLM infrastructure.
  5. workcells + LCDLforge-workcells runs the pack with LCDL inference under LLM_* profile.
  6. parse + detection gateBoth paths converge on parse and expect-ai-rule-detection.sh validation.