RFC: ADR-003 — Contribution governance for async agents and humans

[scottschreckengaust]

Summary

Establish a formal governance process for how autonomous agents and humans pick up, own, and deliver work at scale. This ADR defines the rules that prevent duplicate effort, unauthorized scope creep, silent conflicts, priority inversion, and wasted rework when multiple contributors (human or AI) work asynchronously on the same codebase.

Use case and motivation

Who it's for: All contributors — AI coding agents (Claude Code, Copilot, Kiro, etc.), human developers, and the admin team that approves work.

Problem today:

1. No formal gate between "issue exists" and "work begins" — an agent can start implementing an unapproved RFC.
2. No mechanism to signal ownership — two agents may independently start the same issue.
3. Discussion threads in issues accumulate but are not folded back into the issue body — later readers (especially agents) miss context buried in thread replies.
4. No alignment requirement between issues and the product roadmap — drift accumulates.
5. No explicit handling of conflicts or unresolved questions — they remain latent until implementation surfaces them.
6. No priority enforcement — agents work on low-priority items while high-priority work sits unassigned.
7. No predecessor validation — agents start step 4 while steps 1-3 are incomplete, causing rework.
8. No cross-referencing gate — duplicate or conflicting issues go undetected until PR conflicts surface.

After this ADR:

• Clear lifecycle: issue → roadmap alignment → admin approval → priority/predecessor check → assignment → cross-reference audit → implementation → PR
• Self-assignment signals ownership; unassigned = available
• Issue body is the canonical source of truth (threads are folded back)
• Unauthorized work is structurally blocked (not just discouraged)
• Priority inversion is challenged before work begins
• Predecessors are verified complete or in-flight before dependent work starts
• Cross-referencing prevents duplicate effort and surfaces conflicts early

Proposed rules

1. No PRs without an Issue

Every PR must reference an issue. The issue provides:

• Rationale (why this work matters)
• Enough context that the solution approach is obvious without additional conversation
• Acceptance criteria that can be verified by the reviewer

2. Issue quality bar

An issue is "ready for work" when a contributor (agent or human) can read the body alone — without reading comments, related issues, or asking clarifying questions — and know exactly what to build.

3. Roadmap alignment

• Issues must align to an item on the product roadmap
• If an issue does NOT align to the roadmap, it must be explicitly approved by an admin (see Rule 4)
• Roadmap alignment is documented in the issue body (link or reference)

4. Admin approval gate

• Only users with admin role can mark an issue as "approved" (via label or status)
• Unapproved + unassigned issues are not workable — agents must not start implementation
• A GitHub Actions workflow enforces that non-admin maintainers cannot add the approved label
• The approved label is the gate between "proposed" and "ready for work"

5. Assignments

• Unassigned = available for pickup
• Assignment may happen via:
  • Self-assignment — contributor picks up an unassigned task
  • Directed assignment — another agent or human assigns the task
  • Priority-based pickup — inspect the open task list for highest priority + earliest predecessor (preferred for autonomous agents)
• Assignment communicates to all other agents/humans: "this is being worked on"
• If an agent cannot self-assign (PAT limitations), it must comment "I am working on this" with an identifier
• Multiple assignment (>1 resource) is a concern — if an issue has multiple assignees, verify this was intentional (e.g., pair programming, stacked PR collaboration) before proceeding. If unclear, ask.

6. Issue body is source of truth

• Discussion in comments/threads must be folded back into the issue body
• The body reflects the current agreed state, not just the original proposal
• Conflicts or unresolved questions are explicitly called out in the body with one of:
  • **UNRESOLVED:** <question> — blocks implementation until answered
  • **DEFERRED:** <question> — tracked in #<future-issue> — does not block, handled later

7. Pre-start review (comprehensive gate)

Before beginning implementation, the assigned contributor must:

7a. Read and verify issue state:

1. Read all comments on the issue
2. Verify no unresolved conflicts exist in the body
3. If clarification is needed: ask in a comment and do not start until answered

7b. Priority evaluation:

