Skip to content

docs: add contract.yaml field reference cheatsheet - #32

Closed
TianHengZhuang wants to merge 1 commit into
Skull-boy:mainfrom
TianHengZhuang:docs/contract-cheatsheet
Closed

TianHengZhuang wants to merge 1 commit into
Skull-boy:mainfrom
TianHengZhuang:docs/contract-cheatsheet

Conversation

@TianHengZhuang

Copy link
Copy Markdown

Summary

Adds docs/contract-cheatsheet.md - a single-page field reference for the Agent Contract v1.1 schema, as requested in #30.

What's Inside

  • Minimal valid contract - the smallest contract.yaml that passes schema validation (just �ersion + system.name)
  • Full field reference - every schema field with type, required status, allowed values, and a concrete example snippet:
    • Identity: �ersion, system, �gent, workflow, domain
    • Behavior: capabilities,
      esources, inputs, outputs
    • Guardrails: permissions, constraints, side_effects, �pprovals
    • Infra: dependencies, state,
      ecovery,
      eplay, observability
    • Metadata: �rtifacts, security,
      isk, implementation, lifecycle
  • Common patterns - three ready-to-adapt templates:
    • Stateless request-response (simplest)
    • Persistent worker with irreversible side effects + approval gate
    • Scheduled task with cost and rate constraints
  • Validation instructions - how to check a contract locally before committing

Design Choices

  • Filed under docs/ alongside existing reference material (contract-model-v1.1.md, design-principles.md, etc.)
  • Uses the same inline-code-fence style as the rest of the docs
  • Cross-links to schemas/v1.1/contract.schema.json for the normative definition
  • No new dependencies or build steps - it's pure Markdown

Closes #30.

Adds a quick-reference guide covering every field in the Agent
Contract v1.1 schema:

- Minimal valid contract example (2 lines)
- Full field reference with type, required status, and examples
- Common patterns: stateless request-response, persistent worker,
  scheduled task with cost constraint
- Validation instructions

Closes Skull-boy#30.
@TianHengZhuang

Copy link
Copy Markdown
Author

Closing this pull request to free capacity on my side after a long stretch without maintainer feedback. The branch remains on my fork if anyone wants to revisit the change later. Thanks for the project.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Docs] Write a contract.yaml field reference cheatsheet

1 participant