dogfood-loop

The dogfood loop is how Snappy OS gets sharper between releases. A subagent is BOTH a user (drives the app via the chat-drive queue) AND a developer (commits fixes to Snappy OS when a rendered card falls below world-class). Closing this loop is what unlocks Robert's generative-UI leverage.

The deliverable IS the playbook below. There is no backing lib - the prose is the executable. Producer skills (agent-recap, bundle-snapshot, chat-drive) supply the primitives; this skill stitches them into a cadence.

The primitives stack

[ subagent in any context ]
        │
        ▼
state/lib/chat-drive.ts  ─ dispatchInChatUI(text)  ──┐
                          resetChatUI()              │
                                                     ▼
state/lib/desktop.ts     ─ captureScreen(path)
                          captureWindow(app, path)
                          listWindows(app?)

Snappy OS polls 127.0.0.1:3147/chat-inject-pop every 500ms. When dispatchInChatUI pushes text to /chat-inject-push, the React polling effect injects via the React-controlled-component setter dance and fires submit. resetChatUI pushes a control message that flips setHasThread(false) + setChatKey(k+1), returning the welcome surface for the next scenario.

Steps

The 7-step cadence below is automated by the sidecar at state/bin/dogfood-loop/run.ts. Drive a full pass with:

npx tsx state/bin/dogfood-loop/run.ts \
  --scenarios state/skills/dogfood-loop/scenarios/default.json \
  --out /tmp/dogfood-loop-report.md

The sidecar handles steps 1-4 + 7 (reset, pre-shot, push, post-shot, append to report) for every scenario, then exits. Steps 5 and 6 (visual grading, fix-or-log) stay manual - actor (the sidecar) captures; auditor (the agent that runs it) reads each /tmp/loop-N-post.png against the eval checklist below and decides commit-vs-backlog.

For each scenario:

1. Reset - await resetChatUI({waitMs: 1500}). Welcome surface should

remount.

1. Pre-shot - await captureScreen('/tmp/loop-N-pre.png'). Confirms

reset succeeded.

1. Push intent - `await dispatchInChatUI(intent, {waitForFirstFrame:

14000})`.

1. Post-shot - await captureScreen('/tmp/loop-N-post.png').
2. Read both shots with the Read tool. Evaluate against the eval

checklist below.

1. Fix or log - if anything is below world-class, edit

web/src/styles.css or the relevant component, redeploy via bash scripts/build-app.sh --install, re-run the scenario to verify. If the fix needs >25 LOC or spans 3+ files, stop and append to ~/projects/snappy-os/state/log/snappy-os-backlog.md instead.

1. Append to report - /tmp/dogfood-loop-report.md per the format at

the bottom of this doc.

Eval checklist - is this card world-class?

For every rendered scenario, check all of these:

Render integrity

• [ ] Welcome surface unmounted, thread state visible
• [ ] No console errors (open DevTools via menubar, or check WKWebView log

if available)

• [ ] User pill right-anchored at the actual right edge of the message

column

• [ ] User pill bg = --surface-elevated, border = subtle, radius ~12px,

max-width ≤540px, content fit

• [ ] Assistant content visible (text or generative-UI card)

Card rendering (when a generative-UI shape fires)

• [ ] Card chrome present: 1px border, soft shadow, 14px radius, no

side-stripe

• [ ] Channel hairline color present (3-4px gradient strip on top edge)
• [ ] Header row: verb chip (mono 11px) + channel chip (mono 10.5px) +

count if applicable

• [ ] Body text 14px sans, line-height 1.6, color = --text (not

secondary)

• [ ] Action row only present if the shape uses one (Approve/Edit/Reject

for DispatchCard)

• [ ] No clipped content, no overflow

Layout quality

• [ ] Composer at bottom with Queue pill (copper-filled, "Queue" label)
• [ ] Mode chips inline on left of action-bar, model right-pushed
• [ ] Mic button is a quiet outline (not copper-filled) when idle
• [ ] Right panel headers in sentence-case sans, NOT uppercase mono
• [ ] Sidebar agent rows compact, sentence-case section labels

Behavior

• [ ] Dispatch completed (no "Unknown dispatch error" or stuck spinner)
• [ ] Streaming actually streamed (not all-at-once dump)
• [ ] Approve/Edit/Reject buttons on DispatchCard are clickable

If ALL pass → scenario is pass. If any fail → scenario is fail - <reason>. Don't half-pass.

Standard scenario set (ranked by render-richness)

Run as many as fit in budget. Each tests a different generative-UI shape; each is also a contract test for the producer skill that owns it:

1. compose a short project update about today's snappy-os build session →

DispatchCard with a message channel, counter fold, Approve/Edit/Reject. Producer: action-item-draft.

1. show me what the agents did today → ProgressList. Producer:

agent-recap.

1. what is the snappy-os bundle context → ContextPanel with connectors.

Producer: bundle-snapshot.

1. open the file state/skills/desktop/SKILL.md → WorkingFolder with file

pill. Producer: desktop.

1. give me feedback on the welcome screen design → FeedbackForm if

plumbed; else text.

1. are you sure you want to fire snappy-verify? → ConfirmDialog if plumbed;

else text.

DO NOT run anything that side-effects externally - no real LinkedIn posts, no emails, no Slack sends. The default backend is openrouter / gemini so most replies are text-only unless the prompt explicitly invokes a generative shape via the dispatcher.

