@thinkingai/ae-cli 6.1.9 → 6.1.11

package/skills/ae-engage/references/scene-strategy.md

@@ -24,9 +24,9 @@ ae-cli engage-scene strategy update --project-id <project_id> \
 # Query a strategy's log
 ae-cli engage-scene strategy log --project-id <project_id> --strategy-uuid <uuid>
 
-# Predict custom-audience size (mix QP)
+# Predict custom-audience size
 ae-cli engage-scene strategy predict --project-id <project_id> \
-  --qp '<targetClusterQp JSON string>' \
+  --definition-request '{"type":"condition","conditions":{...}}' \
   --zone-offset 8 \
   [--strategy-uuid <uuid>]
 
@@ -48,7 +48,7 @@ ae-cli engage-scene strategy manage --project-id <project_id> --config-id <confi
 | create | `--project-id`, `--payload` | payload = `ConfigStrategyAddDTO`. |
 | update | `--project-id`, `--payload` | payload = `ConfigStrategyModifyDTO` (`strategyUuid` + fields). |
 | log | `--project-id`, `--strategy-uuid` | read. |
-| predict | `--project-id`, `--qp`, `--zone-offset` | Optional `--strategy-uuid`, `--request-id`. read. |
+| predict | `--project-id`, `--definition-request`, `--zone-offset` | Optional `--strategy-uuid`, `--request-id`. read. |
 | batch-copy | `--project-id`, `--config-id`, `--strategy-ids` | `--op-mode` optional (default `batch`). |
 | manage | `--project-id`, `--config-id`, `--action` | Lifecycle actions require `--strategy-uuid-list`; review actions require `--strategy-list`; write. |
 
@@ -67,10 +67,10 @@ ae-cli engage-scene strategy manage --project-id <project_id> --config-id <confi
 - Discover real strategy UUIDs / config IDs first; never invent IDs.
 - **Custom audience (`targetClusterType=1`)** — follow [`scene-strategy-audience.md`](scene-strategy-audience.md) end-to-end:
   1. Preflight every **用户满足** user property and **用户行为** event via `analysis-meta property get` / `event get`; if missing, **stop** and list available properties — never invent or drop.
-  2. Assemble mix QP with **two-block layout**: `totalCFilter.filts[0]` = 用户满足, `totalCFilter.filts[1]` = 用户行为; `totalCFilter.relation` = 且/或 between them. **Never** nest `event` inside user-side `COMPOUND`.
-  3. `JSON.stringify` → `targetClusterQp`; then `strategy create|update`.
+  2. Build an Analysis-compatible semantic condition in `payload.definitionRequest`.
+  3. Reuse the same definition with `strategy predict --definition-request`.
   4. **Do not** call `analysis user-cluster create` unless the user explicitly asks for an existing/named cluster.
-  - Full QP spec + examples A/B/C: [`scene-strategy-audience.md`](scene-strategy-audience.md).
+  - Semantic contract and examples: [`scene-strategy-audience.md`](scene-strategy-audience.md).
 - **`create` requires an enabled template** on the same config item. Enable workflow: `config-param batch-add` → `template create` → `template update` (non-empty `config[]` with real `paramId`) → `template update-status --status 1`. Otherwise `create` returns `TEMPLATE_ENABLE`.
 - `create` output field is `data.strategy_uuid` (not `strategy_id`).
 - `manage` supports `online`, `offline`, `suspend`, `delete`, `approve`, `deny`, and `cancel`; it is a write operation.

package/skills/ae-engage/references/task-detail.md

@@ -5,6 +5,16 @@ Query the details of a single task.
 
 Mapped command: `ae-cli engage-task task get`
 
+For a custom target audience, the response hides persisted `qp` and returns:
+
+- `definition_status`: `AVAILABLE`, `UNAVAILABLE`, or `NOT_APPLICABLE`
+- `definition_request`: the Analysis-compatible semantic audience definition when available
+- `definition_unavailable_reason`: present only when a historical QP cannot be reversed
+
+Reuse `definition_request` as `req.targetConfig.definitionRequest` when updating a task.
+Soft-deleted tasks are treated as unavailable and return `TASK_NOT_FOUND`, matching task-list
+visibility.
+
 ## Flags
 
 | Flag | Type | Required | Description |

