Feature Flag Lifecycle Management in Shipping and Launch Processes: A Complete Guide

Feature flag lifecycle management integrates feature toggles into every stage of the OpenCode model—from specification through deployment—enabling teams to ship safely with instant rollback capabilities.

Feature flag lifecycle management is the systematic practice of governing feature toggles from creation to retirement within continuous delivery pipelines. The Agent-Skills repository by Addy Osmani implements this through a structured six-stage workflow that embeds flags into the entire development lifecycle. This approach ensures that every new capability can be deployed to production hidden behind a flag, then progressively exposed to users with full monitoring and automated safeguards.

How Feature Flags Flow Through the OpenCode Model

The lifecycle follows the OpenCode model’s six-stage flow—DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP—with the feature-flag workflow woven into each stage. According to the skills/shipping-and-launch/SKILL.md file, this integration ensures that flags are treated as first-class artifacts throughout the pipeline.

Define Stage: Specification-Driven Flag Creation

During the DEFINE stage, governed by the spec-driven-development skill, engineers write a specification that explicitly records the flag name, default state, and rollout strategy. This spec lives alongside the code in a version-controlled file such as docs/feature-flags/awesome-search.yaml.

Recording the flag in the specification from day one guarantees that the intent is clear to reviewers and future maintainers. It also establishes the removal criteria before any code is written, preventing permanent technical debt.

Plan Stage: Task Breakdown for Flag Management

The PLAN stage, managed by planning-and-task-breakdown/SKILL.md, includes the work-breakdown for flag implementation. The plan outlines specific tasks for flag implementation, CI gate configuration, roll-out monitoring, and flag removal.

By scheduling flag-related steps just like any other feature work, the plan ensures that the removal criteria are tracked and that the team does not leave dead code or stale configurations in the system.

Build Stage: Incremental Implementation

During the BUILD stage, guided by incremental-implementation/SKILL.md, developers commit the flag booleans—often via a config file or environment variable—and guard the new code paths with a conditional check. The flag is checked in but kept disabled by default.

This approach allows the code to be merged continuously without exposing the feature to users. It enables continuous integration and delivery while keeping the new capability hidden until the verification and rollout phases.

Verify Stage: Dual-State Testing

The VERIFY stage, combining test-driven-development and debugging-and-error-recovery skills, requires automated tests that run both with the flag on and off. CI pipelines run the full test matrix, and a canary or staging environment flips the flag on for a subset of traffic.

This dual-state testing detects regressions early and validates that the flag gating works correctly before any production exposure. It ensures that the system behaves correctly regardless of the flag’s state.

Review Stage: Code Review Quality Gates

During the REVIEW stage, governed by code-review-and-quality/SKILL.md, pull-request reviewers check that the flag follows the repository’s feature-flag guidelines. They verify naming conventions, default state, documentation, and the presence of a removal plan.

These quality gates prevent accidental permanent flags and enforce a clean, auditable implementation. They ensure that every flag has a clear path to retirement.

Ship Stage: Gradual Rollout and Launch

The SHIP stage, defined in skills/shipping-and-launch/SKILL.md and triggered by .claude/commands/ship.md, executes the gradual rollout to production. The flag is progressively exposed using the defined strategy (e.g., 1% → 10% → 100%), while monitoring dashboards watch for errors, performance impact, and user metrics.

If issues arise, the team can instantly roll back by toggling the flag off. Once the feature is stable and reaches 100% rollout, the flag is turned on for all users and later removed in a follow-up change, eliminating dead code.

Implementation Examples

The following snippets illustrate how a typical feature flag is handled in a JavaScript project following the Agent-Skills workflow.

1. Define the Flag (Spec-Driven Phase)

# docs/feature-flags/awesome-search.yaml

name: awesome-search
description: Enable the next-generation search UI
default: false
rollout:
  strategy: gradual
  steps:
    - percent: 1
    - percent: 10
    - percent: 100
removal-criteria: "All automated tests pass with flag on and performance impact < 5%."

Stored in the repository, this spec is extracted by the spec-driven-development skill during the DEFINE stage.

2. Implement the Flag in Code (Build Phase)

// src/flags.js
export const flags = {
  awesomeSearch: process.env.AWESOME_SEARCH === 'true',
};

// src/search.js
import { flags } from './flags.js';

export function renderSearch() {
  if (flags.awesomeSearch) {
    return renderAwesomeSearchUI(); // new UI
  }
  return renderLegacySearchUI();   // existing UI
}

The flag defaults to false because the environment variable is not set in CI, keeping the feature hidden during BUILD.

3. Test Both States (Verify Phase)

