.forge

A universal, forge-neutral directory convention for project-level configuration, automation, and metadata. It unifies disparate forge-specific directories (.github/, .gitlab/, .gitea/, etc.) into a single standardized location.

What it is

The .forge directory lives at the root of a project repository and provides a predictable structure for everything a project needs beyond its source code — identity, CI/CD pipelines, templates, AI configuration, and federation metadata. It works with any hosting platform.

Directory structure

.forge/
├── README.md                   # Project overview (optional)
├── manifest.yml               # Project identity (required)
├── pipelines/                  # CI/CD definitions
│   ├── github.yml
│   ├── gitlab.yml
│   ├── forgejo.yml
│   └── shared.yml
├── templates/                  # Issue/PR templates
│   ├── issue_template.md
│   ├── pr_template.md
│   └── discussions/
├── build/                      # Build and deployment config
├── ai/                         # AI agent configuration
├── federation/                 # Federation metadata
└── meta/                       # Additional project metadata

Layered architecture

.forge is organized into a required core layer and optional extension layers. Each layer can be adopted independently — a project can start with just the manifest and add layers as needed.

Core layer

The manifest is the only required file. It declares the project’s identity.

# .forge/manifest.yml
id: example.project
name: Example Project
version: 0.1.0
maintainer: exampleLabs
license: MIT
description: "Unified configuration for multi-forge deployment."

Field	Required	Description
`id`	yes	Unique project identifier
`name`	yes	Human-readable project name
`version`	yes	Current version (semver)
`maintainer`	yes	Maintaining organization or individual
`license`	yes	SPDX license identifier
`description`	no	Short project description

Extension layers

Metadata layer

Self-description for dependency resolution, federation, and indexing.

specs:
  - owts-01
  - spdx-license:MIT
dependencies:
  - name: seabreeze
    version: ">=1.0"

Automation layer

CI/CD pipelines and deployment configuration.

pipelines/ : Platform-specific CI/CD definitions alongside shared pipeline logic. Platform adapters (e.g., github.yml) reference shared.yml for common steps.

build/ : Build tooling, Docker Compose files, and deployment configuration.

# .forge/build/docker-compose.yml
services:
  app:
    build: .
    expose:
      - 8080

Federation layer

Interoperability metadata for federated services and OWTA-compatible endpoints.

# .forge/federation.yml
federation:
  protocol: activitypub
  tier: owts-01-tier2
  endpoints:
    - https://api.example.net/outbox

Semantic layer

Project identity, ethics, and philosophy.

# .forge/intents.yml
ethics:
  alignment: human-centric
  data-usage: transparent
philosophy:
  - open
  - federated
  - privacy-respecting

Design principles

Forge Neutrality : .forge is not tied to any specific hosting platform. Configuration is expressed in a platform-independent format and translated to forge-specific formats via adapters.

Self-Containment : The .forge directory carries all project metadata within the repository itself. No external services or registries are required for the directory to be meaningful.

Modularity : Each layer (core, metadata, automation, federation, semantic) is independent. Adopt only the layers your project needs.

Extensibility : Custom directories and files can be added without breaking the standard. Tools should ignore entries they do not recognize.

Human & Machine Readable : All files use plain-text formats (Markdown and YAML) that are equally accessible to humans and automated tools.

All shared conventions apply. See the .forge guidelines for content and structural best practices.

CLI integration

The Forge CLI provides tooling for managing .forge directories.

Command	Description
`forge sync`	Sync `.forge/` definitions to forge-specific formats
`forge lint`	Validate schema and structure
`forge publish`	Push to multiple forges using shared config
`forge info`	Display manifest data

Examples

Minimal setup

.forge/
└── manifest.yml

Just the manifest. Enough to declare the project’s identity and be discoverable.

Full multi-forge setup

.forge/
├── manifest.yml
├── pipelines/
│   ├── github.yml
│   ├── gitlab.yml
│   ├── forgejo.yml
│   └── shared.yml
├── templates/
│   ├── issue_template.md
│   └── pr_template.md
├── build/
│   └── docker-compose.yml
├── ai/
│   └── agent-config.yml
├── federation/
│   └── federation.yml
└── meta/
    └── intents.yml

FAQ

How does `.forge` relate to `.github/` or `.gitlab/`?

.forge is a forge-neutral alternative. Instead of maintaining separate .github/, .gitlab/, and .gitea/ directories with duplicated configuration, you maintain a single .forge/ directory. The Forge CLI can sync .forge definitions to platform-specific formats when needed. Projects that only use one forge can still benefit from the standardized layout.

Status

Draft v0.1

This standard is in early draft. The directory layout is subject to change as feedback is collected from the community.

Governance

Governed by the Open WebTech Association (OWTA). Licensed under CC-BY-SA 4.0.

Forge CLI — tooling for managing and syncing .forge directories.
OWTA Standards — the broader standards family that .forge belongs to.