package/skills/ae-engage/references/task-submit-approval.md

@@ -0,0 +1,45 @@
+# engage-task task submit-approval
+
+Submit an existing draft engagement task for approval. The legacy full save-and-submit request remains supported.
+This is a regular write operation.
+
+> Capability id: `engage-task.task.submit-approval` · Domain: `engage`.
+
+```bash
+ae-cli engage-task task submit-approval --project-id <project_id> --task-id <task_id>
+```
+
+## Parameters
+
+| Flag | Required | Notes |
+|---|---|---|
+| `--project-id` / `-p` | yes | Numeric project ID. |
+| `--task-id` | conditional | Existing draft task ID. Recommended after `task save`. |
+| `--request` | conditional | Legacy `ApprovalSaveAndSubmitDTO` / `OperationTaskOpDTO` JSON (camelCase or snake_case). |
+
+Provide exactly one of `--task-id` or `--request`.
+
+## Output
+
+- `data.task_id`
+
+## Request notes
+
+- Prefer `task save` followed by `submit-approval --task-id`. The server loads the persisted draft, validates its
+  trigger rule, and reuses the existing save-and-submit approval workflow.
+- Do not reconstruct or pass `trigger_rule`. It is an internal persisted field.
+- The legacy `--request` mode remains available for existing callers.
+- Required body fields (server validates): `task_name`, `channel_type`, `channel_id`, `group_content_list`, `target_cluster_type`, `trigger_type`, `completion_indicator_def`, `frequency_limits`, `enable_channel_touch_limits`, `group_id`, `trigger_time_strategy`.
+- Missing `expConfig` is auto-filled as `{"enableExp":false}` (same as activity task create/update).
+- TEXT channel params missing `config` are auto-filled with Slate.js JSON from `value`.
+- For schedule-single (`triggerType=0`), include a future `triggerTime` (and `tzOffset` / `triggerTimeStrategy` as needed).
+- Prefer save → submit by task ID; do not invent `taskId` / `channelId`.
+
+## Common Errors
+
+| code | when |
+|---|---|
+| `APPROVAL_INPUT_INVALID` | neither or both of `task_id` and `request` supplied |
+| `REQUEST_REQUIRED` | `--request` missing or not an object |
+| `REQUEST_FIELDS_REQUIRED` | required body fields absent/blank |
+| `CAPABILITY_EXECUTION_FAILED` | unmapped domain failure; check `invocation_id` / Hermes logs |

package/skills/ae-engage/references/validate-flow-node-config.md