// tests/search.test.js
import { renderSearch } from '../src/search.js';
import { flags } from '../src/flags.js';

describe('Search UI', () => {
  test('renders legacy UI when flag is off', () => {
    process.env.AWESOME_SEARCH = 'false';
    expect(renderSearch()).toMatchSnapshot(); // legacy snapshot
  });

  test('renders awesome UI when flag is on', () => {
    process.env.AWESOME_SEARCH = 'true';
    expect(renderSearch()).toMatchSnapshot(); // new snapshot
  });
});

CI runs the test suite twice—once with the flag set to false and once to true—ensuring dual-state coverage.

4. Gradual Rollout Script (Ship Phase)

#!/usr/bin/env bash

# scripts/rollout-awesome-search.sh

set -e

# Example using a simple feature-flag service CLI

flagctl set awesome-search --percentage 1
sleep 300   # let traffic settle

if monitor --error-rate < 0.1%; then
  flagctl set awesome-search --percentage 10
  sleep 300
  # ... continue until 100%

fi

The shipping-and-launch skill calls this script during the SHIP step, executing the gradual percentage rollout.

5. Flag Removal (Post-Launch)

#!/usr/bin/env bash

# scripts/remove-awesome-search.sh

set -e

# 1️⃣ Delete flag config

git rm docs/feature-flags/awesome-search.yaml
git commit -m "Remove awesome-search flag definition"

# 2️⃣ Unwrap code

apply_patch <<'PATCH'
--- a/src/search.js
+++ b/src/search.js
@@
-  if (flags.awesomeSearch) {
-    return renderAwesomeSearchUI();
-  }
-  return renderLegacySearchUI();
+  return renderAwesomeSearchUI(); // flag removed, always on
 PATCH

After the flag reaches 100% and passes the removal criteria, a follow-up change runs the removal script to eliminate technical debt.

Key Repository Files

The following files define the feature-flag lifecycle management system in the Agent-Skills repository:

File	Role
skills/shipping-and-launch/SKILL.md	Describes the full shipping and launch workflow, including flag handling.
skills/spec-driven-development/SKILL.md	Defines how specs (including flag specs) are created and stored.
skills/planning-and-task-breakdown/SKILL.md	Shows how flag-related tasks are broken down and scheduled.
skills/incremental-implementation/SKILL.md	Guides the implementation of guarded code paths.
skills/test-driven-development/SKILL.md	Explains dual-state testing for flags.
skills/code-review-and-quality/SKILL.md	Lists review checklist items for feature flags.
.claude/commands/ship.md	Command that triggers the SHIP skill, which runs rollout scripts.

Summary

• Feature flag lifecycle management integrates toggles into every phase of the OpenCode model, from definition to removal.
• Each stage—DEFINE, PLAN, BUILD, VERIFY, REVIEW, SHIP—contains specific flag-related tasks documented in the Agent-Skills repository.
• Dual-state testing ensures code works correctly whether flags are enabled or disabled.
• Gradual rollout scripts automate percentage-based exposure while monitoring error rates.
• Removal criteria defined in the specification phase prevent permanent technical debt by mandating flag cleanup after full launch.

Frequently Asked Questions

What is the OpenCode model in feature flag lifecycle management?

The OpenCode model is a six-stage software delivery framework—DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP—implemented in the Agent-Skills repository. According to skills/shipping-and-launch/SKILL.md, this model treats feature flags as first-class artifacts that must pass through each stage with specific validation criteria, ensuring safe incremental delivery.

How does the VERIFY stage ensure feature flag safety?

The VERIFY stage, governed by skills/test-driven-development/SKILL.md and skills/debugging-and-error-recovery/SKILL.md, mandates dual-state testing. CI pipelines execute the full test matrix twice—once with the flag enabled and once disabled—while canary environments expose the flag to limited traffic. This detects regressions in both code paths before production exposure.

What triggers the gradual rollout in the SHIP stage?

The SHIP stage is triggered by the .claude/commands/ship.md command, which invokes the shipping-and-launch skill. This executes rollout scripts—such as scripts/rollout-awesome-search.sh—that progressively increase traffic exposure (typically 1% → 10% → 100%) while monitoring error rates and performance metrics. If thresholds are exceeded, the script can instantly roll back the flag to zero percent.

When should feature flags be removed from the codebase?

Feature flags should be removed immediately after reaching 100% rollout and satisfying the removal criteria documented in the original specification (e.g., docs/feature-flags/awesome-search.yaml). According to skills/spec-driven-development/SKILL.md, the removal process involves deleting the flag configuration, committing the change, and unwrapping the conditional code to eliminate the legacy path, thereby preventing accumulation of technical debt.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}