---
name: ai-upgrade
description: Upgrade existing automated or manual tests for AI-first validation, including porting legacy suites into editable CARBON AI-intent tests and adding sparse local model-powered screenshot quality checkpoints. Use for Selenium, Playwright, Cypress, pytest, JUnit, Gherkin, Robot, TestRail, Xray, spreadsheet or manual test cases, brittle selectors, slow suites, AI-readiness assessments, migration requests, screenshot review assertions, or converting existing assets into reusable AI testing assets.
---

# CARBON AI Upgrade

Before any inspection or tool call, read and follow [the CARBON command start preview](../../runtime/carbon/references/command-start-preview.md). Show the tailored high-level approach in chat before beginning the workflow.

Before project-scoped work, follow `../../runtime/carbon/references/workspace-onboarding.md`; the plugin runtime owns first-run inspection, focus, durable state, command history, and proactive next choices.

At the start, call `carbon_set_preferences` with no arguments. Read `aiUpgradeOptions` without requesting or exposing the configured model-provider key.

Use the returned global `executionContext` while baking upgraded tests: apply its prompt, read its context documents, and use the configured username. Keep the password out of converted definitions and artifacts; only an approved child runner may receive it through `carbon-runtime context exec -- <runner command>`.

Improve the user's existing test investment instead of discarding it. This workflow assesses and changes local project assets only.

## Offer the AI augmentation routes

Run the deterministic inspection before proposing edits:

```bash
../../bin/carbon-runtime ai-upgrade inspect --root <project>
```

Always keep ordinary deterministic modernization available. If a local model key and exact model are configured, offer quick screenshot reviews at the inspection's high-value checkpoints. If the user already asked to add them, show the selected files, checkpoints, and transmission boundary; obtain project-scoped approval; install the helper; then patch the tests. Otherwise continue the fully local deterministic upgrade and offer `$carbon-settings` to configure screenshot review. Never ask the user to paste a key into chat or source.

A model-provider key does not make the provider local: the test executes locally, but each approved screenshot and short focus prompt are sent to that provider.

For a requested legacy-to-intent port, use the plugin-level contract at `../../runtime/carbon/references/intent-test-contract.md` and the launcher `../../bin/carbon-runtime intent import`. Preserve TestRail/Xray IDs, source path/framework/hash/title, create drafts, and continue the returned full bake through `carbon_manage_import_bake`. Only observed passes activate; failed and blocked cases remain drafts.

## Assess

1. Locate the current tests and configuration with fast file search.
2. Identify frameworks, languages, execution commands, suite size, test data, fixtures, selectors, retries, waits, mocks, and CI integration.
3. Run the smallest safe existing test or lint command when practical to establish a baseline.
4. Report the main constraints: brittleness, redundant coverage, missing assertions, long feedback loops, unclear intent, poor isolation, inaccessible test data, or gaps in positive, negative, boundary, and regression coverage.

## Modernize

When the user asks for implementation, make focused changes that preserve intended behavior:

- replace brittle timing and selectors with observable user behavior;
- make test intent and pass criteria explicit;
- extract reusable setup, data, and page objects only where they reduce duplication;
- add high-value missing negative and edge coverage;
- produce AI-readable failure evidence and focused rerun commands;
- convert procedural legacy cases into durable AI intent while retaining exact selectors, status codes, wire formats, timing, authorization, or destructive constraints when they are genuine contracts;
- execute every converted case through the safest matching local adapter; classify non-passes as test-definition, infrastructure, product, or unknown; repair only the converted test definition up to the bounded limit and rerun it;
- keep deterministic tests and browser exploration inside the local coding-agent workflow.

## Add local AI screenshot quick checks

Read `../../runtime/carbon/references/ai-upgrade-visual-checks.md` before modifying automation. Apply these rules:

1. Prefer an existing screenshot. Otherwise capture only after a stable, decision-relevant visible state: initial page ready, critical error, consequential confirmation, checkout/receipt, dashboard, or a meaningful user-visible assertion.
2. Add normally 1–3 checkpoints per high-value test file, not after every action. Keep deterministic selectors, values, URLs, API state, accessibility assertions, and business oracles authoritative.
3. Avoid login/password, payment, health, private-customer, token, admin-secret, or other sensitive screenshots unless transmission to the selected provider is explicitly authorized.
4. Show the exact files and anchors before mutation. Use `apply_patch` after approval; preserve the suite's conventions and avoid unrelated refactors.
5. Install the provider-neutral helper only after approval:

```bash
../../bin/carbon-runtime ai-upgrade install-helper \
  --root <project> \
  --provider <openai|anthropic|gemini> \
  --model <exact-vision-model> \
  --fail-on critical \
  --on-error warn \
  --confirm
```

6. Add one framework-native adapter that captures a screenshot and invokes `.carbon/upgrade/ai-visual-check.py`; do not duplicate child-process code in every test, and never embed an API key. Run through `../../bin/carbon-runtime context exec -- <approved-test-command>` so a protected configured key reaches only the child runner.
7. Default subjective or uncertain findings to warnings, fail only high-confidence critical visible defects, and treat provider errors as blocked/warnings rather than product passes. Save the JSON result beside the screenshot and attach it to the framework's evidence when supported.
8. Run every touched test plus the smallest relevant suite. Report provider judgment separately from deterministic pass/fail and preserve screenshot-only limitations.

Verify the changed suite after editing. A pass needs observed evidence. Do not claim conversion success from static inspection, do not label runner/auth/environment blockers as product bugs, and do not change product code as an automatic import repair.

## Required HTML result

Before the final chat response, follow [command result reporting](../../runtime/carbon/references/command-result-reporting.md). Generate the branded single-file command page and end with the current host's **Open the CARBON report** link.
