gilde

← All craftbooks

Flagged Feature Rollout

Build: software and codeevalv1.1.2released 2026-09-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.

The deliverable `{{workPath}}/plan.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.
  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.

The deliverable `{{workPath}}/verify.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.
  4. Evaluatereviewer

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

    Show working prompt
    Review `{{workPath}}/verify.md` against the original scope: every claim cites a real path, the severities and priorities are defensible, and nothing important in scope was skipped. Open the underlying files for at least the top findings; do not grade from the report's own summary. If a finding cannot be verified, say so explicitly.

Write your review to the artifact `{{workPath}}/review.md` with one `write_artifact` call: what you checked, what held, what did not (as a findings table with columns `| Severity | File | Line | Problem | Fix |` when anything needs fixing), ending with exactly `Verdict: PASS` or `Verdict: REVISE`. The gate enforces the verdict: a well-formed REVISE is routed back to the `verify` step automatically with your findings. On PASS, `advance_task_step` to `finish`.
  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