agentleFS
robritacca-dotcomrobritacca-dotcom/rift-ds/.claude/skills/dogfood/SKILL.md

dogfood

Skill9 starsChanged yesterdayMITView on GitHub

Run a dogfood round: send several agents out to build real apps from the published rift-ds package as a stranger would, each logging every place it got stuck, then verify the findings against the repo, merge them with the owner's own build report, compare who found what, and track the round in a ledger until rounds come back clean. Use when asked to dogfood rift-ds, run a dogfood round, send agents to build with the package, or find consumer-side gaps. Never fixes anything itself.

  • Installs packages

81 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use dep-refs, feature-boundary-planner and 9 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • betacatslingSkill

    dep-refs

    Use when needs to inspect TypeScript export references in the z-code workspace, list exports from a file, verify whether an export is unused before deletion, investigate who imports a symbol during refactors, or combine pnpm knip unused-export results with pnpm dep:refs symbol-level reference tracing.

    Also in 5 projects that use this

  • betacatslingSkill

    feature-boundary-planner

    Map a ZCode behavior change to current UI surfaces, state owners, protocol commands, persistence, and validation. Use for impact analysis, product-boundary planning, or an implementation handoff grounded in the checked-out source.

    Also in 5 projects that use this

  • lir-navcooSkill

    yuanbao

    Yuanbao (元宝) groups: @mention users, query info/members.

    Also in 18 projects that use this

  • Cartograf666Skill

    architecture-governance

    Bootstrap, document, enforce, and review a project's architecture through layer responsibilities, dependency direction, architecture manifests, legacy baselines, Change Envelopes, cross-layer approval policy, and deterministic architecture checks. Use when starting a project, auditing an existing codebase, planning cross-layer work, preventing architecture erosion, reviewing structural changes, or deciding whether implementation may expand into another layer.

    Also in 5 projects that use this

  • john-data-chenSkill

    touchdesigner-mcp

    Control a running TouchDesigner instance via twozero MCP — create operators, set parameters, wire connections, execute Python, build real-time visuals. 36 native tools.

    Also in 7 projects that use this

  • math-incSkill

    minecraft-modpack-server

    Set up a modded Minecraft server from a CurseForge/Modrinth server pack zip. Covers NeoForge/Forge install, Java version, JVM tuning, firewall, LAN config, backups, and launch scripts.

    Also in 5 projects that use this

The file

We split this skill into the rules it gives an agent

3 rules. 0 are common, 3 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 81 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    no new blocker cluster,

    line 116
  2. Distinctive:

    no more than two new friction clusters,

    line 117
  3. Distinctive:

    every builder finished its brief without reading package source or writing a workaround for a library gap,

    line 118

“Common” is measured: kept by at least 6 in 10 of the 81 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

dogfood

Reviewers who read the site produce opinions. Builders who install the package produce friction. This skill turns the second into a repeatable loop: N agents each build a real app from the package with consumer knowledge only, log every snag as they hit it, and the owner builds one more by hand. The run then verifies every finding against the repo, merges the reports, compares who found what, and records the round in a ledger so the next round measures progress rather than starting over.

The skill finds and reports. It never fixes. Fixes go through the normal skills (new-component, api-consistency, design-qa and so on) after the owner picks them from the triage, then ship in a release, and the next round tests that release.

When invoked

