From 744492df431f432f62a2555bd90233b3ea38582e Mon Sep 17 00:00:00 2001 From: bgagent <345885+scottschreckengaust@users.noreply.github.com> Date: Tue, 19 May 2026 06:59:40 +0000 Subject: [PATCH 1/2] 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) --- docs/decisions/003-contribution-governance.md | 81 ++++++++++++++++ .../004-tabula-rasa-documentation.md | 90 ++++++++++++++++++ .../decisions/003-contribution-governance.md | 85 +++++++++++++++++ .../004-tabula-rasa-documentation.md | 94 +++++++++++++++++++ 4 files changed, 350 insertions(+) create mode 100644 docs/decisions/003-contribution-governance.md create mode 100644 docs/decisions/004-tabula-rasa-documentation.md create mode 100644 docs/src/content/docs/decisions/003-contribution-governance.md create mode 100644 docs/src/content/docs/decisions/004-tabula-rasa-documentation.md diff --git a/docs/decisions/003-contribution-governance.md b/docs/decisions/003-contribution-governance.md new file mode 100644 index 0000000..70a33ac --- /dev/null +++ b/docs/decisions/003-contribution-governance.md @@ -0,0 +1,81 @@ +# ADR-003: Contribution governance for async agents and humans + +**Status:** accepted +**Date:** 2026-05-19 + +## Context + +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. + +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. + +## Decision + +### No PRs without an Issue + +Every PR references an issue. The issue provides rationale, sufficient context for the solution to be obvious, and verifiable acceptance criteria. + +### Issue quality bar + +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. + +### Roadmap alignment + +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. + +### Admin approval gate + +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. + +### Self-assignment on start + +Unassigned means available. On starting work, self-assign. Multiple assignees (>1) require intentionality verification. + +### Issue body is source of truth + +Discussion threads are folded back into the body. Unresolved conflicts are marked explicitly: +- `**UNRESOLVED:** ` — blocks implementation +- `**DEFERRED:** — tracked in #N` — does not block + +### Pre-start review + +Before implementation, the assigned contributor must: + +**Read and verify:** All comments read, no unresolved conflicts. + +**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?" + +**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." + +**Cross-reference audit:** Search open issues for duplicates. Search open PRs (including drafts) for conflicts. Flag overlaps. Check the full dependency graph. + +**Final gate:** If all checks pass, comment "Starting implementation." + +### Identity and attribution + +Agents use identifiable credentials. The prompting user and acting agent must be distinguishable. PRs include `Co-Authored-By` for AI contributors. + +### Work-in-progress discipline + +Provide progress signals at checkpoints. If blocked or abandoning, comment and unassign. Do not start multiple issues simultaneously unless explicitly parallelizable. + +### Completion and handoff + +CI passes before requesting review. After merge, verify acceptance criteria and close. Create follow-up issues for discovered work before closing. + +## Consequences + +- (+) Prevents duplicate effort — assignment signals ownership +- (+) Prevents priority inversion — agents challenge low-priority requests +- (+) Prevents rework — predecessor validation catches out-of-order work +- (+) Issue body stays current — threads are folded back +- (+) Cross-reference audit catches duplicates early +- (-) Pre-start overhead for small tasks +- (-) Requires discipline to fold threads into body +- (!) Assumes priority labels exist and are maintained + +## References + +- Issue #134 — full RFC with open questions and automation requirements +- Roadmap: Scale and collaboration (Agent swarm, Multi-user and teams) +- ADR-001 — delivery methodology referenced by completion rules diff --git a/docs/decisions/004-tabula-rasa-documentation.md b/docs/decisions/004-tabula-rasa-documentation.md new file mode 100644 index 0000000..ea50e14 --- /dev/null +++ b/docs/decisions/004-tabula-rasa-documentation.md @@ -0,0 +1,90 @@ +# ADR-004: Tabula rasa documentation standard + +**Status:** accepted +**Date:** 2026-05-19 + +## Context + +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. + +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. + +## Decision + +### The Tabula Rasa Test + +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. + +### Minimally sufficient + +Write the minimum that makes the reader succeed — not the minimum words, but the minimum *sufficient* content. + +- Novice needs explanation: one-sentence "what this does" before each step +- Expert needs speed: scannable structure (numbered steps, headers, tables) +- Both need confidence: expected output or success criteria after key steps + +### Progressive disclosure + +``` +Layer 1: What (one paragraph — what this helps you do) +Layer 2: Steps (numbered, self-contained, runnable) +Layer 3: Further reading (links with one-sentence descriptions) +``` + +Never force a novice to read expert material to proceed. Never force an expert to wade through explanations to find the command. + +### International English + +- Simple sentence structure (subject-verb-object) +- No idioms or colloquialisms +- Concrete words ("run this command" not "execute the following") +- One idea per sentence +- Active voice + +### Self-contained references + +When referencing another document: +- State what the reader gets from it: "See [Deployment Guide](link) for AWS account setup (required before this step)" +- Never assume the reader has read it +- Never use "as mentioned above" — each section must stand alone after context compaction + +### Testable documentation + +- Commands are copy-pasteable (no hidden dependencies) +- Expected output shown after non-trivial commands +- Prerequisites listed at the top, not discovered mid-flow +- Error states documented: "If you see X, it means Y. Fix: Z" + +### Terminology consistency + +- Use the same term for the same concept everywhere +- Bold on first use with parenthetical definition +- Maintain a project glossary for machine and human consumption + +### Quality checklist (per document) + +- First paragraph answers: "What does this help me do?" +- Prerequisites listed at top +- Every command includes directory context +- Acronyms expanded on first use +- No dangling references +- Expected output shown after key steps +- Error states documented for common failures +- Further reading links have descriptions +- Passes the tabula rasa test + +## Consequences + +- (+) New users complete guides without external help +- (+) Agents execute workflows without human clarification +- (+) Documentation gaps are discoverable (ADR-007 progressive failure protocol) +- (+) International accessibility improves +- (-) More writing effort per document +- (-) Experts may find some material overly explicit (mitigated by progressive disclosure) +- (!) Existing documentation does not meet this standard — improvement is incremental, not a rewrite + +## References + +- Issue #135 — full RFC with application matrix and open questions +- Roadmap: Documentation and specifications +- ADR-007 — knowledge acquisition protocol (complements this standard) diff --git a/docs/src/content/docs/decisions/003-contribution-governance.md b/docs/src/content/docs/decisions/003-contribution-governance.md new file mode 100644 index 0000000..faab575 --- /dev/null +++ b/docs/src/content/docs/decisions/003-contribution-governance.md @@ -0,0 +1,85 @@ +--- +title: 003 contribution governance +--- + +# ADR-003: Contribution governance for async agents and humans + +**Status:** accepted +**Date:** 2026-05-19 + +## Context + +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. + +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. + +## Decision + +### No PRs without an Issue + +Every PR references an issue. The issue provides rationale, sufficient context for the solution to be obvious, and verifiable acceptance criteria. + +### Issue quality bar + +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. + +### Roadmap alignment + +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. + +### Admin approval gate + +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. + +### Self-assignment on start + +Unassigned means available. On starting work, self-assign. Multiple assignees (>1) require intentionality verification. + +### Issue body is source of truth + +Discussion threads are folded back into the body. Unresolved conflicts are marked explicitly: +- `**UNRESOLVED:** ` — blocks implementation +- `**DEFERRED:** — tracked in #N` — does not block + +### Pre-start review + +Before implementation, the assigned contributor must: + +**Read and verify:** All comments read, no unresolved conflicts. + +**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?" + +**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." + +**Cross-reference audit:** Search open issues for duplicates. Search open PRs (including drafts) for conflicts. Flag overlaps. Check the full dependency graph. + +**Final gate:** If all checks pass, comment "Starting implementation." + +### Identity and attribution + +Agents use identifiable credentials. The prompting user and acting agent must be distinguishable. PRs include `Co-Authored-By` for AI contributors. + +### Work-in-progress discipline + +Provide progress signals at checkpoints. If blocked or abandoning, comment and unassign. Do not start multiple issues simultaneously unless explicitly parallelizable. + +### Completion and handoff + +CI passes before requesting review. After merge, verify acceptance criteria and close. Create follow-up issues for discovered work before closing. + +## Consequences + +- (+) Prevents duplicate effort — assignment signals ownership +- (+) Prevents priority inversion — agents challenge low-priority requests +- (+) Prevents rework — predecessor validation catches out-of-order work +- (+) Issue body stays current — threads are folded back +- (+) Cross-reference audit catches duplicates early +- (-) Pre-start overhead for small tasks +- (-) Requires discipline to fold threads into body +- (!) Assumes priority labels exist and are maintained + +## References + +- Issue #134 — full RFC with open questions and automation requirements +- Roadmap: Scale and collaboration (Agent swarm, Multi-user and teams) +- ADR-001 — delivery methodology referenced by completion rules diff --git a/docs/src/content/docs/decisions/004-tabula-rasa-documentation.md b/docs/src/content/docs/decisions/004-tabula-rasa-documentation.md new file mode 100644 index 0000000..d125ab3 --- /dev/null +++ b/docs/src/content/docs/decisions/004-tabula-rasa-documentation.md @@ -0,0 +1,94 @@ +--- +title: 004 tabula rasa documentation +--- + +# ADR-004: Tabula rasa documentation standard + +**Status:** accepted +**Date:** 2026-05-19 + +## Context + +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. + +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. + +## Decision + +### The Tabula Rasa Test + +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. + +### Minimally sufficient + +Write the minimum that makes the reader succeed — not the minimum words, but the minimum *sufficient* content. + +- Novice needs explanation: one-sentence "what this does" before each step +- Expert needs speed: scannable structure (numbered steps, headers, tables) +- Both need confidence: expected output or success criteria after key steps + +### Progressive disclosure + +``` +Layer 1: What (one paragraph — what this helps you do) +Layer 2: Steps (numbered, self-contained, runnable) +Layer 3: Further reading (links with one-sentence descriptions) +``` + +Never force a novice to read expert material to proceed. Never force an expert to wade through explanations to find the command. + +### International English + +- Simple sentence structure (subject-verb-object) +- No idioms or colloquialisms +- Concrete words ("run this command" not "execute the following") +- One idea per sentence +- Active voice + +### Self-contained references + +When referencing another document: +- State what the reader gets from it: "See [Deployment Guide](link) for AWS account setup (required before this step)" +- Never assume the reader has read it +- Never use "as mentioned above" — each section must stand alone after context compaction + +### Testable documentation + +- Commands are copy-pasteable (no hidden dependencies) +- Expected output shown after non-trivial commands +- Prerequisites listed at the top, not discovered mid-flow +- Error states documented: "If you see X, it means Y. Fix: Z" + +### Terminology consistency + +- Use the same term for the same concept everywhere +- Bold on first use with parenthetical definition +- Maintain a project glossary for machine and human consumption + +### Quality checklist (per document) + +- First paragraph answers: "What does this help me do?" +- Prerequisites listed at top +- Every command includes directory context +- Acronyms expanded on first use +- No dangling references +- Expected output shown after key steps +- Error states documented for common failures +- Further reading links have descriptions +- Passes the tabula rasa test + +## Consequences + +- (+) New users complete guides without external help +- (+) Agents execute workflows without human clarification +- (+) Documentation gaps are discoverable (ADR-007 progressive failure protocol) +- (+) International accessibility improves +- (-) More writing effort per document +- (-) Experts may find some material overly explicit (mitigated by progressive disclosure) +- (!) Existing documentation does not meet this standard — improvement is incremental, not a rewrite + +## References + +- Issue #135 — full RFC with application matrix and open questions +- Roadmap: Documentation and specifications +- ADR-007 — knowledge acquisition protocol (complements this standard) From 6b724e68736e9a830c0097d9bed28af58ec9cedb Mon Sep 17 00:00:00 2001 From: bgagent <345885+scottschreckengaust@users.noreply.github.com> Date: Thu, 21 May 2026 06:58:59 +0000 Subject: [PATCH 2/2] docs(ADR-003): remove limiting language, enrich context model MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address review feedback: - Issue quality bar: body is primary directive, not exclusively sufficient — comments, predecessors, downstream goals all add context - Issue body section: renamed from "source of truth" to "primary directive"; reviewer synthesizes threads with body before implementation - Pre-start review: adds context synthesis step (predecessors, adjacent state, forward-look into downstream) - Work-in-progress: allows serializable work with declared ordering Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/decisions/003-contribution-governance.md | 14 ++++++++------ .../docs/decisions/003-contribution-governance.md | 14 ++++++++------ 2 files changed, 16 insertions(+), 12 deletions(-) diff --git a/docs/decisions/003-contribution-governance.md b/docs/decisions/003-contribution-governance.md index 70a33ac..d58720a 100644 --- a/docs/decisions/003-contribution-governance.md +++ b/docs/decisions/003-contribution-governance.md @@ -17,7 +17,7 @@ Every PR references an issue. The issue provides rationale, sufficient context f ### Issue quality bar -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. +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. ### Roadmap alignment @@ -31,9 +31,11 @@ Only `admin` users can mark an issue `approved`. Unapproved and unassigned issue Unassigned means available. On starting work, self-assign. Multiple assignees (>1) require intentionality verification. -### Issue body is source of truth +### Issue body as primary directive -Discussion threads are folded back into the body. Unresolved conflicts are marked explicitly: +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. + +Unresolved conflicts are marked explicitly: - `**UNRESOLVED:** ` — blocks implementation - `**DEFERRED:** — tracked in #N` — does not block @@ -41,13 +43,13 @@ Discussion threads are folded back into the body. Unresolved conflicts are marke Before implementation, the assigned contributor must: -**Read and verify:** All comments read, no unresolved conflicts. +**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. **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?" **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." -**Cross-reference audit:** Search open issues for duplicates. Search open PRs (including drafts) for conflicts. Flag overlaps. Check the full dependency graph. +**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. **Final gate:** If all checks pass, comment "Starting implementation." @@ -57,7 +59,7 @@ Agents use identifiable credentials. The prompting user and acting agent must be ### Work-in-progress discipline -Provide progress signals at checkpoints. If blocked or abandoning, comment and unassign. Do not start multiple issues simultaneously unless explicitly parallelizable. +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). ### Completion and handoff diff --git a/docs/src/content/docs/decisions/003-contribution-governance.md b/docs/src/content/docs/decisions/003-contribution-governance.md index faab575..7668aad 100644 --- a/docs/src/content/docs/decisions/003-contribution-governance.md +++ b/docs/src/content/docs/decisions/003-contribution-governance.md @@ -21,7 +21,7 @@ Every PR references an issue. The issue provides rationale, sufficient context f ### Issue quality bar -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. +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. ### Roadmap alignment @@ -35,9 +35,11 @@ Only `admin` users can mark an issue `approved`. Unapproved and unassigned issue Unassigned means available. On starting work, self-assign. Multiple assignees (>1) require intentionality verification. -### Issue body is source of truth +### Issue body as primary directive -Discussion threads are folded back into the body. Unresolved conflicts are marked explicitly: +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. + +Unresolved conflicts are marked explicitly: - `**UNRESOLVED:** ` — blocks implementation - `**DEFERRED:** — tracked in #N` — does not block @@ -45,13 +47,13 @@ Discussion threads are folded back into the body. Unresolved conflicts are marke Before implementation, the assigned contributor must: -**Read and verify:** All comments read, no unresolved conflicts. +**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. **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?" **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." -**Cross-reference audit:** Search open issues for duplicates. Search open PRs (including drafts) for conflicts. Flag overlaps. Check the full dependency graph. +**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. **Final gate:** If all checks pass, comment "Starting implementation." @@ -61,7 +63,7 @@ Agents use identifiable credentials. The prompting user and acting agent must be ### Work-in-progress discipline -Provide progress signals at checkpoints. If blocked or abandoning, comment and unassign. Do not start multiple issues simultaneously unless explicitly parallelizable. +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). ### Completion and handoff