Manage Flag Lifecycle

Manage metadata, archive readiness, archive/unarchive, and deletion for Harness FME feature flags. Related: update-flag-targeting (targeting), discover-feature-flags (stale flags), cleanup-feature-flags (code removal).

Tools

Works through the Harness MCP server or the Harness CLI; names are from tool-map.md.

Output

Structured summary per operation-summary.md:

• Metadata: before → after for changed fields
• Archive readiness: verdict (ready / caution / blocked), per-env impressions.lastImpressionAt, active experiments, dependents (if checked)
• Archive/unarchive/delete: verification result (status or 404), per-env impact
• Next steps or follow-up actions

Instructions

Follow write-safety.md for all writes. Concepts are in concepts.md.

Phase 1: Establish scope

Follow scope-establishment.md. Restate scope before proceeding.

Phase 2: Collect inputs

Ask for flag name(s) and the operation. For metadata updates, ask which fields to change. For delete definition, ask for the target environment ID. If the user asks "is this flag safe to archive", run the archive readiness gate (Phase 5) and stop there.

Phase 3: Read current state

Get flag metadata. For archive/unarchive/delete operations, also list definitions through every page using explicit MCP filters.limit: 100; size does not control this list. Follow pagination for definitions, environments and experiments; incomplete inventories stop readiness/deletion checks. Report current metadata (description, tags, owners, rolloutStatus, status) and per-env definition summary (environment ID/name, impressions.lastImpressionAt, isKilled, defaultTreatment).

Phase 4: Metadata update

If updating rollout status, list rollout statuses first, resolve the user's name to the UUID, then show the resolved name. Tags and owners are arrays and replaced whole in a merge patch. Read first, merge the user's change, and send the full new array.

Present the plan: <flag> metadata update — <reason>. Show before → after for each changed field. STOP and confirm per write-safety.md.

Update flag with rolloutStatus as {id: "<uuid>"}. Verify and confirm fields match the plan.

Phase 5: Archive readiness gate

Run every time before archive, even if checked earlier. Four checks gather data, then present the verdict per concepts.md and write-safety.md:

1. Impressions per environment: List definitions for the flag. Record impressions.lastImpressionAt (ISO-8601; null = never evaluated; absent = unknown) for each environment and note whether it's production.
2. Experiment check: List experiments for this flag across all environments with status ACTIVE and PAUSED, applying the shared pagination completeness checks (both status queries on CLI); a full page with a page-length total still needs another request. An incomplete scan stops the write. ACTIVE → blocked (STOP). PAUSED → caution (warn, require explicit acknowledgment per write-safety.md). COMPLETED → ignore.
3. Dependent flags: Opt-in scan per tool-map.md. If declined, mark dependents: unchecked.
4. Already archived: Check the flag's status field. If ARCHIVED, report it and skip archive (no-op).

Present the verdict (ready / caution / blocked) per concepts.md, with every reason. blocked stops the archive; caution needs explicit acknowledgment. Recommend cleanup-feature-flags first if any production environment has recent traffic. STOP here if the user asked "is this safe to archive".

Phase 6: Archive

Run the readiness gate (Phase 5). If blocked, STOP. If caution, require explicit acknowledgment. Explain: "Archiving <flag> affects all environments. SDKs will return control."

Confirm per write-safety.md: "This archives <flag> in all environments. SDKs will return control. Archive?"

Archive flag with audit comment and title. On 409 (OPA governance): report it, never bypass, never delete instead. STOP. Verify: status field is ARCHIVED.

Phase 7: Unarchive

Read the flag and all definitions first (Phase 3). Targeting resumes as it was when the flag was archived. Confirm per write-safety.md: "Unarchiving <flag> will resume the previous targeting. <per-env summary>. Unarchive?"

Unarchive flag with audit comment and title. On 409 (dependents block it): report the error. STOP. Verify: status field is ACTIVE.

Phase 8: Delete definition (one environment)

List environments to check isProduction. List experiments for the flag (ACTIVE and PAUSED) scoped to this environment, completing every page per the experiment check. ACTIVE → blocked: STOP; acknowledgement cannot permit definition deletion. PAUSED → caution: warn and require explicit acknowledgement. COMPLETED → ignore. An incomplete or failed experiment scan also stops deletion. Do not pause/complete an experiment automatically to bypass the block; resolving its lifecycle is a separate approved workflow followed by a fresh check. Read the current definition and report its live defaultTreatment and whether it's killed, so the confirmation names what's being removed, not just the environment. Explain: "Deleting the <flag> definition in <env> (currently serving <defaultTreatment>) means SDKs in that environment will get control." Only after the gate passes, confirm per write-safety.md.

Delete definition. Verify with a 404 on get. Expect 404. If still present, report failure.

Phase 9: Delete flag

Prefer archive. Explain that delete is permanent and also deletes every environment's definition. Before deleting, run the dependent-flag scan (Phase 5 check 3), because a dependent makes the delete fail with an unhelpful error. Require archive first (run Phase 6) plus a second, separate confirmation naming the flag. Only proceed if the user explicitly confirms both steps.

Confirm: "This permanently deletes <flag> and all its definitions. This can't be undone. Delete?" Delete flag. If the delete fails, report the error and STOP. Verify with a 404 on get. Expect 404. If still present, report failure.

Phase 10: Bulk (explicit list ≤ 20 flags)

For discovering candidates across a project, route to discover-feature-flags. Run the archive readiness gate (Phase 5) per flag. Present one table: Flag | Verdict | Reasons. Confirm once for the ready ones only. Each caution flag needs its own acknowledgment; blocked flags are skipped. Execute sequentially and report per-flag results.

Examples

• "Update the description for dark-mode to 'Enable new dark theme UI'" — Metadata update; confirm and update.
• "Is new-checkout-flow safe to archive?" — Run readiness gate (Phase 5); report verdict and stop.
• "Archive beta-feature" — Readiness gate, confirm, archive, verify.
• "Unarchive holiday-promo" — Read definitions, show what will resume, confirm, unarchive, verify.
• "Delete the test-flag definition in staging" — Complete the environment-scoped experiment check; ACTIVE blocks, PAUSED needs acknowledgement. Only then confirm, delete and verify 404.
• "Delete old-experiment" — Prefer archive; if user insists, archive first, confirm again, delete flag, verify 404.
• "Change the rollout status to 'Complete' for launched-feature" — Resolve status name to UUID, confirm, update, verify.

Performance Notes

• One fully paginated definition inventory covers a flag's environments; it can require multiple requests. Never treat a page as the complete set.
• Dependent flag scan cost: one paginated definition inventory per flag in the project. Offer it as opt-in per tool-map.md.
• Bulk operations (≤ 20): readiness checks are parallel reads; writes are sequential.

Troubleshooting

See tool-map.md for generic errors.