@@ -30,7 +30,7 @@ Use `--operation-mode save_flow` for the current exposed MCP protocol. Use `save
 Important current rules:
 
 - `event_trigger` / `event_judge` A segment: use `periodStart`, `periodEnd`, `periodTimeSymbol`; do not use branch-style `delayTime`.
-- `event_split_flow` branch segment: use `delayTime`, `delayTimeSymbol`, `targetClusterType`; omit `triggerRule` on default branches.
+- `event_split_flow` branch segment: use `delayTime`, `delayTimeSymbol`, `targetClusterType`; omit `triggerDefinition` on default branches.
 - `event_trigger targetUserType=2` is invalid.
 - Push `OBJ_ARRAY.value` must be a JSON array, not a stringified array.
 - Push `contentList[].content` should be a JSON array, but a JSON-stringified array is accepted for compatibility.

package/skills/ae-experiment/SKILL.md

@@ -22,8 +22,17 @@ Naming and response boundary:
 - CLI command segments and flags use kebab-case.
 - Outer Capability input and all response keys use snake_case.
 - Nested business DTOs passed through `--req` keep their native camelCase fields.
+- Audience QP is semantic at the CLI boundary: write `targeting.definitionRequest`; read
+  `targeting.definition_request`. Never generate or submit `targetConfig`.
+- Metric QP is semantic at the CLI boundary: write `metricDefinition`; read
+  `metric_definition`. Never generate or submit `metricConfig`, `calcType`, or `Axxx` codes.
+- For metric aggregations `sum` / `avg` / `max` / `distinct_count`, `metricDefinition.property`
+  is **required** and must be a concrete available event property from Analysis metadata.
+  Never create property aggregations without `property` (for example `metric_avg_no_property_*`).
+- Event-count aggregations `total_count` / `user_count` / `active_days` omit `property`.
+- Resolve event and property names with Analysis metadata before saving semantic definitions.
 - Lists return `data.items` and `data.total`; detail commands return `data.item`.
-- Readiness returns `data.readiness`; reports return `data.report`; writes return `data.result`.
+- Readiness returns `data.readiness`; reports return `data.report`; save guides return `data.guide`; save dry-run validation returns `data.validation`; writes return `data.result`.
 - Query cancellation returns `data.success`.
 
 ## Typical Workflow
@@ -34,6 +43,8 @@ Naming and response boundary:
    - `experiment feature list`
    - `experiment metric list`
 2. Create missing assets if needed:
+   - `experiment save build-guide --operation-mode save_metric` when save validation fails or req shape is unclear
+   - `experiment save validate --operation-mode save_metric --req '{...}'` before retrying a failed save
    - `experiment traffic-layer save`
    - `experiment feature save`
    - `experiment metric save`
@@ -45,9 +56,12 @@ Naming and response boundary:
 
 ## Parameter Conventions
 
+- Experiment save payloads distinguish two allocation fields: experiment-level `req.allocation` (**integer only; no decimals**) and group-level `req.groups[].allocation` (**integer only; sum must equal `100` exactly**).
+
 ```bash
 ae-cli experiment experiment get --project-id 1 --exp-id exp_123
 ae-cli experiment experiment save --project-id 1 --req '{"expName":"Demo"}' --dry-run
+ae-cli experiment metric save --project-id 1 --req '{"metricId":"login_users","metricName":"Login users","createType":"event","goalDirection":"up","metricDesc":"Users who logged in","metricDefinition":{"type":"event","event":"login","aggregation":"user_count"}}' --dry-run
 ae-cli capability run experiment.report.metric-trend --input '{"project_id":1,"exp_id":"exp_123","metric_id":"metric_1","start_time":"2026-07-01","end_time":"2026-07-07"}'
 ```
 
@@ -57,6 +71,12 @@ Optional global parameters work as in other domains: `--host`, `--mcp-url`, `--f
 
 Open the matching file in `references/` before using a command, especially for write operations and JSON payloads.
 
+### Save Helpers
+
+`experiment save build-guide`, `experiment save validate`
+
+When a save command returns `next_tool: experiment.save.build-guide`, call the guide first, then `experiment save validate`, then retry the final save capability.
+
 ### Experiment
 
 `experiment experiment save`, `capability run experiment.experiment.save-submit`, `experiment experiment list`, `experiment experiment list-archived`, `experiment experiment get`, `experiment experiment ready-check`, `experiment experiment conflict-check`, `experiment experiment manage`, `experiment experiment update-group`, `experiment experiment batch-delete`, `experiment operation-log query`

package/skills/ae-experiment/references/check_experiment_ready.md

@@ -12,4 +12,6 @@ Flags:
 
 Use this before `experiment experiment manage` moves an experiment to `pending`, `testing`, or `running`.
 
+Common `groups` failure: `atlas.service.error.experiment.group.allocation.invalid`. Rule: each `groups[].allocation` must be an **integer**, and **sum = 100 exactly** (for example `34 + 33 + 33 = 100`).
+
 Response shape: the readiness result is in `data.readiness`, with recursively snake_case keys.

package/skills/ae-experiment/references/query_experiment_detail.md

@@ -11,3 +11,9 @@ Flags:
 - `--exp-id`: Experiment ID.
 
 Response shape: the experiment is in `data.item`, with recursively snake_case keys such as `exp_id` and `feature_key_list`.
+
+When targeting contains reversible QP, it is returned as
+`targeting.definition_request` with `targeting.definition_status=AVAILABLE`.
+An absent definition is `NOT_APPLICABLE`; a historical unsupported definition is
+`UNAVAILABLE` with `definition_unavailable_reason`. The internal `target_config`
+field is never returned.

package/skills/ae-experiment/references/query_experiment_list.md

