forge.yaml

forge.yaml sits at the root of a project repository and lists the project’s lanes. FORGE writes it when the owner approves a structure change. CORE reads it to verify each lane in its own folder. It is the only record of a project’s structure on GitHub.

Example

# FORGE project manifest — written by FORGE when the owner approves a change,
# read by CORE to verify each lane folder (core/ci/<lane id>). Edit it through FORGE.
version: 1
project: social-ops
lanes:
  - id: source-mapping
    name: Source mapping
    kind: pipeline
    path: pipelines/source-mapping
    components: [source.postgres]
  - id: social-bot
    name: Social media bot
    kind: web
    path: apps/social-bot

Fields

Field	Type	Rule
`version`	integer	Must be `1`. Anything else: `version N is not supported (want 1)`
`project`	string	The repo name. Informational
`lanes`	list	1 to 12 lanes in FORGE
`lanes[].id`	string	`^[a-z0-9][a-z0-9-]{0,38}$`, unique in the project
`lanes[].name`	string	1 to 80 characters
`lanes[].kind`	string	`pipeline` or `web`
`lanes[].path`	string	The lane’s folder: clean, relative, unique, never nested inside another lane’s folder, and with no hidden (`.x`) or relative segments. `.` is allowed only for a single-lane project
`lanes[].components`	list of strings	Catalog component ids. Informational, and CORE ignores them

Default folders. When a lane’s path is left empty in the draft, FORGE uses pipelines/<id> for a pipeline lane and apps/<id> for a web lane.

Unknown keys are ignored, at the top level and per lane, by both readers. A newer writer may add fields before an older reader knows about them.

Invalid manifests

Neither reader guesses.

FORGE refuses to overwrite a manifest it cannot parse: the repo's forge.yaml is invalid, so FORGE will not overwrite it blind: …. A file that does not decode reads as forge.yaml is not YAML: ….
CORE reports the whole project as core/ci = failure with the description forge.yaml is invalid: <first reason>, and posts no per-lane status.

FORGE caps a project at 12 lanes. CORE’s reader (core/grpc/cmd/forgecheck) caps at 50, which bounds the statuses one verification run posts. The FORGE limit is the one a user meets.

Editing it

Edit the manifest through FORGE. The canvas, the new pipeline|app command and Approve lane changes all end in an approval that rewrites the file with the header shown above. An approval commits forge.yaml only when the approved lanes differ from what the repo holds, comparing order, ids, names, kinds, folders and components. Each new lane also gets its kind’s AGENTS.md in its folder.

A repo made before projects has no forge.yaml. It reads as one lane at . of its kind, and CORE verifies it by its topic’s profile, as before.

Sources

grpc/internal/project/manifest.go (Parse, Marshal, ValidateLanes, Same, DefaultPath, MaxLanes); grpc/cmd/chat_server.go (syncManifest); core’s grpc/cmd/forgecheck/manifest.go.

App kinds