aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
docs: update AGENTS.md with governance directives and ADR discoverability
- Dominant language
- TypeScript
- Stars
- 143
- Forks
- 46
- Avg merge
- 3d 9h
- Merged PRs (30d)
- 20
Description
## Summary
Update AGENTS.md to surface the ADR governance framework so that a brand-new agent with ONLY AGENTS.md as a starting point can discover and follow all architectural decisions, contribution rules, and process gates.
## Problem
Currently, AGENTS.md has a single routing table entry:
```
| Architecture decisions (ADRs) | docs/decisions/ | Run mise //docs:sync after adding or editing an ADR |
```
This tells agents WHERE ADRs live but not:
- That governance rules (ADR-003) exist and are binding
- That pre-start checks are required before beginning any work
- That admin approval gates block unauthorized implementation
- How to find the roadmap and verify alignment
- How to discover outstanding PRs/issues for cross-referencing
## Deliverables
- [ ] Add a "Before starting work" section (or equivalent) to AGENTS.md that:
- Directs agents to read `docs/decisions/003-contribution-governance.md`
- Summarizes the critical gates (approval, priority, predecessors, cross-ref)
- Links to the product roadmap for alignment verification
- [ ] Expand the routing table entry for `docs/decisions/` with context:
- "Binding architectural decisions — read before modifying architecture or process"
- [ ] Add a "Governance" or "Process" section that briefly explains:
- Issue-first workflow (no PRs without issues)
- Admin approval requirement
- Priority evaluation (challenge lower-priority when higher exists)
- Predecessor validation
- [ ] Reference the full ADR index (`docs/decisions/README.md`) for the complete framework
- [ ] Verify: an agent reading only AGENTS.md would know to check ADRs, roadmap, and open issues before starting
## Blocked by
- #145 (ADR governance framework) — all ADRs should be merged before this references them, ensuring stable links
## Alignment
Aligns with **Documentation and specifications** roadmap theme and ADR-004 (tabula rasa documentation standard — AGENTS.md must be self-sufficient for agent onboarding).
## Why not part of PR #143
PR #143 implements the ADR-003/004 decision records themselves. This issue updates AGENTS.md to *reference* those decisions. The dependency is intentional: AGENTS.md should point to merged, stable ADR content — not draft PRs. Updating AGENTS.md before the ADRs merge would create references to files that don't exist on `main`.
---
* Approved by: (pending admin approval)
* Reviewed by: (pending)
Contributor guide
Assessment
This issue has not been assessed yet.