Skip to main content

ADR-005: Agentic Governance Structure (.agent)

Context​

AI agents are active participants in the codebase. To work effectively, they need explicit, machine-readable rules, skills, and workflows that are versioned alongside the project. Any error, should be documented and prevented as an agentic rule. Any repeatable action or decision should be documented as an agentic skill or workflow.

Decision​

We establish the .agent/ directory as the local intelligence core of the repository:

  1. .agent/rules/: Defines behavioral constraints and standards.
  2. .agent/skills/: Project-specific capabilities and localized documentation skills.
  3. .agent/workflows/: Standard Operating Procedures (SOPs) for recurrent tasks.

Consequences​

  • Positive: High observability of AI intentions, reproducible agent behavior, and clear separation between "Repository Content" and "AI Instructions".
  • Maintenance: Requires keeping the rules updated as the project evolves.