ci-local-parity

name	ci-local-parity
description	Reproduce ai-repo PR checks locally with Poe and CI scripts, including per-package typecheck and coverage behavior. Use when validating changes before push or when user asks which local commands match CI.
license	MIT
compatibility	claude cursor opencode
metadata	{"version":"1.0.0","languages":"python","audience":"developers","workflow":"automation","since":"2026-05-07"}

What I do

Run ai repository checks locally with the closest possible parity to PR CI:

• Map changed files to affected packages
• Run checks in CI order: format-check → lint → test → typecheck → coverage → depcheck
• Apply per-package behavior (strict vs baseline typecheck, test args, extras)
• Highlight checks that cannot be fully reproduced via Poe

When to use me

• User asks how to run CI checks locally in ai
• User wants the exact local commands before opening/updating a PR
• User asks about Poe tasks vs CI scripts and where they differ

Use instead

• ci-fix — diagnosing an already-failed CI run
• ruff — lint/format-only cleanup without CI parity
• uv — dependency/lockfile maintenance

---

Workflow

Step 0: Preconditions

Run from the repo root. Verify tooling:

uv --version
uv run poe --help

If uv is missing, stop and ask the user to install it.

---

Step 1: Determine target packages

git fetch origin main
git diff --name-only origin/main...HEAD

Map changed files to packages using the dir field in: .github/actions/get-packages-matrix/package_configuration.json

→ See references/package-matrix.md for the full package list.

---

Step 2: Run baseline checks (CI order)

From inside each package directory:

uv run ruff format --check .   # CI lint = format check + lint check
uv run poe lint
uv run poe test
uv run poe depcheck

poe format writes files — it is not equivalent to the CI lint step.

---

Step 3: Typecheck (strict vs baseline)

Determine mode from package_configuration.json flags:

• Strict (typecheck_use_baseline: false, typecheck_require_zero_errors: true):

  uv run poe typecheck
  

• Baseline (new errors vs origin/main only):

  uv run poe ci-typecheck
  # fallback if task missing:
  bash "$(git rev-parse --show-toplevel)/.github/scripts/dev.sh" typecheck --dir .
  

→ See references/package-matrix.md for per-package mode.

---

Step 4: Coverage (diff-based)

uv run poe ci-coverage
# fallback if task missing:
bash "$(git rev-parse --show-toplevel)/.github/scripts/dev.sh" coverage --dir .

Full-package (non-diff) coverage:

uv run poe coverage

---

Step 5: Call out CI gaps

Some jobs are not reproducible via Poe. Note them explicitly; do not claim full parity.

→ See references/ci-gaps.md for the full list (min-deps, config-check, PR policy).

---

Quick recipes

Any package — closest PR-CI parity

cd <package_dir>
uv run ruff format --check .
uv run poe lint
uv run poe test
uv run poe depcheck
uv run poe ci-typecheck || bash "$(git rev-parse --show-toplevel)/.github/scripts/dev.sh" typecheck --dir .
uv run poe ci-coverage  || bash "$(git rev-parse --show-toplevel)/.github/scripts/dev.sh" coverage  --dir .

Strict packages: unique_toolkit, unique_sdk, unique_skill_tool

cd <package_dir>
uv run ruff format --check .
uv run poe lint
uv run poe test        # sdk: add -- -m "not integration"
uv run poe depcheck
uv run poe typecheck
uv run poe ci-coverage || bash "$(git rev-parse --show-toplevel)/.github/scripts/dev.sh" coverage --dir .

---

Tips

1. Always include ruff format --check — CI lint is two commands, not one.
2. Check the matrix flags; don't assume strict or baseline mode.
3. Prefer ci-* Poe tasks for diff parity; fall back to dev.sh when absent.
4. Never claim full parity — deps/config/policy jobs require manual steps.
5. Run from the repo root so script paths and git base refs resolve correctly.