Skip to content

docs: add agent contributor guide - #163

Open
owainlewis wants to merge 2 commits into
mainfrom
codex/improve-agents-md
Open

docs: add agent contributor guide#163
owainlewis wants to merge 2 commits into
mainfrom
codex/improve-agents-md

Conversation

@owainlewis

@owainlewis owainlewis commented Jul 29, 2026

Copy link
Copy Markdown
Owner

Summary

Add a concise repository-specific contributor guide for coding agents.

The guide focuses on rules that are difficult to infer safely from code:

  • the ownership boundary that keeps Push a small gateway
  • the required Rust quality gate
  • durability, ordering, recovery, and delivery guarantees
  • backend, job, security, testing, and documentation constraints

It deliberately avoids a code map, source file names, and duplicated
implementation explanations. Agents are directed to the contributor and
architecture documentation for discoverable detail.

Why

Push had strong contributor and architecture documentation but no root
AGENTS.md. Important constraints were easy to miss, especially around cursor
ordering, durable delivery, backend session recovery, job replay, and security.

This adds a short, stable layer of project invariants without duplicating the
repository structure or details that will drift as the code changes.

Test plan

  • cargo fmt --all --check
  • cargo clippy --locked --all-targets -- -D warnings
  • cargo build --locked
  • cargo test --locked (367 tests passed)
  • mkdocs build --strict
  • git diff --check
  • Confirmed the guide contains no source, test, config, or documentation paths
  • Fresh independent review approved the simplified guide with no important
    findings

Risks

Low. This is contributor documentation only. The remaining maintenance risk is
that required commands or architecture invariants may change. The guide tells
agents to follow CI and the canonical project documentation for deeper detail.

Related issue

None.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants