aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
docs(governance): refine ADR-012 to many-to-many ADR↔Persona↔Skill graph with bidirectional backlinks + parity linter
- Dominant language
- TypeScript
- Stars
- 143
- Forks
- 46
- Avg merge
- 3d 9h
- Merged PRs (30d)
- 20
Description
## Summary
Refine ADR-012's operational-knowledge model from a strict **upward tree** (Skill → Guide → ADR) into a **many-to-many graph** with **Persona** as a first-class node, enforced by **bidirectional frontmatter backlinks** and a **parity linter** in CI. This makes downstream artifacts (personas, skills) detectably-in-sync with their parent ADRs without a full-repository semantic read — directly mitigating the staleness risk ADR-012 itself flags but does not solve.
> Refinement, not reversal (per #380 boundary test): the three-layer ADR→Guide→Skill **decision stands**; we are extending the "Reference direction" section. This is intended as the **first real exercise** of the in-place refinement path introduced by #380 — ADR-012 is edited in place with a `## Changelog` entry, not superseded.
## Motivation
ADR-012 §"Reference direction" asserts references point **upward only** in a tree. Real usage breaks the tree:
1. **One ADR → many personas** — ADR-003 shapes Planner, Implementor, Reviewer, **and** Administrator.
2. **One persona → many ADRs** — Administrator is shaped by ADR-003, ADR-009, and the security-triage ADR (#277/ADR-016).
3. **One skill → many personas** — shared skills (e.g. `validate-dependencies`) serve Implementor **and** Planner.
ADR-012 lists this as an unmitigated risk: *"(!) Reference chain integrity must be maintained — a broken link between layers means drift goes undetected."* This issue mitigates it mechanically.
## Decision to encode (graph + invariant)
```
ADR (decision) ──affects──▶ Persona ──exercises──▶ Skill
▲ many-to-many ▲ │ many-to-many │ │
└────────────────┴──────────┴──────────────┴─ optional direct Skill→ADR
```
- **Persona** becomes a first-class node (e.g. Administrator, PR Reviewer, Issue Triager, Implementor, Planner), living under a documented home (`docs/personas/` and/or the plugin `agents/` dir — to be decided in design).
- **Edges are declared in frontmatter on both endpoints**, e.g.:
- ADR: `personas: [planner, implementor, reviewer, administrator]`
- Persona: `adrs: [ADR-003, ADR-008]`, `skills: [pickup-issue, validate-dependencies]`
- Skill: `adrs: [ADR-003]` (or explicit `adrs: []` for intentionally standalone), `personas: [implementor]`, `guide: CONTRIBUTOR_WORKFLOW.md`
- **Invariant (parity linter):** every declared edge MUST be reciprocated on the other endpoint. A one-directional edge fails CI. A skill with no ADR parent MUST declare `adrs: []` explicitly (deliberate, not an oversight).
- **Maturity is derived, not stored:** do NOT add "operationalized / enforced / validated" status fields to ADRs (they rot — cf. ADR-003's `Implemented/Planned` enforcement column). Compute maturity by walking the graph: operationalized iff ≥1 persona references it; enforced iff a skill/hook implements it.
## Honest boundary (tabula-rasa / ADR-010)
The parity linter verifies **structural** consistency (links resolve and reciprocate; supersede flags surface dependents for review) — **not semantic freshness** (that the skill still reflects the ADR's intent). State this limit explicitly in the ADR so the standard doesn't over-promise. Semantic freshness remains a human/agent judgment.
## Deliverables
- [ ] Amend ADR-012 §"Reference direction" in place: many-to-many graph, Persona as first-class node, bidirectional edges; add a `## Changelog` entry + bump `Last-updated` (uses #380 mechanics).
- [ ] Define the frontmatter edge schema for ADR / Persona / Skill (and where personas live).
- [ ] Specify the parity-linter contract (inputs, the reciprocity invariant, failure output) — implementation may be a follow-up.
- [ ] Document the supersede interaction: when an ADR goes `superseded`, the linter flags all referencing personas/skills for review.
- [ ] Sync Starlight mirror for ADR-012; commit alongside source.
## Acceptance criteria
- [ ] ADR-012 expresses ADR↔Persona↔Skill as a many-to-many graph with reciprocal edges; the old "upward tree only" wording is replaced and a changelog entry records the refinement.
- [ ] The frontmatter schema is precise enough that a linter can be written from the ADR alone.
- [ ] The structural-vs-semantic limit is stated explicitly.
- [ ] No implementation-maturity status fields are added to any ADR.
## Dependencies
- **Blocked by #380** (in-place refinement must be a sanctioned operation before ADR-012 can be edited in place rather than superseded).
- Related: #186 (ADR-003 decomposition produces the first personas/skills this graph will bind); #254 (mechanical module-boundary enforcement — same "graph integrity as CI gate" technique, prior art); #246 (agent asset registry — overlaps on skill/capability cataloguing; reconcile).
## References
- ADR-012 §"Reference direction", §Consequences (the `(!)` integrity risk this resolves)
- #380 — refine-in-place standard (prerequisite)
- #246, #254 — related registry / boundary-enforcement work
---
*Filed under contribution governance (ADR-003). No implementation/file edits until `approved` + assigned.*
Contributor guide
Research direction
Read ADR-012's “Reference direction” and “Consequences” sections, then review #380 for the sanctioned in-place refinement mechanics. Define the ADR, Persona, and Skill frontmatter schema, parity-linter contract, supersede behavior, and Starlight mirror update; done means the acceptance criteria are documented and the source and mirror agree.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100