flag-rollout
Skill2 starsChanged 5 months agoMITView on GitHub
Phased rollout discipline for production. Ship code default-OFF, ramp 1%→10%→50%→100% with monitoring windows, auto-rollback on metric breach, scheduled cleanup. The "phased delivery in prod" backbone.
In this repository60 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- analyzeSkill
- animation-disciplineSkill
- api-versioningSkill
- autopilotSkill
- browser-e2eSkill
- characterizeSkill
- clarifySkill
- codemodSkill
- constitution-compactSkill
- constitutionSkill
- context-budgetSkill
- creative-webSkill
- db-migrationSkill
- debugSkill
- detect-stackSkill
- dispatch-criteriaSkill
- dreamSkill
- experimentSkill
- fastapiSkill
- flag-cleanupSkill
- flask-realtimeSkill
- framework-detectorSkill
- front-end-designSkill
- grill-meSkill
- handoffSkill
- image-generationSkill
- implementSkill
- initiativeSkill
- instinctSkill
- loopSkill
- nextjsSkill
- observabilitySkill
- okr-alignSkill
- parallel-swarmSkill
- pivotSkill
- planSkill
- pr-bodySkill
- prime-disciplineSkill
- prod-observabilitySkill
- react-nodeSkill
- react-viteSkill
- release-trainSkill
- researchSkill
- reviewSkill
- security-guardSkill
- self-healSkill
- shipSkill
- skill-creatorSkill
- specifySkill
- tailwind-disciplineSkill
- tasksSkill
- tdd-loopSkill
- token-budgetSkill
- typographySkill
- verify-loopSkill
- verifySkill
- wip-checkpointSkill
- <kebab-case-skill-name>Skill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 4 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 31
Pre-check — is the target flag still mid-ramp?: Before emergency-100%, query the provider for the *target* flag's current rollout %.
- Distinctive: line 49
If exit gate not met → wait
- Distinctive: line 50
If exit gate met + next stage exists → ramp
- Very specific: line 56
If at 100% for ≥ cleanup_after → invoke flag-cleanup skill
- Very specific: line 57
If auto_rollback_threshold breached → /rollback-flag <name> immediately
- Distinctive: line 63
When ramping, the SLO burn-rate becomes the rollback trigger.
- Very specific: line 83
Don't ramp two related flags simultaneously: If db_flag is the foundation for api_flag, ramp db first to 100%, then start api.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Flag Rollout
Ship code default-OFF. Ramp through cohorts. Auto-rollback on metric breach. Clean up when stable.
The ramp ritual
| Stage | Flag value | Wait | Exit gate |
| Land | default-OFF | merge | flag exists in provider, default-OFF deployed |
| Internal | staff ON | 1-2 days | zero errors, dogfooding feedback positive |
| Canary | 1% | 24-48 hours | error rate ≤ baseline + 0.1pp; p95 latency within budget |
| 10% | 10% | 48-72 hours | error rate ≤ baseline + 0.05pp; engagement metric ≥ baseline |
| 50% | 50% | 3-7 days | success metric significant (per spec's success_metric) |
| 100% | 100% (default-ON in config) | observation | one full week without regression |
| Cleanup | flag deleted | T+cleanup_after | spec marked complete; flag removed from code |
Each row's exit gate is mechanical — read from observability + flag provider, not from feel.
Emergency path — hotfixes (Round 12 D)
A hotfix is corrective, not a new capability, so it skips the gradual ramp. When a spec carries service_tier: emergency (set by the hotfix pipeline):
Pre-check — is the target flag still mid-ramp? Before emergency-100%, query the provider for the target flag's current rollout %. Two cases:
- Target is at 100% (or unflagged baseline code). The failure is live for everyone → emergency deploy to 100% immediately. This is the normal hotfix case.
- Target is a NEW-feature flag still mid-ramp (< 100%, e.g. the bug was found in the 10% canary). Do NOT jump to 100%. Deploy the fix to the current ramp cohort only (match the present %), keep
auto_rollbackON, and let the normal ramp resume once the fix is confirmed. Promoting an unvalidated feature to everyone under cover of a "hotfix" defeats the ramp's blast-radius limit — you'd be exposing the whole feature to 100% of users, not just fixing the bug for the cohort already seeing it.
| Stage | Flag value | Wait | Exit gate |
| Emergency deploy | 100% if target already at 100%, else current ramp % | none | fix merged + evidence bundle PASS |
| Watch | unchanged from deploy | 30-min observation | auto_rollback STAYS ON — slo.yml thresholds (error_rate ≥1%/5m, p95 ≥2x/10m) are the safety net that replaces the gradual ramp |
The gradual ramp exists to limit blast radius of new behavior. A hotfix's job is to reduce an already-live failure, so waiting at 1% would prolong the incident — but only for behavior that is already at that exposure. A fix for a feature still at 10% stays at 10%. The auto-rollback guardrail is what keeps emergency-100% safe: if the "fix" makes things worse, the SLO breach reverts it within minutes. When the emergency deploy succeeds, fire repository_dispatch: flag-shipped → the hotfix issue moves to SHIPPED (same as a normal flag at 100%).
Process
- Read spec's
## Rolloutsection — flag.name, flag.type, default, success_metric, auto_rollback_threshold, cleanup_after. - Verify flag exists in the flag-provider (OpenFeature / LaunchDarkly / PostHog / Unleash). Create if missing.
- Check current stage — query provider for current rollout %.
- Decide next action:
- If exit gate not met → wait
- If exit gate met + next stage exists → ramp
- When the flag reaches 100% → mark the spec issue SHIPPED (Round 11 C). Fire a repository_dispatch so
issue-lifecycle.ymlmoves the board:gh api repos/:owner/:repo/dispatches -f event_type=flag-shipped \ -F client_payload[issue_number]="$(awk '/^github_issue:/{print $2}' specs/active/<spec-id>*.md)" - If at 100% for ≥ cleanup_after → invoke
flag-cleanupskill - If auto_rollback_threshold breached →
/rollback-flag <name>immediately
- Document the decision in
.claude/memory/playbooks/flag-rollout.mdor per-flag log. - Schedule next check (cron or scheduled-task) at the wait-window for this stage.
Auto-rollback discipline
When ramping, the SLO burn-rate becomes the rollback trigger. Define in the spec:
auto_rollback_threshold:
error_rate: ">= 1% for 5 minutes"
p95_latency_increase: ">= 2x baseline for 10 minutes"
custom: "checkout_failure_rate >= 0.5%"The release agent's post-deploy watch monitors these. If breached:
- Flip flag to 0% (rollback-flag skill)
- Open incident (
/incident-start) - Post to Slack / page on-call
- Don't revert code — flag flip is sufficient and faster
Hard rules
- Default-OFF unless proven otherwise. Even for "small" changes. Costs nothing; saves everything.
- Don't skip stages. No "1% → 100%" leaps. Each stage is its own learning.
- Wait the window. Bugs surface after time, not after request count. A 24h window is a 24h window even if 1% is silent.
- Cleanup is part of done. A 100% flag still in the codebase is debt. Schedule cleanup at
cleanup_after. - Don't ramp two related flags simultaneously. If
db_flagis the foundation forapi_flag, ramp db first to 100%, then start api.
References
- Provider-agnostic: OpenFeature spec (https://openfeature.dev/specification/)
- LaunchDarkly best practices (https://docs.launchdarkly.com/guides/best-practices)
- Pete Hodgson's "Feature Toggles" patterns (martinfowler.com)
- See also:
.claude/memory/playbooks/flag-rollout.md,flag-kill.md,flag-cleanup.md
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