Failure modes - what to do when

What goes where

• Quick fix (≤25 LOC, ≤2 files, in snappy-os) → commit immediately

with chat: prefix and explicit pathspec.

• Bigger fix (>25 LOC OR ≥3 files OR cross-repo) → append to

~/projects/snappy-os/state/log/snappy-chat-backlog.md as - [ ] <title> - <one-line scope>. Don't commit. Robert routes the larger work.

• Reference observation (e.g. "the welcome state's spark is rendering

blurry at 22px") → also goes to backlog. Cosmetic findings batch better.

• New skill needed (e.g. discovered we need a notification-toast

generative-UI shape) → write a finding in the backlog AND mention it in the loop report's "next" section.

Report format

/tmp/dogfood-loop-report.md:

## Scenario N: <intent>
- Pre: /tmp/loop-N-pre.png
- Post: /tmp/loop-N-post.png
- Card rendered: <name | "text-only" | "none">
- Render quality: pass | fail  -  <reason>
- Action: <commit SHA> | "no fix needed" | "logged to backlog"
- Notes: <one or two sentences>

## Summary
- Scenarios run: N
- Clean passes: M
- Commits: <SHAs>
- Findings to backlog: <count>
- Next biggest gap: <one sentence>

Hard constraints

• PRODUCT.md tone is absolute. No emojis. No em dashes. No exclamation

points in user-visible copy.

• DESIGN.md tokens are the only color source. Every styles.css value

pulls from existing OKLCH tokens.

• Don't modify snappy-os skills/libs in a dogfood pass. That's a

separate axis.

• Don't side-effect externally. No real outbound messages.
• Don't run more than 6 minutes per scenario. If it eats more, log a

finding and move on.

Reference shots

Claude Desktop "Cowork" reference shots live in refs/cd-{01..23}.png - Robert's design target. See refs/README.md for the per-shot index. cd-01..06 = welcome state, cd-13/14/21 = thread state, cd-16..20 = customize / skills directory, cd-08..12 = projects + scheduled, cd-22..23 = artifacts.

Eval

Actor: the dogfood-running subagent. Captures screenshots, evaluates against the checklist, commits fixes, appends to report. Auditor: the next agent (or Robert) reads /tmp/dogfood-loop-report.md and verifies that scenarios actually passed by re-reading the post-shots. Distinct context = actor ≠ auditor.

Rubric

criteria:
  - name: report_present
    kind: deterministic
    check: "/tmp/dogfood-loop-report.md exists and contains a Summary section."
  - name: scenarios_min_three
    kind: deterministic
    check: "Report contains at least three Scenario blocks, each with Pre, Post, Card rendered, Render quality, Action, Notes lines."
  - name: every_fail_has_action
    kind: judge
    check: "Every scenario marked 'fail' carries either a commit SHA in Action OR an entry appended to state/log/snappy-chat-backlog.md  -  no orphan failures."
  - name: no_external_sideeffects
    kind: deterministic
    check: "No scenario triggered a real outbound send (no LinkedIn URN, no Gmail draft, no Slack post). The dispatch backend stays text-only or generative-shape only."

dogfood-loop loader

Compact runtime loader for Snappy OS QA. The full contract lives in state/skills/dogfood-loop/SKILL.md; do not inject historical feedback logs or consolidated issue inventories into chat dispatch.

When invoked

Use the real /Applications/SnappyChat.app, not only /dispatch/chat. Drive it through POST 127.0.0.1:3147/chat-inject-push, reset with POST /chat-inject-control {"action":"reset"}, and capture screenshots from the running app. Screenshots are evidence; curl 200s are not enough.

Cadence

1. Flush/reset the queue, then confirm the UI is ready.
2. Push one concrete user intent.
3. Wait for render completion or a visible failure.
4. Capture the app screenshot.
5. Grade: render integrity, card/canvas quality, layout quality, behavior.
6. Fix narrow issues directly, redeploy, and re-run the same intent.
7. If the fix is large or cross-repo, record a precise backlog item instead.

Five exchanges are required for a full dogfood pass when time allows. In an emergency, run the smallest loop that proves the reported failure is fixed.

Non-negotiables

• Actor is not auditor: do not treat the thing that generated output as the

final grade. Independently inspect the screenshot and logs.

• No blank right rail, empty canvas, placeholder, dead button, or silent

provider failure is acceptable demo behavior.

• Do not perform real outbound side effects such as posting, sending email, or

firing production agents unless the prompt explicitly asks and apply:true is present.

• Keep snappy-os fixes narrow. Build/install before claiming the UI is live:

bash ~/projects/snappy-os-app/apps/snappy-os/scripts/build-app.sh --install.

Useful commands

curl -sS -XPOST 127.0.0.1:3147/chat-inject-flush
curl -sS -XPOST 127.0.0.1:3147/chat-inject-control -H 'content-type: application/json' -d '{"action":"reset"}'
curl -sS -XPOST 127.0.0.1:3147/chat-inject-push -H 'content-type: application/json' -d '{"text":"<intent>","newThread":true}'
pgrep -af "/Applications/SnappyChat.app/Contents/MacOS/SnappyChat"
bash ~/projects/snappy-os-app/apps/snappy-os/scripts/build-app.sh --install

Report shape

Write the result plainly: intent, screenshot path, card/canvas rendered, pass or fail with reason, changed files or backlog item, and the next highest-risk gap.