Contributor Standards

Standards for working with CONTEXT.md, docs/adr/, and AI-agent-assisted contributions.

These apply to every PR — fix, enhancement, or feature. They are part of the merge contract, not optional background reading.

Standards hierarchy (canonical, in order):

1. CONTEXT.md — domain language and module naming
2. docs/adr/ — accepted architectural decisions
3. Approved issue scope

CONTEXT.md

What it is

CONTEXT.md is the single source of truth for domain vocabulary. It defines:

• Domain terms — canonical Module names, seam vocabulary, and Interface names (e.g. Dispatch Policy Module, Command Contract Validation Module, Planning Workspace Module)
• Recurring PR mistakes — CodeRabbit findings that recur; covers tests, shell guards, changesets, docs
• Workflow learnings — patterns distilled from triage + PR cycles

Format

CONTEXT.md is written as flat named sections under ## Domain terms (for Modules/seams) and ## sections for recurring rules. Machine-oriented predicates use KEY.SUBKEY=value flat format in code blocks under ## AI Ops Memory.

Adding a new Module or seam:

• Add a ### <Module Name> entry under ## Domain terms.
• Write one paragraph. State what the Module owns. Be concrete — list the Interface names and policy boundaries it covers.
• Do not add synonyms; pick one name and use it everywhere.

Extending an existing predicate:

• Add a KEY.SUBKEY=value line inside the relevant ## AI Ops Memory block.
• Do not create a new top-level section for a variation on an existing concept.

When to add a new predicate vs extend an existing one:

• New predicate: the concept has a distinct identity, distinct owner, and is not covered by any existing section.
• Extend existing: the new fact qualifies, constrains, or amends an already-named Module. Add it as a sub-entry or amendment paragraph.

Contributor requirements

• Read CONTEXT.md in full before naming anything (modules, interfaces, seams, tests, PRs).
• Use CONTEXT.md vocabulary consistently in code comments, tests, issue/PR text, and docs.
• Do not invent synonyms. If you need a concept that is not in the glossary, note it explicitly in the issue or PR rather than using ad-hoc language.
• Do not rewrite CONTEXT.md as part of drive-by cleanup; propose focused updates tied to the approved issue scope.
• CONTEXT.md is maintainer-owned. Contributors can propose additions via issue discussion, but final wording is the maintainer's call.

Example (correct)

A PR that adds a new query adapter should use the term Native Dispatch Adapter Module (from CONTEXT.md), not "native adapter," "query native handler," or any other variant.

ADRs

What they are

docs/adr/ contains Architecture Decision Records. Each ADR is a concise record of one accepted decision: the problem, the decision, and the consequences. Accepted ADRs are the current standard.

Currently accepted ADRs:

When an ADR is required

An ADR is required when a decision:

• Introduces or removes a Module seam that other code will depend on.
• Changes the policy contract of an existing accepted ADR.
• Establishes a new architectural invariant (naming convention, test contract, CI enforcement).

An ADR is optional (a comment in the relevant issue or PR is sufficient) when:

• The change is a bugfix that lands squarely within an existing accepted decision.
• The change is a docs or test improvement with no architectural surface.

Naming conventions

NNNN-<short-slug>.md — four-digit zero-padded sequence number, followed by a kebab-case slug that names the Module or decision. Example: 0003-model-catalog-module.md.

Required sections

Every ADR must open with:

# <Title>

- **Status:** Accepted | Proposed | Deprecated
- **Date:** YYYY-MM-DD

Body: one-paragraph decision summary, then ## Decision (specifics), then ## Consequences (behavioral changes downstream callers can rely on).

Amendments are appended as ## Amendment (YYYY-MM-DD): <topic> sections — the original body is never rewritten.

Status block format

- **Status:** Accepted
- **Date:** 2026-05-09

Status values: Proposed (under discussion), Accepted (current standard), Deprecated (superseded — include a forward reference to the replacement).

Cross-reference style