1. Identify the issue's priority (p0 = critical/blocking, p1 = important, p2 = nice-to-have)
2. Check for unassigned higher-priority issues in the same area
3. If asked to work a p2 while p0 or p1 items are unassigned and actionable — challenge the requestor: "There are higher-priority unassigned items (#X, #Y). Should I work on those first?"
4. Document the priority justification if proceeding with a lower-priority item despite higher-priority alternatives

7c. Predecessor validation (GraphQL dependency graph is authoritative):

1. Query the GitHub GraphQL dependency graph — use the blockedBy field on this issue as the authoritative source for ordering:

   { node(id: "<issue-id>") { ... on Issue { blockedBy(first: 10) { nodes { number state } } } } }

   • If any blocking issue is open (not closed): this issue is not ready for work — hard gate
   • Do not override based on issue body prose alone
2. Check parent and subIssues ordering — if this issue is a sub-issue, verify prior siblings in the parent's list are complete or in-flight
3. Reconcile graph vs. prose — if the issue body says "depends on #X" but no blockedBy relationship exists (or vice versa):
   • Flag the inconsistency in a comment
   • Add the missing GraphQL relationship (addBlockedBy mutation) or update stale prose
   • Rule: graph is authoritative for machine enforcement; prose explains why the dependency exists
4. Check if predecessors are complete, in-flight (assigned + active PR), or blocked
5. If predecessors are incomplete AND not in a stacked PR AND unassigned — challenge: "Steps 1-3 (#X, #Y, #Z) appear incomplete. Starting step 4 may cause rework if earlier steps change the foundation. Should I work on predecessors first?"
6. If the work is part of a stacked PR chain, verify the base branch exists and is in reviewable state

7d. Cross-reference audit:

