Handbook

Platform reference architecture

Visual companion to the Ecosystem reference (machine-readable ecosystem_reference.v1) and the Product intersection map (contracts). This page explains how each element fits and how data flows between repos and products.

Updated

Diagrams below use ASCII flowcharts (handbook-safe). SVG versions live under docs/assets/ecosystem/ and are copied into the published handbook as platform-handbook-assets/.

1. Layered reference model

Governance (schemas, ADRs) is separate from runners (workcells) and products (Lenses, Fleet, LCDL, KS).

Platform layered reference model

How governance, the Lenses control plane, runners, and shared practice layers relate without product submodules of platform.

  1. GOVERNANCE (sibling)forge-platform holds schemas, ADRs, glossary, and ecosystem_reference as a sibling repo.
  2. CONTROL PLANEforge-lenses is the local ForgeRun, evidence, and approval UI over .forge/runs.
  3. forge-lcdlGoverned LLM transport and trace summaries for workcell tasks.
  4. forge-fleetControlled docker_argv job execution with templates and job logs.
  5. forge-workcellsPrivate workcell runner code including local_llm_worker and pack loading.
  6. blueprintsCanonical SDLC/PDLC policy, Versonas, and recipes as standalone source.
  7. forgesdlc-ksDesign system, micro-packs, and the website-ux-auditor harness.
  8. forge-sdlcMethodology product site publishing ForgeSDLC practice knowledge.

Platform layers (SVG)

2. ForgeRun spine (system of record)

Every governed effort hangs off one ForgeRun (frun_*). Workcells attach AgentRuns (arun_*) and return WorkcellResult; humans decide via EvidencePacket and ApprovalRequest.

ForgeRun spine flow

How human intent becomes a traceable ForgeRun with agent work, evidence, and approval on disk.

  1. [Human intent]The operator or orchestrator states what governed work should accomplish.
  2. Lenses (control)Lenses creates the ForgeRun and reads or writes .forge/runs/ in the workspace.
  3. ForgeRun frun_*The frun_* record anchors all related agent and workcell activity.
  4. AgentRun arun_*Each arun_* binds a workcell id to work under the parent ForgeRun.
  5. Workcell runner (see §3–§8)The bound runner receives WorkcellRequest and returns WorkcellResult.
  6. EvidencePacket / ApprovalRequestStructured proof and human approval gates attach to the ForgeRun for review.

ForgeRun spine (SVG)

3. Element: forge-platform