Reference sibling ADRs by filename, not by title prose: see \0001-dispatch-policy-module.md``. This survives title edits.

ADR README index

docs/adr/ does not currently maintain a separate README.md index. The canonical index is the table in this document (above). If an ADR is added, update this table in the same PR.

Governance

• ADR creation and final wording is maintainer-owned. Contributors must not open ADR files as part of a contribution PR.
• Contributors can — and should — give input on proposed ADR direction in the linked issue discussion.
• Once an ADR is Accepted, reopening the decision must be explicit (a dedicated issue with rationale), not implied by a drive-by PR change.
• If your PR intentionally revisits an accepted ADR decision, call it out explicitly in the issue and the PR body: "This revisits ADR-0002 because…"

AI-agent-assisted work

When AI assistance is appropriate

AI assistance is appropriate for every contribution type. The bar for correctness and review quality does not change because the code was AI-assisted.

Pre-work requirements

Before any AI agent writes a single line of code or docs, it must read:

1. CONTEXT.md in full.
2. The ADRs relevant to the area being changed (check docs/adr/).
3. The approved issue scope.

If you are dispatching an AI agent, include these reads in the agent's prompt explicitly. An agent that invents synonyms for CONTEXT.md vocabulary or contradicts an accepted ADR without flagging it has failed the pre-work requirement.

In the PR body, state which ADR or standards section was followed. If using an AI assistant, this statement is your responsibility as the author — not the agent's.

Worktree isolation

Agent-written code must use an isolated worktree to prevent branch pollution. The standard pattern:

git worktree add ../my-feature-worktree fix/NNNN-short-description

Never commit agent output directly to main or to an already-open feature branch without review.

Model selection

Sonnet for most tasks — implementation, test writing, docs, triage. Use the current Sonnet model unless the task requires deep reasoning over a large context.

Opus for architecture-level tasks — ADR authorship (maintainer only), cross-cutting refactors, adversarial review of complex PRs. Using a more capable model when a capable model suffices wastes context and delays the cycle.

General-purpose vs specialist agents: prefer the specialist agent for the domain (e.g. a TypeScript-aware agent for SDK surface changes, a docs-aware agent for contributor docs) over a general-purpose agent. Specialist agents load less irrelevant context.

TDD discipline

For any Behavior-Adding Task (see CONTEXT.md):

1. RED — commit a failing test that names the expected behavior before writing the implementation.
2. GREEN — write the minimum implementation that makes the test pass.
3. REFACTOR — polish without changing behavior; tests must still pass.

Commit each phase separately. A PR that has no failing-test commit for a new behavior will be asked to add one before merge.

Adversarial review requirement

Before opening a PR:

• Read each changed section as if you are a hostile reviewer. Does it stand alone? Does it cite existing artefacts accurately? Is anything aspirational that is not actually current practice?
• Mark aspirational items as [proposed] in the text if they describe future intent rather than current behavior.
• Check that every cross-reference (file path, ADR number, CONTEXT.md term) resolves to something that actually exists on disk.

CR-loop discipline

After a reviewer thread is addressed:

• Fix the code or docs in a new commit (never amend a pushed commit).
• Resolve the thread via GraphQL mutation — do not rely on auto-resolve and do not post a reply comment:

gh api graphql -f query='mutation { resolveReviewThread(input:{threadId:"PRRT_..."}) { thread { isResolved } } }'

Address every reviewer finding claim-by-claim. Do not dismiss a thread because one sub-claim is a false positive — read all sub-claims before deciding.

Standards followed — block (proposed)

The maintainer is evaluating whether to require a ## Standards followed block in every issue and PR body. Current proposal:

• Enhancements and features: required. List the ADR(s) and CONTEXT.md section(s) consulted.
• Bug fixes: lighter-weight. A one-line note suffices: "Follows ADR-0002 command contract."

This is marked [proposed] — it is not yet a merge gate. Feedback on workflow impact is welcome in issue #3232.