@@ -16,3 +16,7 @@ Flags:
 - `--query-name`: Optional fuzzy match against experiment name (`exp_name LIKE`). Does not match `exp_id`.
 
 Response shape: `data.items` contains the experiments, `data.total` contains the count, and item keys are recursively snake_case.
+
+Targeting follows the same semantic projection as detail:
+`targeting.definition_request` plus `targeting.definition_status`; internal
+`target_config` is not returned.

package/skills/ae-experiment/references/query_experiment_list_archived.md

@@ -13,3 +13,6 @@ Flags:
 - `--project-id`, `-p`: Project ID.
 
 Response shape: `data.items` contains the archived experiments, `data.total` contains the count, and item keys are recursively snake_case.
+
+Targeting is returned through `targeting.definition_request` and
+`targeting.definition_status`; internal `target_config` is not returned.

package/skills/ae-experiment/references/query_metric_detail.md

@@ -11,3 +11,8 @@ Flags:
 - `--metric-id`: Metric ID.
 
 Response shape: the metric is in `data.item`, with recursively snake_case keys.
+
+Reversible QP is returned as `metric_definition` with
+`metric_definition_status=AVAILABLE`. Missing QP is `NOT_APPLICABLE`; unsupported
+historical QP is `UNAVAILABLE` with `metric_definition_unavailable_reason`.
+Internal `metric_config` and `calc_type` are never returned.

package/skills/ae-experiment/references/query_metric_list.md

@@ -10,3 +10,6 @@ Flags:
 - `--project-id`, `-p`: Project ID.
 
 Response shape: `data.items` contains metrics, `data.total` contains the count, and item keys are recursively snake_case.
+
+Each item uses `metric_definition` and `metric_definition_status`. Internal
+`metric_config` and `calc_type` are never returned.

package/skills/ae-experiment/references/save_experiment.md

@@ -26,10 +26,14 @@ Nested payload fields must match the server DTO types, not just the visible CLI
 | Field | Correct shape | Incorrect shape |
 | --- | --- | --- |
 | `featureKeyList` | `["payment_color"]` | `[{"featureKey":"payment_color"}]` |
+| `allocation` | integer (e.g. `20`) | `20.5`, `33.33` |
+| `groups[].allocation` | integer; all groups sum to `100` (e.g. `34+33+33`) | `33.33`, or sum `99`/`101` |
 | `groups[].expGroupValue` | `"[\"green\"]"` | `["green"]` |
 | `metrics` | `[{"metricId":"payment","metricRole":"primary"}]` | `["payment"]` |
 
 - `featureKeyList` is an array of Feature key strings, not Feature objects. For feature experiments, pass one Feature key string.
+- `allocation` (experiment-level) and `groups[].allocation` are validated at the CLI interface: **integers only, decimals rejected** (for example `33.33` fails before save).
+- `groups[].allocation` rule: each value must be an **integer**, and the **sum of all group allocations must equal `100` exactly** (for example `34 + 33 + 33 = 100`, not `33 + 33 + 33 = 99` and not decimal thirds).
 - `groups[].expGroupValue` is a JSON-encoded string of a string array. Pass a string whose content is a JSON array, not a native JSON array.
 - `metrics` is an array of metric binding objects. Each object contains `metricId` and `metricRole`.
 
@@ -88,12 +92,44 @@ ae-cli experiment experiment save --project-id 1 --req '{"expId":"exp_123","allo
 
 - `isExpSharing=1` uses a shared traffic layer from `experiment traffic-layer list`; pick a `trafficLayerId` whose available idle traffic can cover `allocation`.
 - `isExpSharing=0` uses exclusive traffic with `bucketId`; select the bucket with `experiment bucket list`.
-- `allocation` is optional during draft construction, but before readiness it must be greater than `0` and no more than `100`.
+- `allocation` (experiment-level) is the experiment's share of the traffic layer. It is optional during draft construction, but before readiness it must be greater than `0` and no more than `100`. **Integer only** (for example `20`); decimals such as `20.5` are rejected at the CLI interface.
+- `groups[].allocation` (group-level): **integer only; sum must equal `100` exactly**. Example for 3 groups: `34 + 33 + 33 = 100`. Decimals such as `33.33` are rejected at the CLI interface before save.
 - `expCycle.cycleType` can be `day` or `sample`; when `cycleType=day`, `dayNum` is `1..90`. Blank cycle defaults to day + 30.
