@otisscott/dogfood

Autonomous dogfooding harness for web apps. Runs scripted scenarios and open-ended exploratory sessions against your dev stack on a schedule, surfaces regressions, files them to your tracker.

Status: v0.1, lifecycle hooks shipped. APIs are still pre-1.0; the on-disk artifact contracts (dogfoodrc.json, sessions/<id>/summary.json, dogfood_findings.md block format, digest metadata.json) are version-locked.

Install

bun add -d @otisscott/dogfood     # or: npm i -D @otisscott/dogfood

Quickstart

# Scaffold .dogfood/ + dogfoodrc.json in your project root
npx dogfood init

# Optional: install skills/agents globally instead
npx dogfood skills install --scope global

# Optional: create local credentials and refresh agent context
npx dogfood credentials init
npx dogfood context generate --force

# Run a scenario
npx dogfood --scenario example

# Schedule it nightly (writes the right artifact for your platform)
npx dogfood schedule --time 01:00 --tz America/New_York

What it does

• Scripted scenarios — markdown-defined journeys driven by a configurable LLM (Kimi, Claude Code -p, OpenAI Codex exec, OpenCode server, llama-cpp) against a configurable browser adapter (agent-browser, Playwright MCP, Stagehand).
• Exploratory sessions — long-form unscripted runs that surface findings the scripted ones wouldn't have caught.
• Lifecycle hooks — declare shell commands at preflight / pre_scenario / post_scenario / pre_digest / post_digest. Hooks see DOGFOOD_STAGE, DOGFOOD_SESSION_ID, DOGFOOD_SESSION_DIR via env. Use them for stack health checks, schema migrations, container warmup, or shipping the digest somewhere.
• Digest — per-day rollup of pass / fail / flake counts, new bugs, recurrences. Both human markdown and a tracker-ready comment.
• Triage — posts the digest to your tracker (Linear via Claude/Kimi MCP, GitHub Issues via gh, or local filesystem).
• Scheduler — dogfood schedule --time HH:MM --tz <iana> writes the right artifact for your platform (launchd / systemd-user / crontab / Windows Task Scheduler) with a stale-fire guard so wake-from-sleep deliveries can't clobber the next slot.
• Project credentials — .dogfood/config/credentials.json stores local testing users and is gitignored by the scaffold.
• Project context — .dogfood/context/project.md maps config, portals, credential keys, scenarios, prompt hints, and artifact paths for skills and driver agents. It is injected into rendered prompts when present.
• Skills / agents — dogfood init installs project-local Codex and Claude skills by default. Use dogfood skills install --scope global for global installs.

Subcommands

dogfood init                         scaffold .dogfood/ + dogfoodrc.json
dogfood --scenario <name>            run one scripted scenario
dogfood --all [--nightly]            run all active scenarios
dogfood --explore --focus "<text>"   open-ended exploratory session
dogfood digest --session <id>        render digest artifacts
dogfood schedule --time HH:MM        manage nightly schedule
dogfood run-hooks <stage>            run lifecycle hooks
dogfood wait-for-url <url>           poll URL until healthy (use in hooks)
dogfood skills install               install bundled skills/agents
dogfood credentials init             create project-local testing credentials
dogfood context generate             generate project context for agents
dogfood read-findings                read exploratory findings from a session
dogfood report-bug                   file a bug from a session artifact

Lifecycle hooks

Declare shell commands in dogfoodrc.json under lifecycle.<stage>.

| Stage | When | Failure mode | Env vars | |-------|------|-------------|----------| | preflight | Before any scenarios run | Abort entire run | DOGFOOD_STAGE | | pre_scenario | Before each scenario | Abort that scenario only | DOGFOOD_STAGE, DOGFOOD_SCENARIO_NAME | | post_scenario | After each scenario | Warn | DOGFOOD_STAGE, DOGFOOD_SCENARIO_NAME, DOGFOOD_SCENARIO_STATUS | | pre_digest | Before digest render | Abort | DOGFOOD_STAGE | | post_digest | After digest render | Warn | DOGFOOD_STAGE, DOGFOOD_DIGEST_DIR |

Use post_scenario to clean up browser sessions or reset state between scenarios:

{
  "lifecycle": {
    "post_scenario": [
      "agent-browser close"
    ]
  }
}

Scenario authoring

Scenarios are Markdown files in .dogfood/scenarios/. Frontmatter goes at the top:

---
portal: wms
user: admin
timeout_s: 300
---

Log in as {{user_email}} at {{base_url}} and verify the dashboard loads.

Frontmatter fields:

| Field | Default | Description | |-------|---------|-------------| | portal | wms | Portal ID from dogfoodrc.json portals[] | | user | admin | Credential key from .dogfood/config/credentials.json | | timeout_s | 300 | Max seconds for this scenario | | status | (none) | Set to draft to skip |

Template variables:

| Variable | Source | |----------|--------| | {{base_url}} | URL of the chosen portal | | {{portal}} | Portal ID | | {{user_email}} / {{user_password}} | Credentials for the chosen user | | {{wms_url}} / {{client_url}} | Named portal URLs | | {{focus}} | Focus text (exploratory only) | | {{duration_seconds}} | Timeout value |

Result sentinel: The driver must emit exactly one line:

DOGFOOD_RESULT: PASS
DOGFOOD_RESULT: FAIL - reason here

Both hyphen (-) and em-dash (—) are accepted after FAIL.

Per-step artifacts: The driver can write single-line JSON files to steps/ inside the scope directory. The harness concatenates them into steps.ndjson after the run.

skipKinds

dogfoodrc.json may declare "skipKinds": ["draft"] (default). Scenario frontmatter with status: <kind> is skipped when <kind> is in skipKinds.

Troubleshooting

| Symptom | Cause | Fix | |---------|-------|-----| | Scenario logged in as wrong user | Browser session reused between scenarios | Add "post_scenario": ["agent-browser close"] to lifecycle | | no DOGFOOD_RESULT sentinel emitted | Driver crashed or timed out before finishing | Check driver_stderr.log in the scenario scope dir | | frontmatter: unknown portal 'x' | Portal ID in scenario doesn't match dogfoodrc.json | Add the portal or fix the scenario frontmatter | | frontmatter: unknown user 'x' | User key not in credentials file | Run dogfood credentials init or fix the key | | Preflight hooks not running | dogfood binary not on PATH | Install globally or ensure node_modules/.bin is on PATH |

Repository

Source, issues, and full docs: github.com/otisscott/dogfooding

License

MIT