Project specification

Choose the contract

Use project v0.2 for projects without agent environments. Use project v0.3 for environment bundles; it adds environment declarations and workflow tests. Read the deployment's live schema before authoring.

For a complete environment specification and every referenced file, use the bakery starter. Its executable values are fictional sample data; replace them deliberately when making your own project.

Describe requirements and provenance

Identity

schema and project: stable key, name, summary, type, categories, version, and license state.

Source and attribution

sources and attribution: source kind, immutable revision or digest when known, authors, and your relationship to the work. Original authored specifications can use a null source URL.

Requirements

models, runtimes, hardware, operating_systems, and dependencies: explicit declaration states, required capabilities, and known constraints.

Configuration

configurations, data_boundary, test_support, and limitations: setup, role bindings, inference/storage/network boundaries, supported tests, and practical limits.

Versioned files

tests references test manifests. Project v0.3 also requires environments with keys, paths, and digests. Referenced prompts, data, and fixtures travel with the bundle.

Optional detail

Evidence references, licensed media, derivative lineage, and bounded extensions. These do not grant verification or execution permissions.

Unknown values stay null or use the field's explicit unknown state. A preferred model is a suggestion; observed model identity and test evidence are separate facts. The schema rejects unknown fields outside extensions.

Write the human-readable guide

Include the required sections: Purpose, Setup, Limitations, and Sources and attribution. Add Architecture and workflow, Execution, and Test and evaluation so another person can reproduce the intended process.

Explain manual steps, unsupported integrations, private configuration, and expected outputs. Use quoted strings for dates in YAML. Anchors, aliases, custom tags, and merge keys are rejected.

Validate and publish with your agent

1. Connect your agent and ask it to prepare a draft from your specification and declared files.
2. Have it call draft_validate for the current revision. Validation checks structure, referenced files, digests, and safety findings; it does not execute the project.
3. Fix each blocking error at its reported field or file. Review warnings and unknown requirements before approval.
4. Open the review URL from your agent. Inspect the exact revision, file set, digest, permissions, and warnings, then decide whether to approve publication.
5. Your agent publishes the approved artifact. A changed draft needs fresh approval; a published version is immutable.

Publication does not run tests or prove a claim. Follow the testing guide for local execution and separately reviewed evidence.