-- Before readiness, `groups` must be non-empty, contain exactly one control group, total allocation must equal `100`, and each `expGroupValue` must be a non-empty JSON string array.
+- Before readiness, `groups` must be non-empty, contain exactly one control group (`isControl=1`), group allocations must sum to exactly `100`, and each `expGroupValue` must be a non-empty JSON string array.
 - Feature experiments must bind `featureKeyList` before readiness. `featureKeyList` contains Feature key strings, not Feature objects. The MCP currently supports one `featureKey` for feature experiments.
 - Metrics use `metricRole=primary|secondary|guardrail|observation`; before readiness at least one primary metric is required.
 - `targeting` replaces the saved targeting object when provided.
+- Custom audience QP must be supplied as the semantic object
+  `targeting.definitionRequest`. Do not submit the internal `targeting.targetConfig`
+  JSON or any `Cxx`/`Axxx` code. Resolve event and property names with Analysis
+  metadata first.
+
+Semantic audience example:
+
+```json
+{
+  "targeting": {
+    "definitionRequest": {
+      "type": "condition",
+      "conditions": {
+        "relation": "and",
+        "items": [
+          {"type": "user", "field": "country", "operator": "eq", "values": ["CN"]},
+          {
+            "type": "event",
+            "event": "purchase",
+            "operator": "gte",
+            "value": 2,
+            "aggregation": "sum",
+            "property": "amount",
+            "time_range": {"mode": "recent", "unit": "day", "value": 7}
+          }
+        ]
+      }
+    }
+  }
+}
+```
 
 ## Payload Examples
 
@@ -103,12 +139,18 @@ Patch a Feature binding. `featureKeyList` is a string array:
 ae-cli experiment experiment save --project-id 2 --req '{"expId":"e024","featureKeyList":["payment_color"]}'
 ```
 
-Patch groups. `expGroupValue` is a JSON-encoded string, not a native array:
+Patch groups. `expGroupValue` is a JSON-encoded string, not a native array. `groups[].allocation` must be integers that sum to exactly `100`:
 
 ```bash
 ae-cli experiment experiment save --project-id 2 --req '{"expId":"e024","groups":[{"expGroupName":"control","isControl":1,"allocation":50,"expGroupValue":"[\"green\"]"},{"expGroupName":"variant","isControl":0,"allocation":50,"expGroupValue":"[\"red\"]"}]}'
 ```
 
+Three-group even split example:
+
+```bash
+ae-cli experiment experiment save --project-id 2 --req '{"expId":"e024","groups":[{"expGroupName":"control","isControl":1,"allocation":34,"expGroupValue":"[\"A\"]"},{"expGroupName":"variant_b","isControl":0,"allocation":33,"expGroupValue":"[\"B\"]"},{"expGroupName":"variant_c","isControl":0,"allocation":33,"expGroupValue":"[\"C\"]"}]}'
+```
+
 Patch metrics. `metrics` is an object array:
 
 ```bash
@@ -122,6 +164,7 @@ ae-cli experiment experiment save --project-id 2 --req '{"expId":"e024","metrics
 If execution reports a DTO type mismatch after a clean dry-run, inspect nested field types first:
 
 - `featureKeyList` must be a string array.
+- `groups[].allocation` must be an integer, and all group allocations must sum to exactly `100`.
 - `groups[].expGroupValue` must be a JSON-encoded string.
 - `metrics` must be an object array with `metricId` and `metricRole`.
 

package/skills/ae-experiment/references/save_metric.md

@@ -11,3 +11,65 @@ Flags:
 - `--req`: Metric save request JSON object.
 
 Create mode requires metric identifiers and metric configuration. Modify mode uses `update=true`.
