gilde

← All craftbooks

Flagged Feature Rollout

Build: software and codeevalv1.0.0released 2026-06-05workflow: build-loop

Add a new feature behind a feature flag so it can ship dark, be toggled per-environment/user, and roll back instantly without a deploy. Plans the flag contract FIRST — the flag name/default, the toggle points, the on/off behavior, the targeting (env/percentage/user), and the cleanup plan — then implements the flagged code with both paths working, then a reviewer verifies both states behave and the off-state default is safe. Covers feature flags, toggle points, percentage/targeted rollout, default-off safety, dark launches, and flag-cleanup discipline.

Steps

Entry step: plan. Each step names the specialist role it wants; the full working prompt is expandable.

  1. Plan the flagplannerentry

    lock flag name, default, toggle points, targeting

    Show working prompt
    Plan the feature flag before coding. Step 1: Name the flag and set its DEFAULT (default-off is the safe choice for new features) and where its value is read from (config/env/flag service). Step 2: Identify the toggle points in the code — exactly where the flag branches old behavior vs new. Step 3: Define the behavior in each state precisely, and the targeting strategy (all-on/off, per-environment, percentage, or specific users). Step 4: Note the rollback story (flip the flag, no deploy) and the cleanup plan (when/how the flag and the dead branch get removed later). Step 5: Write a numbered acceptance-criteria checklist of 5-9 items (e.g. 'flag-off reproduces the original behavior exactly', 'flag-on enables the new feature', 'the default is safe', 'no code path runs both branches'). `write_task_note` the flag plan + checklist and write the same to the produces path.
  2. Build the flagged featuredeveloper

    implement both paths behind the flag

    Show working prompt
    Implement the feature behind the flag to the plan. Step 1: Read the flag value from the agreed source with the safe default. Step 2: At each toggle point, branch cleanly: flag-OFF must reproduce the original behavior exactly (no behavior change for existing users), flag-ON enables the new feature. Step 3: Keep the flag check at the boundary so the two paths are clear and neither leaks into the other; support the targeting strategy (e.g. percentage/user check) if specified. Step 4: Ensure the new feature is reachable only when on, and that the off path is the trusted fallback. Write the implementation to the produces path. On a loop-back, fix only the named gap. `write_task_note` the file path and which criteria now pass.
  3. Verify both statesreviewer

    confirm off=original, on=new, safe default

    Show working prompt
    Verify the flag behaves in both states. Step 1: With the flag OFF, confirm the behavior is identical to before the feature existed (existing tests still green, no surprises). Step 2: With the flag ON, confirm the new feature works as specified. Step 3: Confirm the default value is the safe one and that flipping the flag fully switches behavior with no deploy needed. Step 4: Confirm targeting (if any) routes correctly and that no path accidentally runs both branches. Write a verification note covering the off-state, on-state, and default to the produces path.
  4. Evaluatereviewer

    Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.

    Show working prompt
    Toggle the flag and test both states. For EACH acceptance criterion: confirm flag-OFF reproduces the original behavior exactly, confirm flag-ON enables the new feature, confirm the default is safe, confirm targeting routes correctly, and confirm no path runs both branches. Write PASS/FAIL per criterion; an off-state that changed existing behavior is a FAIL.

Then route — this is the whole point of the loop:

- **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`.
- **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "build" })` to loop back. The builder fixes exactly those gaps.

Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.
  5. Finishdeveloper

    All acceptance criteria met. Stamp a short summary and report DONE.

    Show working prompt
    Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.

Triggers

Phrases that suggest this craftbook to a crew.

Source

View this craftbook on GitHub · MIT license