Skip to content

Commit daf33f1

Browse files
scottschreckengaustclaude
scottschreckengaust
and
claude
committed
docs: ADR-003 contribution governance + ADR-004 tabula rasa documentation
ADR-003 defines how agents/humans pick up, own, and deliver work: priority evaluation, predecessor validation, cross-reference audit, self-assignment, and issue body as source of truth. ADR-004 defines the documentation standard: zero-context self-sufficiency, progressive disclosure, international English, testable instructions, and the tabula rasa quality test. Refs #134, #135 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 0174e2a commit daf33f1

4 files changed

Lines changed: 350 additions & 0 deletions

File tree

‎docs/decisions/003-contribution-governance.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# ADR-003: Contribution governance for async agents and humans
2+
3+
**Status:** accepted
4+
**Date:** 2026-05-19
5+
6+
## Context
7+
8+
ABCA is designed for multiple autonomous agents to work concurrently on the codebase. Without explicit governance rules, agents duplicate effort, start unapproved work, ignore priority order, miss predecessors, and create merge conflicts that require human intervention to untangle.
9+
10+
The rules below define how any contributor — human or AI — picks up, owns, and delivers work. They prevent priority inversion, wasted rework, unauthorized scope creep, and silent conflicts at scale.
11+
12+
## Decision
13+
14+
### No PRs without an Issue
15+
16+
Every PR references an issue. The issue provides rationale, sufficient context for the solution to be obvious, and verifiable acceptance criteria.
17+
18+
### Issue quality bar
19+
20+
An issue is "ready for work" when a contributor can read the body alone — without comments, related issues, or clarifying questions — and know exactly what to build.
21+
22+
### Roadmap alignment
23+
24+
Issues align to the [product roadmap](https://github.com/aws-samples/sample-autonomous-cloud-coding-agents/blob/main/docs/guides/ROADMAP.md). Issues that do not align require explicit admin approval.
25+
26+
### Admin approval gate
27+
28+
Only `admin` users can mark an issue `approved`. Unapproved and unassigned issues are not workable. A GitHub Actions workflow prevents non-admins from adding the `approved` label.
29+
30+
### Self-assignment on start
31+
32+
Unassigned means available. On starting work, self-assign. Multiple assignees (>1) require intentionality verification.
33+
34+
### Issue body is source of truth
35+
36+
Discussion threads are folded back into the body. Unresolved conflicts are marked explicitly:
37+
- `**UNRESOLVED:** <question>` — blocks implementation
38+
- `**DEFERRED:** <question> — tracked in #N` — does not block
39+
40+
### Pre-start review
41+
42+
Before implementation, the assigned contributor must:
43+
44+
**Read and verify:** All comments read, no unresolved conflicts.
45+
46+
**Priority evaluation:** Identify priority (`p0`/`p1`/`p2`). If asked to work a lower-priority item while higher-priority items are unassigned, challenge: "Should I work on #X (p0) instead?"
47+
48+
**Predecessor validation:** If predecessors are incomplete, unassigned, and not in a stacked PR — challenge: "Steps 1-3 are incomplete. Starting step 4 may cause rework."
49+
50+
**Cross-reference audit:** Search open issues for duplicates. Search open PRs (including drafts) for conflicts. Flag overlaps. Check the full dependency graph.
51+
52+
**Final gate:** If all checks pass, comment "Starting implementation."
53+
54+
### Identity and attribution
55+
56+
Agents use identifiable credentials. The prompting user and acting agent must be distinguishable. PRs include `Co-Authored-By` for AI contributors.
57+
58+
### Work-in-progress discipline
59+
60+
Provide progress signals at checkpoints. If blocked or abandoning, comment and unassign. Do not start multiple issues simultaneously unless explicitly parallelizable.
61+
62+
### Completion and handoff
63+
64+
CI passes before requesting review. After merge, verify acceptance criteria and close. Create follow-up issues for discovered work before closing.
65+
66+
## Consequences
67+
68+
- (+) Prevents duplicate effort — assignment signals ownership
69+
- (+) Prevents priority inversion — agents challenge low-priority requests
70+
- (+) Prevents rework — predecessor validation catches out-of-order work
71+
- (+) Issue body stays current — threads are folded back
72+
- (+) Cross-reference audit catches duplicates early
73+
- (-) Pre-start overhead for small tasks
74+
- (-) Requires discipline to fold threads into body
75+
- (!) Assumes priority labels exist and are maintained
76+
77+
## References
78+
79+
- Issue #134 — full RFC with open questions and automation requirements
80+
- Roadmap: Scale and collaboration (Agent swarm, Multi-user and teams)
81+
- ADR-001 — delivery methodology referenced by completion rules

‎docs/decisions/004-tabula-rasa-documentation.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# ADR-004: Tabula rasa documentation standard
2+
3+
**Status:** accepted
4+
**Date:** 2026-05-19
5+
6+
## Context
7+
8+
Documentation written by people with deep project knowledge assumes readers share that knowledge. Acronyms go unexpanded, prerequisite steps are skipped as "obvious," and instructions break for anyone starting from zero — including autonomous agents with fresh context windows.
9+
10+
This is especially damaging for a platform designed to be operated by agents: every documentation gap becomes a hard failure point. Agents cannot guess, infer from memory, or ask a colleague what "bootstrap the toolkit" means.
11+
12+
## Decision
13+
14+
### The Tabula Rasa Test
15+
16+
Every document must pass: **Can someone with zero project knowledge, following only what is written, complete the described outcome?** If any step requires knowledge not present in the document or explicitly linked, the document fails.
17+
18+
### Minimally sufficient
19+
20+
Write the minimum that makes the reader succeed — not the minimum words, but the minimum *sufficient* content.
21+
22+
- Novice needs explanation: one-sentence "what this does" before each step
23+
- Expert needs speed: scannable structure (numbered steps, headers, tables)
24+
- Both need confidence: expected output or success criteria after key steps
25+
26+
### Progressive disclosure
27+
28+
```
29+
Layer 1: What (one paragraph — what this helps you do)
30+
Layer 2: Steps (numbered, self-contained, runnable)
31+
Layer 3: Further reading (links with one-sentence descriptions)
32+
```
33+
34+
Never force a novice to read expert material to proceed. Never force an expert to wade through explanations to find the command.
35+
36+
### International English
37+
38+
- Simple sentence structure (subject-verb-object)
39+
- No idioms or colloquialisms
40+
- Concrete words ("run this command" not "execute the following")
41+
- One idea per sentence
42+
- Active voice
43+
44+
### Self-contained references
45+
46+
When referencing another document:
47+
- State what the reader gets from it: "See [Deployment Guide](link) for AWS account setup (required before this step)"
48+
- Never assume the reader has read it
49+
- Never use "as mentioned above" — each section must stand alone after context compaction
50+
51+
### Testable documentation
52+
53+
- Commands are copy-pasteable (no hidden dependencies)
54+
- Expected output shown after non-trivial commands
55+
- Prerequisites listed at the top, not discovered mid-flow
56+
- Error states documented: "If you see X, it means Y. Fix: Z"
57+
58+
### Terminology consistency
59+
60+
- Use the same term for the same concept everywhere
61+
- Bold on first use with parenthetical definition
62+
- Maintain a project glossary for machine and human consumption
63+
64+
### Quality checklist (per document)
65+
66+
- First paragraph answers: "What does this help me do?"
67+
- Prerequisites listed at top
68+
- Every command includes directory context
69+
- Acronyms expanded on first use
70+
- No dangling references
71+
- Expected output shown after key steps
72+
- Error states documented for common failures
73+
- Further reading links have descriptions
74+
- Passes the tabula rasa test
75+
76+
## Consequences
77+
78+
- (+) New users complete guides without external help
79+
- (+) Agents execute workflows without human clarification
80+
- (+) Documentation gaps are discoverable (ADR-007 progressive failure protocol)
81+
- (+) International accessibility improves
82+
- (-) More writing effort per document
83+
- (-) Experts may find some material overly explicit (mitigated by progressive disclosure)
84+
- (!) Existing documentation does not meet this standard — improvement is incremental, not a rewrite
85+
86+
## References
87+
88+
- Issue #135 — full RFC with application matrix and open questions
89+
- Roadmap: Documentation and specifications
90+
- ADR-007 — knowledge acquisition protocol (complements this standard)

‎docs/src/content/docs/decisions/003-contribution-governance.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
title: 003 contribution governance
3+
---
4+
5+
# ADR-003: Contribution governance for async agents and humans
6+
7+
**Status:** accepted
8+
**Date:** 2026-05-19
9+
10+
## Context
11+
12+
ABCA is designed for multiple autonomous agents to work concurrently on the codebase. Without explicit governance rules, agents duplicate effort, start unapproved work, ignore priority order, miss predecessors, and create merge conflicts that require human intervention to untangle.
13+
14+
The rules below define how any contributor — human or AI — picks up, owns, and delivers work. They prevent priority inversion, wasted rework, unauthorized scope creep, and silent conflicts at scale.
15+
16+
## Decision
17+
18+
### No PRs without an Issue
19+
20+
Every PR references an issue. The issue provides rationale, sufficient context for the solution to be obvious, and verifiable acceptance criteria.
21+
22+
### Issue quality bar
23+
24+
An issue is "ready for work" when a contributor can read the body alone — without comments, related issues, or clarifying questions — and know exactly what to build.
25+
26+
### Roadmap alignment
27+
28+
Issues align to the [product roadmap](https://github.com/aws-samples/sample-autonomous-cloud-coding-agents/blob/main/docs/guides/ROADMAP.md). Issues that do not align require explicit admin approval.
29+
30+
### Admin approval gate
31+
32+
Only `admin` users can mark an issue `approved`. Unapproved and unassigned issues are not workable. A GitHub Actions workflow prevents non-admins from adding the `approved` label.
33+
34+
### Self-assignment on start
35+
36+
Unassigned means available. On starting work, self-assign. Multiple assignees (>1) require intentionality verification.
37+
38+
### Issue body is source of truth
39+
40+
Discussion threads are folded back into the body. Unresolved conflicts are marked explicitly:
41+
- `**UNRESOLVED:** <question>` — blocks implementation
42+
- `**DEFERRED:** <question> — tracked in #N` — does not block
43+
44+
### Pre-start review
45+
46+
Before implementation, the assigned contributor must:
47+
48+
**Read and verify:** All comments read, no unresolved conflicts.
49+
50+
**Priority evaluation:** Identify priority (`p0`/`p1`/`p2`). If asked to work a lower-priority item while higher-priority items are unassigned, challenge: "Should I work on #X (p0) instead?"
51+
52+
**Predecessor validation:** If predecessors are incomplete, unassigned, and not in a stacked PR — challenge: "Steps 1-3 are incomplete. Starting step 4 may cause rework."
53+
54+
**Cross-reference audit:** Search open issues for duplicates. Search open PRs (including drafts) for conflicts. Flag overlaps. Check the full dependency graph.
55+
56+
**Final gate:** If all checks pass, comment "Starting implementation."
57+
58+
### Identity and attribution
59+
60+
Agents use identifiable credentials. The prompting user and acting agent must be distinguishable. PRs include `Co-Authored-By` for AI contributors.
61+
62+
### Work-in-progress discipline
63+
64+
Provide progress signals at checkpoints. If blocked or abandoning, comment and unassign. Do not start multiple issues simultaneously unless explicitly parallelizable.
65+
66+
### Completion and handoff
67+
68+
CI passes before requesting review. After merge, verify acceptance criteria and close. Create follow-up issues for discovered work before closing.
69+
70+
## Consequences
71+
72+
- (+) Prevents duplicate effort — assignment signals ownership
73+
- (+) Prevents priority inversion — agents challenge low-priority requests
74+
- (+) Prevents rework — predecessor validation catches out-of-order work
75+
- (+) Issue body stays current — threads are folded back
76+
- (+) Cross-reference audit catches duplicates early
77+
- (-) Pre-start overhead for small tasks
78+
- (-) Requires discipline to fold threads into body
79+
- (!) Assumes priority labels exist and are maintained
80+
81+
## References
82+
83+
- Issue #134 — full RFC with open questions and automation requirements
84+
- Roadmap: Scale and collaboration (Agent swarm, Multi-user and teams)
85+
- ADR-001 — delivery methodology referenced by completion rules

‎docs/src/content/docs/decisions/004-tabula-rasa-documentation.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
title: 004 tabula rasa documentation
3+
---
4+
5+
# ADR-004: Tabula rasa documentation standard
6+
7+
**Status:** accepted
8+
**Date:** 2026-05-19
9+
10+
## Context
11+
12+
Documentation written by people with deep project knowledge assumes readers share that knowledge. Acronyms go unexpanded, prerequisite steps are skipped as "obvious," and instructions break for anyone starting from zero — including autonomous agents with fresh context windows.
13+
14+
This is especially damaging for a platform designed to be operated by agents: every documentation gap becomes a hard failure point. Agents cannot guess, infer from memory, or ask a colleague what "bootstrap the toolkit" means.
15+
16+
## Decision
17+
18+
### The Tabula Rasa Test
19+
20+
Every document must pass: **Can someone with zero project knowledge, following only what is written, complete the described outcome?** If any step requires knowledge not present in the document or explicitly linked, the document fails.
21+
22+
### Minimally sufficient
23+
24+
Write the minimum that makes the reader succeed — not the minimum words, but the minimum *sufficient* content.
25+
26+
- Novice needs explanation: one-sentence "what this does" before each step
27+
- Expert needs speed: scannable structure (numbered steps, headers, tables)
28+
- Both need confidence: expected output or success criteria after key steps
29+
30+
### Progressive disclosure
31+
32+
```
33+
Layer 1: What (one paragraph — what this helps you do)
34+
Layer 2: Steps (numbered, self-contained, runnable)
35+
Layer 3: Further reading (links with one-sentence descriptions)
36+
```
37+
38+
Never force a novice to read expert material to proceed. Never force an expert to wade through explanations to find the command.
39+
40+
### International English
41+
42+
- Simple sentence structure (subject-verb-object)
43+
- No idioms or colloquialisms
44+
- Concrete words ("run this command" not "execute the following")
45+
- One idea per sentence
46+
- Active voice
47+
48+
### Self-contained references
49+
50+
When referencing another document:
51+
- State what the reader gets from it: "See [Deployment Guide](link) for AWS account setup (required before this step)"
52+
- Never assume the reader has read it
53+
- Never use "as mentioned above" — each section must stand alone after context compaction
54+
55+
### Testable documentation
56+
57+
- Commands are copy-pasteable (no hidden dependencies)
58+
- Expected output shown after non-trivial commands
59+
- Prerequisites listed at the top, not discovered mid-flow
60+
- Error states documented: "If you see X, it means Y. Fix: Z"
61+
62+
### Terminology consistency
63+
64+
- Use the same term for the same concept everywhere
65+
- Bold on first use with parenthetical definition
66+
- Maintain a project glossary for machine and human consumption
67+
68+
### Quality checklist (per document)
69+
70+
- First paragraph answers: "What does this help me do?"
71+
- Prerequisites listed at top
72+
- Every command includes directory context
73+
- Acronyms expanded on first use
74+
- No dangling references
75+
- Expected output shown after key steps
76+
- Error states documented for common failures
77+
- Further reading links have descriptions
78+
- Passes the tabula rasa test
79+
80+
## Consequences
81+
82+
- (+) New users complete guides without external help
83+
- (+) Agents execute workflows without human clarification
84+
- (+) Documentation gaps are discoverable (ADR-007 progressive failure protocol)
85+
- (+) International accessibility improves
86+
- (-) More writing effort per document
87+
- (-) Experts may find some material overly explicit (mitigated by progressive disclosure)
88+
- (!) Existing documentation does not meet this standard — improvement is incremental, not a rewrite
89+
90+
## References
91+
92+
- Issue #135 — full RFC with application matrix and open questions
93+
- Roadmap: Documentation and specifications
94+
- ADR-007 — knowledge acquisition protocol (complements this standard)

0 commit comments

Comments
 (0)