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

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

Abierto
#146 0 comentarios 0 reacciones 1 asignado Reclamado por @scottschreckengaust Ver en GitHub
documentation enhancement governance
Lenguaje dominante
TypeScript
Estrellas
143
Forks
46
Merge medio
3 d 10 h
PR fusionados (30 d)
24

Descripción

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

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.