Skip to content

docs: codify example design and review guidance#15

Merged
rlippmann merged 1 commit into
mainfrom
codex/agents-example-governance
Jun 28, 2026
Merged

docs: codify example design and review guidance#15
rlippmann merged 1 commit into
mainfrom
codex/agents-example-governance

Conversation

@rlippmann

Copy link
Copy Markdown
Owner

Summary

Codifies example design, completion, and self-review guidance in AGENTS.md.

This consolidates the example review criteria that have emerged while building the first enforcement-point examples and makes them available to future contributors and Codex tasks.

Why

Recent example work established a consistent set of expectations:

  • examples should demonstrate a single primary enforcement point
  • authoritative state should be explicit
  • model output should not authorize state-dependent behavior
  • examples should include observable runtime behavior changes
  • adversarial or equivalent tests should be used where practical

These expectations were already being applied during review. This change documents them directly in AGENTS.md and reduces ambiguity for future example work.

Example metadata

  • Enforcement point: repository governance
  • Domain: example development workflow
  • Technology/runtime: repository-wide
  • Example type: repository maintenance
  • Does this use directive drafter? should normally be no: no
  • Does this derive state from model output? must be no for primary examples: no

Checklist

  • Repository scaffolding / governance change
  • One primary enforcement point
  • Explicit authoritative state
  • No model-derived state mutation
  • Adversarial stub or equivalent test
  • Observable runtime behavior change
  • Domain vocabulary is natural
  • Framework is secondary to the enforcement point
  • Docs updated
  • Tests/smoke checks added where practical

Notes

This PR:

  • consolidates example design guidance
  • adds example completion requirements
  • adds example self-review guidance
  • reduces duplication between existing example-design sections

No runtime behavior is changed.

@rlippmann
rlippmann merged commit e217d25 into main Jun 28, 2026
5 checks passed
@rlippmann
rlippmann deleted the codex/agents-example-governance branch June 28, 2026 04:46
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.

1 participant