Contributing workflow

Use the same Poetry-based commands locally that CI runs on pull requests. The goal is to keep the repository readable after the collapsed-file cleanup and to catch formatting, lint, test, docs, and eval regressions before review.

Set up development dependencies

poetry install --with dev,docs

Formatting and linting

Ruff is the Python formatter and linter for OTerminus. Do not add Black or another overlapping tool for normal Python formatting or lint enforcement.

Format Python code before opening a PR:

poetry run ruff format .

Verify formatting without changing files:

poetry run ruff format --check .

Run lint checks across the repository:

poetry run ruff check .

Keep non-Python source readable too:

• Markdown should use normal headings, blank lines, lists, and valid fenced code blocks.
• YAML and TOML should stay expanded and reviewable, not collapsed into one-line files.
• Avoid mixing large formatting-only rewrites with feature or behavior changes; split them into a separate PR when practical.

Tests and evals

Run the unit test suite locally:

poetry run pytest

CI reports package coverage with:

poetry run pytest --cov=src/oterminus --cov-report=term-missing

Run deterministic eval fixtures when planner, router, validator, structured rendering, policy, or command-family behavior changes:

poetry run oterminus-evals

These local test and eval commands should not require an Ollama service.

Documentation rules

Update /docs in the same PR when you change behavior, architecture, command support, configuration, policy, validation, evals, or user-facing behavior. Documentation is part of the change, not follow-up work.

Keep documentation organized this way:

• Keep README.md as the landing page and quick orientation.
• Put detailed product, architecture, reference, eval, and contributor material under /docs.
• Update MkDocs navigation when adding, moving, or deleting docs pages.
• Do not include secrets, real tokens, real audit logs, or personal local paths in docs or fixtures.

Validate docs before review:

poetry run mkdocs build --strict
poetry run python scripts/check_docs_links.py

The docs workflow runs the strict build on pull requests and pushes to main, but deploys only after a push to main.

Pre-PR quality commands

Run the checks that match your change before opening a PR:

poetry run ruff format .
poetry run ruff format --check .
poetry run ruff check .
poetry run pytest --cov=src/oterminus --cov-report=term-missing
poetry run python scripts/check_docs_links.py
poetry run mkdocs build --strict
poetry run oterminus-evals

Pull request template and checklist

Every pull request should use .github/pull_request_template.md and keep every checklist item in place. If an item is not applicable, mark it as N/A in the PR description instead of deleting it.

In addition to formatting, lint, test, docs, and eval checks, the PR template requires explicit confirmation that core architecture invariants still hold for behavior-affecting changes (for example capability-first command support, structured-first behavior, ambiguity gates, validator and policy separation, and local-only audit logging expectations).

When command registry/spec files change, refresh generated command reference docs in the same PR. When behavior, architecture, command support, config, evals, policy, validation, or user-facing behavior changes, docs updates are mandatory in the same PR (not follow-up work).