gilde

← All craftbooks

Installable Offline PWA

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

Build an installable Progressive Web App that works offline — an HTML app shell, a web app manifest, and a service worker that caches the shell so it loads with no network. Scopes the app's one job and the offline strategy first, designs the app shell, then implements the manifest, registration, and a cache-first service worker. PWAs fail at installability and the service-worker caching contract, so the scope phase locks the cached asset list and the offline behavior before coding, keeping a small model from shipping a manifest that fails the install criteria or a service worker that never caches.

Steps

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

  1. Scopeplannerentry

    the app's job + offline strategy + cached assets

    Show working prompt
    Scope the PWA. (1) State the app's one job in a sentence (e.g. 'a checklist that works offline'). (2) List the app-shell assets to precache (index.html, the CSS/JS, icons) for offline load. (3) Choose the caching strategy (cache-first for the shell) and what happens for uncached requests. (4) Define the manifest essentials: name, short_name, start_url, display 'standalone', theme/background color, and at least a 192 and 512 icon. (5) Write an acceptance-criteria checklist of 5-8 items, e.g. 'a web app manifest is linked with required fields', 'a service worker registers', 'the SW precaches the shell on install', 'the app loads offline after first visit (cache-first)', 'icons are referenced', 'no console errors'. Write to notes/scope.md and via write_task_note. No code yet.
  2. App shell designdesigner

    shell layout, theme colors, offline indicator

    Show working prompt
    Design the app shell. (1) Lay out the minimal shell UI for the app's one job and pick a palette (hex) including the theme/background colors used in the manifest. (2) Specify an online/offline indicator so the user knows their state. (3) Keep the shell light so it caches small and loads instantly. (4) Note the icon look. Write the shell spec to notes/design.md and via write_task_note. No code yet.
  3. Builddeveloper

    index.html + manifest + service worker

    Show working prompt
    Build the PWA to the scope and shell spec. (1) Write index.html as the app shell with the app's UI; link the web app manifest and add theme-color meta. (2) Write manifest.webmanifest (or manifest.json) with name, short_name, start_url, display standalone, theme/background colors, and 192/512 icon entries. (3) In index.html, register the service worker on load (navigator.serviceWorker.register). (4) Write sw.js that on 'install' precaches the shell asset list into a named cache, and on 'fetch' serves cache-first falling back to network. (5) Show the online/offline indicator. On a loop-back, fix only the named gaps. write_task_note the file paths 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
    Evaluate the PWA. Read index.html, the manifest, and sw.js. Check EACH criterion from notes/scope.md and write PASS/FAIL with a reason: is a manifest linked with name/start_url/display-standalone/theme-color and 192+512 icons, does index.html call serviceWorker.register, does sw.js cache the shell on the install event, does fetch serve cache-first (so a second load works offline), are icons referenced, zero console errors? If a browser/DevTools is available, simulate offline and reload to confirm it still loads. A service worker that never caches the shell 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