aws-samples / aws-samples/sample-autonomous-cloud-coding-agents

docs: update AGENTS.md with governance directives and ADR discoverability

Open
#146 0 comments 0 reactions 1 assignee Claimed by @scottschreckengaust View on GitHub
documentation enhancement governance
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.