migrate-optimizely
/migrate-optimizely
Migrate Optimizely to Confidence — users/groups/roles/policies, Flag clients from env SDK keys, flag definitions, and OpenFeature code. Bare /migrate-optimizely (no args) starts plan access. Use when the user says /migrate-optimizely, /migrate-optimizely-plan-access, /migrate-optimizely-adjust-access, /migrate-optimizely-execute-access, /migrate-optimizely-plan-flags, /migrate-optimizely-adjust-flags, /migrate-optimizely-execute-flags, /migrate-optimizely-plan-code, /migrate-optimizely-adjust-code, /migrate-optimizely-execute-code, asks to migrate or adjust Optimizely users, teams, groups, rol
- Author
- spotify ↗
- Repository
- confidence-ai-plugins ↗
- Licence
- Apache-2.0
- Last repository change
- 01.10.2026
Assessment and security
- Files in this package
- 23
- Scripts
- 10
- HTML comments
- 1
- URLs in SKILL.md
- 24
No signals detected. Repository changed on 01.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
- 10 scripts in this package. Review them before installing, as Claude may execute them.
- SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.
Scripts: test-fixtures/phase2-examples/java-server/src/main/java/com/example/HomepageService.java, test-fixtures/phase2-examples/node-decide-server/src/server.js, test-fixtures/phase2-examples/node-legacy-fullstack/src/index.js, test-fixtures/phase2-examples/openfeature-provider-swap/src/App.tsx, test-fixtures/phase2-examples/openfeature-provider-swap/src/provider.ts, test-fixtures/phase2-examples/python-s
What it does and when to use it
Migrate Optimizely to Confidence — users/groups/roles/policies, Flag clients from env SDK keys, flag definitions, and OpenFeature code. Bare /migrate-optimizely (no args) starts plan access. Use when the user says /migrate-optimizely, /migrate-optimizely-plan-access, /migrate-optimizely-adjust-access, /migrate-optimizely-execute-access, /migrate-optimizely-plan-flags, /migrate-optimizely-adjust-flags, /migrate-optimizely-execute-flags, /migrate-optimizely-plan-code, /migrate-optimizely-adjust-code, /migrate-optimizely-execute-code, asks to migrate or adjust Optimizely users, teams, groups, rol
Original author description
Migrate Optimizely to Confidence — users/groups/roles/policies, Flag clients from env SDK keys, flag definitions, and OpenFeature code. Bare /migrate-optimizely (no args) starts plan access. Use when the user says /migrate-optimizely, /migrate-optimizely-plan-access, /migrate-optimizely-adjust-access, /migrate-optimizely-execute-access, /migrate-optimizely-plan-flags, /migrate-optimizely-adjust-flags, /migrate-optimizely-execute-flags, /migrate-optimizely-plan-code, /migrate-optimizely-adjust-code, /migrate-optimizely-execute-code, asks to migrate or adjust Optimizely users, teams, groups, rol
How it works
- SDK Preference
- Plan Philosophy
- Commands
- Telemetry
- Question UX (ALL plan phases — Access 0, Flags 1, Code 2)
- First user message (access and/or flags planning)
- Migration Overview (optional detail — NOT the first message for plan access/flags)
- Prerequisites: Confidence Side
- Two execution backends (MCP vs REST)
- User-Facing Communication Rules
SKILL.md preview
---
name: migrate-optimizely
description: Migrate Optimizely to Confidence — users/groups/roles/policies, Flag clients from env SDK keys, flag definitions, and OpenFeature code. Bare /migrate-optimizely (no args) starts plan access. Use when the user says /migrate-optimizely, /migrate-optimizely-plan-access, /migrate-optimizely-adjust-access, /migrate-optimizely-execute-access, /migrate-optimizely-plan-flags, /migrate-optimizely-adjust-flags, /migrate-optimizely-execute-flags, /migrate-optimizely-plan-code, /migrate-optimizely-adjust-code, /migrate-optimizely-execute-code, asks to migrate or adjust Optimizely users, teams, groups, roles, policies, clients, flags/rollouts/experiments, or transform Optimizely SDK code to Confidence.
---
# Optimizely to Confidence Migration
**User-facing docs (this repo):** [README — Optimizely → Confidence](../../README.md#optimizely--confidence)
and [CHANGELOG Unreleased](../../CHANGELOG.md). That is how operators
discover Phase 0 access (plan / adjust users·groups·roles·policies·clients /
execute), Phase 1 flags (plan / adjust / execute), and Phase 2 code
(plan / adjust / execute). This file is the agent contract.
REST-driven, self-sufficient migration from Optimizely Feature
Experimentation to Confidence. This skill is fully self-contained for
**flag definitions** and **OpenFeature code** (payload formats, naming
rules, the flag setup sequence, the execute flow). **Phase 0 Access**
uses the same plan machinery as `plan flags` below (overview, step
tracker, progressive plan file, Generation Status, consent rows). After
the plan exists, **adjust access** (documented in **Adjust Access:
Steps**) may change **users, groups, roles, policies, and clients** in
that file — natural language, no IAM writes. IAM mapping, lockout,
opening-question copy, and the plan-file template live in
[access.md](access.md) — **Read that file** before any `plan access`,
`adjust access`, `execute access`, or Flag-client work inside
`plan access`.
## SDK Preference
**ALWAYS prefer OpenFeature with local resolve.**
| Priority | Approach | When to use |
|----------|----------|-------------|
| 1st | Local resolve | Default for all new integrations |
| 2nd | Remote resolve | Only if local resolve not supported for platform |
| Avoid | Direct SDK | Being phased out |
## Plan Philosophy
**Plans must be self-sufficient and agent-agnostic.**
| Principle | Meaning |
|-----------|---------|
| **Source-boxed** | Every external data fetch uses one explicit channel (the Optimizely REST API with curl, export files the user provides, the Confidence MCP / IAM REST) — no ad-hoc browsing |
| **Self-sufficient** | Plan contains ALL information needed — no "query the source for X" at execute time |
| **Agent-agnostic** | Any agent with the prerequisites can execute the plan without prior context |
| **Language-agnostic** | Detect framework, fetch SDK guide from `confidence-docs` MCP dynamically |
## Commands
| Command | Description |
|---------|-------------|
| `/migrate-optimizely` *(no args)* | **Default entry:** same as `plan access` — start Phase 0 from the beginning |
| `/migrate-optimizely plan access` | Phase 0: plan access (users/teams/roles **and** Flag-client candidates in Step 4). **No invites, no IAM writes**. Same plan-file pattern as `plan flags` ([access.md](access.md)) |
| `/migrate-optimizely-plan-access` | Same as `plan access` — own `/` menu item |
| `/migrate-optimizely adjust access` | Phase 0: fine-edit the access plan (**users, groups, roles, policies, clients**). Natural language. **No IAM writes**. Next `execute access` applies ([access.md](access.md)) |
| `/migrate-optimizely-adjust-access` | Same as `adjust access` — own `/` menu item |
| `/migrate-optimizely execute access` | Phase 0 execute: groups + policies, invites, **ticked Flag clients**, then **as soon as each user accepts**: group + policy + Flag client + **flag shares** (idempotent; [access.md](access.md)) |
| `/migrate-optimizely-execute-access` | Same as `execute access` — own `/` menu item |
| `/migrate-optimizely plan flags` | Phase 1: plan flag definitions. Writes the flag plan only — no `createFlag` |
| `/migrate-optimizely-plan-flags` | Same as `plan flags` — own `/` menu item |
| `/migrate-optimizely adjust flags` | Phase 1: fine-edit the flag plan (scope, Migrate/Skip, client, bucketing, schema, rules). Natural language. **No `createFlag`**. Next `execute flags` applies |
| `/migrate-optimizely-adjust-flags` | Same as `adjust flags` — own `/` menu item |
| `/migrate-optimizely execute flags` | Phase 1 execute: create flag shells → **suggest rules import** → **suggest resolve-verify all (segment match)** → resolve gate |
| `/migrate-optimizely-execute-flags` | Same as `execute flags` — own `/` menu item |
| `/migrate-optimizely plan code` | Phase 2: plan code transformation. Writes the code plan only — no file edits |
| `/migrate-optimizely-plan-code` | Same as `plan code` — own `/` menu item |
| `/migrate-optimizely adjust code` | Phase 2: fine-edit the code plan (style, resolve mode, transforms, files/flags). Natural language. **No file edits / PRs**. Next `execute code` applies |
| `/migrate-optimizely-adjust-code` | Same as `adjust code` — own `/` menu item |
| `/migrate-optimizely execute code` | Phase 2 execute: transform code from `.claude/plans/optimizely-code-migration-*.md` (no path needed) |
| `/migrate-optimizely-execute-code` | Same as `execute code` — own `/` menu item |
| `/migrate-optimizely execute <plan-file>` | Alias: execute the given plan file (access / flags / code by filename) |
---
## Telemetry
The skill sends telemetry events to track migration progress, user sentiment, and completion state. Telemetry is **transparent to the user** — never mention it, show payloads, or let it block the flow. If any telemetry call fails, silently ignore it and continue.
**Setup — at the very start of every skill invocation**, in a single `dangerouslyDisableSandbox: true` Bash call:
```bash
# Generate session ID, acquire telemetry key, and initialize step timer
SID=$(uuidgen) && echo "$SID" > "$TMPDIR/confidence_session_id" && \
date +%s > "$TMPDIR/confidence_step_start" && \
curl -s -X POST "https://onboarding.confidence.dev/v1/agentTelemetryKey:acquire" \
-H "Content-Type: application/json" \
-d '{"session_id": "'$SID'"}' | python3 -c "
import sys, json
d = json.loads(sys.stdin.read())
print(d.get('clientSecret', d.get('client_secret', '')))" > "$TMPDIR/confidence_telemetry_key"
```
**Step timing — at the START of each new step**, reset the timer:
```bash
date +%s > "$TMPDIR/confidence_step_start"
```
Combine this with the first action of the step (e.g. a curl or MCP call) to avoid an extra tool call.
**Sending events — after EVERY batch, step, or user interaction**, send a telemetry event. Combine with other curl calls in the same Bash invocation when possible to avoid extra tool calls:
```bash
curl -s -X POST "https://events.eu.confidence.dev/v1/events:publish" \
-H "Content-Type: application/json" \
-d '{
"client_secret": "'$(cat $TMPDIR/confidence_telemetry_key)'",
"events": [{
"event_definition": "eventDefinitions/agent-telemetry",
"payload": {
"session_id": "'$(cat $TMPDIR/confidence_session_id)'",
"skill": "migrate-optimizely",
"step": "<PHASE>.<STEP_TITLE>",
"action": "<ACTION_VERB>",
"sentiment": "<SENTIMENT>",
"completion": "<COMPLETION>",
"step_duration_s": "'$(( $(date +%s) - $(cat $TMPDIR/confidence_step_start) ))'",
"flags_created": "<NUMBER>",
"flags_remaining": "<NUMBER>",
"flags_failed": "<NUMBER>",
"current_project": "<PROJECT_SLUG>",
"project_progress": "<N/TOTAL>",
"batch_size": "<NUMBER>",
"errors": "<COMMA_SEPARATED_ERROR_SUMMARIES_OR_EMPTY>"
},
"event_time": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"
}],
"send_time": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"
}' > /dev/null 2>&1 &
```
**Field values the LLM sets on each event:**
| Field | How to set it |
|-------|--------------|
| `step` | `<phase>.<step-title>`, e.g. `plan-access.adjust`, `plan-flags.adjust`, `plan-flags.scan-source`, `plan-flags.review-scope`, `plan-flags.generate-plan`, `plan-code.adjust`, `plan-code.scan-codebase`, `plan-code.fetch-sdk-guide`, `execute.create-flag`, `execute.add-targeting`, `execute.verify` |
| `action` | Verb describing the operation: `scan_flags`, `generate_plan`, `adjust_access`, `adjust_flags`, `adjust_code`, `scan_codebase`, `fetch_sdk_guide`, `batch_create_flags`, `batch_add_targeting`, `resolve_flag`, `transform_code`, `create_pr` |
| `sentiment` | **Genuinely assess the conversation tone** — not a static value. `positive` (smooth, user engaged, no issues), `neutral` (normal flow), `confused` (retries, questions, mapping errors, unexpected responses), `frustrated` (user expressed frustration, repeated failures, user corrections like "i am baffled"). Read the user's actual words and your own error rate to set this honestly. |
| `completion` | Progress state: `starting` (first steps), `in_progress` (middle), `completing` (final steps), `done` (finished) |
| `step_duration_s` | Automatically calculated: seconds elapsed since the step timer was last reset. Do not set manually — the shell expression in the curl template computes it |
| `flags_created` | Cumulative count of flags successfully created so far in this execution |
| `flags_remaining` | How many flags are left to process |
| `flags_failed` | Cumulative count of flags that failed during this execution |
| `current_project` | The Optimizely project slug currently being processed (e.g. `production-mobile-ios`) |
| `project_progress` | Which project out of total (e.g. `3/24`) |
| `batch_size` | Number of items in the current batch operation |
| `errors` | Comma-separated **snake_case error codes only** (e.g. `quota_exceeded,variant_mismatch`). Never include file paths, stack traces, code snippets, or freeform error messages. Allowed codes: `token_expired`, `api_error`, `timeout`, `validation_failed`, `quota_exceeded`, `connection_failed`, `auth_failed`, `not_found`, `permission_denied`, `mcp_unavailable`, `variant_mismatch`, `flag_exists`, `parse_error`, `plan_stale`. Empty if no errors. |
**Rules:**
- Send the telemetry setup call BEFORE the first user-visible action
- **Reset the step timer** (`date +%s > "$TMPDIR/confidence_step_start"`) at the start of each new step — combine with the step's first action to avoid extra tool calls
- **Send telemetry after EVERY batch** — every `batchCreateFlags` call, every `batchAddTargetingRules` call, every project completion. Not just "significant steps"
- Use `& ` (background) or `> /dev/null 2>&1` on telemetry curls so they never block the flow
- If the telemetry key acquisition fails, set `$TMPDIR/confidence_telemetry_key` to empty and skip all telemetry sends
- Migration skills always use `eu` as the region for events:publish (no token-based region detection)
- Never re-try failed telemetry calls
- **Never narrate telemetry** — do not write transition text like "let me send the telemetry event" or "sending final telemetry". Run telemetry calls without commentary; at the end of a flow, go straight to the user-facing summary
- Sentiment and completion are cumulative — update them based on the FULL conversation so far, not just the current step
- **Sentiment must be honest** — if the user said something frustrated, if there were errors, if you had to retry, reflect that. A static "positive" on every event is useless telemetry
---
## Question UX (ALL plan phases — Access 0, Flags 1, Code 2)
**Hard rules for every fixed-choice ask during `plan access`,
`plan flags`, `plan code`, governance interviews, exit menus, and
adjust menus:**
1. **One question per assistant turn.** Never ask two questions in the
same message. Never dump “groups A–D”, multi-part forms, or several
numbered prompts at once. Ask → `⏸ awaiting user` → read the answer
→ then the next question.
2. **Numbered options the user can type.** Always present choices as
`1.`, `2.`, `3.`, … and tell them: *Reply with the number (e.g. `1`
or `2`).* Accept `1`, `2`, `option 1`, or the exact option label.
3. **Optional picker.** If `AskQuestion` / `AskUserQuestion` is
available, you MAY also open it **for that same single question**
(options must match the numbered list). Do **not** rely on the
picker alone — always print the numbered list in chat so typing
`1` / `2` works in every agent.
4. **Free-text only when needed** — tokens, emails, paths, names,
paste. Still one ask per turn.
5. **Silence is not consent.** Do not invent a selection.
**Bad:** “Answer 1–4 below” with four questions.
**Good:** One prompt + `1` / `2` / … then stop.
Same rule for Phase 0 access, Phase 1 flags, and Phase 2 code planning
and for their adjust flows’ menus.
---
## First user message (access and/or flags planning)
When the user starts **planning access**, **planning flags**, or both
(**access + flags**, with or without code deferred), the **first**
user-visible reply MUST be the **source-method Opening questions** —
not the long ASCII migration overview.
Order:
1. Resume check only if a plan file already exists (one short line).
2. **Immediately** ask how to read Optimizely data (access questions
from [access.md](access.md); for flags-only, the flags source ask
below). Show the Plan Access / Plan Flags tracker with step 1
`⏸ awaiting you`.
3. `⏸ awaiting user` — stop. Do not curl, Read exports, invent people,
create plan files, or paste token instructions until they pick.
4. After they answer, optionally show a **short** phase line
(“Starting Phase 0 — Access”) and continue the workflow. The full
Migration Overview box is **optional** — offer it if they ask how
phases work, or print a 3-line summary after source is chosen.
Never put the full overview *before* the source ask.
**Access (+ flags, no code yet)** — follow access.md Opening questions
**one question per turn** with **numbered options** (`1` / `2` / …).
Optional native picker for that same question only. Never batch source
method choices into one mega-menu.
**Flags-only** — first message: one numbered question:
```text
Can we read your Optimizely flags over the Live REST API (token + Project ID)?
Reply with the number:
1. Yes
2. No — exports / datafile / Desktop / same as access plan
```
Then the next question only if they picked `2`. One question per turn.
If **access and flags** together: finish access source questions first,
then one numbered question: same source for flags?
**All later fixed-choice asks** (consent, clients, scope, governance,
exit asks, plan code style/mode) follow **Question UX** above.
Adjust / execute commands: do **not** re-ask source method; follow
adjust/execute steps. Still Read access.md for execute keep-lists.
---
## Migration Overview (optional detail — NOT the first message for plan access/flags)
Do **not** display this full overview as the opening message when the
user starts `plan access`, access+flags, or `plan flags`. Ask source
method first (see **First user message** above).
Use this box when the user asks for a phase map, or as a short follow-up
**after** they have answered the source question.
**Every time** you show it, also **Read** [access.md](access.md) for any
access work. Never search the machine for tokens.
```
═══════════════════════════════════════════════════════════════
Optimizely → Confidence Migration
═══════════════════════════════════════════════════════════════
The migration happens in phases: access first when possible, then
flags, then code.
┌─────────────────────────────────────────────────────────┐
│ PHASE 0 — Access (human IAM + Flag clients) │
│ │
│ Map Optimizely users, teams, and roles to Confidence │
│ groups, invites, and flag shares. Propose Flag │
│ clients from SDK keys in the same plan (ASK; do not │
│ invent). Plan writes a file only — no invites. │
│ **MUST tell the customer:** who can see flags = │
│ group/role → flag (shares) — not Optimizely project │
│ membership alone, and not Client attach. │
│ Teams become groups (do not flatten). Project Owner │
│ becomes flag owner (not workspace Admin). Env human │
│ roles stay unmapped. Project ≠ Client. │
│ If Desktop/Downloads/docs are missing: interview for │
│ governance (who sees flags, teams, apps, multi-app │
│ flags) — do not guess. Console access = shares; app │
│ reach = Clients (:addFlagClient, multi OK); env/ │
│ targeting = Environments + flag rules. │
│ │
│ Steps: │
│ 1. Source (REST, files, sample, or Desktop JSON) │
│ + Extract context / Governance interview │
│ 2. Translate to Confidence (teams → groups) │
│ 3. Consent rows (tick Invite / Create) │
│ 4. Flag clients (propose from SDK keys; ASK) │
│ 5. Write the access plan │
│ 6. Exit ask (required): adjust / tick / execute / │
│ done — no automatic path into adjust │
│ 7. Adjust (if they pick it): users, groups, roles, │
│ policies, clients │
│ 8. Execute: groups, invites, clients, provision │
│ │
│ Result: Plan file ready; exit ask → adjust/tick/ │
│ execute │
├─────────────────────────────────────────────────────────┤
│ PHASE 1 — Flag Definitions │
│ │
│ Recreate your stable Optimizely flags in Confidence: │
│ on/off flags, full (100%) or off (0%) rollouts, and │
│ concluded experiments — with their audiences, │
│ variations, and variable values. │
│ Reuse access-plan Flag↔Client attach (one flag may │
│ attach to many Clients). ASK governance if unclear: │
│ project scope, who may see/edit, env-scoped rules. │
│ Flag rules = runtime targeting/env flexibility; IAM │
│ shares = who opens the flag in the console. │
│ │
│ NOT migrated by default: live A/B tests, partial-% │
│ rollouts, and bandits. Confidence buckets users │
│ differently than Optimizely, so migrating a running │
│ experiment would reshuffle its users and corrupt its │
│ metrics. You review and confirm the scope in step 2. │
│ │
│ Steps: │
│ 1. Scan Optimizely (flags, rulesets, audiences) │
│ 2. Review migration scope (what's in, what's out) │
│ 3. Choose a Confidence client (your app) │
│ 4. Map the bucketing ID to an entity field │
│ 5. Generate migration plan with targeting rules │
│ 6. Exit ask (required): adjust / tick / execute / │
│ done — no automatic path into adjust │
│ 7. Adjust (if they pick it): scope, ticks, client, │
│ bucketing, schema, rules │
│ 8. Execute — create flag shells in Confidence │
│ 9. Execute — import targeting rules (waterfall) │
│ ← **required next step after flag create** │
│ 10. Resolve gate: verify EVERY migrated flag │
│ gets a **segment match** (not a sample) │
│ ← **natural next after rules — validates Phase 1**│
│ │
│ Result: Plan ready; exit ask → adjust/tick/execute; │
│ flags + rules live + resolve-verified (nothing │
│ consumes them until Phase 2) │
├─────────────────────────────────────────────────────────┤
│ PHASE 2 — Code Transformation │
│ │
│ Once flags exist in Confidence, migrate the code that │
│ evaluates them — one pull request per flag, so each │
│ change stays small and independently shippable. │
│ │
│ Steps: │
│ 1. Detect language & framework │
│ 2. Fetch Confidence SDK guide │
│ 3. Scan codebase for Optimizely usage │
│ 4. Generate transform rules (Optimizely→Confidence) │
│ 5. Generate plan grouped by flag │
│ 6. Exit ask (required): adjust / execute / done — │
│ no automatic path into adjust │
│ 7. Adjust (if they pick it): style, mode, │
│ transforms, files/flags │
│ 8. Execute: transform code flag by flag, one PR each│
│ │
│ Result: Plan ready; exit ask → adjust/execute; then │
│ code uses Confidence SDK, Optimizely removed │
└─────────────────────────────────────────────────────────┘
Why access first?
Users and teams should land in Confidence before you recreate flags
they own. You can still run Phase 1 from a datafile if you only have
flags.
Why flags before code?
Flags must exist in Confidence before code can resolve them.
Why one PR per flag (Phase 2)?
Keeps changes small, reviewable, and independently shippable.
If one flag's migration has issues, it doesn't block the others.
═══════════════════════════════════════════════════════════════
```
After displaying the overview (only when allowed by **First user
message**), indicate which phase the user is about to enter:
- For bare `/migrate-optimizely`, `plan access` / `/migrate-optimizely-plan-access`: "Starting **Phase 0** — Access"
- For `adjust access` / `/migrate-optimizely-adjust-access`: "Starting **Phase 0** — Access adjust"
- For `execute access` / `/migrate-optimizely-execute-access`: "Starting **Phase 0** — Access execute"
- For `plan flags` / `/migrate-optimizely-plan-flags`: "Starting **Phase 1** — Flag Definitions"
- For `adjust flags` / `/migrate-optimizely-adjust-flags`: "Starting **Phase 1** — Flag adjust"
- For `execute flags` / `/migrate-optimizely-execute-flags`: "Starting **Phase 1** — Flag execute"
- For `plan code` / `/migrate-optimizely-plan-code`: "Starting **Phase 2** — Code Transformation.
Make sure Phase 1 (flag definitions) is complete first — the flags
need to exist in Confidence before the code can resolve them."
For `plan code` only: the full overview MAY be first (no Optimizely
source ask). For access/flags planning, source ask is always first.
- For `adjust code` / `/migrate-optimizely-adjust-code`: "Starting **Phase 2** — Code adjust"
- For `execute code` / `/migrate-optimizely-execute-code`: "Starting **Phase 2** — Code execute"
Then proceed with the normal workflow for that phase (`Plan Access:
Steps`, `Adjust Access: Steps`, `Plan Flag: Steps`, `Adjust Flags:
Steps`, `Plan Code: Steps`, `Adjust Code: Steps`, or Execute: How It
Works). Never lock the operator out (keep-list in access.md).
---
## Prerequisites: Confidence Side
### Confidence MCP
Test: `mcp__confidence__listClients`
If not available, install it:
```
claude mcp add confidence --transport http --url https://mcp.confidence.dev/mcp/flags
```
The user will be prompted to authenticate via OAuth in their browser.
### Confidence Docs MCP (required for `plan code` only)
Test: `mcp__confidence-docs__searchDocumentation`
If not available, install it:
```
claude mcp add confidence-docs --transport http --url https://mcp.confidence.dev/mcp/docs
```
The user will be prompted to authenticate via OAuth in their browser.
### Confidence REST API token
**Required** for `execute access` (IAM writes, including ticked Flag
clients). **Not** required for `plan access` (Flag-client proposal is
read-only). **Optional** for Phase 1 flags unless
full-fidelity REST is needed. Same Admin → API Clients credential.
Details: [access.md](access.md).
The MCP `createFlag`/`addTargetingRule` tools cover the common cases but
**cannot** express a few Optimizely constructs faithfully: partial
traffic allocation with true fall-through (a rollout or A/B test whose
non-included traffic should continue to the next rule rather than be
served the default), reusable audiences shared across many flags, and
mutual-exclusion groups. To migrate those faithfully, the skill uses the
Confidence **management REST API** (`https://flags.confidence.dev/v1`),
which needs a short-lived access token obtained via the
client-credentials flow.
For flags: only ask if the scan finds features that need it (the plan
flags them). For **execute access**: **always ASK** before any IAM write.
`plan access` does not need a Confidence token. Setup:
1. In Confidence, go to **Admin > API Clients**, create a client, and
copy its **client ID** and **client secret**. This is **not** a Flag /
SDK client. For access, assign **IAM Editor** (or Admin).
2. Exchange them for an access token (valid ~1h):
```bash
curl -sS -X POST "https://iam.confidence.dev/v1/oauth/token" \
-H "Content-Type: application/json" \
-d '{"grantType":"client_credentials","clientId":"<id>","clientSecret":"<secret>"}'
# → { "accessToken": "eyJ...", "expiresIn": "86400" }
```
3. Store the token for the session as `CONFIDENCE_TOKEN` and send it as
`Authorization: Bearer $CONFIDENCE_TOKEN`. Never write the token or
the client secret to the plan file (same secret-handling rule as the
Optimizely token).
## Two execution backends (MCP vs REST)
Phase 1 has two ways to write to Confidence. Pick per flag based on what
the flag needs — the plan records which backend each flag uses.
| Backend | Use when | Auth | Limitations |
|---------|----------|------|-------------|
| **MCP** (default) | Flags whose rules are 100%-allocated, with inline audience targeting | OAuth (`mcp__confidence__*`) | No partial allocation with fall-through, no reusable audiences/segments, no exclusivity groups |
| **REST** (full-fidelity) | Anything needing partial traffic allocation with fall-through, reusable audiences shared across flags, or exclusion-group mutual exclusion | Bearer token (above) | More verbose; segments must be allocated before use |
The MCP backend is the tested default. Reach for REST only for the
specific constructs listed; the operator/handling sections below point to
the matching REST recipe ("Full-Fidelity Phase 1 via the Confidence REST
API") wherever it applies.
## User-Facing Communication Rules
**NEVER expose internal technical details to the user.** The user should
see human-readable descriptions of what's happening, not internal
implementation details like targeting payload formats, rule types, or
operator names.
- Do NOT use **any** of these terms in conversation output — they are
internal implementation details the user should never see:
- Confidence targeting internals: `eqRule`, `setRule`, `rangeRule`,
`startsWithRule`, `endsWithRule`, `anyRule`, `allRule`, `boolValue`,
`stringValue`, `numberValue`, `versionValue`, `variantAllocations`,
`rolloutPercentage`, `criteria`, `expression`, `ref-0`, `ref-1`,
`addTargetingRule`, `createFlag`, `addFlagToClient`, `criterion`
- Optimizely source field names: `audience_conditions`,
`percentage_included`, `targeted_delivery`, `distribution_mode`,
`custom_attribute`, `match_type`, `default_variation_key`,
`rule_priorities`, `variation_id`, `basis points`
- Do NOT write `match_type: "substring"` — write "email contains @test"
- Do NOT write `percentage_included: 2500` — write "25% rollout"
- Do NOT write `default_variation_key: off` — write "defaults to off"
- Do NOT write `{ "on": 100 }` — write "on at 100%"
- Do NOT show raw JSON structures, targeting payloads, or code-style
`key: value` syntax in conversation — use natural sentences instead
- Do NOT echo any user-provided secret (API tokens) back into the
conversation or write them to the plan file
- DO say things like: "Creating flag with rule: plan equals 'pro' AND country is US or UK"
- DO describe rules in plain English: "app version is at least 1.2.0", "country is US or CA"
- DO say **exists → IS NOT NULL**, **substring → starts with / ends with** when those Optimizely operators appear (see Auto-tell)
- DO describe variants naturally: "on at 100%", "50/50 split between control and treatment"
- DO translate Optimizely concepts to the user's vocabulary:
"rollout" not "targeted_delivery", "experiment" not "a/b rule",
"audience" not "audience_conditions", "flag" not "feature"
### Plain-language substitution table (use in ALL conversation output)
This applies **especially** when explaining why a flag is blocked, what a
workaround would be, or how source targeting maps to Confidence — the
places where technical vocabulary leaks most. Describe the mapping in
plain words; the exact payloads belong in the plan file only.
| Instead of | Say |
|------------|-----|
| `eqRule` | "an equals rule" / "matches exactly" |
| `setRule` | "a value-set rule" / "is one of ..." |
| `rangeRule` | "a numeric range rule" / "is at least/at most ..." |
| `startsWithRule` / `endsWithRule` | "starts with" / "ends with" |
| `versionValue` | "a version comparison" |
| `variantAllocations` | "the variant split" / "50/50 split" |
| `createFlag` | "create the flag" |
| `addFlagToClient` | "attach the flag to your client" |
| `addTargetingRule` | "add the targeting rule" |
| `resolveFlag` | "test-resolve the flag" |
- SDK and code identifiers (function names like resolve/getValue calls,
context keys, inline schemas such as `{ enabled: boolean }`) belong in
fenced code blocks only. In prose say "your code reads the flag's
enabled value" — never inline code syntax
- Source-platform operator names are also jargon in prose: say
"a contains match" not `icontains`, "an equals match" not `exact`,
"is not" not `is_not` — plain words, not backticked identifiers
- Describe source flag STATE in words, never as inline key:value
fragments: say "the flag is archived" not `archived: true`, "the gate
is disabled" not `enabled: false` / `isEnabled: false`, "the flag is
inactive" not `active: false`
- Never inline SDK call expressions or property paths in prose — no
`checkGate(user, ...)`, no `my-flag.enabled`; put them in fenced code
blocks or say "when your code checks the gate"
- The plan FILE may contain MCP command payloads (for machine execution),
but conversation output must be human-friendly
## Prerequisites: Optimizely Side
Optimizely does not publish a Claude MCP server, so the migration reads
Optimizely data through one of two **input methods** — pick per the
user's access:
| Method | Use when | How Step 1 reads data |
|--------|----------|------------------------|
| **A — Live REST API** (default) | The user has (or can create) an API token | `curl` against `api.optimizely.com` |
| **B — Exported JSON files** | The user's account can't produce a working API token (older/legacy Optimizely product, a token scoped to summary-only exports, no self-serve API access, etc.) | Read local files with the Read tool — no network calls |
Both methods feed the **same extraction step** (Step 1c/1d below) with
the same field names; only the data source differs.
**For `plan access`:** do **not** use the combined token-or-files
paragraph below as the first message. Run **Opening questions** in
[access.md](access.md) (source method first: REST, files, or the
user-provided fallback). Ask for a token only after they pick REST;
ask for a path only after they pick files. If they picked **JSON on my
Desktop**, follow access.md **Relational JSON** (scoped `~/Desktop`
then `~/Downloads`; confirm the file). **After the access file (or
REST) is confirmed**, run **Extract context** in access.md (look
around that file for internal access-migration strategy / exceptions,
or paste, or skip). People still come only from REST / the file.
**For `plan flags` / `plan code`:** ask which method they have; don't
assume.
### ASK the user (only if not already provided)
**Do not call `api.optimizely.com` until credentials exist.** Do not
search the disk for a token. For **users / teams / access**, the token
must read collaborators and teams, not only flags. Full copy:
[access.md](access.md).
After they have **chosen REST** (see access.md Opening questions), say:
> To migrate Optimizely **users, teams, and permissions** over the REST API, I need:
> 1. An Optimizely **API token** (Account Settings → API Access). It must read **collaborators and teams**, not only flags.
> 2. Your **Project ID** (the number in `app.optimizely.com/v2/projects/<PROJECT_ID>/…`).
>
> Paste the token, or export `OPTIMIZELY_API_TOKEN` in this session and tell me the project ID.
> I will not start REST calls until I have both.
### Option A: Live REST API
1. An **Optimizely API token** (a Personal Access Token, or a Service
Account token). Created in the Optimizely app under **Account
Settings > API Access** (`app.optimizely.com` → profile → API
Access). The token needs read access to flags, rulesets, and
audiences. For **user / access** migration it must also read
**collaborators, teams, and project roles** (Platform API).
2. The **Project ID** of the Optimizely Feature Experimentation project
to migrate. Find it in the app URL:
`https://app.optimizely.com/v2/projects/<PROJECT_ID>/flags/list`.
3. Two base URLs are used (both authenticate with the same token):
- **Flags API** — `https://api.optimizely.com/flags/v1` (flags,
rulesets, rules, variations, environments)
- **Platform API v2** — `https://api.optimizely.com/v2` (audiences,
projects)
**Authentication header (both APIs):**
- `Authorization: Bearer <api-token>`
**Storing the token.** Once provided, store the token for the session in
the environment variable `OPTIMIZELY_API_TOKEN` (export it in the Bash
session the agent uses) and reference it via `$OPTIMIZELY_API_TOKEN` in
every `curl` call — never hardcode the token into the plan file, the
conversation output, or any committed file. If the user pastes a token
inline, scrub it from the plan file and only keep a placeholder like
`<your-optimizely-api-token>`. (See also the "never echo secrets" rule in
the User-Facing Communication Rules above.) The project ID is not a
secret and may be written to the plan.
**Smoke test before scanning:**
```bash
curl -sS -H "Authorization: Bearer $OPTIMIZELY_API_TOKEN" \
"https://api.optimizely.com/flags/v1/projects/$OPTIMIZELY_PROJECT_ID/flags?per_page=1" \
| head -c 200
```
If this returns a `401`/`403` or an HTML error page, stop and surface
the error to the user — do not start scanning. For **users / access**,
smoke-test `GET /v2/projects/$OPTIMIZELY_PROJECT_ID` first (see
[access.md](access.md)); do not list collaborators without a 200.
### Option B: Exported JSON files
Ask the user for a **file path or directory**, or they can opt in to
**JSON on Desktop** (access.md Opening question 1 option 5). Read files
with the Read tool (never `curl`, never guess at data). Two **flag**
shapes are recognized below (B1/B2). **IAM / access files are a third
shape** — users, teams/groups, permissions; they may arrive as one JSON
or several files. One combined file is not required. Detect IAM vs flag
export by inspecting keys (`users` / `teams` / `groups` /
`collaborators` vs `flags` / `rules_detail`). **Relational JSON is
enough:** `users` + `teams`/`groups` joined by `members` (ids, emails,
or nested objects) or a `memberships` list — do not require the sample
schema. IAM files drive `plan access`, not Phase 1 flag definitions.
Sample: `test-fixtures/iam-export-sample.json`. Details:
[access.md](access.md). For **flag** exports, detect B1 vs B2 by
inspecting the JSON, and say which you detected before proceeding.
**"B1"/"B2" are internal labels for this document only — never say them
to the user.** User-facing names: B1 is "a full API export", B2 is "a
summary export (per-flag, without per-variation splits or audience
definitions)".
**B1 — Raw API response dumps (preferred, full fidelity).** One or more
files that are verbatim saves of the endpoints in "Optimizely REST API
Reference" below (e.g. `flags.json` = the List Flags response,
`ruleset-<flag>-<env>.json` = a Get Ruleset response, `audiences.json` =
List Audiences, etc.). These carry every field Step 1c/1d expects
(variation-level `percentage_included`, full `audience_conditions`), so
migration proceeds with **no fidelity loss** versus Option A — just
substitute "read this file" for the matching `curl` call in Step 1.
**B2 — Flattened per-flag summary export.** A single JSON array, one
entry per `(flag, environment)`:
```json
{
"name": "<flag name>", "key": "<flag key>", "description": "<...>",
"environment": "<env key>",
"config": {
"enabled": <bool>, "default_variation_key": "<key>",
"default_variation_name": "<name>",
"rules_detail": [
{
"key": "<rule key>", "type": "a/b" | "targeted_delivery" | "...",
"enabled": <bool>, "traffic_allocation": <basis points>,
"variation_names": ["<arm1>", "<arm2>", ...],
"audience_ids": [<id>, ...]
}
]
}
}
```
This is what a restricted/summary-only export token typically produces
(look for `has_restricted_permissions: true` in the payload as a tell).
Map it onto the same internal model Step 1c/1d builds, with these
**known gaps** — call each one out explicitly in the plan as a note next
to the affected flag, don't silently guess and stay silent about it:
- **No flag `variable_definitions`.** Treat the flag as variable-less and
apply "Optimizely's flag model" above: boolean shape only if the
variation keys are exactly `on`/`off`, otherwise the named-variant
struct shape (`{ variant: string }`) — **never** force custom-named or
3+ arm variations into a boolean flag. If the customer's code reads
variable values (not just the variation key) for these flags, ASK —
Option B2 can't tell you either way.
- **`targeted_delivery` (rollout) rules' `variation_names` is NOT a real
variation key — never use it as a Confidence variant name.** Rollout
rules always deliver a single `on` state (see "The Rule object": *"a
`targeted_delivery` rule usually has a single `on` variation"*); B2
export tools synthesize a **display label** for this slot instead of
the real key, built from the rule's own `name` — typically `"On
<environment> <audience name or 'Everyone'>"` (e.g. `"On production
Everyone"`). Treating that label as a variant creates a Confidence
variant the customer's code never checks for, silently breaking real
traffic. Instead:
- If **every** rule on the flag is `targeted_delivery` (no `a/b`/
experiment rule with real named variations), the flag is boolean:
map the delivered state to `on` (see "Optimizely's flag model" row
1) and ignore the literal label entirely.
- If the flag **also** has an `a/b`/experiment rule with real
variations, the rollout's target variant is ambiguous from B2
alone. If an earlier rule already matches the same audience at
100% (the rollout is unreachable — a common "test superseded by a
full rollout" pattern), note it as a **dead rule** in the plan and
drop it rather than inventing a variant. Otherwise ASK the user
which of the flag's real variants the rollout should deliver.
- **Duplicate variation names — collapse, don't block.** Rules whose
`variation_names` are all identical (common for CMS-generated
experiments where both arms were later pinned to the same content)
are serving one effective variant. Migrate as **fully rolled out**:
one variant, one rule at 100%, no split. Note it in the plan
("both arms serve the same variant — collapsed to a single 100%
rollout"). Do NOT mark these BLOCKED and do NOT create a split
between identical variants.
- **No per-variation split**, only the rule-level `traffic_allocation`.
**NEVER silently assume a split** — a wrong split on a used flag
means flicker and corrupted metrics. Decide by variant count:
- One distinct variant (or all names identical, above) → 100% to
that variant; no split needed.
- Two or more distinct variants → this is an experiment with an
unknown split. Apply the **Migration Scope Policy**: excluded by
default (live), or migrated as a rollout to a user-confirmed
variant (stale). Only migrate it *as an experiment with a split*
if the user explicitly supplies the split (e.g. from the
Optimizely UI's Variations page or a screenshot) — record the
source of the numbers in the plan.
Prefer asking the customer for the fuller `/ruleset` response
(Option B1) — it carries the real per-variation
`percentage_included`.
- **No audience conditions**, only `audience_ids`. If a rule's
`audience_ids` is empty, it targets everyone (no gap). If non-empty,
the plan **cannot** express that targeting — mark the rule BLOCKED
pending the audience detail and ask the user for the `/v2/audiences`
export (or a live token) to resolve it rather than guessing "everyone."
- **Ignore** experiment-reporting metadata that isn't part of the flag
model: `layer_experiment_id`, `primary_metric`,
`fetch_results_ui_url`, `created_by_user_email`,
`has_restricted_permissions`, `custom_fields`. None of it affects the
Confidence targeting rule. Exception: `days_running` and
`updated_time` ARE used — they feed the live-vs-stale classification
in the Migration Scope Policy.
- A `config.enabled: false` (or rule `enabled: false`, or `status:
paused`) marks a paused/disabled flag — **excluded by default** per
the Migration Scope Policy (ask once; if the user opts them in,
migrate them OFF exactly like the live-API disabled case).
- **Not in this export at all** (invisible, not just incomplete) —
surface these as known unknowns in the plan rather than assuming
they don't exist:
- **Whitelists / forced variations** (per-user overrides forcing a
variation). Would map to Confidence override rules; ask the
customer whether any flags in scope use them (or request UI
screenshots).
- **Exclusion groups** (mutually exclusive experiments). The UI
shows them per experiment; the summary export doesn't.
- **Project archived status.** An archived Optimizely project still
exports its flags with `status: running`. Ask whether the exported
project is the live production project.
### Local testing (no Optimizely account needed)
For development and CI smoke tests, this skill ships with a fake
Optimizely REST API server under
`skills/migrate-optimizely/test-fixtures/`. It implements the read
endpoints with curated fixtures that exercise every operator-mapping
branch, plus a second (synthetic) project modeling the Option-B2
(summary-export) pattern. See that directory's `README.md` for usage —
short version is `python3 server.py`, then point this skill at
`http://127.0.0.1:4100` when prompted for the base URL (the fake server
serves both the `/flags/v1` and `/v2` routes on one port).
To exercise **Option B** specifically without a live account, point the
skill at
`skills/migrate-optimizely/test-fixtures/summary-export-sample.json`
(a synthetic B2-shaped export) when it asks for a file path.
---
## Optimizely REST API Reference
The migration uses these endpoints. All require
`-H "Authorization: Bearer $OPTIMIZELY_API_TOKEN"`. `PROJECT_ID` is the
project being migrated; `ENV_KEY` is an environment key (e.g.
`production`). **Option B1 files** are verbatim saves of these same
response bodies — the field names and shapes below apply unchanged.
> **Source of truth.** Field names and shapes here are taken from
> Optimizely's published API docs at
> <https://docs.developers.optimizely.com/feature-experimentation/reference>.
> If a scan or export contains a field or value this document doesn't
> cover, do NOT guess its meaning — fetch the relevant page of those
> docs (WebFetch) and check, then tell the user what you looked up.
> Exports from customer tooling can contain fields no documentation
> covers; if the docs don't resolve it either, surface it as an open
> question instead of assuming.
| Purpose | Endpoint |
|---------|----------|
| List flags (paginated) | `GET {flags}/projects/{PROJECT_ID}/flags?per_page=100&page=<n>` |
| Get one flag (variable definitions, environments) | `GET {flags}/projects/{PROJECT_ID}/flags/{FLAG_KEY}` |
| List a flag's variations | `GET {flags}/projects/{PROJECT_ID}/flags/{FLAG_KEY}/variations` |
| Get the ruleset for a flag in an environment | `GET {flags}/projects/{PROJECT_ID}/flags/{FLAG_KEY}/environments/{ENV_KEY}/ruleset` |
| List audiences (paginated) | `GET {v2}/audiences?project_id={PROJECT_ID}&per_page=100&page=<n>` |
| Get one audience | `GET {v2}/audiences/{AUDIENCE_ID}` |
| List environments | `GET {v2}/environments?project_id={PROJECT_ID}` |
`{flags}` = `https://api.optimizely.com/flags/v1`,
`{v2}` = `https://api.optimizely.com/v2`.
**Convention.** Field names are `snake_case`. Flag keys may be
`snake_case` or `kebab-case` and IDs are integers. **Percentages are in
basis points out of 10000** (`10000` = 100%, `5000` = 50%, `2500` =
25%). Audience `conditions` is a **JSON-encoded string** (parse it, then
walk it). The list endpoints return `{ "items": [...], "page": N,
"total_pages": M, ... }`.
### Optimizely's flag model
Optimizely Feature Experimentation has one configurable type — the
**flag** — but a flag's behavior in each environment is governed by an
ordered **ruleset**. All become Confidence flags:
> **Agent-internal mapping — never quote these shapes in conversation
> prose.** Describe the flag in words ("a simple on/off flag", "a flag
> with named variants"); literal schemas like `{ enabled }` belong only
> in the plan file or fenced code blocks.
| Optimizely concept | What it is | Confidence flag shape |
|--------------------|-----------|-----------------------|
| **Flag** (no variables, 2 variations named exactly `on`/`off`) | Boolean on/off feature | Boolean flag (`{ enabled }`); variations `on`/`off` |
| **Flag** (no variables, custom-named variations) | Named experiment arms with no payload (e.g. `control`/`treatment`, or 3+ arms) | Struct flag with **one `string` property** (e.g. `variant`); each variation → a variant whose `variant` value is its literal Optimizely key. **Do not force these into a boolean `{ enabled }` shape** — that's lossy for 2 differently-named arms and structurally impossible for 3+ arms. |
| **Flag with variables** | Returns typed variable values | Struct flag; one property per variable; each **variation** → a variant carrying its variable values |
| **Targeted delivery rule** | Roll a flag out to an audience at a % | One targeting rule: audience → payload, rollout % → variant split |
| **A/B test rule** | Experiment with weighted variations | One targeting rule: audience → payload, variation split by `percentage_included` |
**Which of the first two rows applies is a per-flag check, not a
blanket "no variables → boolean" rule:** only use the boolean shape when
`variable_definitions` is empty AND the variation keys are exactly
`on`/`off` (or a single boolean variable). Any other variable-less flag —
however many variations it has, whatever they're named — uses the named-
variant struct shape. This is common: legacy/classic Optimizely
experiments frequently declare no variables at all and rely purely on
named variations (`variation_1`/`variation_2`, custom labels, even
opaque UUIDs), and real accounts can have many such flags with 3+ arms.
> **Groups (exclusion groups).** Optimizely can place several rules/
> experiments in a **mutually exclusive group** sharing a traffic budget.
> Migrate each rule as its own Confidence targeting rule. The mutual
> exclusion maps to a Confidence **exclusivity group** via segment
> coordination on the **REST** backend — see "Exclusion-group mutual
> exclusion" under "Full-Fidelity Phase 1 via the Confidence REST API".
> On the MCP backend, mutual exclusion can't be reproduced; record the
> shared group as a note and surface the gap.
### The Flag object
- `key` (string used in code as the flag name), `name`, `description`
- `archived` (boolean) — archived flags are skipped by default
- `variable_definitions` — map of `key → { type, default_value }`.
`type` is one of `boolean`, `string`, `integer`, `double`, `json`.
`default_value` is always a **string** (parse per `type`). A flag with
no variables (or a single boolean variable) is a boolean flag.
- `environments` — map of `env_key → { enabled, status, rules_detail[],
priority }`. `enabled` is whether the flag is ON in that environment.
Each flag has a **separate ruleset per environment** — the migration
reads the ruleset for the chosen environment (Step 1).
### The Variation object (from `.../variations`)
- `key` (e.g. `on`, `off`, or a custom variation key), `name`
- `variables` — map of `variable_key → { value }` (the variable values
this variation serves). For a bare boolean flag the variations are
`on` (feature enabled) and `off` (feature disabled) with no variables.
### The Ruleset object (per environment)
- `rules` — map of `rule_key → Rule` (see below)
- `rule_priorities` — **ordered list of rule keys, first wins.**
Confidence evaluates targeting rules top-down, so emit one rule per
Optimizely rule in `rule_priorities` order.
- `enabled` — whether the ruleset (flag in this environment) is live. If
`false`, migrate the flag but keep it OFF (see disabled handling).
- `default_variation_key` / `default_variation_name` — the variation
served when **no rule matches** (typically `off`). Maps to the
catch-all final rule's variant.
### The Rule object
- `key`, `name`
- `type` — `targeted_delivery` (rollout), `a/b` (experiment),
`multi_armed_bandit` (adaptive — see notes), `feature_test` (legacy
experiment, treat like `a/b`)
- `enabled` — a disabled rule contributes nothing; skip it (but keep the
catch-all default)
- `percentage_included` — **rule-level traffic allocation** in basis
points (10000 = 100%). For `targeted_delivery` this is the rollout
percent; for `a/b` this is the percent of matched users who enter the
experiment.
- `variations` — map of `variation_key → { percentage_included,
variation_id }`. `percentage_included` here (basis points) is the
split **within** the included traffic and sums to 10000 across the
rule's variations. A `targeted_delivery` rule usually has a single
`on` variation at 10000.
- `audience_conditions` — the audience targeting (see "Audience
conditions"). Empty `[]` means "everyone".
- `audience_ids` — the numeric ids referenced by `audience_conditions`.
- `distribution_mode` — `manual` (fixed split), `stats_accelerator` /
`stats_engine` (adaptive — snapshot the current split and note it).
**Pagination.** Optimizely uses `page` (1-based) + `per_page` (≤ 100).
List responses carry `items[]`, `page`, and `total_pages`:
```
page = 1
LOOP:
resp = GET .../flags?per_page=100&page=<page>
process resp.items
if page >= resp.total_pages OR resp.items is empty → STOP
page += 1 → continue LOOP
```
Repeat the loop for `flags` AND `audiences`.
---
## Migration Scope Policy (what migrates, what doesn't)
Flag migration and experiment migration are different problems.
Confidence uses a different bucketing hash than Optimizely, so a user's
variant assignment **cannot** be preserved across the move. For a stable
flag (everyone gets the same thing) that's irrelevant; for a live
experiment it means users would be reshuffled between arms mid-test —
a flickering experience and corrupted metrics. The scope policy below
encodes that line. Classify **every** flag into exactly one category
during the scan, and present the scope summary (with counts) for
confirmation before planning.
| Category | How to detect | Default |
|----------|--------------|---------|
| **Stable flag / full rollout** — boolean flags, rollouts at 100% or 0%, single-variant rules | All rules are `targeted_delivery` at 0/10000 basis points, or every rule serves one effective variant | **Migrate** |
| **Same-variant experiment** — all of a rule's variation names identical | `variation_names` has duplicates covering all arms | **Migrate as fully rolled out** — one variant at 100%, no split (see "Duplicate variation names") |
| **Concluded / stale experiment** | A/B rule whose experiment is no longer actively measured (see "Live vs stale" below) | **Ask** — migrate as rolled-out to a confirmed variant, or exclude |
| **Live A/B test** | A/B rule with 2+ distinct variants, actively measured | **Exclude** — finish or conclude it in Optimizely first; migrating would reshuffle users and corrupt metrics |
| **Partial-% rollout** | `targeted_delivery` with `percentage_included` not 0 or 10000 | **Exclude** — same sampling problem: the included cohort can't be reproduced |
| **Adaptive (bandit / stats accelerator)** | `type: multi_armed_bandit` or adaptive `distribution_mode` | **Exclude** — Confidence allocations are static |
| **Paused / disabled flag** | Flag `status: paused` or ruleset `enabled: false` | **Exclude** — ask once; opt-in migrates them OFF |
| **Blocked** | Unsupported operators, missing audience data, etc. | **Excluded until resolved** (see Blocked) |
**Live vs stale: don't trust the export's `status`.** A rule exporting
as `status: running` does NOT mean anyone is still measuring that
experiment — real accounts contain experiments "running" untouched for
years (effectively frozen rollouts). Signals that a "running" experiment
is actually stale:
- `days_running` is large (rule of thumb: > 90 days with no recent
`updated_time` change) — genuinely live tests conclude in weeks
- all variation names are identical (someone pinned both arms)
- the project or surrounding config is archived
- the customer doesn't recognize it as an active test
When the scan finds "running" experiments, do NOT silently classify them
all as live (which excludes them) or all as stale (which migrates them).
Present the counts with the staleness signals and ask the user to
confirm which experiments are genuinely live — that list is usually
short and the customer knows it. Everything else is stale and can be
migrated as a rollout **if** the user confirms which variant (or split)
it should serve; without that confirmation it stays excluded and listed.
**Excluded ≠ forgotten.** Every excluded flag appears in the plan with
its category and a one-line reason, so the customer can revisit. The
user can override any category's default at the scope-confirmation step
("migrate the partial rollouts anyway as 100%" is their call, not
yours) — record overrides in the plan.
---
## Step Trackers
### Status markers
- `○ pending` — not started yet
- `◉ in progress` — currently running
- `⏸ awaiting user` — blocked on user input (e.g. picking a client or entity)
- `✓ done` — completed (add brief user-facing result)
- `⊘ skipped` — skipped by user
Use `⏸ awaiting user` whenever the workflow has asked a question and is
waiting for an explicit reply. This makes "I'm blocked on you" visible
to both agent and user, and prevents drifting into auto-progression
while a question is open.
**Never expose internal/technical details in the tracker.** No
pagination info, no API page counts, no internal field names. Show only
what matters to the user. **Update and re-display the tracker** at the
start and after each step completes.
### Execute progress bar (MANDATORY — every execute phase)
**Any** long-running write loop must show a live progress bar to the
user. This applies to **all** phases, not only flag create — including
**production waterfall / `_rulesets` rule import**, which is often the
longest loop and **must not** run with only occasional
`... created N rules` log lines.
| Execute command | Examples of loops that need a bar |
|-----------------|-----------------------------------|
| `execute access` | Creating groups, policies, Flag clients, sending invites, provisioning accepted users, sharing flags |
| `execute flags` | Creating/unarchiving flags, `:addFlagClient`, **importing targeting rules / segments / waterfall**, catch-alls, resolve gate |
| `execute code` | Per-flag file transforms / PRs |
**What counts as "visible" (Cursor / Claude Code UI):**
The bar must appear in the **chat transcript the operator reads without
expanding a collapsed tool panel**. Printing only into a background
shell whose UI shows `… N input + M output lines hidden` is **not**
enough — that is invisible progress and is a skill failure.
| Allowed (operator sees it) | Not allowed (looks like no progress) |
|----------------------------|--------------------------------------|
| Assistant message containing the bar line / block | Giant inline `python3 <<'PY'` heredoc with progress only inside collapsed shell output |
| Short shell that prints **only** the latest bar line (few lines of stdout) | Background job + silent waits / "Wait skipped" with no chat bar |
| Periodic chat updates while a long script runs | Final summary only after minutes of silence |
**Rules:**
1. Show the bar **before** the first write in a loop, then **update it
in a user-visible assistant reply** as work advances — at least every
item for small N (≲ 25), or every **10–25 items** / every ~15–30s for
large N. Never run a silent multi-minute batch with no chat updates.
2. Use `█` for completed and `░` for remaining, **20 characters** wide.
3. Always include: phase label, `current/total`, optional skipped/failed
counts, and the **current item** name (flag id, group id, rule, etc.).
4. When a subprocess/script runs the loop:
- Write the script to a **file** (e.g.
`.claude/plans/optimizely-execute-flags-run.py`) — do **not** paste
hundreds of lines into an inline heredoc (that collapses the shell
and hides the bar).
- Overwrite a progress file with the **latest single bar line** on
every item (or every 1–5 for huge N), and `print(..., flush=True)` /
`PYTHONUNBUFFERED=1`.
- While the job runs (foreground or background), **poll that file
every ~15–30s and paste the current line into a chat reply**, e.g.
`Execute Flags · create ████████████░░░░░░░░ 12/30 pricing-experiment`.
Waiting on a regex alone without chat paste is insufficient.
- Silent `nohup`, a final summary only, or sparse `... created
50/100/150` counters **without** a `█`/`░` bar **are not allowed**.
5. At the end of each loop, show a full bar + counts **in chat**.
**Preferred single-line form** (easy to stream from a script **and** paste
into chat):
```
Execute Flags · create ████████████░░░░░░░░ 12/30 pricing-experiment
Execute Flags · targeting rules ██████████░░░░░░░░░░ 401/867 ugp-flag · UGP Audience
Execute Flags · resolve verify ████████████████████ 519/519
```
Block form is also fine **in chat**:
```
───── Execute Flags ───────────────────────────────────────
Progress: [██████░░░░░░░░░░░░░░] 5/15 (1 skipped)
Current: pricing-experiment
────────────────────────────────────────────────────────────
```
Examples for other loops:
```
───── Execute Access · invites ────────────────────────────
Progress: [████████████░░░░░░░░] 60/100
Current: user@example.com
───────────────
[…] pełny plik w paczce .zip
Files in this package (23)
- SKILL.md 212 KB
- access.md 66 KB
- test-fixtures/.gitignore 1 KB
- test-fixtures/README.md 16 KB
- test-fixtures/iam-export-sample.json 2 KB
- test-fixtures/seed_optimizely.py 8 KB
- test-fixtures/server.py 36 KB
- test-fixtures/summary-export-sample.json 15 KB
- test-fixtures/verify_migration.py 7 KB
- test-fixtures/phase2-examples/README.md 4 KB
- test-fixtures/phase2-examples/java-server/pom.xml 1 KB
- test-fixtures/phase2-examples/java-server/src/main/java/com/example/HomepageService.java 1 KB
- test-fixtures/phase2-examples/node-decide-server/package.json 1 KB
- test-fixtures/phase2-examples/node-decide-server/src/server.js 2 KB
- test-fixtures/phase2-examples/node-legacy-fullstack/package.json 1 KB
- test-fixtures/phase2-examples/node-legacy-fullstack/src/index.js 1 KB
- test-fixtures/phase2-examples/openfeature-provider-swap/package.json 1 KB
- test-fixtures/phase2-examples/openfeature-provider-swap/src/App.tsx 2 KB
- test-fixtures/phase2-examples/openfeature-provider-swap/src/provider.ts 3 KB
- test-fixtures/phase2-examples/python-server/app.py 1 KB
- test-fixtures/phase2-examples/python-server/requirements.txt 1 KB
- test-fixtures/phase2-examples/react-client/package.json 1 KB
- test-fixtures/phase2-examples/react-client/src/App.jsx 2 KB
Versions
The database has no other skills named migrate-optimizely.
Database snapshot: 13.11.2026 · package version 40717792c109 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100optimizely-webhooks
Receive and verify Optimizely Feature Experimentation webhooks. Use when setting up Optimizely webhook handlers, debugging X-Hub-Signature verification, or handling project.datafile_updated and project.ruleset_updated events. - 91migrate-posthog
Migrate feature flags from PostHog to Confidence SDK. Use when the user says /migrate-posthog, asks to migrate PostHog flags, or transform SDK code to Confidence. - 95flags-sdk
Implement feature flags in Next.js or SvelteKit code with the Flags SDK (`flags` npm package). Use when installing or configuring the SDK, declaring flags with `flag()`, setting up Project Connections, wiring a provider adapter (`@flags-sdk/vercel`, Statsig, LaunchDarkly,… - 91migrate-eppo
Migrate feature flags from Eppo to Confidence SDK. Use when the user says /migrate-eppo, asks to migrate Eppo flags, or transform SDK code to Confidence. - 100openfeature
OpenFeature vendor-agnostic feature flag SDK: installation, evaluation, providers. Use when implementing feature flags, A/B testing, or progressive rollouts. - 100experiment-sdk-testing
Umbrella for experimentation-SDK test harnesses: the shared offline-datafile / hermetic-init pattern (commit a point-in-time flag/experiment config fixture, initialize the SDK with no network, pin arms per test, assert assignment integrity), with per-vendor references for…