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

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

Aperta
#146 0 commenti 0 reazioni 1 assegnatario Rivendicata da @scottschreckengaust Vedi su GitHub
documentation enhancement governance
Lingua principale
TypeScript
Stelle
143
Fork
46
Merge medio
3g 9h
PR unite (30g)
20

Descrizione

## 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)

Guida per i contributori

Apri la guida per i contributori

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.