Skip to content

.forge Guidelines

Guidelines specific to the .forge standard, extending the general guidelines.

Content

  • Treat the manifest as source of truth. The manifest file is the canonical declaration of project identity. Keep it accurate and in sync with other project metadata files (package.json, pyproject.toml, Cargo.toml, etc.).
  • Keep platform adapters thin. Pipeline files for specific forges (e.g., github.yml, gitlab.yml) should reference shared steps from shared.yml rather than duplicating logic. The less platform-specific code, the easier it is to add or drop a forge.
  • Write agent-agnostic AI config. Configuration in ai/ should be tool-neutral where possible. Describe capabilities and constraints in a generic format rather than coupling to a specific AI assistant’s proprietary schema.
  • Make templates platform-readable. Issue and PR templates should work as plain Markdown while following the conventions of their target forge. Avoid platform-specific syntax that would break rendering elsewhere.

Structure

  • Adopt layers incrementally. Start with the core layer (the manifest) and add extension layers only when the project needs them. Do not scaffold empty directories for unused layers.
  • One pipeline file per platform. Each target forge gets its own file in pipelines/. Shared steps and reusable logic belong in shared.yml, not duplicated across platform files.
  • Separate concerns by directory. Build config goes in build/, templates in templates/, federation metadata in federation/, AI config in ai/. Do not mix concerns within a single directory.
  • Use meta/ for supplementary metadata. Project philosophy, intent declarations, and other semantic metadata belong in meta/. Keep the .forge/ root clean — only the manifest and README belong there.

Portability

  • Design for forge migration. The value of .forge is forge neutrality. When writing pipeline definitions or templates, think about what would need to change if the project moved to a different hosting platform. Minimize those touch points.
  • Avoid forge-specific features in shared config. Features unique to a single forge (GitHub Actions marketplace, GitLab includes) belong in the platform adapter, not in shared.yml.

Versioning

  • Keep the manifest version in sync. When you tag a release, update the version field in manifest.yml. Consider automating this via the Forge CLI or a pipeline step.
  • Use semver. The manifest version field follows semantic versioning. This is the project version, distinct from the .forge standard version.