governace

Imported from DalekileModikwe/cm-glassiva (governace/AGENTS.md). Install upstream with npx skills add DalekileModikwe/cm-glassiva --skill governace. Copyright stays with the author.

AGENTS.md

Purpose

This file defines how agents must work in this repository.

It is the root operating contract for agent contributors. Agents must read this file before making meaningful changes.

This repository is designed to support both human contributors and coding agents. Important project context is stored in markdown files so that contributors do not depend on chat history, memory, or compressed context.

Core Rule

Agents must understand before they act.

Before changing code, infrastructure, documentation, configuration, or tests, an agent must identify:

• what the task is asking for
• what context is required
• which policies apply
• which state documents may become stale
• what evidence is required
• what risks or ambiguities exist

Implementation comes after context, not before it.

Repository Context Model

This repository uses durable markdown context.

The main context areas are:

/
├─ AGENTS.md
├─ README.md
├─ .codex/
├─ .claude/
├─ .agents/skills-editable/
├─ docs/
│  ├─ operating-model/
│  ├─ policy/
│  ├─ state-editable/
│  ├─ reference-editable/
│  └─ templates/
├─ tasks-editable/
└─ work-editable/

Folder Meaning

.codex/

Repo-scoped Codex configuration and command rules.

• .codex/config.toml
• .codex/rules/default.rules

Do not place secrets, tokens, credentials, or private environment values here.

.claude/

Repo-scoped Claude Code configuration and permission guidance.

• .claude/settings.json
• .claude/permissions.md
• .claude/README.md

.claude/ is the Claude-facing peer of .codex/. The two folders sit side by side so that a project can work with either agent, or both, without churn. Keep them in sync on intent (what is safe, what must be approved) even though the file formats differ.

As other agents are adopted (for example .cursor/, .aider/, or a tool-agnostic .agent/), follow the same pattern: give each agent its own folder and keep agent-specific configuration scoped there. The shared operating contract stays in AGENTS.md and docs/, not inside any one agent's folder.

Do not place secrets, tokens, credentials, or private environment values here.

.agents/skills-editable/

Reusable agent workflows.

A skill is not a task. A skill describes how to perform a repeated class of work, such as:

• adding an endpoint
• splitting a Lambda
• running test audits
• investigating with AWS CLI
• deploying infrastructure
• reviewing cost
• updating state docs
• proposing policy changes

The skills-editable folder is editable because skills may mature as the repository matures.

docs/operating-model/

Defines how work is performed.

Important files:

• agent-workflow.md
• task-lifecycle.md
• policy-governance.md
• evidence-standard.md

Agents must follow these files.

docs/policy/

Defines repository rules and engineering standards.

Important files:

• coding-policy.md
• configuration-centralization-policy.md
• comment-policy.md
• naming-conventions-policy.md (file on disk is naming-conventions-policy.md)
• logging-policy.md
• testing-policy.md
• git-ready-policy.md
• cleanliness-policy.md
• production-ready-criteria.md
• human-contributor-rules.md

Agents must identify which policy files apply to a task before making meaningful changes.

docs/state-editable/

Contains living project truth.

Important files:

• architecture.md
• current-implementation.md
• target-architecture.md
• api-surface.md
• domain-rules.md
• decision-log.md
• known-gaps.md
• changelog.md

Agents are expected to update these files when implementation changes repository truth.

docs/reference-editable/

Contains practical working guides.

Important files:

• setup.md
• getting-started.md
• how-to-build.md
• telemetry.md
• faq.md
• troubleshooting.md

Agents may update these files when setup, build, telemetry, FAQ, or troubleshooting knowledge changes.

docs/templates/

Contains reusable document templates.

Use these when creating or refreshing project docs, task files, evidence records, decision entries, policy proposals, and skill files.

tasks-editable/

Contains task definitions.

Recommended structure:

tasks-editable/
├─ active/
├─ backlog/
├─ done/
└─ templates/

Every meaningful task should have a task file.

work-editable/

Temporary scratch area for investigation notes, working notes, and task-local drafts.

Durable truth must not remain hidden in work-editable/. If information becomes important, promote it to the correct state or reference document.

Meaning of -editable

Folders marked -editable contain project-specific or task-specific context.

Agents may help define and maintain these areas, but must not invent critical missing information.

If a required *-editable file is missing, incomplete, stale, or too vague for safe execution, the agent must gather requirements, clarify assumptions, or update the file before major implementation work.

Required Reading Before Work

For any non-trivial task, agents must read:

1. AGENTS.md
2. the relevant task file under tasks-editable/active/
3. docs/operating-model/agent-workflow.md
4. docs/operating-model/task-lifecycle.md
5. relevant policy files under docs/policy/
6. relevant state files under docs/state-editable/

If the task file does not exist, the agent must create one from the template or request the missing task context.

Task File Requirement

A proper task must include, at minimum:

• background/context
• task description
• definition of done
• evidence required

These are mandatory.

If any of these are missing, the agent must treat the task as under-specified and clarify or draft the missing sections before executing meaningful work.

Standard Agent Workflow

Agents must follow this workflow:

1. Read the task.
2. Identify required context.
3. Read applicable policies and state docs.
4. Identify missing or stale context.
5. Ask for clarification or update editable docs where needed.
6. Plan the work.
7. Implement within scope.
8. Verify the work.
9. Update affected docs.
10. Record evidence.
11. Perform a completion review.
12. Leave the repo clean and Git-ready.

