RFC: ADR-006 — Feature flags for concurrent development with partial conflicts

[scottschreckengaust]

Summary

Define when and how to use feature flags to enable concurrent development on overlapping areas without blocking merges, while maintaining system stability and providing clear ownership of flag lifecycle.

Use case and motivation

Problem today:

1. Two agents/humans working on related but non-identical features in the same area must serialize — one waits for the other to merge.
2. Incomplete features either block the main branch or require long-lived feature branches that diverge painfully.
3. SRE and testers need the ability to disable in-progress work without reverting commits.
4. No convention exists for how flags are introduced, who owns them, or when they're removed.

After this ADR:

• Concurrent work on partially-conflicting features proceeds via flags
• Incomplete work merges to main behind flags (trunk-based development)
• SRE can disable features in production without code changes
• Flag lifecycle has clear ownership and expiration

Proposed approach

When to use feature flags

Situation	Use a flag?
Feature spans multiple PRs, incomplete state is unsafe	Yes
Two contributors touch the same module for different purposes	Yes (isolate each behind a flag)
SRE needs a kill switch for a new capability	Yes
Simple refactor with no behavioral change	No
Bug fix	No
One-PR feature that's complete on merge	No

Flag ownership

• Every flag has an owner (the issue that introduced it)
• Every flag has an expiration (the issue/PR that removes it)
• Flags without a removal plan are rejected in review

Separation of concerns

• Planners decide which features get flags (issue/RFC level)
• Implementors add/use flags in code (PR level)
• SRE/operators toggle flags in production (runtime level)
• No self-approval — the person who introduces a flag cannot approve its own removal

Open questions

1. Flag mechanism: CDK context variables? DynamoDB runtime config? Environment variables?
2. Should flags be typed/structured (not just boolean) to support gradual rollout?
3. Maximum flag lifetime before mandatory cleanup?
4. How do flags interact with the Cedar policy engine (governance of flagged tool-call behavior)?

Alignment

Aligns with Scale and collaboration — enables multiple autonomous agents to merge concurrent work without blocking, and with Observability and safe deploy — kill switches for new capabilities.

Dependencies

• ADR-003 (RFC: ADR-003 — Contribution governance for async agents and humans #134) — governance (flag introduction requires approval)
• ADR-005 — feedback loop (reviewer may flag-gate a feature during review)

---

• RFC PR: (pending approval)
• Approved by: (pending)
• Reviewed by: (pending)

[scottschreckengaust]

Open questions

1. Flag mechanism: CDK context variables? DynamoDB runtime config? Environment variables?
2. Should flags be typed/structured (not just boolean) to support gradual rollout?
3. Maximum flag lifetime before mandatory cleanup?
4. How do flags interact with the Cedar policy engine (governance of flagged tool-call behavior)?

Many of these open questions are how. A centralized or common feature flag configuration system should be available to the systems needing them. The CDK context variables do not seem like the right place and not all systems can read environment variables - so Dynamo feels the right place. Typed/structured works because those are scalable to different needs (boolean is the minimum). No maximum flag lifetime, but a report on days since first merge to review the backlog with a date to be removed with overdue markings.