Skip to content

Agent Contract Standard

Overview

This document serves as the normative specification for a valid .agents contract within any Bluefly project repository. It defines what constitutes a valid, portable agent interface.

The .agents/ Directory

Every Bluefly project that interacts with OpenStandardAgents MUST contain an .agents/ directory at its root. This directory represents the contract the project exposes to the workspace.

Required Artifacts

A valid contract MUST contain:

  • project.yaml: The primary identity and capability descriptor for the project's agents.
  • registry.yaml: Registration of the project's models, tools, and endpoints within the broader topology.
  • bindings/: A directory defining explicit mappings to external tools, data sources, and Packs.
  • policies/: A directory defining governance, authorization, and business rules specific to the project's agents.

Optional Artifacts

A contract MAY contain:

  • skills/: Project-specific skills that are not (yet) promoted to PackV2.
  • workflows/: Declarative workflows scoped strictly to the project domain.
  • templates/: Prompt templates and context framing used by the project's agents.

Forbidden Artifacts

A contract MUST NOT contain:

  • Runtime caches, logs, or temporary memory (e.g., SQLite databases for active agent state).
  • Generated projections.
  • Hardcoded secrets or credentials (must use 1Password references or the local agent-scoped auth store via CLI).
  • Any file belonging to the .gc or .agents-workspace scopes.

Validation

Contracts are considered immutable at runtime. Any mutation must occur via source control (Git) or the authorized OpenClaw CLI commands that manage the declarative configuration, not by mutating files during active agent execution.

Relationship to repository-structure-standard.md

.agents/ carries two coexisting layers, not one. This document is authoritative for the OSSA machine contract layer above (project.yaml, registry.yaml, bindings/, policies/) — required only for projects that interact with OpenStandardAgents. repository-structure-standard.md §2 is authoritative for the provider-independent knowledge layer (.agents/context/, .agents/roles/) and for skill-authoring conventions (SKILL.md spec compliance).

The two documents share one directory name for skills/. Read them together: this document governs whether a skill has been promoted to PackV2 (the OSSA lifecycle question); repository-structure-standard.md §2.1 governs how a skill still living in .agents/skills/ must be authored (SKILL.md frontmatter, one authoring authority, no forked copies). Neither document supersedes the other. The Forbidden Artifacts list above binds the entire .agents/ directory, both layers included.