Forge Platform

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…

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.

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 (ASCII)

                    [forge-platform]
                    schemas · ADRs
                           |
            contracts (no product submodules)
                           |
         +-----------------+------------------+
         |                 |                  |
    [forge-lenses]   [forge-lcdl]      [forge-fleet]
    control plane    LLM transport     execution
         |                 ^                  ^
         |                 |                  |
         +--------+ [forge-workcells] --------+
                  runners (private)
                           ^
                           |
                  [forgesdlc-kitchensink]
                  packs · UX harness

Repo layout (MVP)

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
forge-workcells repo private local_llm_worker and future workcell runners
forge-lcdl product org Governed LLM transport and contracts
forge-lenses product org Control plane, run spine UI
forgesdlc-kitchensink repo public Design system, UX harness, micro-packs
forge-fleet product private Template execution
forge-cdp-manager product org CDP surface leases, registry, control-plane HTTP
blueprints repo public Policy; submodules into platform only

How repos integrate (flow)

  Operator ──► Lenses ──► ForgeRun (frun_*)
                │              │
                │              ├──► AgentRun (arun_*) ──► workcell runner
                │              │         │
                │              │         ├── forge-workcells ──► LCDL
                │              │         ├── forge-fleet (container)
                │              │         └── platform local_runner (alpha)
                │              │
                │              └──► EvidencePacket ◄── human review
                │
                └── reads BlueprintContextPack ◄── blueprints

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

  Need forge-platform content?
        |
        +-- Building handbook HTML? ----YES--> submodule in fpw only
        |
        +-- Product repo (Lenses/Fleet/KS)? --NO--> use handbook URL + schema IDs
        |
  Need to run a workcell?
        |
        +-- YES --> submodule or pip install forge-workcells (private)
        |
        +-- Domain pack? --> always in KS (not in workcells repo)

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

  ForgeRun (frun_*)
       |
       +-- AgentRun (arun_*)  workcell=local_llm_worker  host=forge-workcells
       +-- AgentRun (arun_*)  workcell=fleet_ux_worker   host=forge-fleet job
       +-- AgentRun (arun_*)  workcell=local_runner      host=platform script
       |
       each completes with WorkcellResult → EvidencePacket path in Lenses

Per-element integration summaries

forge-platform ↔ products

  forge-platform --(schema IDs, docs)--> all products
  forge-platform <-X-- submodule ------  product repos (FORBIDDEN)
  forge-platform <--- submodule --------  forge-platform-website ONLY

forge-lenses ↔ Fleet / LCDL / workcells

  Lenses ---- submits / displays ----> FleetJobSummary
  Lenses ---- displays traces ------> LCDLTraceSummary
  Lenses ---- (post-MVP) invokes ---> forge-workcells
  Fleet --- never writes final -----> ForgeRun decision (Lenses does)

forge-workcells ↔ forge-lcdl ↔ KS

  KS harness --pack path + context.json--> forge-workcells
  forge-workcells --LLM_* profile-------> forge-lcdl
  forge-lcdl --HTTP--------------------> gateway
  forge-workcells --stdout JSON--------> KS parse-ai-agent-findings.mjs

See Platform reference architecture §7–§8.

Micro-agent data flow (local LLM path)

  [1] harness serves Before fixture (http.server)
           |
           v
  [2] analyze-website-ux.mjs --site --max-pages 1
           |
           v
  [3] ux-audit-slice + ux-playwright-evidence
           |
           v
  [4] ux-assemble-context.mjs --> context.json
           |
           v
  [5] forge-workcells run (pack ux-ai-rule-v1)
           |
           v
  [6] forge-lcdl chat/completions
           |
           v
  [7] parse-ai-agent-findings.mjs
           |
           v
  [8] expect-ai-rule-detection.sh

Micro-agent flow (SVG)

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
              |
     +--------+--------+
     v                 v
  Cursor            --llm
  agent -p          workcells + LCDL
     |                 |
     +--------+--------+
              v
        parse + detection gate