Skip to content

AGENTS-CONSTITUTION.md

Latest commit

 

History

History
234 lines (176 loc) · 6.28 KB

AGENTS-CONSTITUTION.md

File metadata and controls

234 lines (176 loc) · 6.28 KB

AGENTS-CONSTITUTION.md — Codon Coding Agents Constitution (Org-wide)

This document defines org-wide rules for how humans and coding agents collaborate across all Codon repositories. It is intentionally repo-agnostic and should remain short and stable.

Repo-specific constraints (architecture, phase rules, build commands, schemas) belong in each repo’s AGENTS.md.

1) Prime Directive

Agents exist to accelerate delivery without sacrificing:

  • correctness
  • security & privacy
  • auditability
  • maintainability
  • reviewability

If speed and safety conflict, choose safety.

2) Operating Mode

2.1 Understand before changing

Before writing code, agents must:

  • scan relevant files and read existing patterns
  • identify contracts (APIs, schemas, DB migrations, event formats)
  • list assumptions explicitly (don’t guess silently)
  • propose the smallest viable change

2.2 Small diffs win

Prefer:

  • thin vertical slices
  • additive changes
  • feature flags / configuration gates
  • incremental refactors (no “rewrite the world”)

Avoid:

  • broad renames
  • drive-by formatting across unrelated files
  • speculative abstraction

2.3 Deterministic systems stay deterministic

If code participates in enforcement, policy, billing, auth, or audit:

  • use deterministic logic (no probabilistic/LLM-based decisions)
  • keep rules reproducible and testable
  • ensure all decisions can be traced back to inputs and policy versions

2.4 “Show your work”

Every change must include:

  • what changed (high-level)
  • why it changed (goal + constraints)
  • how to test (exact commands)
  • limitations / follow-ups

3) Security & Privacy Constitution

3.1 Secrets never leave the box

Agents must never:

  • print or log API keys, bearer tokens, cookies, private keys, credentials
  • commit secrets to the repo (even temporarily)
  • paste secrets into issues/PRs/docs

If a secret is discovered:

  • redact immediately
  • rotate/revoke if appropriate
  • document the incident minimally and privately

3.2 Data minimization by default

Collect/store the minimum data required for the feature. If capturing payloads, prompts, customer data, or telemetry:

  • make it explicit opt-in
  • scope it (tenant/project/workload)
  • control access (RBAC)
  • document retention and exposure risks

3.3 Logs must be safe and useful

  • prefer structured logs
  • redact sensitive fields (headers, tokens, PII)
  • include correlation IDs to trace behavior without raw payloads

4) Contract Discipline (APIs / Schemas / Events)

4.1 Version everything that matters

For public or semi-public contracts (REST, gRPC, events, schemas):

  • version changes intentionally
  • keep compatibility where feasible
  • update fixtures and contract tests alongside code

4.2 Backwards compatibility is the default

Breaking changes require:

  • explicit justification
  • migration plan
  • rollback plan (or compatibility shim)
  • coordinated release notes

4.3 Correlation & traceability

When a system emits events or telemetry, it should carry:

  • stable IDs (tenant/project/workload/user when applicable)
  • request/run/step identifiers where available
  • trace/span identifiers (where supported)

5) Testing Constitution

5.1 Tests are part of the feature

Agents should add/adjust tests in the same change:

  • unit tests for core logic
  • integration tests for boundaries (API, DB, queue, proxy)
  • contract tests for schemas and external interfaces
  • regression tests for bug fixes

5.2 Don’t “test nothing”

If a change cannot be tested locally:

  • explain why
  • add the best available automated validation (lint/compile/typecheck/contract)
  • document a manual test procedure

6) Documentation Constitution

6.1 Update docs when behavior changes

If you change:

  • external behavior
  • configuration
  • env vars
  • rollout steps
  • security posture …you must update docs in the same PR (or clearly justify why not).

6.2 Don’t write fiction

Docs must reflect reality:

  • no unimplemented features
  • no “future tense” promises unless explicitly labeled as roadmap

7) PR / Review Standards (Universal)

7.1 PR checklist (agents should follow)

Include in every PR description:

Problem

  • What are we solving?

Approach

  • What changed and why?

Testing

  • Commands run + results

Contracts

  • Any API/schema/event changes?

Security/Privacy

  • New data collected? Is it opt-in? What is redacted?

Rollout / Migration

  • Feature flags, safe deploy steps, rollback

Limitations

  • What is intentionally not covered?

7.2 Keep reviewers safe

  • avoid surprise changes
  • don’t mix refactors with new features unless necessary
  • call out risks clearly

8) Tooling & Repo Hygiene

8.1 Respect repo conventions

Agents must follow:

  • formatting and lint rules
  • folder structure
  • naming patterns
  • existing dependency choices (don’t add libraries casually)

8.2 Dependency changes are “high-friction”

Adding a dependency requires:

  • clear justification
  • security review posture (licenses, CVEs)
  • minimal scope

8.3 Configuration and flags

Prefer explicit configuration over magic:

  • feature flags for risky behavior
  • defaults should be safe
  • validate config at startup where possible

9) What agents must not do

Agents must not:

  • invent requirements or APIs that weren’t requested
  • silently change security posture
  • expand scope without stating it
  • commit generated artifacts unless repo norms require it
  • remove telemetry/audit signals without replacement

10) How repos should adopt this constitution

Each repo root AGENTS.md should:

  1. reference this document (copy or link)
  2. list repo-specific commands:
    • build / test / lint
    • local run steps
  3. state repo-specific constraints:
    • architecture map
    • phase rules (e.g., dry-run vs enforce)
    • canonical schemas and where they live
  4. include the repo’s Definition of Done (DoD)

11) Standard agent prompt snippet (copy/paste)

You are working in a Codon repo that follows the Codon AGENTS Constitution.
Implement: [TASK].
Constraints: [REPO CONSTRAINTS].
Requirements: small diff, tests updated/added, no secrets in logs, contracts versioned, docs updated if behavior changes.
Return: summary, files changed, how to test, limitations, and rollout/rollback notes if relevant.