1. Search open issues for duplicates or overlapping scope (title, labels, related keywords)
2. Search open PRs (including drafts, excluding fork network) for conflicting or overlapping work
3. If duplicates found: comment on both issues flagging the overlap, ask for consolidation decision
4. If conflicting PRs found: flag the conflict and ask how to proceed (rebase, wait, or scope adjustment)
5. Check if other issues reference this one — understand the full dependency graph
6. Identify any missing relevancy (issues that should reference each other but don't)

7e. Final gate:

1. If all checks pass: comment "Starting implementation" (signals to watchers)
2. If any check fails: document the blocker and do not start

8. Identity and attribution

• Agents identify themselves via their Git user config or PAT-derived identity
• When the user prompting an agent is the same identity as the issue author, the agent should be explicit about which "hat" it's wearing (e.g., "Implementing as assigned contributor" vs. "Asking a clarifying question as reviewer")
• PRs include Co-Authored-By for AI contributors
• The identity used for assignment must be traceable to who/what is doing the work

9. Work-in-progress discipline

• Once assigned and started, provide progress signals (PR draft, comments) at least every meaningful checkpoint
• If blocked or context-switching away: comment the blocker, unassign if abandoning
• Stale assignments (no activity for configurable period) are flagged for review
• Do not start multiple issues simultaneously unless they are explicitly parallelizable (no shared state or sequential dependencies)

10. Dependency graph maintenance

The GitHub GraphQL sub-issue and blocking relationships are the machine-enforceable dependency system. They must be maintained:

• When creating an issue that depends on another: add blockedBy via GraphQL mutation (addBlockedBy)
• When creating a parent/child relationship: add subIssue via GraphQL mutation (addSubIssue)
• When a blocking issue is resolved: the blockedBy relationship remains (historical); the blocked issue becomes workable because the blocker's state is now closed
• When issue scope changes (dependencies added/removed): update both the graph AND the issue body prose
• Sync rule: Graph is authoritative for enforcement. Prose explains rationale. If they diverge, fix the one that's wrong — usually the prose (the graph was set programmatically and is less likely to rot).

11. Completion and handoff

• PRs must pass CI before requesting review
• PR description follows the position template (ADR-001 for stacked PRs, or a simplified version for standalone PRs)
• After merge: verify the issue's acceptance criteria are met, then close
• If the work revealed new issues or follow-up needs: create them before closing (don't leave implicit TODOs)

GitHub automation requirements

• Workflow: prevent non-admins from adding approved label
• Workflow: prevent PR merge if linked issue is not approved
• Workflow: flag issues with multiple assignees for intentionality check
• Workflow: auto-label stale assignments (no PR or comment in N days)
• (Optional) Workflow: auto-assign on branch push matching issue number pattern
• (Optional) Workflow: priority label enforcement on new issues

Out of scope

• Specific code review standards (covered by existing AGENTS.md)
• PR merge strategy (squash vs. merge — covered by ADR-001 for stacked PRs)
• SLA or time-based escalation for stale assignments (advisory only in this ADR)
• Specific identity federation mechanisms (PAT management, bot accounts)
• Automated priority assignment (this ADR defines the evaluation; tooling is future work)

Alignment

This RFC aligns with the roadmap's Scale and collaboration theme — specifically enabling multiple autonomous agents to work concurrently on the codebase without human coordination overhead. The governance rules are prerequisites for the "Agent swarm" and "Multi-user and teams" capabilities listed in the roadmap.

Dependencies

• Requires docs/decisions/ framework (ADR-001, PR docs: establish ADR framework and ADR-001 stacked pull requests #130) — but can land in any order since ADR numbering is sequential, not dependency-ordered
• GitHub Actions workflows for label protection

Alternative solutions

Approach	Why not preferred
Trust-based (no formal gates)	Doesn't scale; agents lack judgment about organizational priorities
CODEOWNERS-only	Controls review but not work initiation
Linear/Jira workflow	External tool dependency; GitHub-native is more accessible to agents
Branch protection only	Prevents merge but not wasted implementation effort
Priority-only (no predecessor check)	Agents start dependent work out of order, causing rework
Manual coordination	Doesn't scale; requires synchronous human presence

Resolved questions

#	Question	Answer	Decided by
1	Should approved be a label or a GitHub Projects status field?	Label — no GitHub Project available yet	@scottschreckengaust
2	Should agents be required to have a dedicated bot identity, or can they use the human's PAT?	Agent uses the GitHub PAT token (which may be their own or a bot identity)	@scottschreckengaust
3	What happens when an assigned contributor goes silent for >N days? (auto-unassign threshold?)	Auto-unassign after N configurable hours if no drafted PR exists. If a draft PR is present, assignment is valid.	@scottschreckengaust
4	Should the priority challenge be a hard gate (refuse to work) or soft gate (warn + proceed if confirmed)?	Soft gate — warn and proceed if confirmed	@scottschreckengaust
5	How should the cross-reference audit handle large repositories with hundreds of open issues?	Search all for now. Future: duplicate remediation, auto-close stale unaddressed issues, resurfacing via reopening or duplication that validates roadmap entry.	@scottschreckengaust

Self-improvement note

This ADR is designed to be self-referential: autonomous agents operating under these rules can identify gaps in the governance process itself, propose improvements via the standard issue → ADR → PR flow, and incrementally refine the process. The rules should be treated as a living system — improved through the same mechanism they govern. Specifically:

• An agent noticing a governance gap (e.g., "I couldn't determine priority because no labeling convention exists") should file an issue proposing the fix
• The ADR itself can be superseded by a future ADR-00N if the process proves insufficient at scale
• Agents should periodically evaluate whether the pre-start checks are catching real problems vs. creating unnecessary friction — and propose adjustments either way

---

Note: This RFC follows its own proposed rules. Once approved by an admin, an assigned contributor should fold any discussion into the body, resolve open questions, and implement as ADR-003.

• RFC PR: (pending approval)
• Approved by: (pending)
• Reviewed by: (pending)

[scottschreckengaust]

So section 5 may be better as "5. Assignments"

Self-Assignment is not necessary - a user may self-assign but another agent (human or other) may assign tasks and the list of open tasks are to be inspected for highest priority and earliest predecessor.