Skip to content

Commit c4a9ed7

Browse files
scottschreckengaustscottschreckengaust
authored
Merge branch 'main' into docs/classic-pat-guidance
2 parents feea8eb + 4364855 commit c4a9ed7

4 files changed

Lines changed: 356 additions & 0 deletions

File tree

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

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
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 the body, together with its linked context — comments, replies, predecessor issues, related PRs (open and merged), and downstream goals — gives the implementer enough to proceed without ambiguity. The body is the primary directive; comments and threads add solution-space context; predecessors establish environmental architecture; downstream issues inform alignment.
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 approval from a permitted user.
25+
26+
### Gated approval
27+
28+
Only permitted users can mark an issue `approved` — a GitHub Actions workflow validates that the label applicant is authorized. An issue is not workable until it is both approved and assigned. After approval, the issue is considered scope-frozen: further revisions that change deliverables require re-approval.
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 as primary directive
35+
36+
The issue body provides the primary directive for implementation. Comments, replies, and clarifying answers add context to the solution space. Ideally the body is sufficient, but it need not be the exclusive source — the reviewer for implementation readiness should synthesize comments and replies with the body to surface inconsistencies and resolve ambiguities before commencing work.
37+
38+
Unresolved conflicts are marked explicitly:
39+
- `**UNRESOLVED:** <question>` — blocks implementation
40+
- `**DEFERRED:** <question> — tracked in #N` — does not block
41+
42+
### Pre-start review
43+
44+
Before implementation, the assigned contributor must:
45+
46+
**Synthesize context:** Read all comments and replies. Review predecessor issues and PRs (both merged and in-flight). Consider downstream goals and adjacent state (other open PRs, recent merges, dependency changes). Surface inconsistencies between body and thread before proceeding.
47+
48+
**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?"
49+
50+
**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."
51+
52+
**Cross-reference audit:** Search open issues for duplicates. Search open PRs (including drafts) for conflicts. Flag overlaps. Check the full dependency graph. Forward-look into downstream actions to ensure alignment.
53+
54+
**Final gate:** If all checks pass, comment "Starting implementation."
55+
56+
### Identity and attribution
57+
58+
Agents use identifiable credentials. The prompting user and acting agent must be distinguishable. PRs include `Co-Authored-By` for AI contributors.
59+
60+
### Work-in-progress discipline
61+
62+
Provide progress signals at checkpoints. If blocked or abandoning, comment and unassign. Do not start multiple issues simultaneously unless explicitly parallelizable or serializable with declared ordering (where context from one directly informs the next).
63+
64+
### Completion and handoff
65+
66+
CI passes before requesting review. After merge, verify acceptance criteria and close. Create follow-up issues for discovered work before closing.
67+
68+
## Consequences
69+
70+
- (+) Prevents duplicate effort — assignment signals ownership
71+
- (+) Prevents priority inversion — agents challenge low-priority requests
72+
- (+) Prevents rework — predecessor validation catches out-of-order work
73+
- (+) Issue body stays current — threads are folded back
74+
- (+) Cross-reference audit catches duplicates early
75+
- (-) Pre-start overhead for small tasks
76+
- (-) Requires discipline to fold threads into body
77+
- (!) Assumes priority labels exist and are maintained
78+
- (!) Self-assignment is not atomic — concurrent agents may race; mitigate by verifying assignment after claiming via refresh
79+
80+
## References
81+
82+
- Issue #134 — full RFC with open questions and automation requirements
83+
- Roadmap: Scale and collaboration (Agent swarm, Multi-user and teams)
84+
- 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: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
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 the body, together with its linked context — comments, replies, predecessor issues, related PRs (open and merged), and downstream goals — gives the implementer enough to proceed without ambiguity. The body is the primary directive; comments and threads add solution-space context; predecessors establish environmental architecture; downstream issues inform alignment.
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 approval from a permitted user.
29+
30+
### Gated approval
31+
32+
Only permitted users can mark an issue `approved` — a GitHub Actions workflow validates that the label applicant is authorized. An issue is not workable until it is both approved and assigned. After approval, the issue is considered scope-frozen: further revisions that change deliverables require re-approval.
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 as primary directive
39+
40+
The issue body provides the primary directive for implementation. Comments, replies, and clarifying answers add context to the solution space. Ideally the body is sufficient, but it need not be the exclusive source — the reviewer for implementation readiness should synthesize comments and replies with the body to surface inconsistencies and resolve ambiguities before commencing work.
41+
42+
Unresolved conflicts are marked explicitly:
43+
- `**UNRESOLVED:** <question>` — blocks implementation
44+
- `**DEFERRED:** <question> — tracked in #N` — does not block
45+
46+
### Pre-start review
47+
48+
Before implementation, the assigned contributor must:
49+
50+
**Synthesize context:** Read all comments and replies. Review predecessor issues and PRs (both merged and in-flight). Consider downstream goals and adjacent state (other open PRs, recent merges, dependency changes). Surface inconsistencies between body and thread before proceeding.
51+
52+
**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?"
53+
54+
**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."
55+
56+
**Cross-reference audit:** Search open issues for duplicates. Search open PRs (including drafts) for conflicts. Flag overlaps. Check the full dependency graph. Forward-look into downstream actions to ensure alignment.
57+
58+
**Final gate:** If all checks pass, comment "Starting implementation."
59+
60+
### Identity and attribution
61+
62+
Agents use identifiable credentials. The prompting user and acting agent must be distinguishable. PRs include `Co-Authored-By` for AI contributors.
63+
64+
### Work-in-progress discipline
65+
66+
Provide progress signals at checkpoints. If blocked or abandoning, comment and unassign. Do not start multiple issues simultaneously unless explicitly parallelizable or serializable with declared ordering (where context from one directly informs the next).
67+
68+
### Completion and handoff
69+
70+
CI passes before requesting review. After merge, verify acceptance criteria and close. Create follow-up issues for discovered work before closing.
71+
72+
## Consequences
73+
74+
- (+) Prevents duplicate effort — assignment signals ownership
75+
- (+) Prevents priority inversion — agents challenge low-priority requests
76+
- (+) Prevents rework — predecessor validation catches out-of-order work
77+
- (+) Issue body stays current — threads are folded back
78+
- (+) Cross-reference audit catches duplicates early
79+
- (-) Pre-start overhead for small tasks
80+
- (-) Requires discipline to fold threads into body
81+
- (!) Assumes priority labels exist and are maintained
82+
- (!) Self-assignment is not atomic — concurrent agents may race; mitigate by verifying assignment after claiming via refresh
83+
84+
## References
85+
86+
- Issue #134 — full RFC with open questions and automation requirements
87+
- Roadmap: Scale and collaboration (Agent swarm, Multi-user and teams)
88+
- 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)