"Run a dogfood round", "dogfood rift-ds", "send agents out to build with the package". Arguments the owner may give: how many builders (default 5), which briefs, which package source (default the published latest), and a round number (default: one past the ledger's last). Ask only when the ledger shows a round still open (reports in but no triage).

The workspace

Everything lives outside this repo, in a sibling folder, so no consumer app ever sees the repo's source and nothing here is committed by accident:

<repo root>/../rift-dogfood/
├── LEDGER.md                  # every gap cluster across rounds, its status, and the round-by-round scoreboard
└── round-<N>/
    ├── ROUND.md               # package version, briefs, builders, start date
    ├── <brief>/               # one app per builder (a fresh Next.js app)
    │   ├── FRICTION.md        # the live log, written as the builder goes
    │   ├── REPORT.md          # the builder's final report
    │   └── shots/             # screenshots
    ├── owner/REPORT.md        # the owner's own build, same format
    └── TRIAGE.md              # this skill's verified, merged, compared result

Find the repo root with git rev-parse --show-toplevel.

Package source

  • Default, the published package: builders run npm install rift-ds@latest. This is what a stranger gets, and it is the honest test.
  • Unreleased work (the owner asks to test main before a release): run npm run build:lib in the repo, then npm pack ./dist --pack-destination <round folder>, and give builders the tarball path to install instead. Record which in ROUND.md, because a finding against a tarball may already be different on npm and vice versa.

The briefs

Each brief is a small real product with a must-use list that aims it at one area of the system. Pick briefs that spread across areas. Keep at least two briefs the same from round to round so the scoreboard compares like with like, and rotate the rest. Before a round, check src/components/registry.json and src/chat/registry.json so every must-use name in a brief still exists.

BriefThe appAimed at
ops-dashboardAn operations dashboard: KPI row, three or four charts of mixed types, a filterable sortable table with row actions, a date rangecharts, DataTable, filters, number formatting
settingsAccount and settings area: profile form with validation, notification preferences, billing plan picker, danger zone with a confirm dialog, toasts on saveforms, Field, choice controls, dialogs, feedback
assistantAn AI assistant app scaffolded with the init bin's chat subcommand, run on the scripted demo transport so no key is needed, with a thread list and one custom cardthe chat widget, init chat, the AI components
mobileA phone-first app (habit tracker or similar) designed at 375px first: bottom navigation, a sheet or drawer, list and detail screens, then made to work on desktopresponsive behaviour, touch, navigation
marketingA product's marketing site plus a docs page, in a shipped theme preset that is not the default, with at least one block from init blocktheming, data-brand, typography, blocks, the app scaffold
trackerA work tracker: board of columns with cards, a list view, an item detail panel, assignees and statusescomposition, status, avatars, empty states
admin-crudAn admin tool over a fake API with latency and failures: list, search, create, edit, delete, with loading, empty and error states everywhereDataTable server mode, states, overlays

New briefs are welcome. A good one is a product someone would really build, with screens that force a choice between composing the library and writing custom CSS.

Running a round

1. Open the round

Read LEDGER.md (first round: create it). Note the clusters still open and the ones marked won't-fix, so the triage can recognise them. Create round-<N>/, write ROUND.md (date, package source and version, briefs, builder count), and give the owner the builder protocol below so their own report uses the same format.

2. Send the builders

Spawn one agent per brief with the Agent tool, all in one message so they run in parallel, in the background. Each prompt is the builder protocol below with the brief, the app folder, the package source and a unique dev-server port (3101, 3102, and so on) filled in. Tell the owner what is running and roughly what it costs: each builder is a full app build, so five builders is a large token spend. Then wait for the notifications; never poll.

3. Collect

When every builder is done (and the owner's report is in, or the owner says to go without it), read every REPORT.md and FRICTION.md. A builder that finished without a report or with an empty log gets one follow-up message asking for it, never a reconstruction by you.

4. Verify every finding against the repo

Builders cannot see the repo and will sometimes be wrong. You can. Give every finding exactly one verdict:

  • CONFIRMED: the gap is real in the package source tested.
  • UNFOUND: the thing exists, but the builder could not find it from the consumer surfaces (types, skills, site, markdown pages). This is still a real gap, a discoverability one; record where they looked and where it actually lives.
  • FIXED-SINCE: real in the version tested, already different on main. Name the commit.
  • BUILDER-ERROR: the package was fine and the builder misused it, with nothing a doc could reasonably have prevented. Say so plainly.
  • NOT-A-GAP: a deliberate decision (check the ledger's won't-fix rows, CLAUDE.md and design.md first). Name where the decision is recorded.

Evidence for a verdict is a file and line, a command and its output, or a screenshot, never memory. A finding that cannot be checked stays out of the ranked list and goes in a short "could not verify" section.

5. Merge into clusters

Group findings that are the same underlying gap, even when worded differently ("no way to format the axis" and "big numbers clip on the chart" are one cluster if one fix closes both). Give each cluster a stable id. If it matches a ledger cluster, reuse that id and note it came back. Score each cluster:

  • severity of its worst finding (blocker 3, friction 2, polish 1)
  • times the number of independent reporters
  • plus the minutes lost the reporters estimated, as a tiebreak

6. Compare and contrast

This is the step that makes the loop improve itself. Build a matrix of clusters against reporters, then say plainly:

  • Found by several, including the owner: high confidence, fix first.
  • Found only by the owner: what agents miss. Name the pattern (taste, feel, motion, copy tone, things that only look wrong) and propose a concrete change to the builder protocol or the briefs so the next round's agents catch it.
  • Found only by agents: breadth the owner did not have time for. Check these hardest in step 4.
  • Found by one builder only: lower confidence, unless it is a blocker.
  • What worked: the things every builder praised or used without friction. Name them, so a fix does not break them.

7. Write the triage and update the ledger

round-<N>/TRIAGE.md: the verdict counts, the ranked cluster list (id, one-line gap, verdict, reporters, score, suggested fix, which skill would do the fix), the comparison from step 6, the protocol changes proposed, and the "could not verify" list.

LEDGER.md: add or update every cluster (id, gap, first round, rounds seen, status: open, fixed in a version, or won't-fix with the reason), then a scoreboard row for the round: date, package version, builders, briefs, new clusters, recurring clusters, blockers, frictions, and how many builders finished their brief without a source-level workaround.

8. Hand over

Report to the owner: the scoreboard row, the top clusters, what only they found, and the proposed protocol changes. End by asking which clusters to fix. Do not start fixing. A won't-fix answer goes in the ledger with the owner's reason so no later round raises it again.

When it is excellent

The loop is done when two rounds in a row meet all of these:

  • no new blocker cluster,
  • no more than two new friction clusters,
  • every builder finished its brief without reading package source or writing a workaround for a library gap,
  • and the owner's own build found nothing the agents had not.

Say so in the hand-over when it happens. Until then, each round's hand-over says which of the four failed.

The builder protocol

Paste this into each builder's prompt, with the bracketed parts filled in.

You are a front-end developer who has never seen the rift-ds source. Your job is to build [brief: the app description and must-use list] with the rift-ds package, and to log every place the package or its docs made that harder than it should have been. The log matters as much as the app.

Where: create a fresh Next.js app (TypeScript, App Router, no Tailwind) at [app folder]. Install the package from [package source]. Run your dev server on port [port] only.

What you may read: the installed package (its .d.ts files, README and CSS), whatever npx rift-ds init installs, the public site at the package's homepage (append .md to a component page's URL for its prop contract as markdown, and /llms.txt lists everything), and the public MCP endpoint listed there. What you may not read: the rift-ds source repository, anywhere on disk or on GitHub. If you catch yourself wanting to, that is a finding: log what you were looking for.

How to build: follow the package's own setup (start with npx rift-ds init and npx rift-ds init app). Use the library's components and semantic tokens. When the library does not cover something, write the smallest custom piece that does, with tokens only, and log it. No raw colours or pixel values without a log entry saying why.

Log as you go, in FRICTION.md in the app folder, the moment you hit something, never reconstructed at the end. One entry per snag:

  • Area: component, subpath, token, CLI, docs, theming, types…
  • Tried: what you were trying to do and which surface you looked at (types, skill, site page, md page, MCP).
  • Happened: what went wrong, with the exact error, type signature or output pasted in.
  • Workaround: what you did instead, and the file it lives in.
  • Cost: minutes lost, your estimate.
  • Severity: blocker (could not proceed without a workaround), friction (cost time or needed custom code), polish (small and visible).
  • Fix: what you would change in the package or its docs.

Also log the good: anything that worked first time or saved you time goes in a "Worked well" list at the bottom.

Check your work like a user would: npm run build must pass. Then screenshot every screen in light and dark, at 1440px and 375px, with npx playwright screenshot --viewport-size=<w>,<h> --color-scheme=<light|dark> <url> <file> into shots/, and look at each one. Anything that looks off is a finding too, logged the same way: misaligned, clipped, wrong colour in dark mode, unreadable, ugly. Do not use any shared browser pane.

Finish with REPORT.md: what you built (screens, and which components you used), the friction log sorted by severity, the three findings you would fix first if you could fix only three, the worked-well list, and anything you are unsure was the package's fault versus your own. Be specific and honest: a precise small finding beats a vague big one, and "I could not find X" is a valid finding. Do not pad the list.

Ground rules

  • Never fix during a round. The round measures the package; changing it mid-round makes the reports disagree about what they tested.
  • Never commit the workspace. It sits outside the repo on purpose. Nothing from a builder's app is copied into the repo without the owner choosing it.
  • Builders are not trusted, only checked. Their findings are leads until step 4 gives each a verdict with evidence.
  • Settled decisions stay settled. A cluster the owner marked won't-fix is reported as recurring, not re-argued.
  • Examples in this skill are fictional. Real component names appear only in briefs, which step 1 checks against the registries each round.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.