Skip to content

Commit 1b8a8cf

Browse files
docs(AGENTS.md): add governance directive — issue required before implementation
Adds two bullets to top of "Common mistakes": 1. Conversational approval ≠ governance approval — create issue first 2. Branch naming must include issue number Implements the "AGENTS.md directive" row from ADR-003's enforcement mechanisms table. Fixes #150 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 8bb9407 commit 1b8a8cf

1 file changed

Lines changed: 2 additions & 0 deletions

File tree

AGENTS.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,8 @@ Handler entry tests: `cdk/test/handlers/orchestrate-task.test.ts`, `create-task.
3939

4040
### Common mistakes
4141

42+
- **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).
43+
- **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`.
4244
- Editing **`docs/src/content/docs/`** instead of **`docs/guides/`** or **`docs/design/`** — content is generated; sync from sources.
4345
- Adding or editing files in **`docs/design/`** or **`docs/guides/`** without running **`cd docs && node scripts/sync-starlight.mjs`** — CI will reject ("Fail build on mutation") because the Starlight mirror files in `docs/src/content/docs/` are stale. Always commit the regenerated mirrors alongside source changes.
4446
- Changing **`cdk/.../types.ts`** without updating **`cli/src/types.ts`** — CLI and API drift.

0 commit comments

Comments
 (0)