/cao-contributing

name: cao-contributing
description: Contribute changes to the CAO (CLI Agent Orchestrator) codebase — the local
  dev loop, the CI gate map, and the pre-PR checklist. Use when the user says "open a PR",
  "why did CI fail", "run the checks before I push", "the mypy/Code Quality job is red",
  "add a test and verify coverage", "bump a dependency", "the uv.lock diff is noisy",
  "a CVE blocks the dependency gate", or when making any code change intended to land on a
  branch/PR. Covers uv-based build/test/lint, lockfile and CVE-floor rules, the ci.yml jobs
  and their pass/fail semantics, and the golden rules that stop a green-locally / red-in-CI
  surprise. Not for authoring agent skills, building providers/plugins/MCP-apps, or
  operating running sessions.

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`](https://github.com/awslabs/cli-agent-orchestrator/blob/main/DEVELOPMENT.md), [`CONTRIBUTING.md`](https://github.com/awslabs/cli-agent-orchestrator/blob/main/CONTRIBUTING.md), and [`CODEBASE.md`](https://github.com/awslabs/cli-agent-orchestrator/blob/main/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 --locked --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 can turn a tolerated warning into a hard failure, or the reverse. 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 --locked --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 ruff check src/ test/ examples/   # dead code -- BLOCKING, and green on main
uv run python scripts/mypy_ratchet.py  # type check -- the gate CI runs (see note below)
uv run mypy src/                    # the raw mypy output, if you want to read it

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.

| Job | Runs | Blocking? | |-----|------|-----------| | **Unit Tests** (3.11 / 3.12) | `uv run pytest test/ examples/workflow/tests/ examples/skills/tests/ --ignore=test/providers/test_kiro_cli_integration.py --ignore=test/e2e -m "not e2e" --cov=src/cli_agent_orchestrator --cov-branch --cov-fail-under=80 --cov-report=term-missing` | **Yes** | | ↳ step: **Validate Markdown links** | `uv run python scripts/validate_markdown_links.py` — every relative link in every tracked `.md`, including `skills/` | **Yes** | | **Code Quality** | black `--check`, isort `--check-only`, `uv run ruff check src/ test/ examples/`, then `uv run python scripts/mypy_ratchet.py` | **Yes** (all four; the mypy step's `continue-on-error` was removed in issue #1005) | | **AG-UI demo (shift-left recording)** | boots a `CAO_AGUI_ENABLED` server, drives the viewer, records a GIF artifact | **Yes** | | **AG-UI construct demos (shift-left recordings)** | same pattern for the L2 construct library | **Yes** | | **AG-UI stock-client live (AC3)** | drives a real third-party AG-UI client against the surface | **Yes** | | **AG-UI operator dashboard** | `examples/ag-ui/ag-ui-operator-dashboard`: installs tmux, then `npm ci`, `test:dependencies`, `tsc`, vitest with a 100% coverage floor on `core/`, `vite build`, and a keyless e2e against a private cao-server with `mock_cli` terminals | **Yes** | | **Agent Plugins dog-food (shift-left recording)** | records the plugin pipeline from `examples/agent-plugins/agent-plugins-dogfood/tools` and gates on drift | **Yes** | | **CAO MCP Apps** | MCP Apps build + backend coverage ratchet floor | **Yes** | | **CAO MCP Apps E2E (Playwri