Skip to content

docs: Read the shared contribution policy #177

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
BenWestgate wants to merge 2 commits into from
Open

docs: Read the shared contribution policy #177

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
68083be
docs: Read the shared contribution policy
BenWestgate Oct 14, 2026
4acc2d2
docs: Preserve project-specific agent checks
BenWestgate Oct 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 26 additions & 34 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,27 +28,22 @@ contains offline verification utilities.

## Development and verification

Use the existing virtual environment when available. Python 3.10 is the minimum;
the supported range is Python 3.10 through 3.15. Install development
dependencies only when needed:
`python -m pip install -e '.[dev]'`. Run the CLI with `codex32 --help`.

Choose checks according to the changed behavior:

- Runtime changes: run affected pytest tests, Ruff lint and formatting checks,
and `python -m mypy src/codex32` when types or source code change.
- Changes spanning modules or security boundaries: run `python -m pytest -q`
and `python -O -m pytest -q`; use the relevant differential tools for changes
to correction or wallet derivation.
- Packaging or release changes: run `python -m build` and
`python -m twine check dist/*` in addition to affected checks.
- Documentation or agent-configuration changes: inspect the diff, check links
and configuration syntax as applicable; do not run application tests solely
for prose or instruction edits.

Use `python -m ruff check .` and `python -m ruff format --check .` for Python
style checks. Once applicable checks pass, repeat or broaden them only for a new
change, failure, or unresolved concern. Report checks that could not run and
Read `CONTRIBUTING.md` for the contribution workflow. Use Python 3.10–3.15
and an existing virtual environment where available; otherwise install
development dependencies with `python -m pip install -e '.[dev]'`.
Pick checks by what changed:

- Runtime changes: affected pytest tests, `python -m ruff check .`,
`python -m ruff format --check .`, and `python -m mypy src/codex32`
when changing types or source.
- Changes spanning modules or security boundaries: the full suite, also under
`python -O`, plus the differential tools for correction or wallet derivation.
- Packaging or release changes: the build and `twine check` steps as well.
- Documentation or agent-configuration changes: inspect the diff and check links
and syntax; do not run application tests for prose edits alone.

Once applicable checks pass, repeat or broaden them only for a new change,
failure, or unresolved concern. Report checks that could not run and
pre-existing failures accurately; do not claim unverified success.

## Reviewability and style
Expand All @@ -61,10 +56,10 @@ avoid comments or tests that restate the implementation. Add or update concise
docstrings when changing public behavior. Write codex32 in lowercase except
when referring to the Codex32 Book.

Keep the installed package below 5,200 logical review lines, as enforced by the
existing test. New dependencies, public API signature or return-shape changes,
and lint suppressions require user authorization; an explicit request can
already provide that authorization.
Keep the installed package below 5,200 logical review lines, enforced by
`test_production_size_budgets_are_enforced`. New dependencies, public API
signature or return-shape changes, and lint suppressions require user
authorization; an explicit request can already provide that authorization.

Use pytest and Hypothesis for meaningful behavioral coverage. Preserve external
vectors, negative cases, and regressions for changed behavior. Prefer one clear
Expand All @@ -86,18 +81,15 @@ Resolve scope questions from the changed code and the invariants first. Ask only
if a material security decision remains unclear; identify the decision rather
than stopping on general uncertainty. Ask before running a recommended security review.

Before acting on a pull request, read `CONTRIBUTING.md` and
`docs/developer/AI_POLICY.md` from its current target branch. Follow that merged
contribution policy when the topic branch contains an older version. AI may
write PR descriptions and review replies under the tool-neutral policy.
Before committing, opening a pull request, or writing an issue, pull request,
or review comment, read `CONTRIBUTING.md` and `docs/developer/AI_POLICY.md`
from the pull request's current target branch; they decide authorship, commit
messages, and who publishes. Follow that merged policy when the topic branch
contains an older version. AI may write PR descriptions and review replies under
the tool-neutral policy.

Follow `SECURITY.md` for private vulnerability reporting. Local edits, checks,
and atomic commits are allowed. Publish only within the user's authorized scope;
permission to use AI does not itself authorize contacting others. Never claim
independent human authorship, commit to master, or push to an open pull request
branch without explicit user direction.

When asked to commit, keep commits focused and independently passing unless the
user explicitly requests a combined commit. Use an imperative subject of at
most 50 characters, followed by rationale, security implications when relevant,
and validation. Use `refs #123` or `fixes #123` when applicable.
Loading