Forge Platform handbook

To refresh the published handbook after edits here, bump the forge-platform submodule in forge-platform-website when you integrate upstream commits (or reuse the workspace multi-repo flows you already use for other handbooks).

Start here

Read in this order:

1. Platform charter
2. Product boundaries
3. Agents and workcells — Forge Agent, runners, catalog, workflows, micro-agent, campaign
4. Intersection map
5. Platform reference architecture — flowcharts per element and integration paths
6. Ecosystem reference — repos, workcells, submodule rules (see samples/ecosystem_reference.v1.json)
7. Roadmap — see also Product roadmap (releases, milestones, epics) and Roadmap rows
8. Sprint structure
9. Forge run spine — schemas/forge_run.v1.schema.json
10. Evidence — schemas/evidence_packet.v1.schema.json

Supporting context elsewhere in docs/ (operating model, approval model, security model, integrations) is indexed in the handbook sidebar alongside ADRs, milestones, prompts, and sprints.

Operator how-to lives under Guides — including Cursor rules and skills (cost-aware planning, triage, and model tiering) and Respecting resources and autonomy (bounded execution and the L0–L8 ladder).

Repo thesis (short)

Forge is a governed delivery control plane with pluggable agent workcells — not a single agent-orchestration product. ForgeSDLC, Blueprints, Lenses, LCDL, Fleet, and optional operators (Hermes and others) each own defined responsibilities; cross-product behaviour is spelled out in bounded contracts (schemas/ and companion docs).

Bootstrap and validation

Bootstrapping (or overwriting) foundational files uses the scripted generator checked into this repo:

python3 bootstrap_forge_platform_foundation.py          # skips existing paths
python3 bootstrap_forge_platform_foundation.py --force    # intentional overwrite
python3 scripts/check_foundation.py

check_foundation.py relies only on the Python standard library. It checks required artifacts exist, parses JSON schemas and samples, and asserts sample schema fields match declared schema identifiers.

Cursor Composer scripts

Operator prompts for iterative work (foundation refresh → assay → sprint charge → product-repo stubs → schema hardening) ship in-repo under .cursor/composer/ so they stay out of the handbook build (ignored by forge-autodoc). The original Forge Platform Cursor Kit zip is the upstream bundle (bootstrap_forge_platform_foundation.py + those composer scripts + kit README.md).

Canonical vs submodule copy

Maintain content in standalone forge-platform (autowww/forge-platform) and propagate via normal git (submodule pushes and bumps in consumers). Editing only the submodule copy inside forge-platform-website without pushing upstream forks the narrative and creates drift.