/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", or when making any code change intended to land on a
  branch/PR. Covers uv-based build/test/lint, 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`](../../DEVELOPMENT.md), [`CONTRIBUTING.md`](../../CONTRIBUTING.md), and [`CODEBASE.md`](../../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.

| Job | Runs | Blocking? | |-----|------|-----------| | **Unit Tests** (3.10 / 3.11 / 3.12) | `uv run pytest test/ examples/workflow/tests/ --ignore=test/providers/test_kiro_cli_integration.py --ignore=test/e2e -m "not e2e" --cov=src/cli_agent_orchestrator --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`, then `uv run mypy src/` | black/isort **yes**; **mypy is non-blocking** (`continue-on-error: true`) | | **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** | | **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 (Playwright)** | browser E2E over the `ui://cao/*` views | **Yes** | | **Rust TUI** (Linux x86_64 / macOS arm64) | `cargo test` for the `tui/` crate | **Yes** | | **Web UI Build** | frontend build | **Yes** | | **AI-DLC Portfolio Example** | example project builds | **Yes** | | **Security Scan** | Trivy | **Yes** | | **Dependency Review** | `actions/dependency-review-action` over the PR's dependency delta: `fail-on-severity: high` plus denied licences `GPL-3.0`/`AGPL-3.0` | **Yes** — CI-only; there is nothing to run locally, and it is skipped on forks (`if: github.repository == 'awslabs/cli-agent-orchestrator'`), so a green run on your fork has not exercised it |

> **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 selectio