Planning Rule

For non-trivial tasks, agents must create a short plan before implementation.

The plan should identify:

• intended approach
• files likely to change
• relevant policies
• expected verification
• docs likely to update
• risks or assumptions

Policy Compliance

Agents must follow repository policies.

If task instructions conflict with policy, the agent must not silently ignore the conflict.

The agent must choose one of these paths:

1. comply with the policy
2. request clarification
3. document a policy exception
4. propose a policy update
5. record a known gap if unresolved

Material policy changes must follow:

• docs/operating-model/policy-governance.md

State Document Maintenance

Agents must update state docs when repository truth changes.

Examples:

• endpoint added or changed -> update docs/state-editable/api-surface.md
• architecture changed -> update docs/state-editable/architecture.md
• target direction changed -> update docs/state-editable/target-architecture.md
• business rule changed -> update docs/state-editable/domain-rules.md
• gap discovered -> update docs/state-editable/known-gaps.md
• meaningful change completed -> update docs/state-editable/changelog.md
• decision made -> update docs/state-editable/decision-log.md

If the code changes and relevant docs become stale, the task is not complete.

Examples and Schemas Rule

Examples, schemas, sample payloads, diagrams, and API references must stay current.

Agents must review and update them when behavior changes.

Stale examples are harmful because they mislead:

• humans
• agents
• QA testers
• integrators
• operators

Testing and Verification Rule

Agents must run or define verification appropriate to the task.

Examples:

• unit tests
• integration tests
• API checks
• infrastructure validation
• build checks
• deployment checks
• log checks
• metric or alarm checks
• manual validation

If a check cannot be run, the agent must clearly state:

• what was not run
• why it was not run
• risk of not running it
• recommended follow-up

Agents must not claim work is complete without evidence.

Evidence Rule

Completion must be evidence-based.

Evidence may include:

• test output
• build output
• API responses
• deployment output
• screenshots
• logs
• metrics
• alarms
• manual verification notes
• updated docs
• known gap entries

Evidence expectations are defined in:

• docs/operating-model/evidence-standard.md

Git-Ready Rule

Before declaring work complete, agents must ensure the work is Git-ready.

This includes:

• scoped changes
• no accidental edits
• no secrets
• no temporary debug residue
• no stale comments
• no stale docs
• verification completed or skipped with explanation
• evidence recorded
• known gaps documented

Refer to:

• docs/policy/git-ready-policy.md

Cleanliness Rule

Agents must leave the repository as clean as or cleaner than they found it.

Do not leave:

• stale code
• stale comments
• stale docs
• outdated examples
• dead files
• vague TODOs
• temporary work in permanent folders
• duplicated logic without explanation

Refer to:

• docs/policy/cleanliness-policy.md

Configuration Rule

Agents must avoid hard-coded environment-specific values.

Prefer:

• environment variables
• parameter store
• secrets manager
• configuration files
• centralized constants only for truly static values

Refer to:

• docs/policy/configuration-centralization-policy.md

Production-Ready Rule

Agents must not confuse implemented work with production-ready work.

Production-ready work must be:

• functional
• tested
• observable
• configurable
• secure enough for intended use
• documented
• supportable
• honest about known gaps

Refer to:

• docs/policy/production-ready-criteria.md

Pushback Rule

Agents are expected to push back when instructions:

• conflict with policy
• create avoidable technical debt
• reduce maintainability
• hide configuration
• weaken security
• skip verification
• leave stale documentation behind
• introduce unnecessary cost
• make future work harder

Pushback should be practical, respectful, and focused on protecting the repository.

Cost Awareness

Agents must consider cost when tasks involve infrastructure or operational changes.

If cost posture is not stated, agents should default to a balanced posture and avoid unnecessarily expensive best-practice implementations.

Tasks should define:

• cost posture
• complexity posture
• risk posture
• delivery urgency

Security Rules

Agents must not:

• commit secrets
• paste secrets into docs
• log sensitive values
• expose tokens
• weaken access controls silently
• bypass security expectations without an explicit decision
• make risky production changes without approval

Use placeholders for sensitive examples.

Shell and Tooling Rules

Agents must respect the command-permission rules defined for whichever agent framework is in use:

• Codex: .codex/config.toml and .codex/rules/default.rules
• Claude Code: .claude/settings.json and .claude/permissions.md

Other agents follow the same pattern in their own folder (for example a future .cursor/ or .aider/).

Mutating commands, destructive commands, infrastructure deployment commands, Git history commands, package installation commands, and shell wrappers generally require approval unless the project rules explicitly allow them.

Completion Checklist

Before declaring work complete, agents must confirm:

• task definition of done satisfied
• evidence recorded
• required verification completed or skipped with explanation
• affected state docs updated
• examples and schemas updated if affected
• known gaps recorded
• changelog updated if meaningful
• decision log updated if a meaningful decision was made
• work is Git-ready
• temporary notes promoted, archived, or removed
• no secrets or sensitive values exposed

Related Documents

• README.md
• docs/operating-model/agent-workflow.md
• docs/operating-model/task-lifecycle.md
• docs/operating-model/policy-governance.md
• docs/operating-model/evidence-standard.md
• docs/policy/coding-policy.md
• docs/policy/git-ready-policy.md
• docs/policy/cleanliness-policy.md
• docs/policy/production-ready-criteria.md