gilde

← All craftbooks

Product Onboarding Tour

Build: interactive and webevalv1.0.0released 2026-06-05workflow: build-loop

Build a single-file product onboarding tour or coachmark walkthrough that guides a new user through key features with sequential tooltips, a highlighted target, next/back/skip controls, and a finish state. Designs the step sequence, what each step points at, and the copy strategy first, writes the step copy, then implements the spotlight overlay and step navigation. Tours break when a step points at the wrong element or skip/finish does not dismiss, so the flow-design phase locks the step-to-target map before any code.

Steps

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

  1. Flow designdesignerentry

    step sequence, targets, spotlight, controls

    Show working prompt
    Design the tour flow. (1) Build a small demo UI (a few buttons/panels) the tour will run on, OR assume target elements by id; list each step and the element it points at. (2) Define the spotlight/overlay treatment (dim the page, highlight the target) and the tooltip position relative to each target. (3) Specify controls: Next, Back, Skip, and Finish on the last step, plus a step counter. (4) Define the finished state (tour dismisses, optionally remembers via localStorage). (5) Write an acceptance-criteria checklist of 5-8 items, e.g. 'the tour starts on load showing step 1', 'each step highlights its target', 'Next/Back move between steps', 'Skip and Finish dismiss the tour', 'a step counter shows position', 'the overlay dims the rest of the page', 'no console errors'. Write to notes/flow-design.md and via write_task_note. No code yet.
  2. Copywritingcopywriter

    per-step tooltip copy + button labels

    Show working prompt
    Write the tour copy. (1) For each step, a short title and one or two sentences explaining the feature and the value — friendly, concise, action-oriented. (2) The button labels (Next, Back, Skip, Got it/Finish). (3) Keep each tooltip skimmable in a few seconds. Write the per-step copy keyed by step to notes/copy.md and via write_task_note.
  3. Builddeveloper

    implement index.html with spotlight + step nav

    Show working prompt
    Implement index.html with inline CSS/JS to the flow and copy. (1) Render the demo UI and a full-page overlay that dims everything. (2) Track the current step; for each, highlight its target (cut-out spotlight or a ring around the element) and position a tooltip with the step's copy near it. (3) Wire Next/Back to move steps and update the counter; Skip and Finish remove the overlay and end the tour (optionally set a localStorage flag). (4) Ensure the tour starts on load at step 1. Style it cleanly and responsively. Vanilla JS, no CDN. On a loop-back, fix only the named gaps without regressing passing criteria. write_task_note the path and passing criteria.
  4. Evaluatereviewer

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

    Show working prompt
    Run the tour. Open index.html if possible: confirm it starts at step 1, step through with Next/Back, try Skip and Finish. Check EACH criterion from notes/flow-design.md and write PASS/FAIL with a reason: does it start on load, does each step highlight the correct target, do Next/Back work, do Skip and Finish dismiss the overlay, does the counter update, does the overlay dim the page, zero console errors? A step pointing at the wrong element, or a tour that will not dismiss, is a FAIL — loop back to build.

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