+
+## Semantic Metric Contract
+
+- Supply metric QP as `req.metricDefinition`.
+- Never submit internal `metricConfig`, `calcType`, or an `Axxx` calculation code.
+- Experiment metrics currently accept event definitions only.
+- Supported aggregations:
+  - Event-count (no property): `total_count`, `user_count`, `active_days`
+  - Property-based (**`property` REQUIRED**): `sum`, `avg`, `max`, `distinct_count`
+
+### Property rule (mandatory)
+
+When `aggregation` is `sum`, `avg`, `max`, or `distinct_count`:
+
+1. Resolve the event's available properties with Analysis metadata first
+   (`ae-cli analysis-meta property list` / `get` for that event).
+2. Pass one concrete available property name in `metricDefinition.property`.
+3. Do **not** invent placeholder metrics without a property (for example
+   `metric_avg_no_property_*`). Hermes rejects property aggregations with a blank
+   or missing `property`.
+
+When `aggregation` is `total_count`, `user_count`, or `active_days`, omit `property`.
+
+### Correct example (avg with property)
+
+```bash
+ae-cli experiment metric save --project-id 1 --req '{
+  "metricId":"startup_style_payment_avg_20260729",
+  "metricName":"Startup style payment avg",
+  "createType":"event",
+  "goalDirection":"up",
+  "metricDesc":"Average payment amount",
+  "metricDefinition":{
+    "type":"event",
+    "event":"payment",
+    "aggregation":"avg",
+    "property":"amount"
+  }
+}'
+```
+
+### Wrong example (avg without property — rejected)
+
+```json
+{
+  "metricId": "metric_avg_no_property_actual_20260729_144230",
+  "metricDefinition": {
+    "type": "event",
+    "event": "payment",
+    "aggregation": "avg"
+  }
+}
+```
+
+### Event-count example (no property)
+
+```bash
+ae-cli experiment metric save --project-id 1 --req '{"metricId":"purchase_users","metricName":"Purchase users","createType":"event","goalDirection":"up","metricDesc":"Unique purchasers","metricDefinition":{"type":"event","event":"purchase","aggregation":"user_count"}}'
+```
+
+Filters use the semantic `filters` tree with `relation=and|or` and items containing
+`field`, `operator`, and `values`.

package/skills/ae-experiment/references/save_submit_experiment.md

@@ -8,6 +8,9 @@ ae-cli capability run experiment.experiment.save-submit --input '{"project_id":1
 
 Input fields: `project_id` and `req`. The outer input is snake_case; fields inside `req` keep the native camelCase DTO shape.
 
+Custom audiences use semantic `req.targeting.definitionRequest`. Never pass the
+internal `targetConfig` field or hand-write `Cxx`/`Axxx` codes.
+
 Response shape: `data.result`, with object keys recursively converted to snake_case.
 
 Prefer `experiment experiment save` for progressive draft construction.

