---
name: carbon-generate
description: Generate prioritized CARBON test candidates from live pages, source code, requirements, screenshots, recordings, APIs, discovered widgets and controls, CARBON's built-in flow library, and user-defined or learned custom flows. Use when the user asks to generate tests, test cases, or coverage for all widgets, controls, journeys, workflows, custom flows, a whole app, a change, or a named product surface without claiming execution.
---

# CARBON Generate

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. Apply its global `executionContext` to generation: honor the reusable prompt and read each configured context document before deriving candidates. Use credential metadata only to identify required setup; never put a password in a generated test.

Generate durable planned tests from the actual product surface. Do not return a
generic checklist or report a generated candidate as passed.

## Choose the Coverage Scope

Infer the smallest useful scope from the request:

- **Focused** — one named or changed control, feature, route, API, or flow.
- **Standard** — the default. Cover every discovered control in scope, primary
  and adjacent standard flows, code-derived contracts, and relevant recorded or
  learned custom flows.
- **Exhaustive** — cover every discovered widget, every matching built-in flow,
  cross-cutting quality families, and every custom or learned flow. Estimate the
  likely case count and plan size before generating when the result will be
  large.

Examples:

```text
/carbon_generate current app
/carbon_generate exhaustive checkout, account, and custom approval flows
$carbon-generate all widgets and learned flows
```

## Inventory the Real Surface

1. Read repository instructions and inspect the requested URLs, source routes,
   components, schemas, APIs, requirements, screenshots, existing tests, and
   recordings that are available in the coding-agent context.
2. Identify semantic widgets and controls, not just CSS appearance: inputs,
   selects, buttons, dialogs, tables, trees, media, editors, uploaders,
   authentication controls, commerce controls, and custom composite widgets.
3. Extract code-derived contracts such as accepted types, required fields,
   regexes, min/max values, roles, permissions, state branches, timeouts,
   retries, and side effects.
4. Identify end-to-end journeys and their initial, intermediate, terminal,
   failure, cancellation, and recovery states.
5. Find custom-flow evidence in user descriptions, route/state-machine code,
   saved recordings, `.carbon/recordings/`, `.carbon/learning/**/learned-tests.json`,
   `.carbon/tests/intent-tests.json`, or a supplied flow specification. Include reviewed `active` intent tests; keep drafts visible as excluded review work and ignore archived tests.

State what was observed, inferred, supplied by the user, or still unknown.

## Select CARBON Knowledge Progressively

Resolve the CARBON plugin root two directories above this skill. Use the
plugin-level runtime selectors through `../../bin/carbon-runtime`:

```bash
../../bin/carbon-runtime select-items --json <widget-and-control-terms>
../../bin/carbon-runtime select-flows --json <journey-and-flow-terms>
```

Read only the matched item and flow references plus:

- `../../runtime/carbon/references/execution/plan-contract.md`
- the directly relevant shared oracle and boundary references
- `../../runtime/carbon/references/flow-spec-template.json` when defining a
  custom flow

Do not load the entire 137-item or 42-flow library into context.

For a custom journey that the standard library does not represent:

1. Derive a flow specification from available product evidence using the flow
   template. Mark inferred states and oracles as candidates.
2. If the user asked CARBON to learn or discover reachable behavior, use the
   bounded Learn mode from `$carbon`.
3. When a learning session exists, generate its custom flow pack with:

```bash
../../bin/carbon-runtime learn generate-flow \
  --session-dir <state-root>/.carbon/learning/<session-id> \
  --spec <flow-spec.json>
```

Do not invent unreachable transitions or silently turn uncertain behavior into
an expected result.

## Generate the Tests

Adapt and deduplicate relevant CARBON cases for each discovered item. Cover, as
applicable:

- happy path, invalid, null, missing, wrong-type, min/max, just-inside,
  just-outside, and power-of-two boundaries
- Unicode, RTL, combining marks, emoji, markup-like text, transport encoding,
  localization, and accessibility
- authentication, authorization, roles, tenant boundaries, security, privacy,
  and sensitive-data handling
- loading, stale state, concurrency, retries, idempotency, recovery,
  performance, resource limits, and failure visibility
- destructive, payment, upload, download, external-message, or other side
  effects as planned-only checks unless separately approved for execution

For each standard or custom flow, include the relevant happy, alternate,
failure, cancellation, back-navigation, refresh, multi-tab, stale-state,
permission, retry, recovery, cleanup, and side-effect checks.

Add cross-widget and cross-flow interaction tests only where risk, shared state,
or a product contract justifies them. Avoid multiplying every input by every
flow without a decision-relevant reason.

## Build a Durable CARBON Plan

Conform to
`../../runtime/carbon/references/execution/plan-contract.md`. Every test needs a
stable ID, title, P0-P3 priority, type, flow, item, reason, provenance,
prerequisites, data, steps, oracle, estimate, dependencies, parallel group,
adapter, safety flags, and `status: "planned"`.

Keep the product oracle separate from any prediction about the current build:

- `oracle` states the desired behavior grounded in a requirement, user promise,
  standard, invariant, or explicitly labeled candidate expectation;
- `oracleBasis` names that authority;
- `predictedOutcome` is `pass`, `fail`, or `unknown` before execution;
- `predictionBasis` cites the source branch, configuration, prior result, or
  other evidence behind that prediction.

When source inspection suggests the product violates a valid oracle, retain the
oracle and set `predictedOutcome: "fail"`. Describe the case as deliberately
bug-revealing. A later failure confirms the suspected product defect; it does
not mean the test was accidentally written backward. Never weaken the oracle
to mirror the implementation.

Provenance must point to the discovered widget, built-in flow, custom flow,
recording, learned candidate, code location, requirement, or CARBON reference
that justified the test. Preserve `learningStatus: "candidate"` for learned or
inferred custom-flow tests. Merge existing candidates without duplicating their
stable IDs.

Write the generated source plan under:

```text
<state-root>/.carbon/generated/<scope-slug>/plan.json
```

Then initialize a durable run shell without executing tests:

```bash
../../bin/carbon-runtime run init \
  --root <state-root> \
  --plan <state-root>/.carbon/generated/<scope-slug>/plan.json \
  --mode medium \
  --target <target>
```

`run init` never executes tests. `medium` records the intended default breadth;
use `quick` or `large` when the user selected that run size. The run shell
provides the normalized `plan.json`, `run.json`, `events.jsonl`,
and `report.html` under `.carbon/runs/<run-id>/`. Do not start browser, API, or
external execution unless the user separately asked for it.

## Preserve the Evidence Boundary

- Every generated test is a **planned candidate** until runtime evidence
  supports its oracle.
- Never report a test as passed from source inspection, a requirement,
  screenshot, recording, or generated steps alone.
- Never perform destructive, payment, account, production, external-message,
  or external actions during generation.
- Label unverified custom-flow transitions and inferred oracles explicitly.
- Keep exclusions, unreachable surfaces, missing credentials, and residual
  uncertainty visible.

## Return

Report:

1. the selected coverage scope and inspected inputs;
2. discovered widgets, standard flows, and custom or learned flows;
3. matched CARBON item and flow references;
4. generated candidate counts by widget, flow, custom flow, priority, and
   coverage family;
5. deduplicated interactions, exclusions, blocked surfaces, and oracle gaps;
6. clickable paths to the generated source plan and durable CARBON report;
7. the explicit notice that the tests are planned candidates, not results; and
8. the next command to review, edit, or execute the plan.

## 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.
