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.
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).
+------------------------------------------------------------------+
| GOVERNANCE (sibling) |
| forge-platform — schemas, ADRs, glossary, ecosystem_reference |
| (never submodule of product repos) |
+------------------------------------------------------------------+
| contracts only (URLs, JSON schema IDs, samples)
v
+------------------------------------------------------------------+
| CONTROL PLANE |
| forge-lenses — ForgeRun / Evidence / Approval UI (.forge/runs) |
+------------------------------------------------------------------+
^ ^ ^
| | |
+--------+--------+ +--------+--------+ +--------+--------+
| forge-lcdl | | forge-fleet | | forge-workcells |
| governed LLM | | docker_argv | | workcell code |
| traces | | templates | | (private) |
+--------+--------+ +--------+--------+ +--------+--------+
^ ^ ^
| | |
+--------+--------+ +--------+--------+ +--------+--------+
| blueprints | | forgesdlc-ks | | forge-sdlc |
| policy/Versona | | packs, harness | | methodology |
+-----------------+ +-----------------+ +-----------------+
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.
[Human intent]
|
v
+-------------+ creates +------------------+
| Lenses | ---------------->| ForgeRun frun_* |
| (control) | | governance mode |
+-------------+ +--------+---------+
^ |
| reads/writes | 1:N
| .forge/runs/ v
| +------------------+
| | AgentRun arun_* |
| | workcell id |
| +--------+---------+
| |
| WorkcellRequest
| v
| +------------------+
| | Workcell runner |
| | (see §3–§8) |
| +--------+---------+
| |
| WorkcellResult
| v
| +------------------+
+--------------------------| EvidencePacket |
| ApprovalRequest |
+------------------+
3. Element: forge-platform
| Role | Owns | Does not own |
|---|---|---|
| Cross-product truth | schemas/*, ADRs, ecosystem sample |
Executing workcells, UI, LLM calls |
forge-platform
|
| publishes (git + handbook)
v
+------------------+ +------------------------+
| forge-platform- | | Product repos |
| website (fpw) | | (read URLs / CI schema) |
| submodules | | NO platform submodule |
| platform only | +------------------------+
+------------------+
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 |
Operator
|
v
+-----------+ API/UI +----------------+
| Lenses | <------------> | .forge/runs/ |
| Studio | | in workspace |
+-----------+ +----------------+
| ^
| projects ForgeRun | written by
v |
+-----------+ summaries +----------------+
| Blueprints| <-------------- | WorkcellResult |
| context | | FleetJobSummary|
+-----------+ | LCDLTraceSummary|
+----------------+
^
| emitted by
workcells / Fleet / LCDL
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 |
WorkcellRequest / task spec
|
v
+-------------+
| forge-lcdl | ---- POST /chat/completions ----> LLM gateway
| transport | <---- assistant JSON/text --------
+-------------+
|
v
LCDLTraceSummary (optional artifact)
|
v
EvidencePacket attachment via Lenses
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 |
campaign_orchestrator / Lenses-approved job
|
v
+-------------+ docker_argv +----------------+
| forge-fleet | -------------------> | container |
| API | <------------------- | fleet_ux_worker|
+-------------+ worker_result +----------------+
|
v
FleetJobSummary ---> Lenses / EvidencePacket
7. Element: forge-workcells (private)
| Role | Owns | Does not own |
|---|---|---|
| Runner code | local_llm_worker, pack loader, arun_* dirs |
Domain packs, schemas |
Consumer (KS harness, later Lenses)
|
| CLI: forge-workcells run
v
+------------------+
| forge-workcells |
| local_llm_worker |
+--------+---------+
|
+--------+---------+
| |
v v
micro-pack forge-lcdl
(path from KS) (LLM_* env)
| |
+--------+---------+
v
agent-output.txt / micro-agent.log
|
v
parse-ai-agent-findings.mjs (KS)
8. Element: forgesdlc-kitchensink
| Role | Owns | Does not own |
|---|---|---|
| Design system + UX harness | micro-packs, website-ux-auditor, fixtures |
Workcell runtime |
tools/forge-micro-agent/packs/ux-ai-rule-v1/
|
+-------> context.json <----- ux-assemble-context.mjs
| ^ ^
| | |
| audit slice playwright evidence
| ^ ^
| | |
+-------> analyze-website-ux.mjs (fixture URL)
|
v
invoke-ai-ruleset-harness.sh --llm
|
v
forge-workcells (sibling or submodule)
9. Element: blueprints
| Role | Owns | Does not own |
|---|---|---|
| Canonical policy | SDLC/PDLC, Versonas, recipes | Live run state |
autowww/blueprints (standalone)
|
| submodule (only into platform)
v
forge-platform/blueprints/
|
| BlueprintContextPack
v
Lenses / Hermes / Factory (read policy, do not write SoR)
10. Element: forge-platform-website
| Role | Owns | Does not own |
|---|---|---|
| Handbook HTML | Firebase deploy shell | Canonical Markdown source |
autowww/forge-platform (source of truth)
|
| git submodule
v
forge-platform-website/forge-platform/
|
| build-site.py + kitchensink
v
website/*.html ---> Firebase forge-platform-1541d
11. Git / submodule topology
workspace/
forge-platform/ [sibling — governance]
blueprints/ --------> autowww/blueprints
forge-platform-website/
forge-platform/ ----> autowww/forge-platform (ONLY allowed platform submodule)
kitchensink/
forge-workcells/ [private sibling or KS submodule]
forge-lenses/
forge-lcdl/
forge-fleet/
forgesdlc-kitchensink/
tools/forge-micro-agent/packs/
(optional) forge-workcells/ ---> autowww/forge-workcells
FORBIDDEN: forge-lenses/forge-platform/
forge-fleet/forge-platform/
forgesdlc-kitchensink/forge-platform/
12. Contract bus (how products integrate)
+------------------+
| ForgeRun |
+--------+---------+
|
+--------------------+--------------------+
| | |
v v v
+-------------+ +-------------+ +------------------+
| Evidence | | Approval | | AgentRun + |
| Packet | | Request | | WorkcellResult |
+-------------+ +-------------+ +------------------+
^ ^ ^
| | |
+----+----+ +----+----+ +-----+-----+
| Lenses | | Human | | Workcells |
| UI | | reviewer| | Fleet LCDL|
+---------+ +---------+ +-----------+
| 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 |
13. Micro-agent: Cursor vs local LLM (comparison flow)
+------------------+
| AI ruleset |
| harness rule N |
+--------+---------+
|
+--------------+--------------+
| |
v v
+----------------+ +----------------+
| Cursor path | | --llm path |
| agent -p | | workcells |
+--------+-------+ +--------+-------+
| |
| | gateway_probe_lcdl
v v
ai-agent.log context.json + LCDL
| |
+-------------+---------------+
v
parse-ai-agent-findings.mjs
v
expect-ai-rule-detection.sh