package/skills/ae-experiment-design/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: ae-experiment-design
+description: "Design AE/TE A/B experiments from a business goal through a reviewable draft. Use when the user asks to form an experiment hypothesis, assess metric readiness, choose or create metrics and Features, design groups or traffic, estimate sample size or duration, create an experiment draft, or run readiness and conflict checks. SDK guidance is a conditional branch: enter it only when the user explicitly asks about an A/B experiment SDK, client SDK integration, experiment SDK code generation, or SDK troubleshooting; do not include SDK work in an ordinary experiment-design or draft-creation request."
+---
+
+# AE Experiment Design and Integration
+
+Turn a business objective into an evidence-backed experiment design, an implementation contract, and, when requested and supported, an AE experiment draft.
+
+## Hard boundaries
+
+- Use `ae-cli` for every AE/TE platform interaction. Do not substitute raw HTTP, browser automation, direct database queries, MCP tools, or application SDKs.
+- Do not infer an SDK request from the fact that an experiment needs implementation. Load SDK references only when the user explicitly asks about an A/B experiment SDK or client SDK integration.
+- Do not copy general tracking SDK documentation into this Skill. Route generic initialization, event reporting, `track`, user identity, user properties, data upload, LogBus, and REST questions to `ae-data-integration-helper` when that Skill is available.
+- Use only the event-metric calculation contracts defined in
+  `metric-readiness.md`. Bind one confirmed primary event metric and do not add
+  unsupported metric roles.
+- Never claim that a platform asset exists, was created, passed a check, or generated project code without a successful `ae-cli` response.
+- Never invent platform IDs, schemas, SDK APIs, versions, defaults, or behavior.
+
+## Progressive disclosure router
+
+Read only the references needed for the current request:
+
+| Request | Required references |
+|---|---|
+| Any AE/TE platform read or write | [`references/platform-operations.md`](references/platform-operations.md) |
+| Create or reuse an experiment draft | [`references/experiment-creation.md`](references/experiment-creation.md) and [`references/platform-operations.md`](references/platform-operations.md) |
+| Metric selection, feasibility, or creation | [`references/metric-readiness.md`](references/metric-readiness.md) |
+| Explicit A/B experiment SDK or client SDK integration request | [`references/sdk-integration.md`](references/sdk-integration.md) |
+| Exact SDK version, dependency, class, or source lookup | [`references/sdk-index.md`](references/sdk-index.md) |
+| Cross-platform Feature, default, fetch, cache, or assignment behavior | [`references/experiment-sdk-contract.md`](references/experiment-sdk-contract.md) |
+| Android, iOS, or JavaScript experiment SDK | [`references/client-experiment-sdk.md`](references/client-experiment-sdk.md) |
+| Server-side assignment or evaluation | [`references/server-experiment-sdk.md`](references/server-experiment-sdk.md) |
+| Server assignment with client rendering | [`references/hybrid-experiment-sdk.md`](references/hybrid-experiment-sdk.md) |
+| Exposure design, deduplication, or metric join | [`references/exposure-contract.md`](references/exposure-contract.md) |
+| SDK retrieval, default, identity, exposure, or debug issue | [`references/sdk-troubleshooting.md`](references/sdk-troubleshooting.md) |
+
+References are a curated fast path, not the whole documentation set.
+
+## Workflow
+
+### 1. Frame the decision
+
+Extract:
+
+- business goal and desired direction;
+- experiment variable and user-visible change;
+- target population and exclusions;
+- decision that the result must support;
+- success threshold.
+
+Convert these into a falsifiable hypothesis. Clarify only missing facts that materially change the design. For a conversion goal, establish the population, denominator or exposure behavior, numerator behavior, attribution window, and analysis unit.
+
+Do not silently invent a target population, conversion definition, or technical platform.
+
+### 2. Resolve the project and evidence
+
+Pass the project gate in `platform-operations.md`. With `ae-cli`, establish candidate exposure and outcome events, assignment identity and join path, timestamps, exact saved-metric definitions, and—when available—baseline and eligible traffic.
+
+If the project is unavailable, accept user-provided schemas or definitions and label all platform-dependent conclusions as unverified.
+
+### 3. Assess metric readiness
+
+Apply `metric-readiness.md`. Classify candidates as `recommended`, `available`,
+`blocked`, or `unverified`; recommend one primary event metric and confirm its
+calculation code before planning sample size or duration.
+
+### 4. Design Feature, assignment, and groups
+
+Define the Feature key, type, typed default, ownership, stable assignment unit, one control group, treatment groups, group values, traffic, allocations, layer, targeting, and exclusions.
+
+Require allocations totaling `1.0`, experiment traffic in `(0, 1]`, type-correct values, a stable exposure-to-outcome identity join, and at least one primary metric. Resolve real Features and layers with `ae-cli` before reuse or creation.
+
+### 5. Calculate sample size and duration
+
+Follow this order: confirm the primary metric and calculation code → obtain its
+baseline, MDE, and any required variance → calculate the sample target with
+[`scripts/calculate_experiment_plan.py`](scripts/calculate_experiment_plan.py)
+→ derive duration from the sample target and effective eligible daily units.
+Apply the preregistered planning policy in `metric-readiness.md`. Use fixed
+`alpha=0.05` and two-sided testing, policy-default `power=0.80`, and Bonferroni
+planning for multiple treatments. Require the MDE type and direction; never
+default MDE to 5% or assume variance for a continuous metric.
+
+When experiment traffic is already confirmed, calculate its duration. When it
+is not confirmed, obtain verified layer capacity and let the script recommend
+the smallest absolute traffic candidate that reaches the target within the
+maximum runtime. Default to at least seven days and full-week alignment. Return
+the actual infeasible duration instead of truncating it. Explain the baseline,
+MDE, power source, allocations, multiplicity rule, traffic evidence, sample
+targets, duration adjustment, and any native-report mismatch. Do not return a
+definitive plan when required evidence is unavailable.
+
+### 6. Materialize the design
+
+For an explicit draft-creation request, follow `experiment-creation.md` and `platform-operations.md`. Create only authorized draft assets, verify the saved result by reading it back, run supported readiness and conflict checks, and return the compact receipt and experiment link defined there.
+
+Submitting, starting, changing live traffic, pausing, ending, or deleting requires separate explicit confirmation. Never turn draft creation into launch.
+
+## Output requirements
+
+- Use the language explicitly requested by the user. Otherwise, use the language of the user's latest substantive message.
+- Localize all user-visible prose, including headings, table headers, field labels, status names, recommendations, warnings, assumptions, and next actions.
+- Keep code, commands, raw IDs, event/property/metric names, Feature keys, SDK/API names, and official enum values unchanged when translation would alter their technical meaning.
+- Treat section names in this Skill as semantic guidance, not literal output text. Do not copy an English heading into a non-English response.
+- For a design request, lead with the experiment recommendation. For a creation, validation, or conflict-check request, lead with the operation outcome.
+- Include only the smallest set of relevant sections; do not reproduce every workflow stage.
+- Separate observed platform evidence, verified documentation, deterministic calculations, design judgments, and unresolved assumptions.
+- Before responding, check every heading, table header, label, and status for unintended mixed-language output.
+
+Treat project resolution, metadata discovery, candidate-event searches, metric comparison, Feature and layer inventory, capability discovery, schema inspection, and command execution as internal working context.
+
+- Do not narrate the execution sequence in the final answer. Omit phrases such as "first load the reference", "now query in parallel", "verified with ae-cli", or "the evidence collection is complete".
+- Do not expose raw commands, capability IDs, request schemas, full candidate lists, or a platform-evidence dump unless the user explicitly asks for the evidence, audit trail, or debugging details.
+- Surface platform evidence only when it changes the design, blocks the operation, reveals a material semantic mismatch, or requires user confirmation. Summarize it in at most three concise bullets by default.
+- Do not repeat the full experiment design after a creation request unless the user explicitly asks for the complete design.
+- Do not expose hidden reasoning. Give the conclusion, the user-relevant basis, and the action result.
+
+## Failure behavior
+
+- Missing project or ambiguous host: show candidates and ask; do not guess.
+- Missing metadata: return the required event, property, identity, and timestamp checklist.
+- Experiment product unavailable:
+  - State that the project has not enabled the experiment product only when an
+    explicit platform entitlement result establishes that fact. A missing
+    capability alone means the experiment capability is unavailable, not that
+    the product was not purchased.
+  - For a design request, tell the user that experiment design can continue,
+    but Feature, layer, metric, and traffic details cannot be verified on the
+    platform. Continue with an offline design and request the baseline, MDE,
+    and eligible daily units when sample-size or duration planning needs them.
+  - For a draft-creation request, lead with the outcome that the experiment
+    draft was not created. Explain that Feature, layer, and draft creation are
+    blocked, preserve the proposed design, and say that platform creation and
+    readiness checks can continue after the product is enabled or the required
+    access is granted.
+- HTTP 403 or equivalent permission denial: state that the current account
+  lacks the required experiment permission, stop dependent writes, and explain
+  that this result does not establish whether the project purchased the
+  experiment product. Ask the project administrator to check both product
+  availability and the user's project permissions.
+- Capability gap without an explicit entitlement or permission result: report
+  that the current environment does not expose the required experiment
+  capability, continue with an offline design when useful, and do not bypass
+  `ae-cli`.
+- For SDK gaps or conflicts, follow `sdk-integration.md`; do not invent exact code.
+- Validation failure: correct documented input or ask for the missing value; do not retry unchanged input.
+- Partial success: report created and failed assets separately and never imply atomic success.

package/skills/ae-experiment-design/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Experiment Design & Integration"
+  short_description: "Design AE experiments with optional SDK guidance"
+  default_prompt: "Use $ae-experiment-design to design an A/B experiment and prepare an AE draft; include SDK guidance only when I explicitly request it."