Skip to content

docs: add AGENTS.md governance directive (ADR-003 enforcement) #150

@scottschreckengaust

Description

@scottschreckengaust

Summary

Add two bullets to the "Common mistakes" section of AGENTS.md that enforce ADR-003's governance requirements at the agent prompt level:

  1. "Starting implementation without an approved GitHub issue" — Explicitly states that conversational approval ≠ governance approval and gives the correct sequence
  2. "Creating branches without an issue reference" — Documents the required branch naming convention

Motivation

ADR-003's enforcement mechanisms table lists "AGENTS.md directive" as one of six enforcement points. The AGENTS.md file currently tells agents where to make changes but never says when they're allowed to start. This is the gap that enables the most common governance bypass: agents interpret conversational momentum as authorization.

The AGENTS.md quality audit (issue #148) identified this as the highest-impact single addition: two bullets, placed at the top of "Common mistakes" where agents look when they're about to act.

Proposed change

 ### Common mistakes

+- **Starting implementation without an approved GitHub issue** — Conversational approval ("yes, do it", "go ahead", "start with X") is NOT governance approval. The correct sequence is: create a GitHub issue with acceptance criteria → get the `approved` label from an admin → self-assign → comment "Starting implementation" → then begin work. Even if the user explicitly directs the work in conversation, create the durable artifact (issue) first. See [ADR-003](./docs/decisions/003-contribution-governance.md).
+- **Creating branches without an issue reference** — Branch names must follow the pattern `(feat|fix|chore|docs)/<issue-number>-short-description`. A branch without an issue number is unauthorized work. Example: `feat/148-operational-knowledge-stack`.
 - Editing **`docs/src/content/docs/`** instead of **`docs/guides/`** or **`docs/design/`** — content is generated; sync from sources.

Acceptance criteria

  • Two new bullets added to top of "Common mistakes" in AGENTS.md
  • Pre-commit hooks pass
  • Commit references this issue

Dependencies

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions