Cao Contributing

Contributing to CAO

How to make a change to the cli-agent-orchestrator codebase and get it through CI cleanly. Read this before pushing a branch or opening a PR. The canonical human docs are DEVELOPMENT.md, CONTRIBUTING.md, and CODEBASE.md — this skill is the operational checklist that mirrors what CI actually enforces.

Golden rules (read these first)

1. Run Python tooling through uv. uv sync --all-extras --dev, uv run pytest …, uv run mypy src/, uv run cao …. There is no bare pip workflow, and the venv CI builds is the one uv manages. Repo scripts are documented in their own text as plain python scripts/<name>.py (for example scripts/sync_skills.py, whose fix-up message and test_skill_packaging_parity.py both quote that form) — run them as uv run python scripts/<name>.py, which satisfies both.
2. Verify the actual CI run after every push — never declare "done" on local tests alone. Poll it: gh pr checks <number> for every workflow on the PR, or gh run list --branch <branch> --workflow CI for ci.yml alone, then gh run view <id> / gh run view <id> --log-failed.
3. When a required check fails unexpectedly, diff EVERYTHING your commit changed — including CI/workflow/config files (.github/workflows/*.yml, pyproject.toml, mypy.ini) — before concluding the cause is pre-existing or external. The signal is often in your own diff (git diff <base>..HEAD -- .github/). A displaced one-line workflow key (see the mypy note below) can turn a tolerated warning into a hard failure.
4. Never mark a task complete while a required CI gate is red. A red gate means not done; investigate, don't rationalize.
5. Match the repo, don't reshape it. Don't bundle unrelated fixes (e.g. repo-wide type errors) into a feature PR, and don't tighten a CI policy as a side effect of an unrelated change.

Local dev loop

uv sync --all-extras --dev          # install (mirrors what CI does)
uv run pytest test/path/to/test_x.py   # run targeted tests while iterating
uv run black src/ test/             # format (CI checks --check)
uv run isort src/ test/             # import order (CI checks --check-only)
uv run mypy src/                    # type check (see the mypy note below)

Write tests RED-first: add a test that reproduces the bug/behavior and fails, then implement until it passes. New features and bug fixes ship with tests.

Keeping patch coverage at 100% for changed lines is a team convention, not a gate. Nothing fails your build over it: the repo has no codecov.yml, so there is no configured status check or target, and the Unit Tests job uploads coverage with fail_ci_if_error: false — even a broken upload is tolerated. Treat the Codecov comment as a review signal to justify, not a red gate to chase.

The CI gate map (.github/workflows/ci.yml)

Know which jobs are blocking vs tolerated so you can tell a real failure from noise. test/test_cao_contributing_skill_accuracy.py fails if this table drifts from ci.yml, so trust it — and if you rename a job, update it here.

CodeQL's four language jobs are part of ci.yml, so Re-run all jobs includes them. The standalone codeql.yml is only for weekly and manual scans; both use the same maintainer-owned scan action. Existing PR branches must pick up the current main workflow before their new CI runs use this wiring. Resolve merge conflicts, update the branch, and approve fork workflows when required rather than merely rerunning a CI run created before the change. An Expected required check without an actual job is not a running scan.

Dependency Security also runs weekly and on manual dispatch through dependency-security.yml, using the same action as CI. A passing local-patch check does not exempt an open HIGH/CRITICAL advisory. See SECURITY.md for inventory artifacts, failure states, and the required-status rollout after the workflow lands.

The -m "not e2e" on the CI command replaces your local addopts — it does not compose with it. So a local run that also deselects integration is a strict subset of CI's selection and can be green while CI is red. Compare deselected counts, not just pass counts.

CI's selection is narrower than the marker alone implies. The same command passes --ignore=test/providers/test_kiro_cli_integration.py and --ignore=test/e2e, and --ignore wins over -m: that Kiro provider test needs an authenticated external CLI and never runs in CI. So most integration-marked tests do run in CI — but not that one, and nothing in CI covers it. If you change it, you have to run it yourself.

mypy is intentionally non-blocking. The repo has known, pre-existing, repo-wide mypy errors (historically in services/agent_scaffold.py, cli/commands/profile.py, services/memory_service.py / api/main.py MemoryArchiveBackend call-arg, and a jsonschema stub). CI tolerates them via continue-on-error: true on the mypy step. Therefore:

• Do not make mypy blocking, and do not bundle those unrelated type-fixes into a feature PR (they belong in a dedicated cleanup PR).
• Your change must add zero new mypy errors — check the delta, not the raw count.
• When you insert a new job/step near the lint job, keep continue-on-error: true attached to the mypy step. A mis-insertion once displaced that line onto the next job's step, silently turning mypy into a hard gate and failing the build for unrelated, pre-existing errors.

Other workflows that gate a PR

ci.yml is not the only workflow on a pull request. These run alongside it, and none sets job-level continue-on-error, so every check they run is blocking. The same accuracy test pins this table to the workflow files.

Two checks can share a name. Each provider workflow has its own Unit Tests and Code Quality, so a PR that touches pyproject.toml shows those names more than once. Read the workflow name next to a failing check before assuming it is the CI one — gh pr checks <number> lists every workflow, whereas gh run list --workflow CI sees only ci.yml.