Role Owns Does not own
Cross-product truth schemas/*, ADRs, ecosystem sample Executing workcells, UI, LLM calls

forge-platform contract publishing

How platform governance reaches the handbook and product repos without becoming a product submodule.

  1. forge-platformCross-product truth lives in schemas, ADRs, glossary, and ecosystem samples.
  2. forge-platform-website (fpw)fpw submodules platform only to build the private handbook HTML.
  3. Product repos (read URLs / CI schema)Other products consume platform contracts by URL and CI schema validation.

Integration: All products consume platform contracts; only fpw submodules platform for HTML build. See ADR-0008.

4. Element: forge-lenses

Role Owns Does not own
Local control plane Run list, evidence review, approvals Hidden LLM reasoning, Docker execution

forge-lenses control plane

How operators review runs, policy context, and runner summaries through Lenses Studio.

  1. OperatorA human opens Lenses Studio to inspect and guide workspace runs.
  2. Lenses StudioStudio API and UI read and write .forge/runs/ beside the workspace.
  3. .forge/runs/ in workspaceOn-disk run state is the shared system of record for ForgeRuns.
  4. Blueprints contextPolicy and Versona context informs what Lenses shows and agents may read.
  5. WorkcellResult / FleetJobSummary / LCDLTraceSummaryRunner artifacts land as reviewable summaries for evidence attachment.

Post-MVP: Lenses will submodule forge-workcells and orchestrate local_llm_worker (design: forge-lenses workcells roadmap).

5. Element: forge-lcdl

Role Owns Does not own
Governed LLM transport LLM_* profile, chat/completions, task contracts Run spine, approval UI

forge-lcdl governed transport

How a workcell task becomes a traceable LLM call and optional evidence on the ForgeRun spine.

  1. WorkcellRequest / task specA runner or harness supplies the governed task or workcell request to LCDL.
  2. forge-lcdl transportLCDL posts to the configured LLM gateway and parses assistant JSON or text.
  3. LCDLTraceSummary (optional artifact)An optional trace summary captures call metadata for downstream review.
  4. EvidencePacket attachment via LensesLenses links LCDL output into the ForgeRun evidence trail for humans.

Micro-agent: read_profile_from_env_file + gateway_probe_lcdl.py before harness --llm.

6. Element: forge-fleet

Role Owns Does not own
Controlled execution Templates, job logs, workspace extract Policy text, final approval

forge-fleet job execution

How approved jobs run in bounded containers and return summaries for Lenses review.

  1. campaign_orchestrator / Lenses-approved jobAn orchestrator or Lenses-approved request enqueues controlled execution.
  2. forge-fleet APIFleet accepts the job and launches docker_argv against a template.
  3. container fleet_ux_workerThe worker container runs the bounded automation and returns worker_result.
  4. FleetJobSummary ---> Lenses / EvidencePacketJob summary flows to Lenses for evidence attachment and human review.

7. Element: forge-workcells (private)

Role Owns Does not own
Runner code local_llm_worker, pack loader, arun_* dirs Domain packs, schemas

forge-workcells micro-agent runner

How KS or Lenses invokes local_llm_worker with packs, LCDL, and governed finding parse.

  1. Consumer (KS harness, later Lenses)The UX harness or future Lenses orchestrator starts a workcell run via CLI.
  2. forge-workcells local_llm_workerThe private runner loads packs and coordinates LLM calls for the task.
  3. micro-pack (path from KS)KS supplies the domain micro-pack path for the ruleset under test.
  4. forge-lcdl (LLM_* env)LCDL transport satisfies LLM calls using the configured LLM_* profile.
  5. agent-output.txt / micro-agent.logRunner writes raw agent output and logs for downstream parsing.
  6. parse-ai-agent-findings.mjs (KS)Kitchen Sink parses findings into expect-ai-rule-detection.sh assertions.

Workcells + micro-agent (SVG)

8. Element: forgesdlc-kitchensink

Role Owns Does not own
Design system + UX harness micro-packs, website-ux-auditor, fixtures Workcell runtime

Kitchen Sink UX harness path

How KS assembles audit context and invokes workcells for governed local-LLM rule checks.

  1. tools/forge-micro-agent/packs/ux-ai-rule-v1/The UX micro-pack defines the AI ruleset under test for the harness.
  2. context.jsonAssembled context bundles audit slice and Playwright evidence for the LLM.
  3. analyze-website-ux.mjs (fixture URL)Deterministic UX analysis feeds the audit slice into context assembly.
  4. invoke-ai-ruleset-harness.sh --llmThe harness script runs the ruleset against context using the local LLM path.
  5. forge-workcells (sibling or submodule)Workcells executes the pack as a private runner beside or inside KS.

9. Element: blueprints

Role Owns Does not own
Canonical policy SDLC/PDLC, Versonas, recipes Live run state

blueprints policy distribution

How canonical policy reaches platform and consumers as read-only BlueprintContextPack.

  1. autowww/blueprints (standalone)Canonical SDLC, PDLC, Versonas, and recipes live in the standalone repo.
  2. forge-platform/blueprints/Platform submodules blueprints as its only embedded policy copy.
  3. Lenses / Hermes / Factory (read policy, do not write SoR)Consumers read BlueprintContextPack for policy; they never own live run state.

10. Element: forge-platform-website

Role Owns Does not own
Handbook HTML Firebase deploy shell Canonical Markdown source

forge-platform-website publish path

How canonical Markdown becomes the private platform handbook on Firebase.

  1. autowww/forge-platform (source of truth)Canonical Markdown, schemas, and docs live in the platform git repo.
  2. forge-platform-website/forge-platform/fpw embeds platform via git submodule for HTML generation only.
  3. website/*.html ---> Firebase forge-platform-1541dbuild-site.py plus kitchensink emits static HTML deployed to Firebase hosting.

11. Git / submodule topology

Workspace git submodule topology

Which repos are siblings, which submodules are allowed, and where platform embedding is forbidden.

  1. workspace/The Code workspace hosts sibling governance and product repos side by side.
  2. forge-platform/ [sibling — governance]Platform stays a sibling repo; product repos must not submodule it.
  3. blueprints/ --------> autowww/blueprintsPlatform embeds blueprints as its policy submodule only.
  4. forge-platform-website/fpw is the Firebase deploy shell for the private handbook.
  5. forge-platform/ ----> autowww/forge-platform (ONLY allowed platform submodule)fpw alone may submodule forge-platform for HTML builds per ADR-0008.
  6. kitchensink/fpw embeds kitchensink for shared handbook layout and components.
  7. forge-workcells/ [private sibling or KS submodule]Runner code lives as a private sibling or optional KS submodule.
  8. forge-lenses/Lenses is a standalone control-plane sibling without platform submodule.
  9. forge-lcdl/LCDL is a governed LLM library sibling consumed by workcells and harnesses.
  10. forge-fleet/Fleet is a controlled execution sibling emitting job summaries to Lenses.
  11. forgesdlc-kitchensink/KS holds design system assets, micro-packs, and UX harness tooling.
  12. tools/forge-micro-agent/packs/Domain micro-packs for governed AI rule checks live under KS tools.
  13. (optional) forge-workcells/ ---> autowww/forge-workcellsKS may optionally submodule private workcells for local harness runs.
  14. FORBIDDEN: forge-lenses/forge-platform/ forge-fleet/forge-platform/ forgesdlc-kitchensink/forge-platform/Product repos must not embed forge-platform; contracts flow by URL and schema only.

Git submodule topology (SVG)

12. Contract bus (how products integrate)

Contract bus integration hub

How ForgeRun anchors evidence, approvals, and workcell artifacts across product producers and consumers.

  1. ForgeRunfrun_* is the hub contract all integrated products read and extend.
  2. Evidence PacketStructured proof artifacts attach to the run for reviewable execution history.
  3. Approval RequestHuman gates record decisions before bounded work continues.
  4. AgentRun + WorkcellResultRunner identity and outcomes link workcells back to the parent ForgeRun.
  5. Lenses UILenses produces and consumes run contracts for local-first inspection.
  6. Human reviewerOperators approve or reject against evidence before downstream automation proceeds.
  7. Workcells Fleet LCDLRunners emit agent runs, results, and product-specific summaries upstream.
Contract Typical producer Typical consumer
forge.run.v1 Lenses, campaign orchestrator All products (read)
forge.evidence_packet.v1 Any workcell Lenses
forge.workcell_request.v1 Lenses, orchestrator Workcell runner
forge.workcell_result.v1 Workcell runner Lenses
forge.agent_run.v1 Runner / platform alpha Lenses
LCDLTraceSummary forge-lcdl Lenses
FleetJobSummary forge-fleet Lenses
BlueprintContextPack blueprints Lenses, agents
forge.ecosystem_reference.v1 forge-platform Docs, tooling

Element integration hub (SVG)

13. Micro-agent: Cursor vs local LLM (comparison flow)

Micro-agent Cursor vs LLM paths

How the same AI ruleset harness runs via Cursor or local workcells with one parse and assert tail.

  1. AI ruleset / harness rule NThe harness selects one governed rule from the UX micro-pack ruleset.
  2. Cursor path / agent -pCursor agent -p executes the rule using the IDE agent path.
  3. --llm path / workcellsThe harness delegates execution to forge-workcells with LCDL transport.
  4. ai-agent.logCursor path output log feeds the shared findings parser.
  5. context.json + LCDLLLM path assembles context and records governed gateway interaction.
  6. parse-ai-agent-findings.mjsKitchen Sink normalizes findings from either execution path.
  7. expect-ai-rule-detection.shAssertions verify the rule fired as expected in the harness fixture.

14. Element: Intelligence Comprehension Service (ICS)

Role Owns Does not own
Granite HTTP runtime /v1/comprehend, session M/H, deterministic-first ladder, FI orchestration in-process ForgeRun SoR, Matrix rooms, CDP automation flows

Intelligence Comprehension Service flow

Clients call ics.forgedc.net; ICS embeds FI packs and LCDL without client-side lmeta.

  1. Channel agents / KA / Cockpit / productsHTTP clients with bearer token; no embedded FI packs.
  2. ics.forgedc.netCloudflare tunnel to Granite Fleet container fi-comprehend.
  3. deterministic catalogRules and exact matches short-circuit before token spend.
  4. FI router and packsProblem-class orchestration with allowlist and maturity gates.
  5. session M/H volumeMachine JSON and human report persisted on Granite.
  6. Lenses attach payloadNon-authoritative projection returned for evidence attach.

Canonical docs: forge-intelligence/docs/comprehension/. Platform hub: Intelligence Comprehension Service. ADR: ADR-0011.