kortix-ai Proactive and schedule-driven; covers the full flag inventory every run, growing the ledger over time as flags are removed or newly flagged.
Step 0 — Orient and resume
# Read the durable ledger first — known flags, their last-seen rollout state,
# what's already been removed, and what's already flagged for human review.
cat .kortix/memory/flag-cleanup-log.md 2>/dev/null || echo "(no ledger yet — first run)"
# Check any open cleanup PRs from a prior run.
gh pr list --repo {{target_repo}} --state open \
--search 'in:title "chore(flags)" OR label:feature-flags' \
--json number,title,headRefName,statusCheckRollup,url
If a prior cleanup PR is still on CI or in review, don't duplicate the work — drive a stalled-but-fixable PR to green, otherwise leave it for review and move on to flags it didn't cover.
Step 1 — Freshen the repo
DEFAULT_BRANCH=$(gh repo view {{target_repo}} --json defaultBranchRef -q .defaultBranchRef.name)
if [ -d /workspace/repo/.git ]; then
cd /workspace/repo && git fetch origin && git checkout "$DEFAULT_BRANCH" && git reset --hard "origin/$DEFAULT_BRANCH"
else
git clone --filter=blob:none https://github.com/{{target_repo}}.git /workspace/repo
cd /workspace/repo
git checkout "$DEFAULT_BRANCH"
fi
Never classify or remove a flag against a stale checkout.
Step 2 — Inventory every flag
cd /workspace/repo
# Flag definitions/registry — adapt the path to this repo's convention
# (e.g. flags.ts, feature-flags.json, a flags/ directory).
grep -rnE "(defineFlag|registerFlag|FEATURE_FLAGS|flags\.(json|ya?ml))" --include="*.ts" --include="*.tsx" --include="*.json" . 2>/dev/null
# Call sites — every place a flag is actually read.
grep -rnE "(isEnabled|useFeatureFlag|getFlag|flags\.[a-zA-Z_]+)\(" --include="*.ts" --include="*.tsx" . 2>/dev/null
For every flag found, record: name, where it's declared, every call site, and
(if the rollout percentage or state is tracked in-repo, e.g. a config file) its
current rollout value. Cross-reference git log -1 --format=%ai -- <flag file or last touched call site> for the flag's last-touched date.
Step 3 — Classify each flag
| Classification | Criteria | Action |
|---|---|---|
| Fully rolled out | Rollout is 100% / hardcoded true with no variant left, or explicitly marked GA |
Remove — inline the "on" branch, delete the "off" branch |
| Long dead | No call site found anywhere in the repo, or unchanged (declaration and all call sites) for more than {{min_flag_age_days}} days with a rollout that was already at 0% or 100% |
Remove entirely, including the dead declaration |
| Partial rollout | Rollout between 0% and 100% exclusive, percentage-based, or user/cohort-targeted | Do not touch. Log in the ledger for human review |
| Active experiment | Tied to an A/B test, gradual ramp still in progress, or flag age under {{min_flag_age_days}} days with no clear rollout signal |
Do not touch. Log in the ledger for human review |
When a flag's rollout state can't be determined from the repo alone (e.g. it's controlled by an external system this agent has no access to), treat it as ambiguous and log it for human review — never guess.
Step 4 — Isolated cleanup branch
cd /workspace/repo
BRANCH="chore/flag-cleanup-$(date +%Y-%m-%d)"
git checkout -b "$BRANCH" "origin/$DEFAULT_BRANCH" # or check out an existing branch from this run
Step 5 — Remove each eligible flag
For every flag classified fully rolled out or long dead:
- Find every call site (
if (flags.x),useFeatureFlag('x'), etc.). - Inline the branch that survives (the "on" branch for fully-rolled-out flags; nothing survives for long-dead flags with no live call site).
- Delete the now-unreachable branch and any helper code that only existed to support it.
- Remove the flag's declaration from its registry/config file.
- Remove now-unused imports and any tests that only exercised the dead branch; update tests that exercised the surviving branch so they no longer gate on the flag.
Do this one flag at a time so a single bad removal is easy to isolate and revert.
Step 6 — Full verification suite (the gate)
The removal is not ready until every check is green.
cd /workspace/repo
pnpm install 2>&1 | tee /tmp/flag-install.log
pnpm typecheck 2>&1 | tee /tmp/flag-typecheck.log
pnpm lint 2>&1 | tee /tmp/flag-lint.log
pnpm build 2>&1 | tee /tmp/flag-build.log
pnpm test 2>&1 | tee /tmp/flag-unit.log
pnpm test:integration 2>&1 | tee /tmp/flag-integration.log # if < ~10 min
Interpreting failures:
| Failure | Action |
|---|---|
| Typecheck/build error from a removed branch's dependency | Fix the mechanical fallout (unused import, dangling type); if non-mechanical, revert that one flag's removal and log it |
| Test failure for the removed flag | Expected if the test only covered the dead branch — delete it; if it covered the surviving branch, fix the test |
| Test failure in an UNRELATED area | File it as a note (likely pre-existing); don't revert unless you can prove causation |
| Any failure you can't resolve in a few lines | Revert that flag's removal, log it as deferred with the reason, keep the rest of the batch |
Step 7 — Commit
cd /workspace/repo
git add -A
git commit -m "chore(flags): remove stale feature flags $(date +%Y-%m-%d)
Removed: <flag-a> (fully rolled out), <flag-b> (long dead)
Verification: typecheck ✓ lint ✓ build ✓ unit ✓ integration ✓"
Step 8 — Open the PR (only when Step 6 is fully green)
A partial green (checks skipped/timed out) is NOT acceptable — rerun or debug.
cd /workspace/repo
git push origin "$BRANCH"
gh pr create --repo {{target_repo}} --base "$DEFAULT_BRANCH" --head "$BRANCH" \
--title "chore(flags): remove stale feature flags ($(date +%Y-%m-%d))" \
--label feature-flags \
--body "Generated by the flag-cleanup agent. The full suite passed in the
sandbox before this PR was opened.
**Removed (fully rolled out or long dead):**
- <flag-a> — fully rolled out, last touched <date>
- <flag-b> — long dead, no live call site found
**Left untouched (flagged for human review):**
- <flag-c> — partial rollout at <percentage>%
- <flag-d> — active experiment
A human owns the merge."
Step 9 — Update the ledger
Append a dated entry to .kortix/memory/flag-cleanup-log.md (see
<ledger-format>), then open + self-merge a scoped change request for the
ledger update only.